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:

device_registrations

The returned DeviceRegistrations object provides functionality for registering, updating, listing and de-registering push devices.

channel_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.

Methods

publish

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

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 callback of the Deferrable with an ErrorInfo object with the failure reason.

DeviceRegistrations object

This object is accessible through client.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

Deferrable get(String deviceId) -> yields DeviceDetails

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. Requires push-admin permission or push-subscribe permission together with device authentication matching the requested deviceId.

Parameters

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

Deferrable list(Hash params) -> yields PaginatedResult<DeviceDetails>

Retrieve all devices matching the params filter as a paginated list of DeviceDetails objects. Requires push-admin permission.

Parameters

params properties

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

Deferrable save(DeviceDetails device) -> yields 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

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

Deferrable remove(String deviceId)

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. Requires push-admin permission or push-subscribe permission together with device authentication matching the requested deviceId.

Parameters

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.

remove_where

Deferrable remove_where(Hash params) -> yield

Delete all devices matching the params filter. Requires push-admin permission.

Parameters

params properties

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.channel_subscriptions 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

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

params properties

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.

list_channels

Deferrable list_channels(Hash params) -> yields 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 properties

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 channel_subscription)

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

Parameters

remove

remove(PushChannelSubscription channel_subscription)

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

remove_where

remove_where(Hash params)

Delete all push channel subscriptions matching the params filter. Requires push-admin permission.

Parameters

params properties

Related types

Ably::Models::DeviceDetails

A DeviceDetails is a type encapsulating attributes of a device registered for push notifications.

Attributes

Ably::Models::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

Subscribe your device to the channel's push notifications.

subscribeClient

Subscribe all devices associated with your device's clientId to the channel's push notifications.

unsubscribeDevice

Unsubscribe your device from the channel's push notifications.

unsubscribeClient

Unsubscribe all devices associated with your device's clientId from the channel's push notifications.

listSubscriptions

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

Ably::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.

Attributes

PushChannelSubscription constructors

PushChannelSubscription.for_device

PushChannelSubscription.for_device(String channel, String device_id) -> PushChannelSubscription

A static factory method to create a PushChannelSubscription object for a channel and single device.

Parameters

Returns

A PushChannelSubscription object

PushChannelSubscription.for_client

PushChannelSubscription.for_client(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

Returns

A PushChannelSubscription object

Ably::Models::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.

Attributes

Methods

first

PaginatedResult first

Returns a new PaginatedResult for the first page of results. When using the Realtime library, the first method returns a Deferrable and yields a PaginatedResult.

has_next?

Boolean has_next?

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

last?

Boolean last?

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

next

PaginatedResult next

Returns a new PaginatedResult loaded with the next page of results. If there are no further pages, then is returned. When using the Realtime library, the first method returns a Deferrable and yields a PaginatedResult.

Example

# When using the REST sync library
first_page = channel.history
puts "Page 0 item 0: #{first_page.items[0].data}"
if first_page.has_next?
  next_page = first_page.next
  puts "Page 1 item 1: #{next_page.items[1].data}"
  puts "Last page?: #{next_page.is_last?}"
end

# When using the Realtime EventMachine library
channel.history do |first_page|
  puts "Page 0 item 0: #{first_page.items[0].data}"
  if first_page.has_next?
    first_page.next do |next_page|
      puts "Page 1 item 1: #{next_page.items[1].data}"
      puts "Last page?: #{next_page.is_last?}"
    end
  end
end