Push Notifications - Admin

Push Admin object

This object is accessible through client.push.admin and provides:

Methods

publish

publish(Object recipient, Object data, callback(ErrorInfo err))Deferrable publish(Hash recipient, Hash data) → yieldpublish(recipient=Object, data=Object)publish(Array recipient, Array data)publish(recipient: ARTPushRecipient, data: AnyObject?, callback: ((ARTErrorInfo?) → Void)?)void publish(String recipient, Object data, CompletionListener listener)

Publishes a push notification directly to a device or group of devices sharing a client identifier. See the push notification direct publishing documentation for more information.

Parameters

recipient

an objectan arraya Hash containing the push recipient details. See the push notification publish REST API documentation for details on the supported recipient fields

data

an objectan arraya Hash containing the push notification data. See the push admin payload structure for details on the supported push payload fields

callback

a function of the form: function(err)

&block

yielded upon success

listener

Listener to be notified on completion
Type: CompletionListener

callback

called upon publishing the message, or with an error

Push Admin PropertiesPush::Admin Properties

The push admin object exposes the following public propertiesattributesmembers:

deviceRegistrationsdevice_registrations

The returned DeviceRegistrations object provides functionality for registering, updating, listing and de-registering push devices.

channelSubscriptionschannel_subscriptions

The returned PushChannelSubscriptions object provides functionality for subscribing, listing and unsubscribing individual devices or groups of identified devices to push notifications published on channels.

DeviceRegistrations object

This object is accessible through client.push.admin.deviceRegistrationsclient.push.admin.device_registrations and provides an API to register new push notification devices, update existing devices, deregister old devices, and retrieve or list devices registered to an app.

Methods

get

