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))
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 object containing the push recipient details. See the push notification publish REST API documentation for details on the supported recipient fields
- data
- an object 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)
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.
Push Admin Properties
The push admin object exposes the following public properties:
deviceRegistrations
The returned DeviceRegistrations object provides functionality for registering, updating, listing and de-registering push devices.
channelSubscriptions
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.deviceRegistrations 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))
get(DeviceDetails device, callback(ErrorInfo err, DeviceDetails device))
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
DeviceDetailsobject containing at a minimum thedeviceIdof the requested device - callback
- is a function of the form:
function(err, device)
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.
list
list(Object params, callback(ErrorInfo err, PaginatedResult<DeviceDetails device> resultPage))
Retrieve all devices matching the params filter as a paginated list of DeviceDetails objects. Requires push-admin permission.
Parameters
- params
- an object containing the query parameters as key value pairs as specified below.
- callback
- is a function of the form:
function(err, resultPage)
params properties
- clientId
- optional filter to restrict to devices associated with that client identifier. Cannot be used with a
deviceIdparamType:String - deviceId
- optional filter to restrict to devices associated with that device identifier. Cannot be used with a
clientIdparamType:String - limit
- 100 maximum number of devices per page to retrieve, up to 1,000Type:
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.
save
save(DeviceDetails device, callback(ErrorInfo err, DeviceDetails device))
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
DeviceDetailsobject - callback
- is a function of the form:
function(err, device)
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.
remove
remove(String deviceId, callback(ErrorInfo err))
remove(DeviceDetails device, callback(ErrorInfo err))
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
DeviceDetailsobject containing at a minimum thedeviceIdof the device - callback
- is a function of the form:
function(err)
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.
removeWhere
removeWhere(Object params, callback(ErrorInfo err))
Delete all devices matching the params filter. Requires push-admin permission.
Parameters
- params
- an object containing the filter parameters as key value pairs as specified below.
- callback
- is a function of the form:
function(err)
params properties
- clientId
- optional filter to restrict to devices associated with that client identifier. Cannot be used with a
deviceIdparamType:String - deviceId
- optional filter to restrict to devices associated with that device identifier. Cannot be used with a
clientIdparamType: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.
This object is accessible through client.push.admin.channelSubscriptions 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))
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
- params
- an object containing the query parameters as key value pairs as specified below.
- callback
- is a function of the form:
function(err, resultPage)
params properties
- channel
- filter to restrict to subscriptions associated with that
channel - clientId
- optional filter to restrict to devices associated with that client identifier. Cannot be used with a
deviceIdparamType:String - deviceId
- optional filter to restrict to devices associated with that device identifier. Cannot be used with a
clientIdparamType:String - limit
- 100 maximum number of channel subscriptions per page to retrieve, up to 1,000Type:
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 which contains the failure reason.
listChannels
listChannels(Object params, callback(ErrorInfo err, PaginatedResult<String> resultPage))
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
- params
- an object containing the query parameters as key value pairs as specified below.
- callback
- is a function of the form:
function(err, resultPage)
params properties
- limit
- 100 maximum number of channels per page to retrieve, up to 1,000Type:
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.
save
save(PushChannelSubscription channelSubscription, callback(ErrorInfo err, PushChannelSubscription channelSubscription))
Subscribe a device or group of devices sharing a client identifier for push notifications published on a channel.
Parameters
- channelSubscription
- a
PushChannelSubscriptionobject - callback
- is a function of the form:
function(err, channelSubscription)
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.
remove
remove(PushChannelSubscription channelSubscription, callback(ErrorInfo err))
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
- channelSubscription
- a
PushChannelSubscriptionobject - callback
- is a function of the form:
function(err)
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.
removeWhere
removeWhere(Object params, callback(ErrorInfo err))
Delete all push channel subscriptions matching the params filter. Requires push-admin permission.
Parameters
- params
- an object containing the filter parameters as key value pairs as specified below.
- callback
- is a function of the form:
function(err)
params properties
- channel
- filter to restrict to subscriptions associated with that
channel - clientId
- optional filter to restrict to devices associated with that client identifier. Cannot be used with
deviceIdparamType:String - deviceId
- optional filter to restrict to devices associated with that device identifier. Cannot be used with
clientIdparamType: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.
Related types
DeviceDetails
A DeviceDetails is a type encapsulating attributes of a device registered for push notifications.
Properties
- id
- unique identifier for the device generated by the device itselfType:
String - clientId
- optional trusted client identifier for the deviceType:
String - formFactor
- form factor of the push device. Must be one of
phone,tablet,desktop,tv,watch,carorembeddedType:String - metadata
- optional metadata object for this device. The metadata for a device may only be set by clients with
push-adminprivilegesType:Object - platform
- platform of the push device. Must be one of
iosorandroidType: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 detailsType:
Object - push.state
- the current state of the push device being either
Active,FailingorFailedType:String - push.errorReason
- when the device’s state is failing or failed, this attribute contains the reason for the most recent failureType:
ErrorInfo
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.
Properties
- channel
- the channel that this push notification subscription is associated withType:
String - deviceId
- the device with this identifier is linked to this channel subscription. When present,
clientIdis never presentType:String - clientId
- devices with this client identifier are included in this channel subscription. When present,
deviceIdis never presentType:String
PushChannelSubscription.forDevice(String channel, String deviceId) → 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 subscriptionType:
String - deviceId
- the device with this identifier will be linked with this push channel subscriptionType:
String
Returns
A PushChannelSubscription object
PushChannelSubscription.forClient(String channel, String clientId) → 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 subscriptionType:
String - clientId
- devices with this client identifier are included in the new push channel subscriptionType:
String
Returns
A PushChannelSubscription object
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.
Properties
Methods
first
first(callback(ErrorInfo err, PaginatedResult resultPage))
Returns a new PaginatedResult for the first page of results.
hasNext
Boolean hasNext()
Returns true if there are more pages available by calling next and returns false if this page is the last page available.
isLast
Boolean isLast()
Returns true if this page is the last page and returns false if there are more pages available by calling next available.
next
next(callback(ErrorInfo err, PaginatedResult resultPage))
Returns a new PaginatedResult loaded with the next page of results. If there are no further pages, then null is returned.
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());
});
});
CopyCopied!