# Push Notifications - Device Activation and Subscription

## Push Device object 

This object is accessible through `client.push` and provides to [push-compatible devices](https://ably.com/docs/push.md) :

### Methods

#### activate 

<If lang="javascript,nodejs">

`activate(registerCallback?(DeviceDetails device, callback(ErrorInfo | null err, DeviceDetails result)), updateFailedCallback?(ErrorInfo | null err)): Promise<void>`

</If>
<If lang="java">

`void activate()`

</If>
<If lang="objc,swift">

`activate(callback: (ARTErrorInfo?, DeviceDetails?) -> Void)`

</If>

<If lang="java,objc,swift">

Register the device for push. When the [activation process](https://ably.com/docs/push/configure/device.md#activate-devices) is completed, Ably will <If lang="java">send a broadcast through the application's [`LocalBroadcastManager`](https://developer.android.com/reference/android/support/v4/content/LocalBroadcastManager). Success or failure will be broadcast through `io.ably.broadcast.PUSH_ACTIVATE`</If><If lang="objc,swift">call the </If><If lang="objc">`(void)didActivateAblyPush:(nullable ARTErrorInfo *)error`</If><If lang="swift">`didActivateAblyPush(error: ARTErrorInfo?)`</If><If lang="objc,swift"> method from the `ARTPushRegistererDelegate`</If>.

</If>
<If lang="javascript,nodejs">

[Activates the device](https://ably.com/docs/push/configure/web.md#activate-browsers) for push notifications. Subsequently registers the device with Ably and stores the `deviceIdentityToken` in local storage.

##### Parameters

| Parameter | Description | Type |
|-----------|-------------|------|
| registerCallback | An optional function passed to override the default implementation to register the local device for push activation | `Callable` |
| updateFailedCallback | An optional callback to be invoked when the device registration failed to update | `Callable` |

##### Returns

Returns a promise. On successful device activation, the promise resolves. On failure, the promise is rejected with an [`ErrorInfo`](#error-info) object that details the reason why it was rejected.

</If>

#### deactivate 

<If lang="javascript,nodejs">

`deactivate(deregisterCallback?(DeviceDetails device, callback(ErrorInfo | null err, String result))): Promise<void>`

</If>
<If lang="java">

`void deactivate()`

</If>
<If lang="objc,swift">

`deactivate(deregisterCallback: (ARTErrorInfo?, deviceId: String?) -> Void)`

</If>

<If lang="java,objc,swift">

Deregister the device for push. When the deactivation process is completed, Ably will <If lang="java">send a broadcast through the application's [`LocalBroadcastManager`](https://developer.android.com/reference/android/support/v4/content/LocalBroadcastManager). Success or failure will be broadcast through `io.ably.broadcast.PUSH_DEACTIVATE`</If><If lang="objc,swift">call the </If><If lang="objc">`(void)didDeactivateAblyPush:(nullable ARTErrorInfo *)error`</If><If lang="swift">`didDeactivateAblyPush(error: ARTErrorInfo?)`</If><If lang="objc,swift"> method from the `ARTPushRegistererDelegate`</If>.

</If>
<If lang="javascript,nodejs">

Deactivates the device from receiving push notifications.

##### Parameters

| Parameter | Description | Type |
|-----------|-------------|------|
| `deregisterCallback` | An optional function passed to override the default implementation to deregister the local device for push activation | `Callable` |

##### Returns

Returns a promise. On successful device deactivation, the promise resolves. On failure, the promise is rejected with an [`ErrorInfo`](#error-info) object that details the reason why it was rejected.

</If>

<If lang="objc,swift">

## Location push notifications 

Starting with iOS 15, Apple supports a power-efficient way to request location through the location push service extension.

The following table explains how to receive location push notifications:

| Action | Details |
|--------|---------|
| Request location token | Call `CLLocationManager.startMonitoringLocationPushes(completion:)` within the `ARTPushRegistererDelegate.didActivateAblyPush(:)` delegate method. This delegate method is the callback for `ARTRealtime.push.activate()`. |
| Register with Ably | Call `ARTPush.didRegisterForLocationNotifications(withDeviceToken:realtime:)` when you receive the location push token. Note the "Location" in the method name to distinguish it from regular push tokens. |
| Handle result | Use the `ARTPushRegistererDelegate.didUpdateAblyPush:` callback, which indicates whether the token was successfully saved. |

</If>

## Related types 

### <If lang="javascript,nodejs,java">DeviceDetails</If><If lang="objc,swift">ARTDeviceDetails</If> 

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

#### <If lang="javascript,nodejs,objc,swift">Properties</If><If lang="java">Members</If>

| Property | Description | Type |
|----------|-------------|------|
| id | Unique identifier for the device generated by the device itself | `String` |
| clientId | Optional trusted [client identifier](https://ably.com/docs/auth/identified-clients.md) for the device | `String` |
| formFactor | Form factor of the push device. Must be one of `phone`, `tablet`, `desktop`, `tv`, `watch`, `car` <If lang="java,objc,swift">or `embedded`</If><If lang="javascript,nodejs">`embedded` or `other`</If> | `String` |
| metadata | Optional metadata object for this device. The metadata for a device may only be set by clients with `push-admin` privileges | `Object` |
| platform | Platform of the push device. Must be one of `ios` <If lang="java,objc,swift">or `android`</If><If lang="javascript,nodejs">`android` or `browser`</If> | `String` |
| deviceSecret | Secret value for the device | `String` |
| push.recipient | Push recipient details for this device. See the [REST API push publish documentation](https://ably.com/docs/api/rest-api.md#message-extras-push) for more details | `Object` |
| push.state | The current state of the push device being either <If lang="java,objc,swift">`Active`, `Failing` or `Failed`</If><If lang="javascript,nodejs">`ACTIVE`, `FAILING` or `FAILED`</If> | `String` |
| <If lang="java,objc,swift">push.errorReason</If><If lang="javascript,nodejs">push.error</If> | When the device's state is failing or failed, this attribute contains the reason for the most recent failure | [`ErrorInfo`](https://ably.com/docs/api/realtime-sdk/types.md#error-info) |

### LocalDevice 

<If lang="java,objc,swift">

An extension of [`DeviceDetails`](#device-details). In addition to the <If lang="java">members</If><If lang="objc,swift">properties</If> of [`DeviceDetails`](#device-details), it includes the following:

</If>

<If lang="javascript,nodejs">

Contains the device identity token and secret of a device.

</If>

#### <If lang="javascript,nodejs,objc,swift">Properties</If><If lang="java">Members</If>

<If lang="javascript,nodejs,java">

| Property | Description | Type |
|----------|-------------|------|
| id | A unique ID generated by the device | `String` |
| deviceSecret | A unique device secret generated by the Ably SDK | `String` |
| deviceIdentityToken | A unique identity token for the device | `String` |

</If>
<If lang="objc,swift">

| Property | Description | Type |
|----------|-------------|------|
| deviceIdentityToken | A unique identity token for the device | `String` |

</If>
<If lang="javascript,nodejs">

#### Methods

#####  listSubscriptions

`listSubscriptions(): Promise&lt;PaginatedResult&lt;PushChannelSubscription&gt;&gt;`

Retrieves push subscriptions active for the local device.

##### Returns

Returns a promise. On success, the promise is fulfilled with a [PaginatedResult](https://ably.com/docs/api/realtime-sdk/types.md#paginated-result) object containing an array of [PushChannelSubscription](https://ably.com/docs/api/realtime-sdk/types.md#push-channel-subscription) objects for each push channel subscription active for the local device. On failure, the promise is rejected with an [`ErrorInfo`](#error-info) object that details the reason why it was rejected.

</If>

### PushChannel 

A `PushChannel` is a property of a [`RealtimeChannel`](https://ably.com/docs/api/realtime-sdk/channels.md#properties) or [`RestChannel`](https://ably.com/docs/api/rest-sdk/channels.md#properties). It provides [push devices](https://ably.com/docs/push.md) the ability to subscribe and unsubscribe to push notifications on channels.

#### Methods

##### subscribeDevice 

<If lang="javascript,nodejs">

`subscribeDevice(): Promise<void>`

</If>
<If lang="java,objc,swift">

`subscribeDevice()`

</If>

Subscribe your device to the channel's push notifications.

<If lang="javascript,nodejs">

##### Returns

Returns a promise. On success, the promise resolves. On failure, the promise is rejected with an [`ErrorInfo`](https://ably.com/docs/api/realtime-sdk/types.md#error-info) object that details the reason why it was rejected.

</If>

#### subscribeClient 

<If lang="javascript,nodejs">

`subscribeClient(): Promise<void>`

</If>
<If lang="java,objc,swift">

`subscribeClient()`

</If>

[Subscribe all devices associated with your device's clientId](https://ably.com/docs/push/publish.md#sub-channels) to the channel's push notifications.

<If lang="javascript,nodejs">

##### Returns

Returns a promise. On success, the promise resolves. On failure, the promise is rejected with an [`ErrorInfo`](https://ably.com/docs/api/realtime-sdk/types.md#error-info) object that details the reason why it was rejected.

</If>

#### unsubscribeDevice 

<If lang="javascript,nodejs">

`unsubscribeDevice(): Promise<void>`

</If>
<If lang="java,objc,swift">

`unsubscribeDevice()`

</If>

Unsubscribe your device from the channel's push notifications.

<If lang="javascript,nodejs">

##### Returns

Returns a promise. On success, the promise resolves. On failure, the promise is rejected with an [`ErrorInfo`](https://ably.com/docs/api/realtime-sdk/types.md#error-info) object that details the reason why it was rejected.

</If>

#### unsubscribeClient 

<If lang="javascript,nodejs">

`unsubscribeClient(): Promise<void>`

</If>
<If lang="java,objc,swift">

`unsubscribeClient()`

</If>

[Unsubscribe all devices associated with your device's clientId](https://ably.com/docs/push/publish.md#sub-channels) from the channel's push notifications.

<If lang="javascript,nodejs">

##### Returns

Returns a promise. On success, the promise resolves. On failure, the promise is rejected with an [`ErrorInfo`](https://ably.com/docs/api/realtime-sdk/types.md#error-info) object that details the reason why it was rejected.

</If>

#### listSubscriptions 

<If lang="javascript,nodejs">

`listSubscriptions(Record<string, string> params?): Promise<PaginatedResult<PushChannelSubscription>>`

</If>
<If lang="java">

`PaginatedResult<PushChannelSubscription> listSubscriptions(String deviceId, String clientId, String deviceClientId, String channel)`

</If>
<If lang="objc,swift">

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

</If>

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](push#push-admin). For more information, see `GET main.realtime.ably.net/push/channelSubscriptions` [Rest API](https://ably.com/docs/api/rest-api.md).

##### Parameters

<If lang="javascript,nodejs">

| Parameter | Description | Type |
|-----------|-------------|------|
| deviceId | A deviceId to filter by | `String` |
| clientId | A clientId to filter by | `String` |
| deviceClientId | A client ID associated with a device to filter by | `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,000 | `Record<string, string>` |

</If>

<If lang="java">

| Parameter | Description | Type |
|-----------|-------------|------|
| deviceId | A deviceId to filter by | `String` |
| clientId | A clientId to filter by | `String` |
| deviceClientId | A client ID associated with a device to filter by | `String` |

</If>

<If lang="objc,swift">

| Parameter | Description | Type |
|-----------|-------------|------|
| deviceId | A deviceId to filter by | `String` |
| clientId | A clientId to filter by | `String` |
| deviceClientId | A client ID associated with a device to filter by | `String` |
| callback | Called with a [`ARTPaginatedResult`](#paginated-result) object containing [`PushChannelSubscription`](https://ably.com/docs/api/realtime-sdk/push-admin.md#push-channel-subscription) objects or an error | Callback |

</If>

<If lang="javascript,nodejs">

##### Returns

Returns a promise. On success, the promise is fulfilled with [`PaginatedResult`](#paginated-result) which encapsulates an array of "PushChannelSubscription":#push-channel-subscription objects corresponding to the current page of results. [`PaginatedResult`](#paginated-result) supports pagination using [`next`](#paginated-result) and [`first`](#paginated-result) methods. On failure, the promise is rejected with an [`ErrorInfo`](https://ably.com/docs/api/realtime-sdk/types.md#error-info) object that details the reason why it was rejected.

</If>
<If lang="objc,swift">

##### Callback result

On success, `resultPage` contains a [`PaginatedResult`](#paginated-result) encapsulating an array of [PushChannelSubscription](https://ably.com/docs/api/realtime-sdk/push-admin.md#push-channel-subscription) objects corresponding to the current page of results. [`PaginatedResult`](#paginated-result) supports pagination using [`next()`](#paginated-result) and [`first()`](#paginated-result) methods.

On failure to retrieve message history, `err` contains an [`ErrorInfo`](https://ably.com/docs/api/realtime-sdk/types.md#error-info) object with the failure reason.

</If>
<If lang="java">

##### Returns

On success, the returned [`PaginatedResult`](#paginated-result) encapsulates an array of [PushChannelSubscription](#push-channel-subscription) objects corresponding to the current page of results. [`PaginatedResult`](#paginated-result) supports pagination using [`next`](#paginated-result) and [`first`](#paginated-result) methods.

Failure to retrieve the message history will raise an [`AblyException`](https://ably.com/docs/api/realtime-sdk/types.md#ably-exception)

</If>

### <If lang="javascript,nodejs">PushChannelSubscription</If><If lang="java">ChannelSubscription</If><If lang="objc,swift">ARTPushChannelSubscription</If> 

A `PushChannelSubscription` is a type encapsulating the subscription of a device or group of devices sharing a [client identifier](https://ably.com/docs/auth/identified-clients.md) to a channel in order to receive push notifications.

#### <If lang="javascript,nodejs,objc,swift">Properties</If><If lang="java">Members</If>

| Property | Description | Type |
|----------|-------------|------|
| channel | The channel that this push notification subscription is associated with | `String` |
| deviceId | The device with this identifier is linked to this channel subscription. When present, `clientId` is never present | `String` |
| clientId | Devices with this [client identifier](https://ably.com/docs/auth/identified-clients.md) are included in this channel subscription. When present, `deviceId` is never present | `String` |

<If lang="java,objc,swift">

### PushChannelSubscription constructors

#### PushChannelSubscription.forDevice 

`PushChannelSubscription.forDevice(String channel, String deviceId) -> PushChannelSubscription`

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

##### Parameters

| Parameter | Description | Type |
|-----------|-------------|------|
| channel | Channel name linked to this push channel subscription | `String` |
| deviceId | The device with this identifier will be linked with this push channel subscription | `String` |

##### Returns

A [`PushChannelSubscription`](https://ably.com/docs/api/realtime-sdk/types.md#push-channel-subscription) object

#### PushChannelSubscription.forClient 

`PushChannelSubscription.forClient(String channel, String clientId) -> PushChannelSubscription`

A static factory method to create a `PushChannelSubscription` object for a channel and group of devices sharing a [client identifier](https://ably.com/docs/auth/identified-clients.md).

##### Parameters

| Parameter | Description | Type |
|-----------|-------------|------|
| channel | Channel name linked to this push channel subscription | `String` |
| clientId | Devices with this [client identifier](https://ably.com/docs/auth/identified-clients.md) are included in the new push channel subscription | `String` |

##### Returns

A `PushChannelSubscription` object

</If>

### <If lang="javascript,nodejs">PaginatedResult</If><If lang="objc,swift">ARTPaginatedResult</If><If lang="java">io.ably.lib.types.PaginatedResult</If> 

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 an [Ably REST API paginated query](https://ably.com/docs/api/rest-api.md#pagination) is accompanied by metadata that indicates the relative queries available to the `PaginatedResult` object.

#### <If lang="javascript,nodejs,objc,swift">Properties</If><If lang="java">Members</If>

| Property | Description | Type |
|----------|-------------|------|
| items | Contains the current page of results (for example an Array of [`Message`](#message) or [`PresenceMessage`](#presence-message) objects for a channel history request) | `Array <Message, Presence, Stats>` |

#### Methods

##### first

<If lang="javascript,nodejs">

`first(): Promise<PaginatedResult>`

</If>
<If lang="java">

`PaginatedResult first()`

</If>
<If lang="objc,swift">

`first(callback: (ARTPaginatedResult?, ARTErrorInfo?) -> Void)`

</If>

<If lang="java,objc,swift">

Returns a new `PaginatedResult` for the first page of results.

</If>
<If lang="javascript,nodejs">

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`](https://ably.com/docs/api/realtime-sdk/types.md#error-info) object that details the reason why it was rejected.

</If>

##### hasNext

<If lang="javascript,nodejs">

`Boolean hasNext()`

</If>
<If lang="java">

`Boolean hasNext()`

</If>
<If lang="objc,swift">

`Boolean hasNext()`

</If>

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

##### next 

<If lang="javascript,nodejs">

`next(): Promise<PaginatedResult | null>`

</If>
<If lang="java">

`PaginatedResult next()`

</If>
<If lang="objc,swift">

`next(callback: (ARTPaginatedResult?, ARTErrorInfo?) -> Void)`

</If>

<If lang="java,objc,swift">

Returns a new `PaginatedResult` loaded with the next page of results. If there are no further pages, then <If lang="javascript,nodejs">`null`</If><If lang="java">`Null`</If><If lang="objc,swift">`nil`</If> is returned.

</If>
<If lang="javascript,nodejs">

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`](https://ably.com/docs/api/realtime-sdk/types.md#error-info) 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`](https://ably.com/docs/api/realtime-sdk/types.md#error-info) object that details the reason why it was rejected.

</If>

##### Example 

<If lang="javascript">

<Code>

###### Javascript

```
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());
```
</Code>

</If>
<If lang="nodejs">

<Code>

###### Nodejs

```
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());
```
</Code>

</If>
<If lang="java">

<Code>

###### Java

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

</If>
<If lang="objc">

<Code>

###### Objc

```
[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());
    }];
}];
```
</Code>

</If>
<If lang="swift">

<Code>

###### Swift

```
channel.history { paginatedResult, error in
    guard let paginatedResult = paginatedResult else {
        print("No results available")
        return
    }
    print("Page 0 item 0: \((paginatedResult.items[0] as! ARTMessage).data)")
    paginatedResult.next { nextPage, error in
        guard let nextPage = nextPage else {
            print("No next page available")
            return
        }
        print("Page 1 item 1: \((nextPage.items[1] as! ARTMessage).data)")
        print("Last page? \(nextPage.isLast())")
    }
}
```
</Code>

</If>