Push Notifications - Admin
Push Admin object
This object is accessible through client.push.admin
and provides:
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.
Methods
publish
publish(Object recipient, Object payload): Promise<void>
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
- payload
- an object containing the push notification data. See the push admin payload structure for details on the supported push payload fields
Returns
Returns a promise. On success to publish the push notification, the promise resolves. On failure, the promise is rejected with an ErrorInfo
object that details the reason why it was rejected.
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): Promise<DeviceDetails>
get(DeviceDetails deviceDetails): Promise<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
- deviceDetails
- a
DeviceDetails
object containing at a minimum thedeviceId
of the requested device
Returns
Returns a promise. On success, the promise is fulfilled with a DeviceDetails
object representing the device registered for push notifications. On failure, the promise is rejected with an ErrorInfo
object that details the reason why it was rejected.
list
list(Object params): Promise<PaginatedResult<DeviceDetails>>
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.
params
properties
- clientId
- optional filter to restrict to devices associated with that client identifier. Cannot be used with a
deviceId
paramType:String
- deviceId
- optional filter to restrict to devices associated with that device identifier. Cannot be used with a
clientId
paramType:String
- limit
- 100 maximum number of devices per page to retrieve, up to 1,000Type:
Integer
- state
- optional filter by the state of the device. Must be one of
ACTIVE
,FAILING
orFAILED
Type:String
Returns
Returns a promise. On success, the promise is fulfilled with 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, the promise is rejected with an ErrorInfo
object that details the reason why it was rejected.
save
save(DeviceDetails deviceDetails): Promise<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
- deviceDetails
- a
DeviceDetails
object
Returns
Returns a promise. On success, the promise is fulfilled with a DeviceDetails
object representing the newly registered or updated device. On failure, the promise is rejected with an ErrorInfo
object that details the reason why it was rejected.
remove
remove(String deviceId): Promise<void>
remove(DeviceDetails deviceDetails): Promise<void>
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
- deviceDetails
- a
DeviceDetails
object containing at a minimum thedeviceId
of the device
Returns
Returns a promise. On success to delete the device, the promise resolves. Note that a request to delete a device that does not exist will result in a successful operation. On failure, the promise is rejected with an ErrorInfo
object that details the reason why it was rejected.
removeWhere
removeWhere(Object params): Promise<void>
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.
params
properties
- clientId
- optional filter to restrict to devices associated with that client identifier. Cannot be used with a
deviceId
paramType:String
- deviceId
- optional filter to restrict to devices associated with that device identifier. Cannot be used with a
clientId
paramType:String
Returns
Returns a promise. On success to delete the device, the promise resolves. Note that a request that does match any existing devices will result in a successful operation. On failure, the promise is rejected with an ErrorInfo
object that details the reason why it was rejected.
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): Promise<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
- params
- an object containing the query parameters as key value pairs as specified below.
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
deviceId
paramType:String
- deviceId
- optional filter to restrict to devices associated with that device identifier. Cannot be used with a
clientId
paramType:String
- limit
- 100 maximum number of channel subscriptions per page to retrieve, up to 1,000Type:
Integer
Returns
Returns a promise. On success, the promise is fulfilled with 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, the promise is rejected with an ErrorInfo
object that details the reason why it was rejected.
listChannels
listChannels(Object params): Promise<PaginatedResult<String>>
Retrieve a list of channels that have at least one device subscribed to push notifications 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.
params
properties
- limit
- 100 maximum number of channels per page to retrieve, up to 1,000Type:
Integer
Returns
Returns a promise. On success, the promise is fulfilled with 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, the promise is rejected with an ErrorInfo
object that details the reason why it was rejected.
save
save(PushChannelSubscription subscription): Promise<PushChannelSubscription>
Subscribe a device or group of devices sharing a client identifier for push notifications published on a channel.
Parameters
- subscription
- a
PushChannelSubscription
object
Returns
Returns a promise. On success, the promise is fulfilled with a PushChannelSubscription
object representing the newly subscribed or updated push channel subscription. On failure, the promise is rejected with an ErrorInfo
object that details the reason why it was rejected.
remove
remove(PushChannelSubscription subscription): Promise<void>
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
- subscription
- a
PushChannelSubscription
object
Returns
Returns a promise. On success to unsubscribe, the promise resolves. On failure, the promise is rejected with an ErrorInfo
object that details the reason why it was rejected.
removeWhere
removeWhere(Object params): Promise<void>
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.
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
deviceId
paramType:String
- deviceId
- optional filter to restrict to devices associated with that device identifier. Cannot be used with
clientId
paramType:String
Returns
Returns a promise. On success to unsubscribe, 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
- 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
orother
Type: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
orbrowser
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 detailsType:
Object
- push.state
- the current state of the push device being either
ACTIVE
,FAILING
orFAILED
Type:String
- push.error
- when the device’s state is failing or failed, this attribute contains the reason for the most recent failureType:
ErrorInfo
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 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 alimit
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.
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,
clientId
is never presentType:String
- clientId
- devices with this client identifier are included in this channel subscription. When present,
deviceId
is never presentType: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 a Ably REST API paginated query is accompanied by metadata that indicates the relative queries available to the PaginatedResult
object.
Properties
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
available.
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
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());
CopyCopied!