get(String deviceId, callback(ErrorInfo err, DeviceDetails device))Deferrable get(String deviceId) → yields DeviceDetailsDeviceDetails get(device_id=String)DeviceDetails get(String deviceId)get(deviceId: ArtDeviceId, callback: ((ARTDeviceDetails?, ARTErrorInfo?) → Void)DeviceDetails get(String deviceId)

get(DeviceDetails device, callback(ErrorInfo err, DeviceDetails device))Deferrable get(DeviceDetails device) → yields DeviceDetails

Obtain the DeviceDetails for a device registered for receiving push registrations matching the deviceId argument, or the id attribute of the provided DeviceDetails object. Requires push-admin permission or push-subscribe permission together with device authentication matching the requested deviceId.

Parameters

deviceId

the unique device ID String for the requested device

device

a DeviceDetails object containing at a minimum the deviceId of the requested device

callback

is a function of the form: function(err, device)

&block

yields a DeviceDetails object upon success

list

list(Object params, callback(ErrorInfo err, PaginatedResult<DeviceDetails device> resultPage))Deferrable list(Hash params) → yields PaginatedResult<DeviceDetails>PaginatedResult list(params=Object)PaginatedResult list_(Array params)list(params: NSDictionary *, callback: ((ARTPaginatedResult?, ARTErrorInfo?) → Void)PaginatedResult list(Param[] params)

Retrieve all devices matching the params filter as a paginated list of DeviceDetails objects. Requires push-admin permission.

Parameters

paramsParam[] params

an object containing the query parameters as key value pairs as specified below.

callback

is a function of the form: function(err, resultPage)

&block

yields a PaginatedResult<DeviceDetails> object
error

params properties

clientId:client_id

optional filter to restrict to devices associated with that client identifier
Type: String

deviceId:device_id

optional filter to restrict to devices associated with that device identifier
Type: String

limit:limit

100 maximum number of devices per page to retrieve, up to 1,000
Type: Integer

save

save(DeviceDetails device, callback(ErrorInfo err, DeviceDetails device))Deferrable save(DeviceDetails device) → yields DeviceDetailsDeviceDetails save(DeviceDetails device_details)DeviceDetails save(DeviceDetails deviceDetails)save(deviceDetails: DeviceDetails, callback: ((DeviceDetails?, ARTErrorInfo?) → Void)DeviceDetails save(DeviceDetails deviceDetails)

Register a new DeviceDetails object, or update an existing DeviceDetails object with the Ably service. Requires push-admin permission or push-subscribe permission together with device authentication matching the requested deviceId.

Parameters

device

a DeviceDetails object

callback

is a function of the form: function(err, device)

&block

yields the new DeviceDetails object upon success

remove

remove(String deviceId, callback(ErrorInfo err))Deferrable remove(String deviceId)remove(String device_id)remove(String deviceId)remove(deviceDetails: DeviceDetails, callback: ((DeviceDetails?, ARTErrorInfo?) → Void)DeviceDetails save(DeviceDetails deviceDetails)

remove(DeviceDetails device, callback(ErrorInfo err))Deferrable remove(DeviceDetails device) → yieldremove(DeviceDetails device_details)remove(DeviceDetails deviceDetails)remove(deviceDetails: DeviceDetails, callback: ((ARTErrorInfo?) → Void)DeviceDetails save(DeviceDetails deviceDetails)

Remove a device registered for receiving push registrations that matches the deviceId argument, or the id attribute of the provided DeviceDetails object. Requires push-admin permission or push-subscribe permission together with device authentication matching the requested deviceId.

Parameters

deviceId

the unique device ID String for the device

device

a DeviceDetails object containing at a minimum the deviceId of the device

callback

is a function of the form: function(err)

&block

yields upon success

removeWhereremove_where

removeWhere(Object params, callback(ErrorInfo err))Deferrable remove_where(Hash params) → yieldremove_where(params=Object)removeWhere(Array params)removeWhere(params: NSDictionary *, callback: (ARTErrorInfo?) → Void)removeWhere(Param[] params)

Delete all devices matching the params filter. Requires push-admin permission.

Parameters

paramsParam[] params

an object containing the filter parameters as key value pairs as specified below.

callback

is a function of the form: function(err)

&block

yields upon success
error

params properties

clientId:client_id

optional filter to restrict to devices associated with that client identifier
Type: String

deviceId:device_id

optional filter to restrict to devices associated with that device identifier
Type: String

PushChannelSubscriptions object

This object is accessible through client.push.admin.channelSubscriptionsclient.push.admin.channel_subscriptions and provides an API to subscribe a push notification device to a channel ensuring it receives any push notifications published in the future on that channel. Additionally, this object allows these subscriptions to be retrieved, listed, updated or removed.

Methods

list

list(Object params, callback(ErrorInfo err, PaginatedResult<PushChannelSubscription> resultPage))Deferrable list(Hash params) → yields PaginatedResult<PushChannelSubscription>PaginatedResult list(params=Object)PaginatedResult list_(Array params)list(params: NSDictionary *, callback: ((ARTPaginatedResult?, ARTErrorInfo?) → Void)PaginatedResult list(Param[] params)

Retrieve all push channel subscriptions that match the provided params filter as a paginated list of PushChannelSubscription objects. Each PushChannelSubscription represents a device or set of devices sharing the same client identifier registered to a channel to receive push notifications.

Parameters

paramsParam[] params

an object containing the query parameters as key value pairs as specified below.

callback

is a function of the form: function(err, resultPage)

&block

yields a PaginatedResult<PushChannelSubscription> object
error

params properties

channel:channel

filter to restrict to subscriptions associated with that channel

clientId:client_id

optional filter to restrict to devices associated with that client identifier. Cannot be used with a clientId:client_id param
Type: String

deviceId:device_id

optional filter to restrict to devices associated with that device identifier. Cannot be used with a deviceId:device_id param
Type: String

limit:limit

100 maximum number of channel subscriptions per page to retrieve, up to 1,000
Type: Integer

listChannelslist_channels

listChannels(Object params, callback(ErrorInfo err, PaginatedResult resultPage))Deferrable list_channels(Hash params) → yields PaginatedResultPaginatedResult list_channels(params=Object)PaginatedResult listChannels(Array params)listChannels(params: NSDictionary *, callback: ((ARTPaginatedResult?, ARTErrorInfo?) → Void)PaginatedResult listChannels(Param[] params)

Retrieve a list of channels with at least one subscribed device as a paginated list of channel name String objects. Requires push-admin permission.

Parameters

paramsParam[] params

an object containing the query parameters as key value pairs as specified below.

callback

is a function of the form: function(err, resultPage)

&block

yields a PaginatedResult<String> object
error

params properties

limit:limit

100 maximum number of channels per page to retrieve, up to 1,000
Type: Integer

save

save(PushChannelSubscription channelSubscription, callback(ErrorInfo err, PushChannelSubscription channelSubscription))save(PushChannelSubscription channel_subscription)PushChannelSubscription save(PushChannelSubscription channel_subscription)PushChannelSubscription save(PushChannelSubscription channelSubscription)save(channelSubscription: PushChannelSubscription, callback: ((PushChannelSubscription?, ARTErrorInfo?) → Void)PushChannelSubscription save(PushChannelSubscription channelSubscription)

Subscribe a device or group of devices sharing a client identifier for push notifications published on a channel.

Parameters

channelSubscriptionchannel_subscription

a PushChannelSubscription object

callback

is a function of the form: function(err, channelSubscription)

remove

remove(PushChannelSubscription channelSubscription, callback(ErrorInfo err))remove(PushChannelSubscription channel_subscription)remove(PushChannelSubscription channel_subscription)remove(PushChannelSubscription subscription)remove(channelSubscription: PushChannelSubscription, callback: ((ARTErrorInfo?) → Void)void save(PushChannelSubscription channelSubscription)

Unsubscribe a device or group of devices sharing a client identifier from push notifications on a channel. Requires push-admin permission or, in the case of a subscription associated with a given deviceId, push-subscribe permission together with device authentication matching that deviceId.

Parameters

channelSubscriptionchannel_subscription

a PushChannelSubscription object

callback

is a function of the form: function(err)

removeWhereremove_where

removeWhere(Object params, callback(ErrorInfo err))remove_where(Hash params)remove_where(params=Object)removeWhere(Array params)removeWhere(params: NSDictionary *, callback: (ARTErrorInfo?) → Void)removeWhere(Param[] params)

Delete all push channel subscriptions matching the params filter. Requires push-admin permission.

Parameters

paramsParam[] params

an object containing the filter parameters as key value pairs as specified below.

callback

is a function of the form: function(err)
error

params properties

channel:channel

filter to restrict to subscriptions associated with that channel

clientId:client_id

optional filter to restrict to devices associated with that client identifier. Cannot be used with clientId:client_id param
Type: String

deviceId:device_id

optional filter to restrict to devices associated with that device identifier. Cannot be used with deviceId:device_id param
Type: String

Related types

DeviceDetailsAbly::Models::DeviceDetails

A DeviceDetails is a type encapsulating attributes of a device registered for push notifications.

PropertiesMembersAttributes

id

unique identifier for the device generated by the device itself
Type: String

clientIdclient_id

optional trusted client identifier for the device
Type: String

formFactorform_factor

form factor of the push device. Must be one of phone, tablet, desktop, tv, watch, car or embedded
Type: String

metadata

optional metadata object for this device. The metadata for a device may only be set by clients with push-admin privileges
Type: ObjectArrayHash

platform

platform of the push device. Must be one of ios or android
Type: String

deviceSecret

Secret value for the device.
Type: String

push.recipient

push recipient details for this device. See the REST API push publish documentation for more details
Type: ObjectArrayHash

push.state

the current state of the push device being either Active, Failing or Failed
Type: String

push.errorReasonpush.error_reason

when the device’s state is failing or failed, this attribute contains the reason for the most recent failure
Type: ErrorInfo

PushChannelSubscriptionAbly::Models::PushChannelSubscription

An PushChannelSubscription is a type encapsulating the subscription of a device or group of devices sharing a client identifier to a channel in order to receive push notifications.

PropertiesMembersAttributes

channel

the channel that this push notification subscription is associated with
Type: String

deviceIddevice_id

the device with this identifier is linked to this channel subscription. When present, clientIdclient_id is never present
Type: String

clientIdclient_id

devices with this client identifier are included in this channel subscription. When present, deviceIddevice_id is never present
Type: String

PushChannelSubscription constructors

PushChannelSubscription.forDevicePushChannelSubscription.for_device

PushChannelSubscription.forDevice(String channel, String deviceId) → PushChannelSubscriptionPushChannelSubscription.for_device(String channel, String device_id) → PushChannelSubscription

A static factory method to create a PushChannelSubscription object for a channel and single device.

Parameters

channel

channel name linked to this push channel subscription
Type: String

deviceIddevice_id

the device with this identifier will be linked with this push channel subscription
Type: String

Returns

A PushChannelSubscription object

PushChannelSubscription.forClientPushChannelSubscription.for_client

PushChannelSubscription.forClient(String channel, String clientId) → PushChannelSubscriptionPushChannelSubscription.for_client(String channel, String client_id) → PushChannelSubscription

A static factory method to create a PushChannelSubscription object for a channel and group of devices sharing a client identifier.

Parameters

channel

channel name linked to this push channel subscription
Type: String

clientIdclient_id

devices with this client identifier are included in the new push channel subscription
Type: String

Returns

A PushChannelSubscription object

PaginatedResultARTPaginatedResultAbly::Models::PaginatedResultio.ably.lib.types.PaginatedResultIO.Ably.PaginatedResult

A PaginatedResult is a type that represents a page of results for all message and presence history, stats and REST presence requests. The response from a Ably REST API paginated query is accompanied by metadata that indicates the relative queries available to the PaginatedResult object.

PropertiesMembersAttributes

itemsItems

contains the current page of results (for example an Array of Message or PresenceMessage objects for a channel history request)
Type: Array <Message, Presence, Stats>Type: List <Message, Presence, Stats>

Methods

firstFirst

first(callback(ErrorInfo err, PaginatedResult resultPage))PaginatedResult firstPaginatedResult first()PaginatedResult first()Task<PaginatedResult> FirstAsync()PaginatedResult first()first(callback: (ARTPaginatedResult?, ARTErrorInfo?) → Void)First() (PaginatedResult, error)

Returns a new PaginatedResult for the first page of results. When using the Realtime library, the first method returns a Deferrable and yields a PaginatedResult.The method is asynchronous and returns a Task which needs to be awaited to get the PaginatedResult.

hasNextHasNexthas_next?has_next

Boolean hasNext()Boolean has_next?Boolean hasNext()Boolean has_next()Boolean HasNext()Boolean hasNext()Boolean hasNext()HasNext() (bool)

Returns true if there are more pages available by calling nextNext and returns false if this page is the last page available.

isLastIsLastlast?is_last

Boolean isLast()Boolean last?Boolean isLast()Boolean is_last()Boolean IsLast()Boolean isLast()Boolean isLast()IsLast() (bool)

Returns true if this page is the last page and returns false if there are more pages available by calling nextNext available.

nextNext

next(callback(ErrorInfo err, PaginatedResult resultPage))PaginatedResult nextPaginatedResult next()PaginatedResult next()Task<PaginatedResult> NextAsync()PaginatedResult next()next(callback: (ARTPaginatedResult?, ARTErrorInfo?) → Void)Next() (PaginatedResult, error)

Returns a new PaginatedResult loaded with the next page of results. If there are no further pages, then nulla blank PaginatedResult will be returnedNullNonenil is returned. The method is asynchronous and return a Task which needs to be awaited to get the PaginatedResultWhen using the Realtime library, the first method returns a Deferrable and yields a PaginatedResult.

Example

channel.history(function(err, paginatedResult) {
  console.log('Page 0 item 0:' + paginatedResult.items[0].data);
  paginatedResult.next(function(err, nextPage) {
    console.log('Page 1 item 1: ' + nextPage.items[1].data);
    console.log('Last page?: ' + nextPage.isLast());
  });
});

channel.history(function(err, paginatedResult) {
  console.log('Page 0 item 0:' + paginatedResult.items[0].data);
  paginatedResult.next(function(err, nextPage) {
    console.log('Page 1 item 1: ' + nextPage.items[1].data);
    console.log('Last page?: ' + nextPage.isLast());
  });
});

PaginatedResult firstPage = channel.history();
System.out.println("Page 0 item 0:" + firstPage.items[0].data);
if (firstPage.hasNext) {
  PaginatedResult nextPage = firstPage.next();
  System.out.println("Page 1 item 1:" + nextPage.items[1].data);
  System.out.println("More pages?:" + Strong.valueOf(nextPage.hasNext()));
};

PaginatedResult firstPage = channel.history();
System.out.println("Page 0 item 0:" + firstPage.items[0].data);
if (firstPage.hasNext) {
  PaginatedResult nextPage = firstPage.next();
  System.out.println("Page 1 item 1:" + nextPage.items[1].data);
  System.out.println("More pages?:" + Strong.valueOf(nextPage.hasNext()));
};

PaginatedResult<Message> firstPage = await channel.HistoryAsync(null);
Message firstMessage = firstPage.Items[0];
Console.WriteLine("Page 0 item 0: " + firstMessage.data);
if (firstPage.HasNext)
{
    var nextPage = await firstPage.NextAsync();
    Console.WriteLine("Page 1 item 1:" + nextPage.Items[1].data);
    Console.WriteLine("More pages?: " + nextPage.HasNext());
}

# When using the REST sync library
first_page = channel.history
puts "Page 0 item 0: #{first_page.items[0].data}"
if first_page.has_next?
  next_page = first_page.next
  puts "Page 1 item 1: #{next_page.items[1].data}"
  puts "Last page?: #{next_page.is_last?}"
end

# When using the Realtime EventMachine library
channel.history do |first_page|
  puts "Page 0 item 0: #{first_page.items[0].data}"
  if first_page.has_next?
    first_page.next do |next_page|
      puts "Page 1 item 1: #{next_page.items[1].data}"
      puts "Last page?: #{next_page.is_last?}"
    end
  end
end

result_page = channel.history()
print 'Page 0 item 0: ' + str(result_page.items[0].data)
if result_page.has_next():
  next_page = result_page.next()
  print 'Page 1 item 1: ' + str(next_page.items[1].data)
  print 'Last page?: ' + str(next_page.is_last())

$firstPage = $channel.history();
echo("Page 0 item 0: " . $firstPage->items[0]->data);
if ($firstPage->hasNext()) {
  $nextPage = $firstPage->next();
  echo("Page 1 item 1: " . $nextPage->items[1]->data);
  echo("Last page?: " . $nextPage->isLast());
}

[channel history:^(ARTPaginatedResult<ARTMessage *> *paginatedResult, ARTErrorInfo *error) {
    NSLog(@"Page 0 item 0: %@", paginatedResult.items[0].data);
    [paginatedResult next:^(ARTPaginatedResult<ARTMessage *> *nextPage, ARTErrorInfo *error) {
        NSLog(@"Page 1 item 1: %@", nextPage.items[1].data);
        NSLog(@"Last page?: %d", nextPage.isLast());
    }];
}];

channel.history { paginatedResult, error in
    let paginatedResult = paginatedResult!
    print("Page 0 item 0: \((paginatedResult.items[0] as! ARTMessage).data)")
    paginatedResult.next { nextPage, error in
        let nextPage = nextPage!
        print("Page 1 item 1: \((nextPage.items[1] as! ARTMessage).data)")
        print("Last page? \(nextPage.isLast())")
    }
}

page0, err := channel.History(nil)
fmt.Println("Page. 0 item 0: %s\n", page0.Messages[0].Data)
page1, err := page0.Next()
fmt.Println("Page. 1 item 1: %s\n", page1.Messages[1].Data)
fmt.Println("Last page? %s\n", page1.IsLast())