Please be aware that you are viewing our bleeding edge unstable documentation. Unless you wanted to view the bleeding edge (and possibly unstable) documentation, we recommend you use our stable docs.

Go to Ably's stable canonical documentation »

I know what I'm doing, let me see the bleeding edge docs »

You are viewing our bleeding edge unstable documentation. We recommend you use our stable documentation »
Fork me on GitHub

Push Notifications - Admin

The client libraries provide a Push Admin API that is intended to be used on a customer’s servers to perform all the management tasks relating to registering devices, managing push device subscriptions and delivering push notifications directly to devices or devices associated with a client identifier.

The push admin API is accessible via the push attribute of the realtime client. For example to publish a push notification directly to a device, you would access the publish method as follows:

var realtime = new Ably.Realtime({ key: apiKey });
realtime.push.admin.publish(recipient, data, function(err) {
  if (err) {
    console.log('Unable to publish push notification; err = ' + err.message);
    return;
  }
  console.log('Push notification published');
});
var realtime = new Ably.Realtime({ key: apiKey });
realtime.push.admin.publish(recipient, data, function(err) {
  if (err) {
    console.log('Unable to publish push notification; err = ' + err.message);
    return;
  }
  console.log('Push notification published');
});
realtime = Ably::Realtime.new(key: api_key);
result = realtime.push.admin.publish(recipient, data) do
  puts 'Push notification published'
end
result.errback do |err|
  puts "Unable to publish push notification; err = #{err}"
end

The push notification service is currently in beta. Before you get started, please take a look at the push service beta notice.

The push admin API offers three key features:

API reference

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) → yield

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 objecta Hash containing the push recipient details. See the push notification publish REST API documentation for details on the supported recipient fields
data
an objecta Hash containing the push notification recipient details. See the push notification publish REST API documentation for details on the supported push recipient payload fields
callback
is a function of the form: function(err)
&block
yielded upon success

Callback result

The callback is called upon success or failure to publish the push notification. When this operation fails, err contains an ErrorInfo object with the failure reason.

Returns

A Deferrable object is returned from the method.

On success, the registered success blocks for the Deferrable and any block provided to the method are yielded to.

Failure to publish the push notification will trigger the errback callbacks of the Deferrable with an ErrorInfo object with the failure reason.

Push Admin PropertiesPush::Admin Properties

The push admin object exposes the following public propertiesattributesmembers:

deviceRegistrationsdevice_registrations

The returned DeviceRegistrations object provide functionality for registering, updating, listing and deregistering 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 DeviceDetails

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.

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

Callback result

On success, device contains the device registered for push notifications as a DeviceDetails object.

On failure to retrieve the device, err contains an ErrorInfo object with the failure reason.

Returns

A Deferrable object is returned from the method.

On success, the registered success blocks for the Deferrable and any block provided to the method yield the device registered for push notifications as a DeviceDetails object.

Failure to retrieve the device will trigger the errback callbacks of the Deferrable with an ErrorInfo object with the failure reason.

list

list(Object params, callback(ErrorInfo err, PaginatedResult<DeviceDetails device> resultPage))Deferrable list(Hash params) → yields PaginatedResult<DeviceDetails>

Retrieve all devices matching the params filter as a paginated list of DeviceDetails objects.

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

Callback result

On success, resultPage contains a PaginatedResult encapsulating an array of DeviceDetails objects corresponding to the current page of results. PaginatedResult supports pagination using next() and first() methods.

On failure to retrieve the devices, err contains an ErrorInfo object with the failure reason.

Returns

A Deferrable object is returned from the method.

On success, the registered success blocks for the Deferrable and any block provided to the method yield a PaginatedResult that encapsulates an array of DeviceDetails corresponding to the current page of results. PaginatedResult supports pagination using next() and first() methods.

Failure to retrieve the devices will trigger the errback callbacks of the Deferrable with an ErrorInfo object with the failure reason.

save

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

Register a new DeviceDetails object, or update an existing DeviceDetails object with the Ably service.

Parameters

