Warning: You are viewing an old version (1.1) of this documentation. We recommend you view the latest version 1.2.

API Reference

Push Notifications - Device Activation and Subscription

Methods
- activate()
- deactivate()

Related types

Push Device object

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

Methods

activate

void activate()activate(callback: (ARTErrorInfo?, DeviceDetails?) → Void)

Register the device for push. When the activation process is completed, Ably will send a broadcast through the application’s LocalBroadcastManager. Success or failure will be broadcast through io.ably.broadcast.PUSH_ACTIVATEcall the (void)didActivateAblyPush:(nullable ARTErrorInfo *)errordidActivateAblyPush(error: ARTErrorInfo?) method from the ARTPushRegistererDelegate.

deactivate

void deactivate()deactivate(deregisterCallback: (ARTErrorInfo?, deviceId: String?) → Void)

Deregister the device for push. When the deactivation process is completed, Ably will send a broadcast through the application’s LocalBroadcastManager. Success or failure will be broadcast through io.ably.broadcast.PUSH_DEACTIVATEcall the (void)didDeactivateAblyPush:(nullable ARTErrorInfo *)errordidDeactivateAblyPush(error: ARTErrorInfo?) method from [email protected]@.

DeviceDetailsAbly::Models::DeviceDetailsARTDeviceDetails

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

PropertiesMembersAttributes

id: unique identifier for the device generated by the device itself
Type: String

clientIdclient_id: optional trusted client identifier for the device
Type: String

formFactorform_factor: form factor of the push device. Must be one of phone, tablet, desktop, tv, watch, car or embedded
Type: String

metadata: optional metadata object for this device. The metadata for a device may only be set by clients with push-admin privileges
Type: ObjectArrayHash

platform: platform of the push device. Must be one of ios or android
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 details
Type: ObjectArrayHash

push.state: the current state of the push device being either Active, Failing or Failed
Type: String

push.errorReasonpush.error_reason: when the device’s state is failing or failed, this attribute contains the reason for the most recent failure
Type: ErrorInfo

LocalDeviceAbly::Models::LocalDevice

An extension of DeviceDetails. In addition to the propertiesmembersattributes of DeviceDetails, it includes the following:

PropertiesMembersAttributes

deviceIdentityToken: a unique identity token for the device
Type: String

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

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

unsubscribeDevice()

Unsubscribe your device from the channel’s push notifications.

unsubscribeClient

unsubscribeClient()

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

listSubscriptions

PaginatedResult<PushChannelSubscription> listSubscriptions(String deviceId, String clientId, String deviceClientId, String channel)listSubscriptions(deviceId: String?, clientId: String?, deviceClientId: String?, channel: String?, callback: (ARTPaginatedResult<PushChannelSubscription>?, ARTErrorInfo?) → Void)

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

Parameters

deviceId: a deviceId to filter by
Type: String

clientId: a clientId to filter by
Type: String

deviceClientId: a client ID associated with a device to filter by
Type: String

callback: called with a ARTPaginatedResult<PushChannelSubscription> object or an error

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 message history, err contains an ErrorInfo object with the failure reason.

Returns

On success, the returned PaginatedResult encapsulates an array of PushChannelSubscription objects corresponding to the current page of results. PaginatedResult supports pagination using next and first methods.

Failure to retrieve the message history will raise an AblyException

PushChannelSubscriptionAbly::Models::PushChannelSubscriptionChannelSubscriptionArtPushChannelSubscription

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.

PropertiesMembersAttributes

channel: the channel that this push notification subscription is associated with
Type: String

deviceIddevice_id: the device with this identifier is linked to this channel subscription. When present, clientIdclient_id is never present
Type: String

clientIdclient_id: devices with this client identifier are included in this channel subscription. When present, deviceIddevice_id is never present
Type: String

PushChannelSubscription constructors

PushChannelSubscription.forDevicePushChannelSubscription.for_device

PushChannelSubscription.forDevice(String channel, String deviceId) → PushChannelSubscriptionPushChannelSubscription.for_device(String channel, String device_id) → 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 subscription
Type: String
deviceIddevice_id: the device with this identifier will be linked with this push channel subscription
Type: String

Returns

A PushChannelSubscription object

PushChannelSubscription.forClientPushChannelSubscription.for_client

PushChannelSubscription.forDevice(String channel, String clientId) → PushChannelSubscriptionPushChannelSubscription.for_device(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

channel: channel name linked to this push channel subscription
Type: String
clientIdclient_id: devices with this client identifier are included in the new push channel subscription
Type: String

Returns

A PushChannelSubscription object

PaginatedResultARTPaginatedResultAbly::Models::PaginatedResultio.ably.lib.types.PaginatedResultIO.Ably.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.

PropertiesMembersAttributes

itemsItems: contains the current page of results (for example an Array of Message or PresenceMessage objects for a channel history request)
Type: Array <Message, Presence, Stats>Type: List <Message, Presence, Stats>

Methods

firstFirst

first(callback(ErrorInfo err, PaginatedResult resultPage))PaginatedResult firstPaginatedResult first()PaginatedResult first()Task<PaginatedResult> FirstAsync()PaginatedResult first()first(callback: (ARTPaginatedResult?, ARTErrorInfo?) → Void)First() (PaginatedResult, error)

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.The method is asynchronous and returns a Task which needs to be awaited to get the PaginatedResult.

hasNextHasNexthas_next?has_next

Boolean hasNext()Boolean has_next?Boolean hasNext()Boolean has_next()Boolean HasNext()Boolean hasNext()Boolean hasNext()HasNext() (bool)

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

isLastIsLastlast?is_last

Boolean isLast()Boolean last?Boolean isLast()Boolean is_last()Boolean IsLast()Boolean isLast()Boolean isLast()IsLast() (bool)

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

nextNext

next(callback(ErrorInfo err, PaginatedResult resultPage))PaginatedResult nextPaginatedResult next()PaginatedResult next()Task<PaginatedResult> NextAsync()PaginatedResult next()next(callback: (ARTPaginatedResult?, ARTErrorInfo?) → Void)Next() (PaginatedResult, error)

Returns a new PaginatedResult loaded with the next page of results. If there are no further pages, then nulla blank PaginatedResult will be returnedNullNonenil is returned. The method is asynchronous and return a Task which needs to be awaited to get the PaginatedResultWhen using the Realtime library, the first method returns a Deferrable and yields a PaginatedResult.

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());
  });
});

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());
  });
});

