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

Push Notifications - Device Activation and Subscription

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

subscribeDevice()

Subscribe your device to the channel’s push notifications.

subscribeClient

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

Need help?

If you need any help with your implementation or if you have encountered any problems, do get in touch. You can also quickly find answers from our knowledge base, and blog.

Support & Help Contact Us
Talk to our technical team

If you're having technical or account issues just get in touch.

Don’t want to chat? Get in touch via our contact page

Try our APIs for free

Our free plan includes

  • 6m messages per month
  • 200 peak connections
  • 200 peak channels
  • Loads of features
Start building