device
a DeviceDetails object
callback
is a function of the form: function(err, device)
&block
yields the new DeviceDetails object upon success

Callback result

On success, device contains the newly registered or updated device as a DeviceDetails object.

On failure to create or update the device, err contains an ErrorInfo object with the failure reason.

Returns

A Deferrable object is returned from the method.

On success, the registered success blocks for the Deferrable and any block provided to the method yield the newly registered or updated device as a DeviceDetails object.

Failure to create or update the device will trigger the errback callbacks of the Deferrable with an ErrorInfo object with the failure reason.

remove

remove(String deviceId, callback(ErrorInfo err))Deferrable remove(String deviceId)

remove(DeviceDetails device, callback(ErrorInfo err))Deferrable remove(DeviceDetails device) → yield

Remove a device registered for receiving push registrations that matches the deviceId argument, or the id attribute of the provided DeviceDetails object.

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

Callback result

The callback is called upon success or failure to delete the device. Note that a request to delete a device that does not exist will result in a successful operation.

When this operation fails, err contains an ErrorInfo object with the failure reason.

Returns

A Deferrable object is returned from the method.

On success, the registered success blocks for the Deferrable and any block provided to the method are yielded to. Note that a request to delete a device that does not exist will result in a successful operation.

Failure to delete the device will trigger the errback callbacks of the Deferrable with an ErrorInfo object with the failure reason.

removeWhereremove_where

removeWhere(Object params, callback(ErrorInfo err))Deferrable remove_where(Hash params) → yield

Delete all devices matching the params filter.

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

Callback result

The callback is called upon success or failure to delete the device. Note that a request that does match any existing devices will result in a successful operation.

When this operation fails, err contains an ErrorInfo object with the failure reason.

Returns

A Deferrable object is returned from the method.

On success, the registered success blocks for the Deferrable and any block provided to the method are yielded to. Note that a request that does match any existing devices will result in a successful operation.

Failure to delete the device will trigger the errback callbacks of the Deferrable with an ErrorInfo object with the failure reason.

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 future on that channel. Additionally, this object allows these subscriptions to be retrieved, listed, updated or removed.

Methods

get

get(PushChannelSubscription channelSubscription, callback(ErrorInfo err, PushChannelSubscription channelSubscription))Deferrable get(PushChannelSubscription channel_subscription) → yields PushChannelSubscription

Retrieve the push channel subscription that matches the provided PushChannelSubscription argument. Each PushChannelSubscription represents a device or set of devices sharing the same client identifier registered to a channel to receive push notifications.

Parameters

channelSubscriptionchannel_subscription
a PushChannelSubscription object
callback
is a function of the form: function(err, channelSubscription)
&block
yields a PushChannelSubscription object upon success

Callback result

On success, channelSubscription contains the push channel subscription as a PushChannelSubscription object

On failure to retrieve the push channel subscription, err contains an ErrorInfo object with the failure reason.

Returns

A Deferrable object is returned from the method.

On success, the registered success blocks for the Deferrable and any block provided to the method yield the push channel subscription as a PushChannelSubscription object.

Failure to retrieve the push channel subscription will trigger the errback callbacks of the Deferrable with an ErrorInfo object with the failure reason.

list

list(Object params, callback(ErrorInfo err, PaginatedResult<PushChannelSubscription> resultPage))Deferrable list(Hash params) → yields PaginatedResult<PushChannelSubscription>

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 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
limit:limit
100 maximum number of channel subscriptions per page to retrieve, up to 1,000
Type: Integer

Callback result

On success, resultPage contains a PaginatedResult encapsulating an array of PushChannelSubscription objects corresponding to the current page of results. PaginatedResult supports pagination using next() and first() methods.

On failure to retrieve the channel subscriptions, err contains an ErrorInfo object with the failure reason.

Returns

A Deferrable object is returned from the method.

On success, the registered success blocks for the Deferrable and any block provided to the method yield a PaginatedResult that encapsulates an array of PushChannelSubscription corresponding to the current page of results. PaginatedResult supports pagination using next() and first() methods.

