Push Notifications - Device Activation and Subscription
Push Device object
This object is accessible through client.push and provides to push-compatible devices :
Methods
activate
activate(registerCallback?(DeviceDetails device, callback(ErrorInfo | null err, DeviceDetails result)), updateFailedCallback?(ErrorInfo | null err)): Promise<void>
Activates the device for push notifications. Subsequently registers the device with Ably and stores the deviceIdentityToken in local storage.
Parameters
| Parameter | Description | Type |
|---|---|---|
| registerCallback | An optional function passed to override the default implementation to register the local device for push activation | Callable |
| updateFailedCallback | An optional callback to be invoked when the device registration failed to update | Callable |
Returns
Returns a promise. On successful device activation, the promise resolves. On failure, the promise is rejected with an ErrorInfo object that details the reason why it was rejected.
deactivate
deactivate(deregisterCallback?(DeviceDetails device, callback(ErrorInfo | null err, String result))): Promise<void>
Deactivates the device from receiving push notifications.
Parameters
| Parameter | Description | Type |
|---|---|---|
deregisterCallback | An optional function passed to override the default implementation to deregister the local device for push activation | Callable |
Returns
Returns a promise. On successful device deactivation, the promise resolves. On failure, the promise is rejected with an ErrorInfo object that details the reason why it was rejected.
Related types
DeviceDetails
A DeviceDetails is a type encapsulating attributes of a device registered for push notifications.
Properties
| Property | Description | Type |
|---|---|---|
| id | Unique identifier for the device generated by the device itself | String |
| clientId | Optional trusted client identifier for the device | String |
| formFactor | Form factor of the push device. Must be one of phone, tablet, desktop, tv, watch, car embedded or other | String |
| metadata | Optional metadata object for this device. The metadata for a device may only be set by clients with push-admin privileges | Object |
| platform | Platform of the push device. Must be one of ios android or browser | String |
| deviceSecret | Secret value for the device | String |
| push.recipient | Push recipient details for this device. See the REST API push publish documentation for more details | Object |
| push.state | The current state of the push device being either ACTIVE, FAILING or FAILED | String |
| push.error | When the device's state is failing or failed, this attribute contains the reason for the most recent failure | ErrorInfo |
LocalDevice
Contains the device identity token and secret of a device.
Properties
| Property | Description | Type |
|---|---|---|
| id | A unique ID generated by the device | String |
| deviceSecret | A unique device secret generated by the Ably SDK | String |
| deviceIdentityToken | A unique identity token for the device | String |
Methods
listSubscriptions
listSubscriptions(): Promise<PaginatedResult<PushChannelSubscription>>
Retrieves push subscriptions active for the local device.
Returns
Returns a promise. On success, the promise is fulfilled with a PaginatedResult object containing an array of PushChannelSubscription objects for each push channel subscription active for the local device. On failure, the promise is rejected with an ErrorInfo object that details the reason why it was rejected.
PushChannel
A PushChannel is a property of a RealtimeChannel or RestChannel. It provides push devices the ability to subscribe and unsubscribe to push notifications on channels.
Methods
subscribeDevice
subscribeDevice(): Promise<void>
Subscribe your device to the channel's push notifications.
Returns
Returns a promise. On success, the promise resolves. On failure, the promise is rejected with an ErrorInfo object that details the reason why it was rejected.
subscribeClient
subscribeClient(): Promise<void>
Subscribe all devices associated with your device's clientId to the channel's push notifications.
Returns
Returns a promise. On success, the promise resolves. On failure, the promise is rejected with an ErrorInfo object that details the reason why it was rejected.
unsubscribeDevice
unsubscribeDevice(): Promise<void>
Unsubscribe your device from the channel's push notifications.
Returns
Returns a promise. On success, the promise resolves. On failure, the promise is rejected with an ErrorInfo object that details the reason why it was rejected.
unsubscribeClient
unsubscribeClient(): Promise<void>
Unsubscribe all devices associated with your device's clientId from the channel's push notifications.
Returns
Returns a promise. On success, the promise resolves. On failure, the promise is rejected with an ErrorInfo object that details the reason why it was rejected.
listSubscriptions
listSubscriptions(Record<string, string> params?): Promise<PaginatedResult<PushChannelSubscription>>
Lists push subscriptions on a channel specified by its channel name (channel). These subscriptions can be either be a list of client (clientId) subscriptions, device (deviceId) subscriptions, or if @concatFilters@ is set to @true@, a list of both. This method requires clients to have the Push Admin capability. For more information, see GET main.realtime.ably.net/push/channelSubscriptions Rest API.
Parameters
| Parameter | Description | Type |
|---|---|---|
| deviceId | A deviceId to filter by | String |
| clientId | A clientId to filter by | String |
| deviceClientId | A client ID associated with a device to filter by | String |
| params | An optional object containing key-value pairs to filter subscriptions by. Can contain clientId, deviceId or a combination of both, and a limit on the number of subscriptions returned, up to 1,000 | Record<string, string> |
Returns
Returns a promise. On success, the promise is fulfilled with PaginatedResult which encapsulates an array of "PushChannelSubscription":#push-channel-subscription objects corresponding to the current page of results. PaginatedResult supports pagination using next and first methods. On failure, the promise is rejected with an ErrorInfo object that details the reason why it was rejected.
PushChannelSubscription
A 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
| Property | Description | Type |
|---|---|---|
| channel | The channel that this push notification subscription is associated with | String |
| deviceId | The device with this identifier is linked to this channel subscription. When present, clientId is never present | String |
| clientId | Devices with this client identifier are included in this channel subscription. When present, deviceId is never present | String |
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 an Ably REST API paginated query is accompanied by metadata that indicates the relative queries available to the PaginatedResult object.
Properties
| Property | Description | Type |
|---|---|---|
| items | Contains the current page of results (for example an Array of Message or PresenceMessage objects for a channel history request) | Array <Message, Presence, Stats> |
Methods
first
first(): Promise<PaginatedResult>
Returns a promise. On success, the promise is fulfilled with a new PaginatedResult for the first page of results. On failure, the promise is rejected with an ErrorInfo object that details the reason why it was rejected.
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.
next
next(): Promise<PaginatedResult | null>
Returns a promise. On success, the promise is fulfilled with a new PaginatedResult loaded with the next page of results. If there are no further pages, then null is returned. On failure, the promise is rejected with an ErrorInfo object that details the reason why it was rejected.
current
current(): Promise<PaginatedResult>
Returns a promise. On success, the promise is fulfilled with a new PaginatedResult loaded with the current page of results. On failure, the promise is rejected with an ErrorInfo object that details the reason why it was rejected.
Example
1
2
3
4
5
const paginatedResult = await channel.history();
console.log('Page 0 item 0:' + paginatedResult.items[0].data);
const nextPage = await paginatedResult.next();
console.log('Page 1 item 1: ' + nextPage.items[1].data);
console.log('Last page?: ' + nextPage.isLast());