Realtime client

The device package uses a realtime client to establish a persistent connection with Ably. The createClient function is the entry point for using the Ably Pub/Sub JavaScript SDK in code that runs on an end user's device, such as a browser, or a React Native, Electron, mobile or desktop app.

import { createClient } from '@ably/pubsub-device';

const pubsubDeviceClient = createClient({
  authCallback: async (tokenParams, callback) => {
    try {
      // Request an Ably-compatible JWT from your own server
      const response = await fetch('https://your-server.example.com/ably-jwt');
      const jwt = await response.text();
      callback(null, jwt);
    } catch (error) {
      callback(error, null);
    }
  },
});

This example uses token authentication: the authCallback requests an Ably-compatible JWT from your server whenever a token is needed, which keeps your API key off the device. A backend service that needs a persistent connection to Ably can create a realtime client on a server instead.

Properties

The realtime client has the following properties, whether it was created on a device or on a server:

The Crypto, Message, PresenceMessage and Annotation helpers are not properties of the client. Import them by name from the package that created the client.

Create a device client

Use createClient() from the @ably/pubsub-device package to create a client that runs on an end user's device.

On an account billed by monthly active users, a device connection must carry a client ID, either set in clientId or carried by the token it authenticates with. Ably rejects a device connection without one at connect.

Create a client with a ClientOptions object. This is the most common form, allowing all available client options to be configured.

A convenience form that takes a single API key or token string. Equivalent to passing { key: '<key>' } or { token: '<token>' } as ClientOptions. Useful for test setups.

The following example creates a device client:

import { createClient } from '@ably/pubsub-device';

const pubsubDeviceClient = createClient({
  authUrl: '/auth',
  clientId: 'user-123',
  logLevel: 3
});

Parameters

createClient() takes the following parameters:

Create a realtime client on a server

If your server requires a persistent connection to Ably, for example to subscribe to channels or enter presence, then you can create a realtime client using createRealtimeClient().

Use createRealtimeClient() from the @ably/pubsub-server package to create the realtime client in a backend service that you operate. It returns a PubSubRealtimeClient, the same client that createClient() from the device package returns under its PubSubClient alias, so every property and method in this section applies to it. Never use the @ably/pubsub-server package in code that runs on an end user's device.

The following example creates a realtime client in a backend service:

import { createRealtimeClient } from '@ably/pubsub-server';

const pubsubRealtimeClient = createRealtimeClient({ key: process.env.ABLY_API_KEY });

Parameters

createRealtimeClient() takes the following parameters:

Open the connection

Calls connection.connect(), explicitly initiating the connection if clientOptions.autoConnect was set to false.

pubsubDeviceClient.connect();

Close the connection

Calls connection.close(), causing the connection to close and entering the closing state. Once closed, the SDK will not attempt to reconnect.

pubsubDeviceClient.close();

Get server time

Returns the time from the Ably service as milliseconds since the Unix epoch. Clients that do not have access to a sufficiently well-maintained time source and wish to issue Ably TokenRequests with a more accurate timestamp should use the clientOptions.queryTime client option instead of this method.

const now = await pubsubDeviceClient.time();

Returns

Promise<number>

Returns a promise. The promise is fulfilled with the server time as milliseconds since the Unix epoch, or rejected with an ErrorInfo object.

Get account stats

Retrieves usage statistics for the account, filtered by the supplied query parameters. Returns a paginated set of Stats objects, each containing usage metrics.

const page = await pubsubDeviceClient.stats({ unit: 'hour', limit: 24 });

Parameters

The stats() method takes the following parameters:

Returns

Promise<PaginatedResult<Stats>>

Returns a promise. The promise is fulfilled with a PaginatedResult of Stats objects, or rejected with an ErrorInfo object.

Stats

Each Stats entry contains the following properties:

Make a REST request

Makes a REST request to a provided path. Useful for accessing Ably APIs that do not have a dedicated method in the SDK, without having to handle authentication, paging, fallback hosts, and MsgPack or JSON support yourself.

const response = await pubsubDeviceClient.request(
  'GET',
  '/channels/arc-one-ego/messages',
  3,
  { limit: 10 }
);

Parameters

The request() method takes the following parameters:

Returns

Promise<HttpPaginatedResponse>

Returns a promise. The promise is fulfilled with an HttpPaginatedResponse, or rejected with an ErrorInfo object. Note that if a response is obtained, any response, even one with a non-2xx status code, resolves as an HttpPaginatedResponse rather than rejecting.

HttpPaginatedResponse

HttpPaginatedResponse contains the following properties:

HttpPaginatedResponse also contains the following methods to handle pagination:

Check for more pages

Returns true if there are more pages available by calling next().

Check if last page

Returns true if this is the last page of results.

Get next page

Returns a promise. The promise is fulfilled with the next page of results as a PaginatedResult, or null if there are no more pages. Rejected with an ErrorInfo object on failure.

Get first page

Returns a promise. The promise is fulfilled with the first page of results as a PaginatedResult, or rejected with an ErrorInfo object.

Get current page

Returns a promise. The promise is fulfilled with the current page of results as a PaginatedResult, or rejected with an ErrorInfo object.

Batch publish to multiple channels

Publish using a single BatchPublishSpec, fulfilled with a single BatchResult.

Publish using an array of BatchPublishSpec objects, fulfilled with one BatchResult per spec.

Each spec publishes one or more messages to up to 100 channels in a single batch publish request.

const result = await pubsubDeviceClient.batchPublish({
  channels: ['channel1', 'channel2'],
  messages: [{ name: 'event', data: 'hello' }]
});

Parameters

The batchPublish() method takes the following parameters:

Returns

Promise<BatchResult | BatchResult[]>

Returns a promise. For a single spec, the promise is fulfilled with a BatchResult. For an array of specs, the promise is fulfilled with an array of BatchResults. Rejected with an ErrorInfo object on failure.

Batch presence query

Retrieves the presence set for up to 100 channels in a single REST request. The presence state includes the clientId of members and their current PresenceAction.

Parameters

The batchPresence() method takes the following parameters:

Returns

Promise<BatchResult[]>

Returns a promise. The promise is fulfilled with an array of BatchResult objects, one per channel, where each results entry is a BatchPresenceSuccessResult or a BatchPresenceFailureResult. Rejected with an ErrorInfo object on failure.

Get the local device

Retrieves a LocalDevice object representing the current device as a push notification target, loading its state from persistent storage if necessary.

Returns

Promise<LocalDevice>

Returns a promise. The promise is fulfilled with the LocalDevice, or rejected with an ErrorInfo object.

PaginatedResult

A PaginatedResult represents a page of results from a paginated query such as stats(), channel.history(), presence.history(), or channel.getMessageVersions().

Properties

PaginatedResult contains the following properties:

PaginatedResult also contains the following methods to handle pagination:

Check for more pages

Returns true if there are more pages available.

Check if last page

Returns true if this is the last page of results.

Get next page

Returns a promise fulfilled with the next page of results, or null if there are no more pages. Rejected with an ErrorInfo object on failure.

Get first page

Returns a promise fulfilled with the first page of results, or rejected with an ErrorInfo object.

Get current page

Returns a promise fulfilled with the current page of results, or rejected with an ErrorInfo object.

ErrorInfo

A standardized, generic Ably error object that contains an Ably-specific error code, a generic HTTP status code, and a human-readable message. All errors emitted by Ably are ErrorInfo instances.