PaginatedResult firstPage = channel.history();
System.out.println("Page 0 item 0:" + firstPage.items[0].data);
if (firstPage.hasNext) {
  PaginatedResult nextPage = firstPage.next();
  System.out.println("Page 1 item 1:" + nextPage.items[1].data);
  System.out.println("More pages?:" + Strong.valueOf(nextPage.hasNext()));
};

PaginatedResult firstPage = channel.history();
System.out.println("Page 0 item 0:" + firstPage.items[0].data);
if (firstPage.hasNext) {
  PaginatedResult nextPage = firstPage.next();
  System.out.println("Page 1 item 1:" + nextPage.items[1].data);
  System.out.println("More pages?:" + Strong.valueOf(nextPage.hasNext()));
};

PaginatedResult<Message> firstPage = await channel.HistoryAsync(null);
Message firstMessage = firstPage.Items[0];
Console.WriteLine("Page 0 item 0: " + firstMessage.data);
if (firstPage.HasNext)
{
    var nextPage = await firstPage.NextAsync();
    Console.WriteLine("Page 1 item 1:" + nextPage.Items[1].data);
    Console.WriteLine("More pages?: " + nextPage.HasNext());
}

# 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

result_page = channel.history()
print 'Page 0 item 0: ' + str(result_page.items[0].data)
if result_page.has_next():
  next_page = result_page.next()
  print 'Page 1 item 1: ' + str(next_page.items[1].data)
  print 'Last page?: ' + str(next_page.is_last())

$firstPage = $channel.history();
echo("Page 0 item 0: " . $firstPage->items[0]->data);
if ($firstPage->hasNext()) {
  $nextPage = $firstPage->next();
  echo("Page 1 item 1: " . $nextPage->items[1]->data);
  echo("Last page?: " . $nextPage->isLast());
}

[channel history:^(ARTPaginatedResult<ARTMessage *> *paginatedResult, ARTErrorInfo *error) {
    NSLog(@"Page 0 item 0: %@", paginatedResult.items[0].data);
    [paginatedResult next:^(ARTPaginatedResult<ARTMessage *> *nextPage, ARTErrorInfo *error) {
        NSLog(@"Page 1 item 1: %@", nextPage.items[1].data);
        NSLog(@"Last page?: %d", nextPage.isLast());
    }];
}];

channel.history { paginatedResult, error in
    let paginatedResult = paginatedResult!
    print("Page 0 item 0: \((paginatedResult.items[0] as! ARTMessage).data)")
    paginatedResult.next { nextPage, error in
        let nextPage = nextPage!
        print("Page 1 item 1: \((nextPage.items[1] as! ARTMessage).data)")
        print("Last page? \(nextPage.isLast())")
    }
}

page0, err := channel.History(nil)
fmt.Println("Page. 0 item 0: %s\n", page0.Messages[0].Data)
page1, err := page0.Next()
fmt.Println("Page. 1 item 1: %s\n", page1.Messages[1].Data)
fmt.Println("Last page? %s\n", page1.IsLast())

The Ably Platform

Our features

Our technology

By use case

Why companies choose Ably

Four pillars of dependability

Blog

Documentation

Explore

Quick links

Push Notifications - Device Activation and Subscription

Push Device object

Methods

activate

deactivate

Related types

DeviceDetailsAbly::Models::DeviceDetailsARTDeviceDetails

PropertiesMembersAttributes

LocalDeviceAbly::Models::LocalDevice

PropertiesMembersAttributes

PushChannelAbly::Models::PushChannel

subscribeDevice

subscribeClient

unsubscribeDevice

unsubscribeClient

listSubscriptions

Parameters

Callback result

Returns

PushChannelSubscriptionAbly::Models::PushChannelSubscriptionChannelSubscriptionArtPushChannelSubscription

PropertiesMembersAttributes

PushChannelSubscription constructors

PushChannelSubscription.forDevicePushChannelSubscription.for_device

Parameters

Returns

PushChannelSubscription.forClientPushChannelSubscription.for_client

Parameters

Returns

PaginatedResultARTPaginatedResultAbly::Models::PaginatedResultio.ably.lib.types.PaginatedResultIO.Ably.PaginatedResult

PropertiesMembersAttributes

Methods

firstFirst

hasNextHasNexthas_next?has_next

isLastIsLastlast?is_last

nextNext

Example