Push Notifications - Device Activation and Subscription

This object is accessible through client.push and provides to push-compatible devices :

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

registerCallback
An optional function passed to override the default implementation to register the local device for push activationType: Callable
updateFailedCallback
An optional callback to be invoked when the device registration failed to updateType: 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(deregisterCallback?(DeviceDetails device, callback(ErrorInfo | null err, String result))): Promise<void>

Deactivates the device from receiving push notifications.

Parameters

deregisterCallback
An optional function passed to override the default implementation to deregister the local device for push activationType: 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.

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, car embedded or otherType: String
metadata
optional metadata object for this device. The metadata for a device may only be set by clients with push-admin privilegesType: Object
platform
platform of the push device. Must be one of ios android or browserType: 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, FAILING or FAILEDType: String
push.error
when the device’s state is failing or failed, this attribute contains the reason for the most recent failureType: ErrorInfo
Contains the device identity token and secret of a device.

Properties

id
a unique ID generated by the deviceType: String
deviceSecret
a unique device secret generated by the Ably SDKType: String
deviceIdentityToken
a unique identity token for the deviceType: 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.

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(): 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(): 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(): 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(): 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(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 rest.ably.io/push/channelSubscriptions Rest API.

Parameters

deviceId
a deviceId to filter byType: String
clientId
a clientId to filter byType: String
deviceClientId
a client ID associated with a device to filter byType: 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,000Type: Record<string, string>

Returns

Returns a promise. On success, the promise is fulfilled with PaginatedResult which encapsulates an array of PushChannelSubscription 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.

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, clientId is never presentType: String
clientId
devices with this client identifier are included in this channel subscription. When present, deviceId is never presentType: String

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(): 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.

Boolean hasNext()

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

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(): 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(): 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.

JavaScript v2.9
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());
Copied!
Select...