Failure to retrieve the channel subscriptions will trigger the errback callbacks of the Deferrable with an ErrorInfo object with the failure reason.

listChannelslist_channels

listChannels(Object params, callback(ErrorInfo err, PaginatedResult resultPage))Deferrable list_channels(Hash params) → yields PaginatedResult

Retrieve a list of channels with at least one subscribed device as a paginated list of channel name String objects.

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

Callback result

On success, resultPage contains a PaginatedResult encapsulating an array of channel name String values corresponding to the current page of results. PaginatedResult supports pagination using next() and first() methods.

On failure to retrieve the channels, err contains an ErrorInfo object with the failure reason.

Returns

A Deferrable object is returned from the method.

On success, the registered success blocks for the Deferrable and any block provided to the method yield a PaginatedResult that encapsulates an array of channel name String values corresponding to the current page of results. PaginatedResult supports pagination using next() and first() methods.

Failure to retrieve the channels will trigger the errback callbacks of the Deferrable with an ErrorInfo object with the failure reason.

save

save(PushChannelSubscription channelSubscription, callback(ErrorInfo err, PushChannelSubscription channelSubscription))Deferrable save(PushChannelSubscription channel_subscription) → yields PushChannelSubscription

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)
&block
yields the new PushChannelSubscription object upon success

Callback result

On success, channelSubscription contains the newly subscribed or updated push channel subscription as a PushChannelSubscription object.

On failure to create or update the channel subscription, err contains an ErrorInfo object with the failure reason.

Returns

A Deferrable object is returned from the method.

On success, the registered success blocks for the Deferrable and any block provided to the method yield the newly subscribed or updated push channel subscription as a PushChannelSubscription object.

Failure to create or update the channel subscription will trigger the errback callbacks of the Deferrable with an ErrorInfo object with the failure reason.

remove

remove(PushChannelSubscription channelSubscription, callback(ErrorInfo err))Deferrable remove(PushChannelSubscription channel_subscription) → yield

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

Parameters

channelSubscriptionchannel_subscription
a PushChannelSubscription object
callback
is a function of the form: function(err)
&block
yields upon success

Callback result

The callback is called upon success or failure to unsubscribe. Note that a request to unsubscribe or remove a subscription that does not exist will result in a successful operation.

When this operation fails, err contains an ErrorInfo object with the failure reason.

Returns

A Deferrable object is returned from the method.

On success, the registered success blocks for the Deferrable and any block provided to the method are yielded to. Note that a request to unsubscribe or remove a subscription that does not exist will result in a successful operation.

Failure to unsubscribe will trigger the errback callbacks of the Deferrable with an ErrorInfo object with the failure reason.

removeWhereremove_where

removeWhere(Object params, callback(ErrorInfo err))Deferrable remove_where(Hash params) → yield

Delete all push channel subscriptions matching the params filter.

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

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

Callback result

The callback is called upon success or failure to unsubscribe. Note that a request to unsubscribe or remove a subscription that does not exist will result in a successful operation.

When this operation fails, err contains an ErrorInfo object with the failure reason.

Returns

A Deferrable object is returned from the method.

On success, the registered success blocks for the Deferrable and any block provided to the method are yielded to. Note that a request to unsubscribe or remove a subscription that does not exist will result in a successful operation.

Failure to unsubscribe will trigger the errback callbacks of the Deferrable with an ErrorInfo object with the failure reason.

DeviceDetailsAbly::Models::DeviceDetails

An 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: Strinf
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 and will be used more extensively in future with smart notifications
Type: ObjectHash
platform
platform of the push device. Must be one of ios, android or browser
Type: String
updateTokenupdate_token
a token that can be used by typically a mobile device to authenticate with Ably later and update an existing device registration (for example, for updating a GCM or FCM registration token)
Type: String
push.recipient
push recipient details for this device. See the REST API push publish documentation for more details
Type: ObjectHash
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.forDevice(String channel, String clientId) → PushChannelSubscriptionPushChannelSubscription.for_device(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


Back to top