From fef83c4d1959897ac4c6ad2c90139d67174626f3 Mon Sep 17 00:00:00 2001 From: Mark Hulbert <39801222+m-hulbert@users.noreply.github.com> Date: Mon, 27 Jul 2026 17:18:01 +0100 Subject: [PATCH 1/7] Add JavaScript migration banners to legacy Pub/Sub API reference pages Each legacy multi-language API reference page now carries an Aside pointing JavaScript and Node.js readers at the equivalent page of the new dedicated JavaScript API reference. Co-Authored-By: Claude Fable 5 --- src/pages/docs/api/realtime-sdk.mdx | 4 ++++ src/pages/docs/api/realtime-sdk/authentication.mdx | 4 ++++ src/pages/docs/api/realtime-sdk/channel-metadata.mdx | 4 ++++ src/pages/docs/api/realtime-sdk/channels.mdx | 4 ++++ src/pages/docs/api/realtime-sdk/connection.mdx | 4 ++++ src/pages/docs/api/realtime-sdk/encryption.mdx | 4 ++++ src/pages/docs/api/realtime-sdk/history.mdx | 4 ++++ src/pages/docs/api/realtime-sdk/messages.mdx | 4 ++++ src/pages/docs/api/realtime-sdk/presence.mdx | 4 ++++ src/pages/docs/api/realtime-sdk/push-admin.mdx | 4 ++++ src/pages/docs/api/realtime-sdk/push.mdx | 4 ++++ src/pages/docs/api/realtime-sdk/statistics.mdx | 4 ++++ src/pages/docs/api/realtime-sdk/types.mdx | 4 ++++ src/pages/docs/api/rest-sdk.mdx | 4 ++++ src/pages/docs/api/rest-sdk/authentication.mdx | 4 ++++ src/pages/docs/api/rest-sdk/channel-status.mdx | 4 ++++ src/pages/docs/api/rest-sdk/channels.mdx | 4 ++++ src/pages/docs/api/rest-sdk/encryption.mdx | 4 ++++ src/pages/docs/api/rest-sdk/history.mdx | 4 ++++ src/pages/docs/api/rest-sdk/messages.mdx | 4 ++++ src/pages/docs/api/rest-sdk/presence.mdx | 4 ++++ src/pages/docs/api/rest-sdk/push-admin.mdx | 4 ++++ src/pages/docs/api/rest-sdk/statistics.mdx | 4 ++++ src/pages/docs/api/rest-sdk/types.mdx | 4 ++++ 24 files changed, 96 insertions(+) diff --git a/src/pages/docs/api/realtime-sdk.mdx b/src/pages/docs/api/realtime-sdk.mdx index ced986c9d7..7f3e1278f1 100644 --- a/src/pages/docs/api/realtime-sdk.mdx +++ b/src/pages/docs/api/realtime-sdk.mdx @@ -8,6 +8,10 @@ redirect_from: - /docs/api/versions/v0.8/realtime-sdk --- + + ## Constructor The Ably Realtime library constructor is overloaded allowing it to be instantiated using a [`ClientOptions`](#client-options) object, or more simply using a string containing an [API key](/docs/auth/basic) or [Token](/docs/auth/token), as shown below: diff --git a/src/pages/docs/api/realtime-sdk/authentication.mdx b/src/pages/docs/api/realtime-sdk/authentication.mdx index 9bafb6dcb6..2c846bad21 100644 --- a/src/pages/docs/api/realtime-sdk/authentication.mdx +++ b/src/pages/docs/api/realtime-sdk/authentication.mdx @@ -21,6 +21,10 @@ redirect_from: - /docs/api/versions/v0.8/realtime-sdk/authentication --- + + This is the Authentication API Reference. ## Tokens diff --git a/src/pages/docs/api/realtime-sdk/channel-metadata.mdx b/src/pages/docs/api/realtime-sdk/channel-metadata.mdx index 21b1c418a9..82afc8a541 100644 --- a/src/pages/docs/api/realtime-sdk/channel-metadata.mdx +++ b/src/pages/docs/api/realtime-sdk/channel-metadata.mdx @@ -7,6 +7,10 @@ redirect_from: - /docs/api/versions/v1.0/realtime-sdk/channel-metadata --- + + ## Types The payload of metadata events for channels is the [`ChannelDetails`](#channel-details) type which contains the `channelId` and other static information about the channel, plus a `status` containing a [`ChannelStatus`](#channel-status) instance which contains information about the current state of the channel. diff --git a/src/pages/docs/api/realtime-sdk/channels.mdx b/src/pages/docs/api/realtime-sdk/channels.mdx index 4b296ac968..87787b1546 100644 --- a/src/pages/docs/api/realtime-sdk/channels.mdx +++ b/src/pages/docs/api/realtime-sdk/channels.mdx @@ -8,6 +8,10 @@ redirect_from: - /docs/api/versions/v0.8/realtime-sdk/channels --- + + ## Channels The `Channels` object, accessed from the [realtime library client constructor](/docs/api/realtime-sdk#channels), is used to create and destroy `Channel` objects. It exposes the following public methods: diff --git a/src/pages/docs/api/realtime-sdk/connection.mdx b/src/pages/docs/api/realtime-sdk/connection.mdx index 249b58eb45..f454263760 100644 --- a/src/pages/docs/api/realtime-sdk/connection.mdx +++ b/src/pages/docs/api/realtime-sdk/connection.mdx @@ -8,6 +8,10 @@ redirect_from: - /docs/api/versions/v0.8/realtime-sdk/connection --- + + ## Connection PropertiesARTConnection PropertiesAbly::Realtime::Connection Attributesio.ably.lib.realtime.Connection MembersIO.Ably.Realtime.Connection Properties The `Connection` object exposes the following public propertiesattributesmembers: diff --git a/src/pages/docs/api/realtime-sdk/encryption.mdx b/src/pages/docs/api/realtime-sdk/encryption.mdx index 0fd6a9fb8a..0df9000cde 100644 --- a/src/pages/docs/api/realtime-sdk/encryption.mdx +++ b/src/pages/docs/api/realtime-sdk/encryption.mdx @@ -15,6 +15,10 @@ redirect_from: - /docs/api/versions/v0.8/realtime-sdk/encryption --- + + The `Ably.Realtime.Crypto``Ably::Util::Crypto``io.ably.lib.util.Crypto``ARTCrypto` object exposes the following public methods: ## Methods diff --git a/src/pages/docs/api/realtime-sdk/history.mdx b/src/pages/docs/api/realtime-sdk/history.mdx index c10251d998..ba058e88d3 100644 --- a/src/pages/docs/api/realtime-sdk/history.mdx +++ b/src/pages/docs/api/realtime-sdk/history.mdx @@ -14,6 +14,10 @@ redirect_from: - /docs/api/versions/v0.8/realtime-sdk/history --- + + ## Channel object The [Realtime `Channel` object](/docs/channels) exposes the following public method to obtain [`Message`](#message) history. diff --git a/src/pages/docs/api/realtime-sdk/messages.mdx b/src/pages/docs/api/realtime-sdk/messages.mdx index e69f0802a8..e1cebd93c9 100644 --- a/src/pages/docs/api/realtime-sdk/messages.mdx +++ b/src/pages/docs/api/realtime-sdk/messages.mdx @@ -8,6 +8,10 @@ redirect_from: - /docs/api/versions/v0.8/realtime-sdk/messages --- + + ## PropertiesAttributesMembers A `Message` represents an individual message that is sent to or received from Ably. diff --git a/src/pages/docs/api/realtime-sdk/presence.mdx b/src/pages/docs/api/realtime-sdk/presence.mdx index 7ca394db05..e58fb64b67 100644 --- a/src/pages/docs/api/realtime-sdk/presence.mdx +++ b/src/pages/docs/api/realtime-sdk/presence.mdx @@ -24,6 +24,10 @@ redirect_from: - /docs/api/versions/v0.8/realtime-sdk/presence --- + + ## Presence PropertiesARTPresence PropertiesAbly::Realtime::Presence Attributesio.ably.lib.realtime.Presence MembersIO.Ably.Realtime.Presence Properties The `Presence` object exposes the following public propertiesattributesmembers: diff --git a/src/pages/docs/api/realtime-sdk/push-admin.mdx b/src/pages/docs/api/realtime-sdk/push-admin.mdx index 53b8b171dd..900d8e71c5 100644 --- a/src/pages/docs/api/realtime-sdk/push-admin.mdx +++ b/src/pages/docs/api/realtime-sdk/push-admin.mdx @@ -13,6 +13,10 @@ redirect_from: - /docs/api/versions/v1.1/realtime-sdk/push-admin --- + + ## Push Admin object This object is accessible through `client.push.admin` and provides: diff --git a/src/pages/docs/api/realtime-sdk/push.mdx b/src/pages/docs/api/realtime-sdk/push.mdx index 146d6949b0..8a10e9d693 100644 --- a/src/pages/docs/api/realtime-sdk/push.mdx +++ b/src/pages/docs/api/realtime-sdk/push.mdx @@ -12,6 +12,10 @@ redirect_from: - /docs/api/versions/v1.1/realtime-sdk/push --- + + ## Push Device object This object is accessible through `client.push` and provides to [push-compatible devices](/docs/push) : diff --git a/src/pages/docs/api/realtime-sdk/statistics.mdx b/src/pages/docs/api/realtime-sdk/statistics.mdx index 13767ea322..15b55ae575 100644 --- a/src/pages/docs/api/realtime-sdk/statistics.mdx +++ b/src/pages/docs/api/realtime-sdk/statistics.mdx @@ -8,6 +8,10 @@ redirect_from: - /docs/api/versions/v0.8/realtime-sdk/statistics --- + + ## Methods ### stats diff --git a/src/pages/docs/api/realtime-sdk/types.mdx b/src/pages/docs/api/realtime-sdk/types.mdx index ff02153053..0d69a52afb 100644 --- a/src/pages/docs/api/realtime-sdk/types.mdx +++ b/src/pages/docs/api/realtime-sdk/types.mdx @@ -12,6 +12,10 @@ redirect_from: - /docs/realtime/versions/v0.8/types --- + + The Ably client library defines both data types and option types. Data types are used to represent object such as messages. Option types are used in method arguments. Where client libraries support both Realtime and REST APIs, the types are shared between both clients. diff --git a/src/pages/docs/api/rest-sdk.mdx b/src/pages/docs/api/rest-sdk.mdx index 63be1691a8..11e4e5e1cc 100644 --- a/src/pages/docs/api/rest-sdk.mdx +++ b/src/pages/docs/api/rest-sdk.mdx @@ -8,6 +8,10 @@ redirect_from: - /docs/api/versions/v0.8/rest-sdk --- + + ## Constructor The Ably REST library constructor is overloaded allowing it to be instantiated using a [`ClientOptions`](#client-options) object, or more simply using a string containing an [API key](/docs/auth/basic) or [Token](/docs/auth/token). diff --git a/src/pages/docs/api/rest-sdk/authentication.mdx b/src/pages/docs/api/rest-sdk/authentication.mdx index 9f6d09c383..9517366258 100644 --- a/src/pages/docs/api/rest-sdk/authentication.mdx +++ b/src/pages/docs/api/rest-sdk/authentication.mdx @@ -21,6 +21,10 @@ redirect_from: - /docs/api/versions/v0.8/rest-sdk/authentication --- + + This is the Authentication API Reference. ## Tokens diff --git a/src/pages/docs/api/rest-sdk/channel-status.mdx b/src/pages/docs/api/rest-sdk/channel-status.mdx index e085e623b7..39b34a7839 100644 --- a/src/pages/docs/api/rest-sdk/channel-status.mdx +++ b/src/pages/docs/api/rest-sdk/channel-status.mdx @@ -14,6 +14,10 @@ redirect_from: - /docs/api/versions/v1.0/rest-sdk/channel-status --- + + ## Types The payload of metadata events for channels is the [`ChannelDetails`](#channel-details) type which contains the `channelId` (AKA the [channel's name](/docs/api/realtime-sdk/channels#name)) and other static information about the channel, plus a `status` containing a [`ChannelStatus`](#channel-status) instance which contains information about the current state of the channel. diff --git a/src/pages/docs/api/rest-sdk/channels.mdx b/src/pages/docs/api/rest-sdk/channels.mdx index bea30de1d4..38e799b008 100644 --- a/src/pages/docs/api/rest-sdk/channels.mdx +++ b/src/pages/docs/api/rest-sdk/channels.mdx @@ -8,6 +8,10 @@ redirect_from: - /docs/api/versions/v0.8/rest-sdk/channels --- + + ## Channels The `Channels` object, accessed from the [rest library client constructor](/docs/api/rest-sdk#channels), is used to create and destroy `Channel` objects. It exposes the following public methods: diff --git a/src/pages/docs/api/rest-sdk/encryption.mdx b/src/pages/docs/api/rest-sdk/encryption.mdx index 98898c9828..5c6191c113 100644 --- a/src/pages/docs/api/rest-sdk/encryption.mdx +++ b/src/pages/docs/api/rest-sdk/encryption.mdx @@ -15,6 +15,10 @@ redirect_from: - /docs/api/versions/v0.8/rest-sdk/encryption --- + + The `Ably.Rest.Crypto``Ably::Util::Crypto``Ably\Utils\Crypto``ably.util.crypto``io.ably.lib.util.crypto``ARTCrypto``IO.Ably.Encryption.Crypto` object exposes the following public methods: ## Methods diff --git a/src/pages/docs/api/rest-sdk/history.mdx b/src/pages/docs/api/rest-sdk/history.mdx index 883f77f66c..f187ea584c 100644 --- a/src/pages/docs/api/rest-sdk/history.mdx +++ b/src/pages/docs/api/rest-sdk/history.mdx @@ -14,6 +14,10 @@ redirect_from: - /docs/api/versions/v0.8/rest-sdk/history --- + + ## Channel object The [Rest `Channel` object](/docs/channels) exposes the following public method to obtain [`Message`](#message) history. diff --git a/src/pages/docs/api/rest-sdk/messages.mdx b/src/pages/docs/api/rest-sdk/messages.mdx index 833cf752b4..9ca9ba2c93 100644 --- a/src/pages/docs/api/rest-sdk/messages.mdx +++ b/src/pages/docs/api/rest-sdk/messages.mdx @@ -8,6 +8,10 @@ redirect_from: - /docs/api/versions/v0.8/rest-sdk/messages --- + + A `Message` represents an individual message that is sent to or received from Ably. ### name diff --git a/src/pages/docs/api/rest-sdk/presence.mdx b/src/pages/docs/api/rest-sdk/presence.mdx index 40c8121b40..404a6ec8e0 100644 --- a/src/pages/docs/api/rest-sdk/presence.mdx +++ b/src/pages/docs/api/rest-sdk/presence.mdx @@ -14,6 +14,10 @@ redirect_from: - /docs/api/versions/v0.8/rest-sdk/presence --- + + ## Methods ### getGet diff --git a/src/pages/docs/api/rest-sdk/push-admin.mdx b/src/pages/docs/api/rest-sdk/push-admin.mdx index 097fb57e21..56431ef320 100644 --- a/src/pages/docs/api/rest-sdk/push-admin.mdx +++ b/src/pages/docs/api/rest-sdk/push-admin.mdx @@ -15,6 +15,10 @@ redirect_from: - /docs/api/versions/v1.1/rest-sdk/push-admin --- + + ## Push Admin object This object is accessible through `client.push.admin` and provides: diff --git a/src/pages/docs/api/rest-sdk/statistics.mdx b/src/pages/docs/api/rest-sdk/statistics.mdx index 31379c5c57..3455087776 100644 --- a/src/pages/docs/api/rest-sdk/statistics.mdx +++ b/src/pages/docs/api/rest-sdk/statistics.mdx @@ -8,6 +8,10 @@ redirect_from: - /docs/api/versions/v0.8/rest-sdk/statistics --- + + ### statsStats diff --git a/src/pages/docs/api/rest-sdk/types.mdx b/src/pages/docs/api/rest-sdk/types.mdx index a1a4997197..daeda03462 100644 --- a/src/pages/docs/api/rest-sdk/types.mdx +++ b/src/pages/docs/api/rest-sdk/types.mdx @@ -9,6 +9,10 @@ redirect_from: - /docs/rest/types --- + + The Ably REST client library defines both data types and option types. Data types are used to represent object such as messages; Option types are used in method arguments. Where client libraries support both Realtime and REST APIs, the types are shared between both clients. From bc5a87dfb8cdda429e4523f4a7c66780a8c7bf48 Mon Sep 17 00:00:00 2001 From: Mark Hulbert <39801222+m-hulbert@users.noreply.github.com> Date: Mon, 27 Jul 2026 17:20:43 +0100 Subject: [PATCH 2/7] Point JavaScript-context links at the new Pub/Sub JS API reference Rewrites links to /docs/api/realtime-sdk and /docs/api/rest-sdk on pages whose only selectable language is JavaScript-family, links inside JavaScript-only blocks, and links carrying an explicit ?lang=javascript|nodejs|react parameter. Language-neutral pages and non-JS contexts keep the legacy multi-language target. Co-Authored-By: Claude Fable 5 --- .../ai-transport/features/token-streaming.mdx | 2 +- src/pages/docs/api/rest-api.mdx | 48 +++++++++---------- src/pages/docs/connect/index.mdx | 4 +- src/pages/docs/faq/index.mdx | 2 +- src/pages/docs/getting-started/javascript.mdx | 2 +- src/pages/docs/getting-started/nextjs.mdx | 2 +- src/pages/docs/getting-started/node.mdx | 2 +- .../docs/getting-started/react-native.mdx | 2 +- src/pages/docs/getting-started/react.mdx | 2 +- .../liveobjects/quickstart/javascript.mdx | 4 +- src/pages/docs/liveobjects/rest-sdk-usage.mdx | 4 +- src/pages/docs/livesync/postgres/models.mdx | 2 +- src/pages/docs/messages/index.mdx | 2 +- src/pages/docs/platform/errors/index.mdx | 2 +- .../integrations/inbound/webhooks.mdx | 2 +- .../docs/platform/integrations/queues.mdx | 2 +- .../platform/integrations/webhooks/index.mdx | 16 +++---- .../pub-sub/guides/handling-discontinuity.mdx | 2 +- src/pages/docs/push/configure/device.mdx | 2 +- src/pages/docs/push/configure/web.mdx | 12 ++--- .../push/getting-started/react-native.mdx | 10 ++-- src/pages/docs/push/getting-started/web.mdx | 4 +- src/pages/docs/push/index.mdx | 8 ++-- src/pages/docs/spaces/setup.mdx | 4 +- 24 files changed, 71 insertions(+), 71 deletions(-) diff --git a/src/pages/docs/ai-transport/features/token-streaming.mdx b/src/pages/docs/ai-transport/features/token-streaming.mdx index d941152d4f..c844cd7d6e 100644 --- a/src/pages/docs/ai-transport/features/token-streaming.mdx +++ b/src/pages/docs/ai-transport/features/token-streaming.mdx @@ -148,7 +148,7 @@ By default, Ably delivers a single response stream at 25 messages per second, or ### Configure rollup behaviour -On the client, set the rollup window for a connection using the `appendRollupWindow` [transport parameter](/docs/api/realtime-sdk#client-options): +On the client, set the rollup window for a connection using the `appendRollupWindow` [transport parameter](/docs/pub-sub/api/javascript/realtime/realtime-client#constructor-params): | `appendRollupWindow` | Maximum message rate for a single response | |---|---| diff --git a/src/pages/docs/api/rest-api.mdx b/src/pages/docs/api/rest-api.mdx index f071814896..265aff801a 100644 --- a/src/pages/docs/api/rest-api.mdx +++ b/src/pages/docs/api/rest-api.mdx @@ -56,7 +56,7 @@ redirect_from: Welcome to the Ably REST API Reference documentation. -The Ably REST API provides a way for a wide range of server and client devices to communicate with the Ably service over [REST](https://en.wikipedia.org/wiki/Representational_State_Transfer). The REST API does not provide a realtime long-lived connection to Ably, but in all other respects is a simple subset of the full [realtime messaging API](/docs/api/realtime-sdk). +The Ably REST API provides a way for a wide range of server and client devices to communicate with the Ably service over [REST](https://en.wikipedia.org/wiki/Representational_State_Transfer). The REST API does not provide a realtime long-lived connection to Ably, but in all other respects is a simple subset of the full [realtime messaging API](/docs/pub-sub/api/javascript/realtime/realtime-client). The primary use-case for the REST API is for servers that are part of the back-end of an application such as a web application, that publish messages, issue access tokens (temporary and client-specific) for its various clients, obtain message and presence history, and retrieve statistics. @@ -81,7 +81,7 @@ Using the REST API directly is fully supported, Ably recommends that customers s The [Ably client libraries SDKs are documented](/docs), and provide additional features that improve performance and resilience that the REST API cannot deliver on its own, such as automatic re-routing around network problems by using alternative datacenters. -You can also use the [Rest#request()](/docs/api/rest-sdk#request) method to make arbitrary API calls against Ably, to use endpoints that libraries do not yet have built-in support for. +You can also use the [Rest#request()](/docs/pub-sub/api/javascript/rest/rest-client#request) method to make arbitrary API calls against Ably, to use endpoints that libraries do not yet have built-in support for. ## Common API behavior @@ -343,7 +343,7 @@ curl https://main.realtime.ably.net/channels/rest-example/messages \ ### Token Authentication -**Token Authentication** uses an Ably-compatible token to authenticate with Ably without sharing a private API key. This can be an [Ably Token](/docs/api/rest-sdk/authentication#tokens) obtained via the REST API [`requestToken`](#request-token) endpoint, an [Ably JWT](/docs/api/rest-sdk/authentication#ably-jwt) signed by your API key, or an [External JWT](https://jwt.io) object [with an embedded Ably-compatible token](/docs/auth/token#embedded). Tokens are authentication credentials that are short-lived, and therefore they may more readily be distributed to clients where there is a risk of compromise. Tokens may also be issued with a particular scope - such as a limited set of [access rights or capabilities](/docs/auth/capabilities) or being limited to use by a specific [`clientId` identity](#identified-clients) - and therefore token-based authentication provides the flexibility to implement access and identity control policies in the application. See the [Token Authentication documentation](/docs/auth/token) for more details. +**Token Authentication** uses an Ably-compatible token to authenticate with Ably without sharing a private API key. This can be an [Ably Token](/docs/pub-sub/api/javascript/rest/auth#tokens) obtained via the REST API [`requestToken`](#request-token) endpoint, an [Ably JWT](/docs/auth/token/jwt) signed by your API key, or an [External JWT](https://jwt.io) object [with an embedded Ably-compatible token](/docs/auth/token#embedded). Tokens are authentication credentials that are short-lived, and therefore they may more readily be distributed to clients where there is a risk of compromise. Tokens may also be issued with a particular scope - such as a limited set of [access rights or capabilities](/docs/auth/capabilities) or being limited to use by a specific [`clientId` identity](#identified-clients) - and therefore token-based authentication provides the flexibility to implement access and identity control policies in the application. See the [Token Authentication documentation](/docs/auth/token) for more details. The construction of an Ably [`TokenRequest`](/docs/api/token-request-spec) is described in the [Authentication Ably TokenRequest spec documentation](/docs/api/token-request-spec). The resulting `token response` object contains the token properties as defined in [Ably TokenRequest spec](/docs/api/token-request-spec). @@ -355,7 +355,7 @@ Authorization: Bearer ``` -The `` is either the `token` attribute of the Ably Token generated by [`requestToken`](#request-token) encoded with [RFC 4648 Base64](https://datatracker.ietf.org/doc/html/rfc4648), or an [Ably JWT](/docs/api/rest-sdk/authentication#ably-jwt). If using a generic HTTP client library it will probably be necessary to add the `Authorization` header explicitly. +The `` is either the `token` attribute of the Ably Token generated by [`requestToken`](#request-token) encoded with [RFC 4648 Base64](https://datatracker.ietf.org/doc/html/rfc4648), or an [Ably JWT](/docs/auth/token/jwt). If using a generic HTTP client library it will probably be necessary to add the `Authorization` header explicitly. Example request: @@ -411,7 +411,7 @@ In JSON format, the accepted types for the `data` payload are: MessagePack additionally [supports byte arrays](https://github.com/msgpack/msgpack/blob/master/spec.md#formats-bin) -A message may be published over REST on behalf of an existing realtime connection when a valid `connectionKey` is present. For example, if you want to publish a message using the REST API so that it appears to come from an existing connected realtime client, then the connection's [private (secret) connection key](/docs/api/realtime-sdk/connection#key) must be included. +A message may be published over REST on behalf of an existing realtime connection when a valid `connectionKey` is present. For example, if you want to publish a message using the REST API so that it appears to come from an existing connected realtime client, then the connection's [private (secret) connection key](/docs/pub-sub/api/javascript/realtime/connection#properties) must be included. Example request: @@ -534,7 +534,7 @@ curl -X POST https://main.realtime.ably.net/channels/push-enabled:rest-example/m ##### Returns -When successful, returns status code 201 and an object with `channel` and `messageId` properties, in case you want to know the message ID assigned to correlate with messages received by realtime subscribers or Ably Integration recipients. When unsuccessful, returns an error as an [ErrorInfo](/docs/api/rest-sdk/types#error-info) object. +When successful, returns status code 201 and an object with `channel` and `messageId` properties, in case you want to know the message ID assigned to correlate with messages received by realtime subscribers or Ably Integration recipients. When unsuccessful, returns an error as an [ErrorInfo](/docs/pub-sub/api/javascript/rest/rest-client#errorinfo) object. ### Unenveloped publish @@ -584,7 +584,7 @@ curl -X POST https://main.realtime.ably.net/channels/rest-example/messages?envel ##### Returns -When successful, returns an object with `channel` and `messageId` properties, in case you want to know the message ID assigned to correlate with messages received by realtime subscribers or integrations recipients. When unsuccessful, returns an error as an [ErrorInfo](/docs/api/rest-sdk/types#error-info) object. +When successful, returns an object with `channel` and `messageId` properties, in case you want to know the message ID assigned to correlate with messages received by realtime subscribers or integrations recipients. When unsuccessful, returns an error as an [ErrorInfo](/docs/pub-sub/api/javascript/rest/rest-client#errorinfo) object. ### Retrieve message history for a channel @@ -659,7 +659,7 @@ curl https://main.realtime.ably.net/channels/rest-example/messages/0182623249887 A successful request returns a single `Message` object containing the latest version of the message. -See [MessageAction](/docs/api/realtime-sdk/types#message-action) for the possible values of the `action` enum. +See [MessageAction](/docs/pub-sub/api/javascript/realtime/message) for the possible values of the `action` enum. ```json @@ -693,7 +693,7 @@ See [Updating and deleting messages](/docs/messages/updates-deletes) for more in The request body contains a Message object with an `action` field specifying the operation, the fields to update, and optional operation metadata in `version`. Any fields not specified will be left as their original values (shallow mixin semantics). For appends, the `data` field is concatenated to the existing message's data rather than replacing it. -The `action` should be set to a [MessageAction](/docs/api/realtime-sdk/types#message-action) int enum: `MESSAGE_UPDATE` (1), `MESSAGE_DELETE` (2), or `MESSAGE_APPEND` (5). +The `action` should be set to a [MessageAction](/docs/pub-sub/api/javascript/realtime/message) int enum: `MESSAGE_UPDATE` (1), `MESSAGE_DELETE` (2), or `MESSAGE_APPEND` (5). ```json @@ -747,7 +747,7 @@ curl -X PATCH https://main.realtime.ably.net/channels/rest-example/messages/0182 ##### Returns -Returns an [`UpdateDeleteResult`](/docs/api/realtime-sdk/types#update-delete-result) object with a single `versionSerial` field: the serial of the version of the updated, deleted, or appended message, or `null` if the message was superseded by a subsequent update before it could be published. +Returns an [`UpdateDeleteResult`](/docs/pub-sub/api/javascript/realtime/realtime-channel#update-message-returns) object with a single `versionSerial` field: the serial of the version of the updated, deleted, or appended message, or `null` if the message was superseded by a subsequent update before it could be published. ```json @@ -786,7 +786,7 @@ curl https://main.realtime.ably.net/channels/rest-example/messages/0182623249887 A successful request returns a [paginated response](pagination) containing all versions of the message, ordered by version serial (oldest to newest). -See [MessageAction](/docs/api/realtime-sdk/types#message-action) for the possible values of the `action` enum. +See [MessageAction](/docs/pub-sub/api/javascript/realtime/message) for the possible values of the `action` enum. ```json @@ -814,13 +814,13 @@ An unsuccessful request returns an error. #### GET rest.ably.io/channels/\{channelId\} -This returns a [ChannelDetails](/docs/api/realtime-sdk/channel-metadata#channel-details) for the given channel, indicating global [occupancy](/docs/api/rest-sdk/channel-status#occupancy). A side-effect of this request, in the current version of this API, is that it will cause the channel in question to become activated; therefore it is primarily intended to be used in conjunction with the [enumeration API](#enumeration-rest) or in situations where the application has another means to know whether or not a given channel is active. +This returns a [ChannelDetails](/docs/pub-sub/api/javascript/realtime/channel-details#ChannelDetails) for the given channel, indicating global [occupancy](/docs/pub-sub/api/javascript/rest/channel-details#ChannelDetails). A side-effect of this request, in the current version of this API, is that it will cause the channel in question to become activated; therefore it is primarily intended to be used in conjunction with the [enumeration API](#enumeration-rest) or in situations where the application has another means to know whether or not a given channel is active. ### Enumerate all active channels #### GET rest.ably.io/channels -This enumerates all active channels in the application. This is a paginated API following the same API conventions as other paginated APIs in the [REST interface](/docs/api/rest-sdk). +This enumerates all active channels in the application. This is a paginated API following the same API conventions as other paginated APIs in the [REST interface](/docs/pub-sub/api/javascript/rest/rest-client). ### Publish annotations for a message @@ -886,7 +886,7 @@ None ##### Returns -When successful, returns status code 201 and an object with annotation details. When unsuccessful, returns an error as an [ErrorInfo](/docs/api/rest-sdk/types#error-info) object. +When successful, returns status code 201 and an object with annotation details. When unsuccessful, returns an error as an [ErrorInfo](/docs/pub-sub/api/javascript/rest/rest-client#errorinfo) object. ### Retrieve all annotations for a message @@ -1090,7 +1090,7 @@ A successful request returns a [paginated response](#pagination) with an array c ### Retrieve metadata for a channel -This returns a [ChannelDetails](/docs/api/realtime-sdk/channel-metadata#channel-details) for the given channel, indicating global [occupancy](/docs/api/rest-sdk/channel-status#occupancy). A side-effect of this request, in the current version of this API, is that it will cause the channel in question to become activated; therefore it is primarily intended to be used in conjunction with the [enumeration API](#enumeration-rest) or in situations where the application has another means to know whether or not a given channel is active. +This returns a [ChannelDetails](/docs/pub-sub/api/javascript/realtime/channel-details#ChannelDetails) for the given channel, indicating global [occupancy](/docs/pub-sub/api/javascript/rest/channel-details#ChannelDetails). A side-effect of this request, in the current version of this API, is that it will cause the channel in question to become activated; therefore it is primarily intended to be used in conjunction with the [enumeration API](#enumeration-rest) or in situations where the application has another means to know whether or not a given channel is active. Example request: @@ -1103,11 +1103,11 @@ curl https://main.realtime.ably.net/channels/{channelId} \ The credentials presented with the request must include the `channel-metadata` permission for the channel in question. -Client libraries currently do not support this API, but it is usable via the generic [request API](/docs/api/rest-sdk#request). +Client libraries currently do not support this API, but it is usable via the generic [request API](/docs/pub-sub/api/javascript/rest/rest-client#request). ### Enumerate all active channels -This enumerates all active channels in the application. This is a paginated API following the same API conventions as other paginated APIs in the [REST interface](/docs/api/rest-sdk). +This enumerates all active channels in the application. This is a paginated API following the same API conventions as other paginated APIs in the [REST interface](/docs/pub-sub/api/javascript/rest/rest-client). This API is intended for occasional use by your servers only; for example, to get an initial set of active channels to be kept up to date using the [channel lifecycle metachannel](/docs/metadata-stats/metadata/subscribe). It is heavily rate-limited: only a single in-flight channel enumeration call is permitted to execute at any one time. Further concurrent calls will be refused with an error with code `42912`. @@ -1120,7 +1120,7 @@ curl https://main.realtime.ably.net/channels \ ``` -This will return either a list of channel names, or a [ChannelDetails](/docs/api/realtime-sdk/channel-metadata#channel-details) object depending on what options you've specified. +This will return either a list of channel names, or a [ChannelDetails](/docs/pub-sub/api/javascript/realtime/channel-details#ChannelDetails) object depending on what options you've specified. The following parameters are supported: @@ -1128,11 +1128,11 @@ The following parameters are supported: |-----------|-------------|------| | limit | _100_ optionally specifies the maximum number of results to return. A limit greater than 1000 is unsupported | integer | | prefix | optionally limits the query to only those channels whose name starts with the given prefix | string | -| by | _id (≥ v3) or value (≤ v2)_ optionally specifies what to return. Use `by=id` to return only channel names or `by=value` to return [`ChannelDetails`](/docs/api/realtime-sdk/channel-metadata#channel-details). Using `by=id` will be much faster, and making very regular `by=value` enumeration queries can prevent channels from closing down from inactivity. | string | +| by | _id (≥ v3) or value (≤ v2)_ optionally specifies what to return. Use `by=id` to return only channel names or `by=value` to return [`ChannelDetails`](/docs/pub-sub/api/javascript/realtime/channel-details#ChannelDetails). Using `by=id` will be much faster, and making very regular `by=value` enumeration queries can prevent channels from closing down from inactivity. | string | The credentials presented with the request must include the `channel-metadata` permission for the wildcard resource `'*'`. -Client libraries do not provide a dedicated API to enumerate channels, but make this available using the [request](/docs/api/rest-sdk#request) method. When using this, you can simply iterate through the [PaginatedResults](/docs/api/rest-sdk/types#paginated-result) to enumerate through the results. +Client libraries do not provide a dedicated API to enumerate channels, but make this available using the [request](/docs/pub-sub/api/javascript/rest/rest-client#request) method. When using this, you can simply iterate through the [PaginatedResults](/docs/pub-sub/api/javascript/rest/rest-client#PaginatedResult) to enumerate through the results. `Enumeration` is possible of all channels in an app, by repeated calls to the API, following the `next` relative link on each successive call, until there is no `next` relative link. However, this is subject to several limitations: @@ -1943,7 +1943,7 @@ None ##### Returns -A successful request will return a [token details object](/docs/api/realtime-sdk/types#token-details) containing the token string. +A successful request will return a [token details object](/docs/pub-sub/api/javascript/realtime/auth#request-token-returns) containing the token string. ```json @@ -2164,9 +2164,9 @@ None ``` -**Failure**: If the batch publish request itself fails, the response includes an [ErrorInfo](/docs/api/rest-sdk/types#error-info) object. +**Failure**: If the batch publish request itself fails, the response includes an [ErrorInfo](/docs/pub-sub/api/javascript/rest/rest-client#errorinfo) object. -**Partial success**: If the batch request itself succeeds, but one or more of the requests within the batch fails, then the response includes a top-level `error` property with a status code of `400` and an error code of `40020`. The `batchResponse` object for the failed request includes the channel name and an [ErrorInfo](/docs/api/rest-sdk/types#error-info) object that describes the error. The successful requests within the batch return a `batchResponse` object for each channel, together with the `messageId` of the published message. +**Partial success**: If the batch request itself succeeds, but one or more of the requests within the batch fails, then the response includes a top-level `error` property with a status code of `400` and an error code of `40020`. The `batchResponse` object for the failed request includes the channel name and an [ErrorInfo](/docs/pub-sub/api/javascript/rest/rest-client#errorinfo) object that describes the error. The successful requests within the batch return a `batchResponse` object for each channel, together with the `messageId` of the published message. ### Batch presence @@ -2251,7 +2251,7 @@ Each object in the `presence` array of each channel describes the presence state ``` -**Failure**: If the batch request itself fails the response body contains an [ErrorInfo](/docs/api/rest-sdk/types#error-info) object. +**Failure**: If the batch request itself fails the response body contains an [ErrorInfo](/docs/pub-sub/api/javascript/rest/rest-client#errorinfo) object. **Partial success**: If the batch request itself succeeds, but one or more of the requests within the batch fails, then the response for the failed request contains an error object with the error code `40020` and a status code of `400`. Successful requests within the batch include a `presence` array that describes the presence state of each of the channel members. diff --git a/src/pages/docs/connect/index.mdx b/src/pages/docs/connect/index.mdx index 8d497f3a53..949752efc8 100644 --- a/src/pages/docs/connect/index.mdx +++ b/src/pages/docs/connect/index.mdx @@ -244,7 +244,7 @@ Chrome's Memory Saver feature assists with controlling the browser's memory foot ### Managing connection lifecycle To ensure predictable connection closure behavior, consider these options: -Set `closeOnUnload:false` in [`ClientOptions`](/docs/api/realtime-sdk#client-options) when initializing the library: +Set `closeOnUnload:false` in [`ClientOptions`](/docs/pub-sub/api/javascript/realtime/realtime-client#constructor-params) when initializing the library: ```realtime_javascript const ably = new Ably.Realtime({ @@ -259,7 +259,7 @@ const ably = new Ably.Realtime({ }); ``` -Manage connection lifecycle explicitly by calling [`close()`](/docs/api/realtime-sdk/connection#close) on the Ably realtime instance when it's no longer needed: +Manage connection lifecycle explicitly by calling [`close()`](/docs/pub-sub/api/javascript/realtime/connection#close) on the Ably realtime instance when it's no longer needed: ```realtime_javascript // When your application determines the connection should close diff --git a/src/pages/docs/faq/index.mdx b/src/pages/docs/faq/index.mdx index a44fa1b9a7..20b74e0e83 100644 --- a/src/pages/docs/faq/index.mdx +++ b/src/pages/docs/faq/index.mdx @@ -463,7 +463,7 @@ You can resolve this in two ways: 1. Run the Ably library in the background script instead of the content script. -2. If you must run the library in the content script, request the background page to handle REST requests ([token authentication](/docs/api/realtime-sdk/authentication)). Instead of using `authUrl`, supply an `authCallback` that asks the background page to request a token. Ensure your auth server calls `requestToken` rather than `createTokenRequest` to avoid the library attempting a REST request. +2. If you must run the library in the content script, request the background page to handle REST requests ([token authentication](/docs/pub-sub/api/javascript/realtime/auth)). Instead of using `authUrl`, supply an `authCallback` that asks the background page to request a token. Ensure your auth server calls `requestToken` rather than `createTokenRequest` to avoid the library attempting a REST request. Specify `transports: ['web_socket']` in the client options, as the default XHR transport may fail. diff --git a/src/pages/docs/getting-started/javascript.mdx b/src/pages/docs/getting-started/javascript.mdx index b8ef1de6b1..68c108b824 100644 --- a/src/pages/docs/getting-started/javascript.mdx +++ b/src/pages/docs/getting-started/javascript.mdx @@ -206,4 +206,4 @@ Continue to explore the documentation with JavaScript as the selected language: * Understand how to effectively [manage connections](/docs/connect?lang=javascript#close). * Explore more [advanced](/docs/pub-sub/advanced?lang=javascript) Pub/Sub concepts. -You can also explore the [Ably CLI](https://www.npmjs.com/package/@ably/cli) further, or visit the Pub/Sub [API references](/docs/api/realtime-sdk?lang=javascript). +You can also explore the [Ably CLI](https://www.npmjs.com/package/@ably/cli) further, or visit the Pub/Sub [API references](/docs/pub-sub/api/javascript/realtime/realtime-client). diff --git a/src/pages/docs/getting-started/nextjs.mdx b/src/pages/docs/getting-started/nextjs.mdx index f8d2623a3d..f7af500d1d 100644 --- a/src/pages/docs/getting-started/nextjs.mdx +++ b/src/pages/docs/getting-started/nextjs.mdx @@ -551,4 +551,4 @@ Continue to explore the documentation with Next.js as the selected language: * Understand how to effectively [manage connections](/docs/connect#close?lang=nextjs). * Explore more [advanced](/docs/pub-sub/advanced?lang=nextjs) Pub/Sub concepts. -You can also explore the [Ably CLI](https://www.npmjs.com/package/@ably/cli) further, visit the Pub/Sub [API references](/docs/api/realtime-sdk?lang=javascript), or browse the [Ably Next.js Fundamentals Kit](https://github.com/ably/ably-nextjs-fundamentals-kit) for more complete examples. +You can also explore the [Ably CLI](https://www.npmjs.com/package/@ably/cli) further, visit the Pub/Sub [API references](/docs/pub-sub/api/javascript/realtime/realtime-client), or browse the [Ably Next.js Fundamentals Kit](https://github.com/ably/ably-nextjs-fundamentals-kit) for more complete examples. diff --git a/src/pages/docs/getting-started/node.mdx b/src/pages/docs/getting-started/node.mdx index b6048d7f2e..4a026b38ee 100644 --- a/src/pages/docs/getting-started/node.mdx +++ b/src/pages/docs/getting-started/node.mdx @@ -199,4 +199,4 @@ Continue to explore the documentation with JavaScript as the selected language: * Understand how to effectively [manage connections](/docs/connect?lang=nodejs#close). * Explore more [advanced](/docs/pub-sub/advanced?lang=nodejs) Pub/Sub concepts. -You can also explore the [Ably CLI](https://www.npmjs.com/package/@ably/cli) further, or visit the Pub/Sub [API references](/docs/api/realtime-sdk?lang=nodejs). +You can also explore the [Ably CLI](https://www.npmjs.com/package/@ably/cli) further, or visit the Pub/Sub [API references](/docs/pub-sub/api/javascript/realtime/realtime-client). diff --git a/src/pages/docs/getting-started/react-native.mdx b/src/pages/docs/getting-started/react-native.mdx index a11cd22803..5ee9e9ab10 100644 --- a/src/pages/docs/getting-started/react-native.mdx +++ b/src/pages/docs/getting-started/react-native.mdx @@ -682,4 +682,4 @@ Continue to explore the documentation with React as the selected language: * Understand how to effectively [manage connections](/docs/connect?lang=react#close). * Explore more [advanced](/docs/pub-sub/advanced?lang=react) Pub/Sub concepts. -You can also explore the [Ably CLI](https://www.npmjs.com/package/@ably/cli) further, or visit the Pub/Sub [API references](/docs/api/realtime-sdk). +You can also explore the [Ably CLI](https://www.npmjs.com/package/@ably/cli) further, or visit the Pub/Sub [API references](/docs/pub-sub/api/javascript/realtime/realtime-client). diff --git a/src/pages/docs/getting-started/react.mdx b/src/pages/docs/getting-started/react.mdx index 9c99323a9c..29077ac6ef 100644 --- a/src/pages/docs/getting-started/react.mdx +++ b/src/pages/docs/getting-started/react.mdx @@ -627,4 +627,4 @@ Continue to explore the documentation with React as the selected language: * Understand how to effectively [manage connections](/docs/connect?lang=react#close). * Explore more [advanced](/docs/pub-sub/advanced?lang=react) Pub/Sub concepts. -You can also explore the [Ably CLI](https://www.npmjs.com/package/@ably/cli) further, or visit the Pub/Sub [API references](/docs/api/realtime-sdk?lang=react). +You can also explore the [Ably CLI](https://www.npmjs.com/package/@ably/cli) further, or visit the Pub/Sub [API references](/docs/pub-sub/api/javascript/realtime/realtime-client). diff --git a/src/pages/docs/liveobjects/quickstart/javascript.mdx b/src/pages/docs/liveobjects/quickstart/javascript.mdx index ae5fae0090..b5325ec333 100644 --- a/src/pages/docs/liveobjects/quickstart/javascript.mdx +++ b/src/pages/docs/liveobjects/quickstart/javascript.mdx @@ -88,7 +88,7 @@ const realtimeClient = new Ably.Realtime({ key: '{{API_KEY}}', plugins: { LiveOb ``` -A [`ClientOptions`](/docs/api/realtime-sdk#client-options) object may be passed to the Pub/Sub SDK instance to further customize the connection, however at a minimum you must set an API key and provide an `Objects` plugin so that the client can use LiveObjects functionality. +A [`ClientOptions`](/docs/pub-sub/api/javascript/realtime/realtime-client#constructor-params) object may be passed to the Pub/Sub SDK instance to further customize the connection, however at a minimum you must set an API key and provide an `Objects` plugin so that the client can use LiveObjects functionality. ## Create a channel @@ -110,7 +110,7 @@ const channel = realtimeClient.channels.get('my_liveobjects_channel', channelOpt ## Get the channel object -The [`channel.object`](/docs/api/realtime-sdk/channels#object) property gives access to the LiveObjects API for a channel. +The [`channel.object`](/docs/liveobjects) property gives access to the LiveObjects API for a channel. Use `channel.object.get()` to obtain a [`PathObject`](/docs/liveobjects/concepts/path-object) that represents the channel object. The channel object is a [`LiveMap`](/docs/liveobjects/map) that always exists on a channel and acts as the top-level entry point for accessing and persisting objects. A `PathObject` provides a path-based API for accessing and manipulating the object hierarchy. The method returns a promise that resolves once the LiveObjects state is synchronized with the Ably system: diff --git a/src/pages/docs/liveobjects/rest-sdk-usage.mdx b/src/pages/docs/liveobjects/rest-sdk-usage.mdx index 484d66c8a6..557ad9b5e2 100644 --- a/src/pages/docs/liveobjects/rest-sdk-usage.mdx +++ b/src/pages/docs/liveobjects/rest-sdk-usage.mdx @@ -11,7 +11,7 @@ LiveObjects provides a JavaScript REST SDK that enables you to directly work wit ## Setup -Create an [`Ably.Rest`](/docs/api/rest-sdk) client instance with the `LiveObjects` plugin: +Create an [`Ably.Rest`](/docs/pub-sub/api/javascript/rest/rest-client) client instance with the `LiveObjects` plugin: ```javascript @@ -32,7 +32,7 @@ channel.object // LiveObjects REST SDK ## Authentication -Authentication is configured when instantiating the REST client. Pass an API key or use [token authentication](/docs/auth/token) via the [`ClientOptions`](/docs/api/rest-sdk#client-options). See the [REST SDK authentication](/docs/api/rest-sdk/authentication) documentation for details. +Authentication is configured when instantiating the REST client. Pass an API key or use [token authentication](/docs/auth/token) via the [`ClientOptions`](/docs/pub-sub/api/javascript/rest/rest-client#constructor-params). See the [REST SDK authentication](/docs/pub-sub/api/javascript/rest/auth) documentation for details. To read objects on a channel, an API key must have the `object-subscribe` [capability](/docs/auth/capabilities). With only this capability, clients have read-only access, preventing them from publishing operations. diff --git a/src/pages/docs/livesync/postgres/models.mdx b/src/pages/docs/livesync/postgres/models.mdx index 26a15d301f..3009f154a4 100644 --- a/src/pages/docs/livesync/postgres/models.mdx +++ b/src/pages/docs/livesync/postgres/models.mdx @@ -380,7 +380,7 @@ Change events from your backend are delivered to the SDK as messages over the [c The SDK supports a short time buffering for change events, facilitating short-term reordering and de-duplication. By default, this feature is not enabled. To activate it, set the `eventBufferOptions.bufferMS` in the [`ClientOption`](#client-options) to a non-zero value. -When using the event buffer, change events are de-duplicated and ordered according to their [`message.id`](/docs/api/realtime-sdk/messages#id), which corresponds to the change event's [`sequenceId`](#sequence). +When using the event buffer, change events are de-duplicated and ordered according to their [`message.id`](/docs/pub-sub/api/javascript/realtime/message#properties), which corresponds to the change event's [`sequenceId`](#sequence). By default, the events in the buffer are ordered numerically if the `message.id` can be coerced to a number. Otherwise, events will be ordered lexicographically by their `message.id`. You can specify a custom ordering based on any part of the message via the `eventBufferOptions.eventOrderer` [`ClientOption`](#client-options). diff --git a/src/pages/docs/messages/index.mdx b/src/pages/docs/messages/index.mdx index f0f2d32f36..58035f5087 100644 --- a/src/pages/docs/messages/index.mdx +++ b/src/pages/docs/messages/index.mdx @@ -33,7 +33,7 @@ The following are the properties of a message: | **timestamp** | The timestamp of when the message was first received by Ably, as milliseconds since the Unix epoch | | **extras** | A JSON object of arbitrary key-value pairs that may contain metadata, and/or ancillary payloads. Valid payloads include those related to [Push Notifications](/docs/push), [deltas](/docs/channels/options/deltas) and headers | | **encoding** | This is typically empty, as all messages received from Ably are automatically decoded client-side using this value. However, if the message encoding cannot be processed, this attribute contains the remaining transformations not applied to the data payload | -| **action** | An [enum](/docs/api/realtime-sdk/types#message-action) telling you whether this is a normal ('create') message, an update to a previous message, an annotation summary, etc. | +| **action** | An [enum](/docs/pub-sub/api/javascript/realtime/message) telling you whether this is a normal ('create') message, an update to a previous message, an annotation summary, etc. | | **serial** | The message's serial (a server-assigned identifier that will be the same in all future updates of this message, and can be used to add [annotations](/docs/messages/annotations) or to [update or delete](/docs/messages/updates-deletes) the message). This will only be set if you enable annotations, updates, deletes, and appends in [rules](/docs/channels#rules) | | **annotations** | An object containing a summary of any [annotations](/docs/messages/annotations) that have been made to the message | | **version** | An object containing [version metadata](/docs/messages/updates-deletes#version-structure) for messages that have been updated or deleted | diff --git a/src/pages/docs/platform/errors/index.mdx b/src/pages/docs/platform/errors/index.mdx index aa972f8cd8..aa19f4e957 100644 --- a/src/pages/docs/platform/errors/index.mdx +++ b/src/pages/docs/platform/errors/index.mdx @@ -114,7 +114,7 @@ If you continue experiencing SSL certificate issues after trying these solutions ## Error info -All errors returned by Ably are standardized and use the [`ErrorInfo`](/docs/api/rest-sdk/types#error-info) object: +All errors returned by Ably are standardized and use the [`ErrorInfo`](/docs/pub-sub/api/javascript/rest/rest-client#errorinfo) object: ```json diff --git a/src/pages/docs/platform/integrations/inbound/webhooks.mdx b/src/pages/docs/platform/integrations/inbound/webhooks.mdx index 016a49506a..ff3cffa7ae 100644 --- a/src/pages/docs/platform/integrations/inbound/webhooks.mdx +++ b/src/pages/docs/platform/integrations/inbound/webhooks.mdx @@ -51,7 +51,7 @@ Ably responds with the `channel` and `messageId`: ``` -A successful request returns a `201` status. Failures return with an [`ErrorInfo`](/docs/api/rest-sdk/types#error-info) response. +A successful request returns a `201` status. Failures return with an [`ErrorInfo`](/docs/pub-sub/api/javascript/rest/rest-client#errorinfo) response. ## Receive webhook messages diff --git a/src/pages/docs/platform/integrations/queues.mdx b/src/pages/docs/platform/integrations/queues.mdx index a366e58d0a..59538959ab 100644 --- a/src/pages/docs/platform/integrations/queues.mdx +++ b/src/pages/docs/platform/integrations/queues.mdx @@ -313,7 +313,7 @@ amqp.connect(url, (err, conn) => { The Node.js example above shows how to consume messages from a queue using AMQP. Take note of the following: * The queue rule wraps each message in an envelope (default behavior). The first step is to parse the envelope JSON. -* The `Message.fromEncodedArray` method decodes the payload into standard [`Message`](/docs/api/realtime-sdk/types#message) objects. +* The `Message.fromEncodedArray` method decodes the payload into standard [`Message`](/docs/pub-sub/api/javascript/realtime/message) objects. * While messages is always an `Array`, each envelope currently contains only one message. -Alternatively, if it is necessary to be explicit about the connection `recoveryKey`, the connection can be recovered by providing the last value of the connection's `recoveryKey` value in the [client options](/docs/api/realtime-sdk#client-options) `recover` attribute when instantiating an SDK. +Alternatively, if it is necessary to be explicit about the connection `recoveryKey`, the connection can be recovered by providing the last value of the connection's `recoveryKey` value in the [client options](/docs/pub-sub/api/javascript/realtime/realtime-client#constructor-params)[client options](/docs/api/realtime-sdk#client-options) `recover` attribute when instantiating an SDK. ## Handling connection failures @@ -464,7 +464,7 @@ This behavior is normal and expected - these brief disconnections are not indica Some classes of errors are fatal. These cause the connection to move to the `FAILED` state. An SDK will not attempt any automatic recovery actions. For example, if your token expires and an SDK has no way to get a new token (so no `authUrl` and `authCallback`), the connection will enter the `FAILED` state -While an SDK will not automatically attempt to reconnect in the `FAILED` state, explicit calls to [`connect()`](/docs/api/realtime-sdk/connection#connect) will make the client try again. +While an SDK will not automatically attempt to reconnect in the `FAILED` state, explicit calls to [`connect()`](/docs/pub-sub/api/javascript/realtime/connection#connect)[`connect()`](/docs/api/realtime-sdk/connection#connect) will make the client try again. ### Nonfatal errors @@ -480,7 +480,7 @@ The Ably SDK will continue attempting to reconnect automatically, but mobile pla If you want to explicitly manage connections based on your app's lifecycle: -- Call [`close()`](/docs/api/realtime-sdk/connection#close) when the app enters the background if you don't need background connectivity. -- Call [`connect()`](/docs/api/realtime-sdk/connection#connect) when the app returns to the foreground to re-establish the connection. +- Call [`close()`](/docs/pub-sub/api/javascript/realtime/connection#close)[`close()`](/docs/api/realtime-sdk/connection#close) when the app enters the background if you don't need background connectivity. +- Call [`connect()`](/docs/pub-sub/api/javascript/realtime/connection#connect)[`connect()`](/docs/api/realtime-sdk/connection#connect) when the app returns to the foreground to re-establish the connection. It's good practice to call `close()` when your app no longer needs the connection, as this properly cleans up resources and removes all listeners. The connection will automatically close after about two minutes of inactivity, but explicit closure is recommended. diff --git a/src/pages/docs/liveobjects/inband-objects.mdx b/src/pages/docs/liveobjects/inband-objects.mdx index 4ffcb99845..34d2b9c88e 100644 --- a/src/pages/docs/liveobjects/inband-objects.mdx +++ b/src/pages/docs/liveobjects/inband-objects.mdx @@ -111,7 +111,7 @@ The client receives `[meta]objects` messages whenever the objects on the channel If there is a high rate of updates to the channel objects the inband messages are throttled. However in the case of `objects` mode, the client is guaranteed to receive a sequence of inband messages after the last change occurs so that the latest data is always available. -[Subscribe](/docs/api/realtime-sdk/channels#subscribe) to `[meta]objects` messages like you would any other message on the channel. For convenience, use a message name filter to only receive messages with the name `[meta]objects` in your listener: +[Subscribe](/docs/pub-sub/api/javascript/realtime/realtime-channel#subscribe)[Subscribe](/docs/api/realtime-sdk/channels#subscribe) to `[meta]objects` messages like you would any other message on the channel. For convenience, use a message name filter to only receive messages with the name `[meta]objects` in your listener: ```javascript @@ -278,7 +278,7 @@ The message `data` is a JSON object with the following property: | Property | Description | | -------- | ----------- | -| `link` | A relative URL path to fetch the current state of the channel object on the channel via the [REST API](/docs/liveobjects/rest-api-usage#fetch-channel-object). This can be used directly with the Ably REST client's [request](/docs/api/rest-sdk#request) method. | +| `link` | A relative URL path to fetch the current state of the channel object on the channel via the [REST API](/docs/liveobjects/rest-api-usage#fetch-channel-object). This can be used directly with the Ably REST client's [request](/docs/pub-sub/api/javascript/rest/rest-client#request)[request](/docs/api/rest-sdk#request) method. | diff --git a/src/pages/docs/messages/annotations.mdx b/src/pages/docs/messages/annotations.mdx index eafa3694d4..dd8fd51f18 100644 --- a/src/pages/docs/messages/annotations.mdx +++ b/src/pages/docs/messages/annotations.mdx @@ -404,7 +404,7 @@ To delete an annotation, use the `annotations.delete()` method on a channel. Pas Deleting an annotation does not remove the original annotation that was published. Instead, the deletion modifies the [annotation summary](#annotation-summaries) for that message by removing the contribution specified by the annotation. -The `clientId` specified in the [client options](/docs/api/realtime-sdk#client-options) will be associated with the published delete annotation. +The `clientId` specified in the [client options](/docs/pub-sub/api/javascript/realtime/realtime-client#constructor-params)[client options](/docs/api/realtime-sdk#client-options) will be associated with the published delete annotation. Specify the [annotation type](#annotation-types) using the `type` field of the annotation object, and optionally specify a `name` for the annotation. The `name` is used to aggregate certain annotations when producing an annotation summary. @@ -507,9 +507,9 @@ await channel.annotations.delete(message.serial, annotation) The simplest way to receive annotation updates is via annotation summaries. A message that has annotations also includes a summary, which is a synopsis of certain details of all annotations for that message. Summaries are updated in response to further annotation events for that message, and summary changes are delivered by default to subscribing clients. -When an already-existing message has an updated summary, the new version of that message will be delivered to subscribers with an [`action`](/docs/api/realtime-sdk/types#action) of `message.summary` (as opposed to `message.create` for the originally-published one), and a `serial` matching the `serial` of the original message. It will have an `annotations` field which contains a `summary` of all the annotations for the message. +When an already-existing message has an updated summary, the new version of that message will be delivered to subscribers with an [`action`](/docs/pub-sub/api/javascript/realtime/message)[`action`](/docs/api/realtime-sdk/types#action) of `message.summary` (as opposed to `message.create` for the originally-published one), and a `serial` matching the `serial` of the original message. It will have an `annotations` field which contains a `summary` of all the annotations for the message. -If you're not subscribing, you can also retrieve the latest version of a message and its summary using [`channel#getMessage`](/docs/api/rest-sdk/channels#get-message). The returned `message` contains the up-to-date `summary`, accessible via `message.annotations.summary`. Messages returned from [history](/docs/storage-history/history) also include the latest summary at the time the history request is made. +If you're not subscribing, you can also retrieve the latest version of a message and its summary using [`channel#getMessage`](/docs/pub-sub/api/javascript/rest/channel#get-message)[`channel#getMessage`](/docs/api/rest-sdk/channels#get-message). The returned `message` contains the up-to-date `summary`, accessible via `message.annotations.summary`. Messages returned from [history](/docs/storage-history/history) also include the latest summary at the time the history request is made. The value of that `summary` field is an object where the keys are the [annotation types](#annotation-types). The structure of the value of each key depends on the summarization method used, for example `total.v1` will have a `total` field, while `flag.v1` will have `total` and `clientIds` fields. @@ -803,7 +803,7 @@ await channel.annotations.subscribe(annotation_handler) ## Retrieve annotations -To retrieve all annotations that have been published for a message, use the `annotations.get()` method on a channel. Pass in either a [message](/docs/messages) instance or the `serial` of the message. This returns a [paginated result](/docs/api/realtime-sdk/types#paginated-result) containing every individual annotation event for that message, starting from the earliest. You can pass an optional `limit` to control the page size. +To retrieve all annotations that have been published for a message, use the `annotations.get()` method on a channel. Pass in either a [message](/docs/messages) instance or the `serial` of the message. This returns a [paginated result](/docs/pub-sub/api/javascript/realtime/realtime-client#PaginatedResult)[paginated result](/docs/api/realtime-sdk/types#paginated-result) containing every individual annotation event for that message, starting from the earliest. You can pass an optional `limit` to control the page size. -## Connection PropertiesARTConnection PropertiesAbly::Realtime::Connection Attributesio.ably.lib.realtime.Connection MembersIO.Ably.Realtime.Connection Properties +## Connection PropertiesARTConnection PropertiesAbly::Realtime::Connection Attributesio.ably.lib.realtime.Connection MembersIO.Ably.Realtime.Connection Properties -The `Connection` object exposes the following public propertiesattributesmembers: +The `Connection` object exposes the following public propertiesattributesmembers: -### idId +### idId A unique public identifier `String` for this connection, used to identify this member in presence events and messages. -### stateState +### stateState -The current [`io.ably.lib.realtime.ConnectionState`](#connection-state) `state`[`IO.Ably.Realtime.ConnectionState`](#connection-state) `state`[`Ably::Realtime::Connection::STATE`](#connection-state) `state`[`ARTRealtimeConnectionState`](#connection-state) `state``state String` of this Connection. See the [`Connection` states](/docs/connect/states#connection-states) for more information. +The current [`io.ably.lib.realtime.ConnectionState`](#connection-state) `state`[`IO.Ably.Realtime.ConnectionState`](#connection-state) `state`[`Ably::Realtime::Connection::STATE`](#connection-state) `state`[`ARTRealtimeConnectionState`](#connection-state) `state``state String` of this Connection. See the [`Connection` states](/docs/connect/states#connection-states) for more information. -### errorReasonreasonErrorReasonerror_reason +### errorReasonreasonErrorReasonerror_reason -When a connection failure occurs this attributememberproperty contains the [`ErrorInfo`](/docs/api/realtime-sdk/types#error-info)[`AblyException`](/docs/api/realtime-sdk/types#ably-exception). +When a connection failure occurs this attributememberproperty contains the [`ErrorInfo`](/docs/api/realtime-sdk/types#error-info)[`AblyException`](/docs/api/realtime-sdk/types#ably-exception). -### keyKey +### keyKey -A unique private connection key `String` used to recover or resume a connection, assigned by Ably. When recovering a connection explicitly, the `recoveryKey``recovery_key` is used in the `recover` [client options](/docs/api/realtime-sdk#client-options) as it contains both the `key` and the last message `serial`. +A unique private connection key `String` used to recover or resume a connection, assigned by Ably. When recovering a connection explicitly, the `recoveryKey``recovery_key` is used in the `recover` [client options](/docs/api/realtime-sdk#client-options) as it contains both the `key` and the last message `serial`. This private connection key can also be used by other REST clients to publish on behalf of this client. See the [publishing over REST on behalf of a realtime client documentation](/docs/pub-sub/advanced#publish-on-behalf) for more info. @@ -46,11 +46,11 @@ The serial number `Integer` of the last message to be received on this connectio -## Connection MethodsARTConnection MethodsAbly::Realtime::Connection Methodsio.ably.lib.realtime.Connection MethodsIO.Ably.Realtime.Connection Methods +## Connection MethodsARTConnection MethodsAbly::Realtime::Connection Methodsio.ably.lib.realtime.Connection MethodsIO.Ably.Realtime.Connection Methods -### connectConnect +### connectConnect - + `connect(): void` @@ -76,7 +76,7 @@ The serial number `Integer` of the last message to be received on this connectio -Explicitly calling `connect``Connect` is unnecessary unless the [`ClientOptions`](/docs/api/realtime-sdk/types#client-options) attribute `autoConnect``auto_connect``AutoConnect` is `false`. Unless already `connected` or `connecting`, this method causes the connection to open, entering the `connecting` state. +Explicitly calling `connect``Connect` is unnecessary unless the [`ClientOptions`](/docs/api/realtime-sdk/types#client-options) attribute `autoConnect``auto_connect``AutoConnect` is `false`. Unless already `connected` or `connecting`, this method causes the connection to open, entering the `connecting` state. @@ -100,9 +100,9 @@ Failure to connect will throw an `AblyException` with an [`errorInfo`](#error-in -### closeClose +### closeClose - + `close(): void` @@ -128,7 +128,7 @@ Failure to connect will throw an `AblyException` with an [`errorInfo`](#error-in -Causes the connection to close, entering the `closing` state. Once `closed`, the library will not attempt to re-establish the connection without an explicit call to [`connect()`](#connect)[`Connect()`](#connect)[`connect`](#connect). +Causes the connection to close, entering the `closing` state. Once `closed`, the library will not attempt to re-establish the connection without an explicit call to [`connect()`](#connect)[`Connect()`](#connect)[`connect`](#connect). @@ -142,15 +142,10 @@ Failure to close the connection will trigger the errback callbacks of the [`Defe -### onOn - -There are threetwo overloaded versions of this method: +### onOn - +There are two overloaded versions of this method: -`on(String event, listener(ConnectionStateChange stateChange))` - - `on(ConnectionEvent *event) -> yields ConnectionStateChange` @@ -184,19 +179,8 @@ The Stream returned can be subscribed for with a listener. -Register the given listener blockfunctionactionlistener for the specified [`ConnectionEvent`](#connection-event) on the `Connection`. The listener is passed a [ConnectionStateChange](#connection-state-change) object that contains the current state, previous state, and an optional reason for the event or state change. - - -`on(String[] events, listener(ConnectionStateChange stateChange))` +Register the given listener blockfunctionactionlistener for the specified [`ConnectionEvent`](#connection-event) on the `Connection`. The listener is passed a [ConnectionStateChange](#connection-state-change) object that contains the current state, previous state, and an optional reason for the event or state change. -Same as above, but registers multiple listeners, one for each event in the array. - - - - -`on(listener(ConnectionStateChange stateChange))` - - `on -> yields ConnectionStateChange` @@ -230,11 +214,7 @@ The Stream returned can be subscribed for with a listener. -Register the given listener blockfunctionactionlistener for all [ConnectionEvents](#connection-event) on the `Connection`. The listener is passed a [ConnectionStateChange](#connection-state-change) object that contains the current state, previous state, the event, and an optional reason for the event or state change. (For the `update` event, the current and previous states will be the same). - - -If an exception is thrown in the listener and bubbles up to the event emitter, it will be caught and logged at `error` level, so as not to affect other listeners for the same event - +Register the given listener blockfunctionactionlistener for all [ConnectionEvents](#connection-event) on the `Connection`. The listener is passed a [ConnectionStateChange](#connection-state-change) object that contains the current state, previous state, the event, and an optional reason for the event or state change. (For the `update` event, the current and previous states will be the same). #### Parameters @@ -245,20 +225,20 @@ If an exception is thrown in the listener and bubbles up to the event emitter, i | event | the connection event to subscribe to | [`ConnectionEvent`](#connection-event) | - + | Parameter | Description | Type | |-----------|-------------|------| -| event(s)event | the connection event(s) to subscribe tothe connection event to subscribe tothe connection event as a Symbol such as `:connected` or `ConnectionEvent` object to subscribe to | `String` or `String[]`[`ConnectionEvent`](#connection-event)[`ConnectionEvent`](#connection-event)[`ARTRealtimeConnectionEvent`](#connection-event) | -| listenerlisteneraction&blockcall | is a function of the form `function(stateChange)` to be notified for matching eventslistener to be notified for matching eventsaction to be executed for matching eventslistener block that is yielded to for matching eventscalled with matching events | function[`ConnectionStateListener`](#connection-state-listener)[`ConnectionStateChange`](#connection-state-listener)blockfunction | +| event | the connection event to subscribe tothe connection event as a Symbol such as `:connected` or `ConnectionEvent` object to subscribe to | [`ConnectionEvent`](#connection-event)[`ConnectionEvent`](#connection-event)[`ARTRealtimeConnectionEvent`](#connection-event) | +| listeneraction&blockcall | listener to be notified for matching eventsaction to be executed for matching eventslistener block that is yielded to for matching eventscalled with matching events | [`ConnectionStateListener`](#connection-state-listener)[`ConnectionStateChange`](#connection-state-listener)blockfunction | -### onceOnce +### onceOnce There are two overloaded versions of this method: - + `once(String event, listener(ConnectionStateChange stateChange))` @@ -284,9 +264,9 @@ There are two overloaded versions of this method: -Register the given listener blockfunctionactionlistener for a single occurrence of the specified [ConnectionEvent](#connection-event) on the `Connection`. Once the listener has been called, it is removed as a registered listener and will not be called again. The listener is passed a [ConnectionStateChange](#connection-state-change) object that contains the current state, previous state, the event, and an optional reason for the state change. (For the `update` event, the current and previous states will be the same). +Register the given listener blockfunctionactionlistener for a single occurrence of the specified [ConnectionEvent](#connection-event) on the `Connection`. Once the listener has been called, it is removed as a registered listener and will not be called again. The listener is passed a [ConnectionStateChange](#connection-state-change) object that contains the current state, previous state, the event, and an optional reason for the state change. (For the `update` event, the current and previous states will be the same). - + `once(listener(ConnectionStateChange stateChange))` @@ -312,28 +292,24 @@ Register the given listener blockfunc -Register the given listener blockactionlistener for a single occurrence of any [ConnectionEvent](#connection-event) on the `Connection`. Once the listener has been called, it is removed as a registered listener and will not be called again. The listener is passed a [ConnectionStateChange](#connection-state-change) object that contains the current state, previous state, and an optional reason for the state change. (For the `update` event, the current and previous states will be the same). - - -If an exception is thrown in the listener and bubbles up to the event emitter, it will be caught and logged at `error` level, so as not to affect other listeners for the same event - +Register the given listener blockactionlistener for a single occurrence of any [ConnectionEvent](#connection-event) on the `Connection`. Once the listener has been called, it is removed as a registered listener and will not be called again. The listener is passed a [ConnectionStateChange](#connection-state-change) object that contains the current state, previous state, and an optional reason for the state change. (For the `update` event, the current and previous states will be the same). #### Parameters - + | Parameter | Description | Type | |-----------|-------------|------| -| event(s)event | the connection event(s) to subscribe tothe connection event to subscribe tothe connection event as a Symbol such as `:connected` or `ConnectionEvent` object to subscribe to | `String` or `String[]`[`ConnectionEvent`](#connection-event)[`ConnectionEvent`](#connection-event)[`ARTRealtimeConnectionEvent`](#connection-event) | -| listenerlisteneraction&blockcall | is a function of the form `function(stateChange)` to be notified for a single occurrence of a matching eventlistener to be notified for a single occurrence of a matching state changeaction to be executed for matching state changeslistener block that is yielded to for a single occurrence of a matching eventcalled with matching events | function[`ConnectionStateListener`](#connection-state-listener)[`ConnectionStateChange`](#connection-state-listener)blockfunction | +| event | the connection event to subscribe tothe connection event as a Symbol such as `:connected` or `ConnectionEvent` object to subscribe to | [`ConnectionEvent`](#connection-event)[`ConnectionEvent`](#connection-event)[`ARTRealtimeConnectionEvent`](#connection-event) | +| listeneraction&blockcall | listener to be notified for a single occurrence of a matching state changeaction to be executed for matching state changeslistener block that is yielded to for a single occurrence of a matching eventcalled with matching events | [`ConnectionStateListener`](#connection-state-listener)[`ConnectionStateChange`](#connection-state-listener)blockfunction | -### offOff +### offOff -There are sixtwo overloaded versions of this method: +There are two overloaded versions of this method: - + `off(String event, listener)` @@ -359,9 +335,9 @@ There are sixblockactionlistener for the [ConnectionEvent](#connection-event). +Remove the given listener blockactionlistener for the [ConnectionEvent](#connection-event). - + `off(listener)` @@ -387,35 +363,16 @@ Remove the given listener blockaction -Remove the given listener blockactionlistener for all [ConnectionEvents](#connection-event) - - -`off(String[] states, listener)` - -Removes the given listener from all [ConnectionEvents](#connection-event) in the array. - -`off(String state)` - -Removes all listeners for a given [`ConnectionEvent`s.](#connection-event) - -`off(String[] states)` - -Removes all listeners for all [ConnectionEvents](#connection-event) in the array. - -`off()` - -Removes all listeners (including both those registered against specific events and those registered without an event). - - +Remove the given listener blockactionlistener for all [ConnectionEvents](#connection-event) #### Parameters - + | Parameter | Description | Type | |-----------|-------------|------| -| event(s)event | the connection event(s) to unsubscribe fromthe connection event to unsubscribe fromthe connection event to subscribe tothe connection event as a Symbol such as `:connected` or `ConnectionEvent` object to unsubscribe from | `String` or `String[]`[`ConnectionEvent`](#connection-event)[`ConnectionEvent`](#connection-event)[`ARTRealtimeConnectionEvent`](#connection-event) | -| listeneraction&block | is the listener function to be removedis the listener to be removedaction to be executed for matching event changesis the listener block to be removedprevious return value from a `on` or `once` call | function[`ConnectionStateListener`](#connection-state-listener)[`ConnectioneventChangeEventArgs`](#connection-state-listener)blockARTEventListener | +| event | the connection event to unsubscribe fromthe connection event to subscribe tothe connection event as a Symbol such as `:connected` or `ConnectionEvent` object to unsubscribe from | [`ConnectionEvent`](#connection-event)[`ConnectionEvent`](#connection-event)[`ARTRealtimeConnectionEvent`](#connection-event) | +| listeneraction&block | is the listener to be removedaction to be executed for matching event changesis the listener block to be removedprevious return value from a `on` or `once` call | [`ConnectionStateListener`](#connection-state-listener)[`ConnectioneventChangeEventArgs`](#connection-state-listener)blockARTEventListener | @@ -423,17 +380,12 @@ Removes all listeners (including both those registered against specific events a `streamSubscription` obtained from calling `on` can be used to cancel a listener by calling `streamSubscription.cancel`. -### pingPing +### pingPing `ping(callback(ErrorInfo err, Number responseInMilliseconds))` - - - -`ping(): Promise` - @@ -456,15 +408,7 @@ Removes all listeners (including both those registered against specific events a -When connected, sends a heartbeat ping to the Ably server and executes the callback with any error and the response time in millisecondsexecutes the callbackcalls the listeneryields the elapsed time in seconds when a heartbeat ping request is echoed from the server. This can be useful for measuring true round-trip latency to the connected Ably server. - - - -#### Returns - -Returns a promise. On success, the promise resolves with a number representing the time in seconds for the heartbeat ping request to be echoed. On failure, the promise is rejected with an [`ErrorInfo`](/docs/api/realtime-sdk/types#error-info) object that details the reason why it was rejected. - - +When connected, sends a heartbeat ping to the Ably server and executes the callbackcalls the listeneryields the elapsed time in seconds when a heartbeat ping request is echoed from the server. This can be useful for measuring true round-trip latency to the connected Ably server. @@ -478,46 +422,6 @@ Failure to receive a heartbeat ping will trigger the errback callbacks of the [` - - -### listeners - -`listeners(eventName?): null | connectionEventCallback[]` - -Returns the listeners for the specified [`ConnectionEvent`](#connection-event). - - - - - -### whenState - -`whenState(targetState): Promise` - -If the connection is already in a given state, returns a promise which immediately resolves to `null`. Otherwise calls [`once`](#once) to return a promise which resolves the next time the connection transitions to the given state. - -#### Parameters - -| Parameter | Description | Type | -|-----------|-------------|------| -| targetState | The [`ConnectionState`](#connection-state) to wait for | `ConnectionState` | - -#### Returns - -Returns a promise. If the connection is already in the given state, the promise will immediately resolve to `null`. If not, it will call [`once()`](#once) to return a promise which resolves the next time the connection transitions to the given state. - - - - - -### createRecoveryKey - -`createRecoveryKey(): null | string` - -Generates a string that can be used by another client to recover the current connection's state using the `recover` property of the [`ClientOptions`](/docs/api/realtime-sdk/types#client-options) object. See [connection state recover options](/connect/states#connection-state-recover-options) for more information. - - - ## Related types @@ -540,28 +444,7 @@ public interface CompletionListener { -### ConnectionStateARTRealtimeConnectionStateConnection::STATE Enumio.ably.lib.realtime.ConnectionState EnumIO.Ably.Realtime.ConnectionState Enumably.ConnectionState Enum - - - -`ConnectionState` is a String with a value matching any of the [`Realtime Connection` states](/docs/connect/states). - - -```javascript -var ConnectionStates = [ - 'initialized', - 'connecting', - 'connected', - 'disconnected', - 'suspended', - 'closing', - 'closed', - 'failed' -] -``` - - - +### ARTRealtimeConnectionStateConnection::STATE Enumio.ably.lib.realtime.ConnectionState EnumIO.Ably.Realtime.ConnectionState Enumably.ConnectionState Enum @@ -718,29 +601,7 @@ enum ConnectionState { -### ConnectionEventARTRealtimeConnectionEventConnection::EVENT Enumio.ably.lib.realtime.ConnectionEvent EnumIO.Ably.Realtime.ConnectionEvent Enumably.ConnectionEvent Enum - - - -`ConnectionEvent` is a String that can be emitted as an event on the `Connection` object; either a [`Realtime Connection` state](/docs/connect/states) or an `update` event. - - -```javascript -var ConnectionEvents = [ - 'initialized', - 'connecting', - 'connected', - 'disconnected', - 'suspended', - 'closing', - 'closed', - 'failed', - 'update' -] -``` - - - +### ARTRealtimeConnectionEventConnection::EVENT Enumio.ably.lib.realtime.ConnectionEvent EnumIO.Ably.Realtime.ConnectionEvent Enumably.ConnectionEvent Enum @@ -921,35 +782,18 @@ public interface ConnectionStateListener { -### ConnectionStateChange ObjectARTConnectionStateChangeio.ably.lib.realtime.ConnectionStateListener.ConnectionStateChangeConnectionStateChangeIO.Ably.Realtime.ConnectionStateChangeably.ConnectionStateChange +### ARTConnectionStateChangeio.ably.lib.realtime.ConnectionStateListener.ConnectionStateChangeConnectionStateChangeIO.Ably.Realtime.ConnectionStateChangeably.ConnectionStateChange -A `io.ably.lib.realtime.ConnectionStateListener.ConnectionStateChange``Ably::Models::ConnectionStateChange``ARTConnectionStateChange``IO.Ably.Realtime.ConnectionStateChange``ConnectionStateChange` is a type encapsulating state change information emitted by the [`Connection`](/docs/api/realtime-sdk/connection) object. See [`Connection#on`](/docs/api/realtime-sdk/connection#on) to register a listener for one or more events. +A `io.ably.lib.realtime.ConnectionStateListener.ConnectionStateChange``Ably::Models::ConnectionStateChange``ARTConnectionStateChange``IO.Ably.Realtime.ConnectionStateChange``ConnectionStateChange` is a type encapsulating state change information emitted by the [`Connection`](/docs/api/realtime-sdk/connection) object. See [`Connection#on`](/docs/api/realtime-sdk/connection#on) to register a listener for one or more events. -#### PropertiesMembersAttributes +#### PropertiesMembersAttributes | Property | Description | Type | |----------|-------------|------| -| currentCurrent | the new state | [State `String`](/docs/api/realtime-sdk/types#connection-state)[`Connection::STATE`](/docs/api/realtime-sdk/types#connection-state)[`ConnectionState`](/docs/api/realtime-sdk/types#connection-state) | -| previousPrevious | the previous state. (for the `update` event, this will be equal to the `current` state) | [State `String`](/docs/api/realtime-sdk/types#connection-state)[`Connection::STATE`](/docs/api/realtime-sdk/types#connection-state)[`ConnectionState`](/docs/api/realtime-sdk/types#connection-state) | -| eventEvent | the event that triggered this state change | [`ConnectionEvent`Connection::EVENT](/docs/api/realtime-sdk/types#connection-event) | -| reasonReason | an [`ErrorInfo`](#error-info) containing any information relating to the transition | [`ErrorInfo`](/docs/api/realtime-sdk/types#error-info) | -| retryInretry_inRetryIn | Duration upon which the library will retry a connection where applicable, as millisecondssecondsa `Timespan` | `Integer``Timespan``Long Integer` | - -### LastConnectionDetails - - - -A `LastConnectionDetails` object provides details on the last connection in a browser environment persisted when the `window beforeunload` fired. This object is provided to the callback specified in the `recover` attribute of [`ClientOptions`](/docs/api/realtime-sdk/types#client-options). The callback in turn instructs the client library whether the connection should be recovered or not. See [connection state recovery](/docs/connect/states) for more information. +| currentCurrent | the new state | [State `String`](/docs/api/realtime-sdk/types#connection-state)[`Connection::STATE`](/docs/api/realtime-sdk/types#connection-state)[`ConnectionState`](/docs/api/realtime-sdk/types#connection-state) | +| previousPrevious | the previous state. (for the `update` event, this will be equal to the `current` state) | [State `String`](/docs/api/realtime-sdk/types#connection-state)[`Connection::STATE`](/docs/api/realtime-sdk/types#connection-state)[`ConnectionState`](/docs/api/realtime-sdk/types#connection-state) | +| eventEvent | the event that triggered this state change | [`ConnectionEvent`Connection::EVENT](/docs/api/realtime-sdk/types#connection-event) | +| reasonReason | an [`ErrorInfo`](#error-info) containing any information relating to the transition | [`ErrorInfo`](/docs/api/realtime-sdk/types#error-info) | +| retryInretry_inRetryIn | Duration upon which the library will retry a connection where applicable, as millisecondssecondsa `Timespan` | `Integer``Timespan``Long Integer` | -Please note that as [`sessionStorage`](https://www.w3.org/TR/webstorage/) is used to persist the `LastConnectionDetails` between page reloads, it is only available for pages in the same origin and top-level browsing context. -#### Properties - -| Property | Description | Type | -|----------|-------------|------| -| recoveryKey | An opaque string obtained from the [recoveryKey](/docs/api/realtime-sdk/connection#recovery-key) attribute of the [Connection object](/docs/api/realtime-sdk/connection) before the page was unloaded. This property is used by the library to recover the connection | `String` | -| disconnectedAt | the time at which the previous library was abruptly disconnected before the page was unloaded. This is represented as milliseconds since epoch | `Integer` | -| location | a clone of [`location`](https://www.w3.org/TR/html5/browsers.html#the-location-interface) object of the previous page's `document` object before the page was unloaded. A common use case for this attribute is to ensure that the previous page URL is the same as the current URL before allowing the connection to be recovered. For example, you may want the connection to be recovered only for page reloads, but not when a user navigates to a different page | `String` | -| clientId | the [`clientId`](/docs/api/realtime-sdk/authentication/#client-id) of the [client's Auth object](/docs/api/realtime-sdk/authentication) before the page was unloaded. A common use case for this attribute is to ensure that the current logged in user's `clientId` matches the previous connection's `clientId` before allowing the connection to be recovered. Ably prohibits changing a `clientId` for an existing connection, so any mismatch in `clientId` during a recover will result in the connection moving to the failed state | `String` | - - diff --git a/src/pages/docs/api/realtime-sdk/encryption.mdx b/src/pages/docs/api/realtime-sdk/encryption.mdx index 0df9000cde..ea119bb781 100644 --- a/src/pages/docs/api/realtime-sdk/encryption.mdx +++ b/src/pages/docs/api/realtime-sdk/encryption.mdx @@ -19,17 +19,12 @@ redirect_from: We've updated the style and readability of our API references, starting with JavaScript. Check out the [Pub/Sub JavaScript SDK API references](/docs/pub-sub/api/javascript/realtime/crypto) in their new location. -The `Ably.Realtime.Crypto``Ably::Util::Crypto``io.ably.lib.util.Crypto``ARTCrypto` object exposes the following public methods: +The `Ably.Realtime.Crypto``Ably::Util::Crypto``io.ably.lib.util.Crypto``ARTCrypto` object exposes the following public methods: ## Methods -### getDefaultParamsget_default_paramsGetDefaultParams +### getDefaultParamsget_default_paramsGetDefaultParams - - -`Crypto.getDefaultParams(Object params): CipherParams` - - `CipherParams Crypto.get_default_params(Hash params)` @@ -53,40 +48,20 @@ The `Ably.Realtime.Crypto` or when setting channel options with `channel.setOptions()`. +You will rarely need to call this yourself, since the client library will handle it for you if you specify `cipher` params when initializing a channel (as in the [getting started example](/docs/channels/options/encryption)). #### Parameters | Parameter | Description | Type | |-----------|-------------|------| -| paramsarguments | The cipher paramsarguments that you want to specify. It must at a minimum include a `key`, which should be either a binary (`byte[]``ArrayBuffer` or `Uint8Array``Buffer`byte array`NSData`) or a base64-encoded `NS``String`. | `Object``Hash``Param[]``[NSObject : AnyObject]``byte[] key`, `byte[] iv`, `CipherMode? mode` | +| paramsarguments | The cipher paramsarguments that you want to specify. It must at a minimum include a `key`, which should be either a binary (`byte[]`byte array`NSData`) or a base64-encoded `NS``String`. | `Hash``Param[]``[NSObject : AnyObject]``byte[] key`, `byte[] iv`, `CipherMode? mode` | #### Returns -On success, the method returns a complete [`CipherParams`](#cipher-params) object. Failure will raise an [`AblyException`](/docs/api/realtime-sdk/types#ably-exception) exception. +On success, the method returns a complete [`CipherParams`](#cipher-params) object. Failure will raise an [`AblyException`](/docs/api/realtime-sdk/types#ably-exception) exception. #### Example - - -```javascript - const cipherParams = Ably.Realtime.Crypto.getDefaultParams({ key: }); - const channelOpts = { cipher: cipherParams }; - const channel = realtime.channels.get('{{RANDOM_CHANNEL_NAME}}', channelOpts); -``` - - - - - -```nodejs - const cipherParams = Ably.Realtime.Crypto.getDefaultParams({ key: }); - const channelOpts = { cipher: cipherParams }; - const channel = realtime.channels.get('{{RANDOM_CHANNEL_NAME}}', channelOpts); -``` - - - ```ruby @@ -140,22 +115,12 @@ let channel = realtime.channels.get("{{RANDOM_CHANNEL_NAME}}", options: options) -### generateRandomKeygenerate_random_keyGenerateRandomKey +### generateRandomKeygenerate_random_keyGenerateRandomKey `Crypto.generateRandomKey(Int keyLength?, callback(ErrorInfo err, Buffer key))` - - - -`Crypto.generateRandomKey(Number keyLength?): Promise` - - - - -`Crypto.generateRandomKey(Number keyLength?): Promise` - @@ -182,11 +147,11 @@ This call obtains a randomly-generated binary key of the specified key length. #### Parameters - + | Parameter | Description | Type | |-----------|-------------|------| -| keyLengthkey_length | Optional. The length of key to generate. For AES, this should be either 128 or 256. If unspecified, defaults to 256. | `Int``Number` | +| keyLengthkey_length | Optional. The length of key to generate. For AES, this should be either 128 or 256. If unspecified, defaults to 256. | `Int` | @@ -199,14 +164,6 @@ This call obtains a randomly-generated binary key of the specified key length. - - -#### Returns - -Returns a promise. On success, the promise is fulfilled with the generated key as an `ArrayBuffer`a `Buffer`. On failure, the promise is rejected with an [`ErrorInfo`](/docs/api/realtime-sdk/types#error-info) object that details the reason why it was rejected. - - - #### Returns @@ -217,24 +174,6 @@ On success, the method returns the generated key as a `by #### Example - - -```javascript - const key = await Ably.Realtime.Crypto.generateRandomKey(256); - const channel = realtime.channels.get('{{RANDOM_CHANNEL_NAME}}', { cipher: { key: key } }); -``` - - - - - -```nodejs - const key = await Ably.Realtime.Crypto.generateRandomKey(256); - const channel = realtime.channels.get('{{RANDOM_CHANNEL_NAME}}', { cipher: { key: key } }); -``` - - - ```ruby @@ -286,13 +225,9 @@ let channel = realtime.channels.get("{{RANDOM_CHANNEL_NAME}}", options: options) ## Related types -### ChannelOptions ObjectARTChannelOptionsChannelOptions Hashio.ably.types.ChannelOptionsIO.Ably.ChannelOptions +### ChannelOptions ObjectARTChannelOptionsChannelOptions Hashio.ably.types.ChannelOptionsIO.Ably.ChannelOptions -Channel options are used for setting [channel parameters](/docs/channels/options) and [configuring encryption](/docs/channels/options/encryption). - - -`ChannelOptions`, a plain JavaScript object, may optionally be specified when instancing a [`Channel`](/docs/channels), and this may be used to specify channel-specific options. The following attributes can be defined on the object: - +Channel options are used for setting [channel parameters](/docs/channels/options) and [configuring encryption](/docs/channels/options/encryption). `ChannelOptions`, a Hash object, may optionally be specified when instancing a [`Channel`](/docs/channels), and this may be used to specify channel-specific options. The following key symbol values can be added to the Hash: @@ -306,14 +241,14 @@ Channel options are used for -#### PropertiesMembersAttributes +#### PropertiesMembersAttributes - + | Property | Description | Type | |----------|-------------|------| -| paramsParams | Optional [parameters](/docs/channels/options) which specify behaviour of the channel. | `Map``JSON Object` | -| cipherCipherParams | Requests encryption for this channel when not null, and specifies encryption-related parameters (such as algorithm, chaining mode, key length and key). See [an example](/docs/channels/options/encryption). Must contain at a minimum a `key`. | [`CipherParams`](/docs/api/realtime-sdk/encryption#cipher-params) or options object or `Param[]` or options hash | +| paramsParams | Optional [parameters](/docs/channels/options) which specify behaviour of the channel. | `Map``JSON Object` | +| cipherCipherParams | Requests encryption for this channel when not null, and specifies encryption-related parameters (such as algorithm, chaining mode, key length and key). See [an example](/docs/channels/options/encryption). Must contain at a minimum a `key`. | [`CipherParams`](/docs/api/realtime-sdk/encryption#cipher-params) or `Param[]` or options hash | @@ -345,22 +280,22 @@ A helper method to generate a `ChannelOptions` for the simple case where you onl On success, the method returns a complete `ChannelOptions` object. Failure will raise an [`AblyException`](/docs/api/realtime-sdk/types#ably-exception). -### CipherParamsARTCipherParamsCipherParams Hashio.ably.lib.util.Crypto.CipherParamsIO.Ably.CipherParams +### CipherParamsARTCipherParamsCipherParams Hashio.ably.lib.util.Crypto.CipherParamsIO.Ably.CipherParams A `CipherParams` contains configuration options for a channel cipher, including algorithm, mode, key length and key. Ably client libraries currently support AES with CBC, PKCS#7 with a default key length of 256 bits. All implementations also support AES128. -Individual client libraries may support either instancing a `CipherParams` directly, using [`Crypto.getDefaultParams()`](/docs/api/realtime-sdk/encryption#get-default-params)[`Crypto.GetDefaultParams()`](/docs/api/realtime-sdk/encryption#get-default-params)[`Crypto.get_default_params()`](/docs/api/realtime-sdk/encryption#get-default-params), or generating one automatically when initializing a channel, as in [this example](/docs/channels/options/encryption). +Individual client libraries may support either instancing a `CipherParams` directly, using [`Crypto.getDefaultParams()`](/docs/api/realtime-sdk/encryption#get-default-params)[`Crypto.GetDefaultParams()`](/docs/api/realtime-sdk/encryption#get-default-params)[`Crypto.get_default_params()`](/docs/api/realtime-sdk/encryption#get-default-params), or generating one automatically when initializing a channel, as in [this example](/docs/channels/options/encryption). -#### PropertiesMembersAttributes +#### PropertiesMembersAttributes - + | Property | Description | Type | |----------|-------------|------| -| keyKey:key | The secret key used for encryption and decryption. Can be binary or base64-encoded. | `byte[]``ArrayBuffer` or `Uint8Array``Buffer`byte array`NSData``String` or base64-encoded `NS``String` | -| algorithm:algorithmAlgorithm | The name of the algorithm in the default system provider, or the lower-cased version of it; eg "aes" or "AES".
_Default: AES_. | `String` | -| keyLength:key_lengthKeyLength | The key length in bits of the cipher, either 128 or 256.
_Default: 256_. | `Integer` | -| mode:modeMode | The cipher mode.
_Default: CBC_. | `String``CipherMode` | +| keyKey:key | The secret key used for encryption and decryption. Can be binary or base64-encoded. | `byte[]`byte array`NSData``String` or base64-encoded `NS``String` | +| algorithm:algorithmAlgorithm | The name of the algorithm in the default system provider, or the lower-cased version of it; eg "aes" or "AES".
_Default: AES_. | `String` | +| keyLength:key_lengthKeyLength | The key length in bits of the cipher, either 128 or 256.
_Default: 256_. | `Integer` | +| mode:modeMode | The cipher mode.
_Default: CBC_. | `String``CipherMode` | diff --git a/src/pages/docs/api/realtime-sdk/history.mdx b/src/pages/docs/api/realtime-sdk/history.mdx index ba058e88d3..c4d5b0abd4 100644 --- a/src/pages/docs/api/realtime-sdk/history.mdx +++ b/src/pages/docs/api/realtime-sdk/history.mdx @@ -24,13 +24,8 @@ The [Realtime `Channel` object](/docs/channels) exposes the following public met ### Methods -### historyHistory +### historyHistory - - -`history(Object params?): Promise>` - - `Task> HistoryAsync(PaginatedRequestParams dataQuery, bool untilAttach = false);` @@ -56,11 +51,11 @@ Gets a [paginated](#paginated-result) set of historical messages for this channe #### Parameters - + | Parameter | Description | Type | |-----------|-------------|------| -| paramsoptionquery | an optional object containing the query parametersan optional array containing the query parametersan optional object containing the query parameters | `Object`[`Param[]`](#param)[`PaginatedRequestParams`](#paginated-request-params) | +| optionquery | an optional array containing the query parametersan optional object containing the query parameters | [`Param[]`](#param)[`PaginatedRequestParams`](#paginated-request-params) | @@ -73,17 +68,17 @@ Gets a [paginated](#paginated-result) set of historical messages for this channe -#### `params` parameters`options` parameters`options` parameters`ARTRealtimeHistoryQuery` properties`PaginatedRequestParams` properties +#### `options` parameters`options` parameters`ARTRealtimeHistoryQuery` properties`PaginatedRequestParams` properties - + | Property | Description | Type | |----------|-------------|------| -| start:startstart | Earliest time in milliseconds since the epoch for any messages retrieved.Earliest `Time` or time in milliseconds since the epoch for any messages retrieved.Earliest time in milliseconds since the epoch for any messages retrieved.
_Default: beginning of time_ | `Number``Int` or `Time``Long` | -| end:endend | Latest time in milliseconds since the epoch for any messages retrieved.Latest `Time` or time in milliseconds since the epoch for any messages retrieved.Latest time in milliseconds since the epoch for any messages retrieved.
_Default: current time_ | `Number``Int` or `Time``Long` | -| direction:directiondirection | `forwards` or `backwards`.`:forwards` or `:backwards`.`forwards` or `backwards`.
_Default: `backwards``:backwards`_ | `String``Symbol` | -| limit:limitlimit | Maximum number of messages to retrieve per page, up to 1,000.
_Default: `100`_ | `Number``Integer` | -| untilAttach:until_attach | when true, ensures message history is up until the point of the channel being attached. See [continuous history](/docs/storage-history/history#continuous-history) for more info. Requires the `direction` to be `backwards` (the default). If the `Channel` is not attached, or if `direction` is set to `forwards`, this option will result in an error.
_Default: `false`_ | `Boolean` | +| :startstart | Earliest `Time` or time in milliseconds since the epoch for any messages retrieved.Earliest time in milliseconds since the epoch for any messages retrieved.
_Default: beginning of time_ | `Int` or `Time``Long` | +| :endend | Latest `Time` or time in milliseconds since the epoch for any messages retrieved.Latest time in milliseconds since the epoch for any messages retrieved.
_Default: current time_ | `Int` or `Time``Long` | +| :directiondirection | `:forwards` or `:backwards`.`forwards` or `backwards`.
_Default: `backwards``:backwards`_ | `String``Symbol` | +| :limitlimit | Maximum number of messages to retrieve per page, up to 1,000.
_Default: `100`_ | `Integer` | +| untilAttach:until_attach | when true, ensures message history is up until the point of the channel being attached. See [continuous history](/docs/storage-history/history#continuous-history) for more info. Requires the `direction` to be `backwards` (the default). If the `Channel` is not attached, or if `direction` is set to `forwards`, this option will result in an error.
_Default: `false`_ | `Boolean` | @@ -99,14 +94,6 @@ Gets a [paginated](#paginated-result) set of historical messages for this channe - - -#### Returns - -Returns a promise. On success, the promise is fulfilled with a [`PaginatedResult`](#paginated-result) encapsulating an array of [`Message`](#message) 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`](/docs/api/realtime-sdk/types#error-info) object that details the reason why it was rejected. - - - #### Callback result @@ -159,13 +146,8 @@ Failure to retrieve the message history will trigger the `errback` callbacks of -### historyHistory +### historyHistory - - -`history(Object params?): Promise>` - - `Task> HistoryAsync(PaginatedRequestParams query, bool untilAttach = false [deprecated])` @@ -191,11 +173,11 @@ Gets a [paginated](#paginated-result) set of historical presence events for this #### Parameters - + | Parameter | Description | Type | |-----------|-------------|------| -| paramsoptionquery | an optional object containing the query parameters, as specified below. | `Object`[`Param[]`](#param)[`PaginatedRequestParams`](/docs/api/realtime-sdk/history#paginated-request-params) | +| optionquery | an optional object containing the query parameters, as specified below. | [`Param[]`](#param)[`PaginatedRequestParams`](/docs/api/realtime-sdk/history#paginated-request-params) | @@ -208,25 +190,17 @@ Gets a [paginated](#paginated-result) set of historical presence events for this -#### `params` parameters`options` parameters`options` parameters`ARTRealtimeHistoryQuery` properties`PaginatedRequestParams` properties +#### `options` parameters`options` parameters`ARTRealtimeHistoryQuery` properties`PaginatedRequestParams` properties - + | Property | Description | Type | |----------|-------------|------| -| start:startStart | Earliest time in milliseconds since the epoch for any presence events retrieved.Earliest `Time` or time in milliseconds since the epoch for any presence events retrieved.Earliest `DateTimeOffset` or time in milliseconds since the epoch for any presence events retrieved.
_Default: beginning of time_ | `Number``Int` or `Time``Long``DateTimeOffset` | -| end:endEnd | Latest time in milliseconds since the epoch for any presence events retrieved.Latest `Time` or time in milliseconds since the epoch for any presence events retrieved.Latest `DateTimeOffset` or time in milliseconds since the epoch for any presence events retrieved.
_Default: current time_ | `Number``Int` or `Time``Long``DateTimeOffset` | -| direction:directionDirection | `forwards` or `backwards`.`:forwards` or `:backwards`.
_Default: `backwards``:backwards`_ | `String``Symbol``Direction` enum | -| limit:limitLimit | Maximum number of presence events to retrieve up to 1,000.
_Default: `100`_ | `Number``Integer` | -| untilAttach:until_attach | when true, ensures presence message history is up until the point of the channel being attached. See [continuous history](/docs/storage-history/history#continuous-history) for more info. Requires the `direction` to be `backwards` (the default). If the `Channel` is not attached, or if `direction` is set to `forwards`, this option will result in an error.
_Default: `false`_ | `Boolean` | - - - - - -#### Returns - -Returns a promise. On success, the promise is fulfilled with a [`PaginatedResult`](#paginated-result) encapsulating an array of [`PresenceMessage`](#presence-message) 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`](/docs/api/realtime-sdk/types#error-info) object that details the reason why it was rejected. +| start:startStart | Earliest time in milliseconds since the epoch for any presence events retrieved.Earliest `Time` or time in milliseconds since the epoch for any presence events retrieved.Earliest `DateTimeOffset` or time in milliseconds since the epoch for any presence events retrieved.
_Default: beginning of time_ | `Int` or `Time``Long``DateTimeOffset` | +| end:endEnd | Latest time in milliseconds since the epoch for any presence events retrieved.Latest `Time` or time in milliseconds since the epoch for any presence events retrieved.Latest `DateTimeOffset` or time in milliseconds since the epoch for any presence events retrieved.
_Default: current time_ | `Int` or `Time``Long``DateTimeOffset` | +| direction:directionDirection | `forwards` or `backwards`.`:forwards` or `:backwards`.
_Default: `backwards``:backwards`_ | `String``Symbol``Direction` enum | +| limit:limitLimit | Maximum number of presence events to retrieve up to 1,000.
_Default: `100`_ | `Integer` | +| untilAttach:until_attach | when true, ensures presence message history is up until the point of the channel being attached. See [continuous history](/docs/storage-history/history#continuous-history) for more info. Requires the `direction` to be `backwards` (the default). If the `Channel` is not attached, or if `direction` is set to `forwards`, this option will result in an error.
_Default: `false`_ | `Boolean` | @@ -276,31 +250,12 @@ Failure to retrieve the presence event history will trigger the `errback` callba ## Related types -### MessageARTMessageAbly::Models::Message Enumio.ably.lib.types.MessageIO.Ably.Message +### ARTMessageAbly::Models::Message Enumio.ably.lib.types.MessageIO.Ably.Message A `Message` represents an individual message that is sent to or received from Ably. #### Properties - - -| Property | Description | Type | -|----------|-------------|------| -| name | The event name, if provided. | `String` | -| data | The message payload, if provided. | `String`, `StringBuffer`, `JSON Object` | -| extras | Metadata and/or ancillary payloads, if provided. Valid payloads include [`push`](/docs/push/publish#payload), `headers` (a map of strings to strings for arbitrary customer-supplied metadata), [`ephemeral`](/docs/pub-sub/advanced#ephemeral), and [`privileged`](/docs/platform/integrations/skip-integrations) objects. | `JSON Object` | -| id | A Unique ID assigned by Ably to this message. | `String` | -| clientId | The client ID of the publisher of this message. | `String` | -| connectionId | The connection ID of the publisher of this message. | `String` | -| connectionKey | A connection key, which can optionally be included for a REST publish as part of the [publishing on behalf of a realtime client functionality](/docs/pub-sub/advanced#publish-on-behalf). | `String` | -| timestamp | Timestamp when the message was first received by the Ably, as milliseconds since the epoch. | `Integer` | -| encoding | This will typically be empty as all messages received from Ably are automatically decoded client-side using this value. However, if the message encoding cannot be processed, this attribute will contain the remaining transformations not applied to the `data` payload. | `String` | -| action | The action type of the message, one of the [`MessageAction`](/docs/api/realtime-sdk/types#message-action) enum values. | `int enum { MESSAGE_CREATE, MESSAGE_UPDATE, MESSAGE_DELETE, META, MESSAGE_SUMMARY }` | -| serial | A server-assigned identifier that will be the same in all future updates of this message. It can be used to add annotations to a message. Serial will only be set if you enable annotations in [rules](/docs/channels#rules). | `String` | -| annotations | An object containing information about annotations that have been made to the object. | [`MessageAnnotations`](/docs/api/realtime-sdk/types#message-annotations) | - - - | Property | Description | Type | @@ -321,7 +276,7 @@ A `Message` represents an individual message that is sent to or received from Ab #### Message.fromEncoded - + `Message.fromEncoded(Object encodedMsg, ChannelOptions channelOptions?) → Message` @@ -342,7 +297,7 @@ A [`Message`](/docs/api/realtime-sdk/types#message) object #### Message.fromEncodedArray - + `Message.fromEncodedArray(Object[] encodedMsgs, ChannelOptions channelOptions?) → Message[]` @@ -361,7 +316,7 @@ A static factory method to create an array of [`Messages`](/docs/api/realtime-sd An `Array` of [`Message`](/docs/api/realtime-sdk/types#message) objects -### PresenceMessageARTPresenceMessageAbly::Models::PresenceMessage Enumio.ably.lib.types.PresenceMessageIO.Ably.PresenceMessage +### ARTPresenceMessageAbly::Models::PresenceMessage Enumio.ably.lib.types.PresenceMessageIO.Ably.PresenceMessage A `PresenceMessage` represents an individual presence update that is sent to or received from Ably. @@ -369,20 +324,20 @@ A `PresenceMessage` represents an individual presence update that is sent to or | Property | Description | Type | |----------|-------------|------| -| actionAction | the event signified by a PresenceMessage. See [`PresenceMessage.action`](/docs/api/realtime-sdk/types#presence-action) | `enum { ABSENT, PRESENT, ENTER, LEAVE, UPDATE }``enum { Absent, Present, Enter, Leave, Update }``int enum { ABSENT, PRESENT, ENTER, LEAVE, UPDATE }``enum { :absent, :present, :enter, :leave, :update }``ARTPresenceAction` | -| dataData | The presence update payload, if provided | `String`, `ByteArray`, `JSONObject`, `JSONArray``String`, `byte[]`, plain C# object that can be converted to Json`String`, `StringBuffer`, `JSON Object``String`, `Binary` (ASCII-8BIT String), `Hash`, `Array``String`, `NSData`, `Dictionary`, `Array``NSString *`, `NSData *`, `NSDictionary *`, `NSArray *` | -| extrasExtras | Metadata and/or ancillary payloads, if provided. The only currently valid payloads for extras are the [`push`](/docs/push/publish#sub-channels), [`ref`](/docs/messages#interactions) and [`privileged`](/docs/platform/integrations/skip-integrations) objects. | `JSONObject`, `JSONArray`plain C# object that can be converted to Json`JSON Object``Hash`, `Array``Dictionary`, `Array``NSDictionary *`, `NSArray *` | -| idId | Unique ID assigned by Ably to this presence update | `String` | -| clientIdclient_idClientIdclientId | The client ID of the publisher of this presence update | `String` | -| connectionIdconnection_idConnectionIdconnectionId | The connection ID of the publisher of this presence update | `String` | -| timestampTimestamp | Timestamp when the presence update was received by Ably, as milliseconds since the epoch. | `Integer``Long Integer``DateTimeOffset``Time``NSDate` | -| encodingEncoding | This will typically be empty as all presence updates received from Ably are automatically decoded client-side using this value. However, if the message encoding cannot be processed, this attribute will contain the remaining transformations not applied to the `data` payload | `String` | +| actionAction | the event signified by a PresenceMessage. See [`PresenceMessage.action`](/docs/api/realtime-sdk/types#presence-action) | `enum { ABSENT, PRESENT, ENTER, LEAVE, UPDATE }``enum { Absent, Present, Enter, Leave, Update }``enum { :absent, :present, :enter, :leave, :update }``ARTPresenceAction` | +| dataData | The presence update payload, if provided | `String`, `ByteArray`, `JSONObject`, `JSONArray``String`, `byte[]`, plain C# object that can be converted to Json`String`, `Binary` (ASCII-8BIT String), `Hash`, `Array``String`, `NSData`, `Dictionary`, `Array``NSString *`, `NSData *`, `NSDictionary *`, `NSArray *` | +| extrasExtras | Metadata and/or ancillary payloads, if provided. The only currently valid payloads for extras are the [`push`](/docs/push/publish#sub-channels), [`ref`](/docs/messages#interactions) and [`privileged`](/docs/platform/integrations/skip-integrations) objects. | `JSONObject`, `JSONArray`plain C# object that can be converted to Json`Hash`, `Array``Dictionary`, `Array``NSDictionary *`, `NSArray *` | +| idId | Unique ID assigned by Ably to this presence update | `String` | +| client_idClientIdclientId | The client ID of the publisher of this presence update | `String` | +| connection_idConnectionIdconnectionId | The connection ID of the publisher of this presence update | `String` | +| timestampTimestamp | Timestamp when the presence update was received by Ably, as milliseconds since the epoch. | `Long Integer``DateTimeOffset``Time``NSDate` | +| encodingEncoding | This will typically be empty as all presence updates received from Ably are automatically decoded client-side using this value. However, if the message encoding cannot be processed, this attribute will contain the remaining transformations not applied to the `data` payload | `String` | #### PresenceMessage constructors #### PresenceMessage.fromEncoded - + `PresenceMessage.fromEncoded(Object encodedPresMsg, ChannelOptions channelOptions?) → PresenceMessage` @@ -403,7 +358,7 @@ A [`PresenceMessage`](/docs/api/realtime-sdk/types#presence-message) object #### PresenceMessage.fromEncodedArray - + `PresenceMessage.fromEncodedArray(Object[] encodedPresMsgs, ChannelOptions channelOptions?) → PresenceMessage[]` @@ -422,25 +377,7 @@ A static factory method to create an array of [`PresenceMessages`](/docs/api/rea An `Array` of [`PresenceMessage`](/docs/api/realtime-sdk/types#presence-message) objects -### Presence actionARTPresenceActionio.ably.lib.types.PresenceMessage.ActionAbly::Models::PresenceMessage::ACTIONIO.Ably.PresenceAction - - - -`Presence` `action` is a String with a value matching any of the [Realtime Presence states & events](/docs/presence-occupancy/presence#trigger-events). - - -```javascript -var PresenceActions = [ - 'absent', // (reserved for internal use) - 'present', - 'enter', - 'leave', - 'update' -] -``` - - - +### ARTPresenceActionio.ably.lib.types.PresenceMessage.ActionAbly::Models::PresenceMessage::ACTIONIO.Ably.PresenceAction @@ -577,7 +514,7 @@ enum ARTPresenceAction : UInt { -### PaginatedResultARTPaginatedResultAbly::Models::PaginatedResultio.ably.lib.types.PaginatedResultIO.Ably.PaginatedResult +### ARTPaginatedResultAbly::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](/docs/api/rest-api/#pagination) is accompanied by metadata that indicates the relative queries available to the `PaginatedResult` object. @@ -585,19 +522,11 @@ A `PaginatedResult` is a type that represents a page of results for all message | Property | Description | Type | |----------|-------------|------| -| itemsItems | contains the current page of results (for example an Array of [`Message`](#message) or [`PresenceMessage`](#presence-message) objects for a channel history request) | `Array ``List ` | +| itemsItems | contains the current page of results (for example an Array of [`Message`](#message) or [`PresenceMessage`](#presence-message) objects for a channel history request) | `Array ``List ` | #### Methods -#### firstFirst - - - -`first(): Promise` - -Returns a promise. On success, the promise is fulfilled with a new [`PaginatedResult`](/docs/api/realtime-sdk/history#paginated-result) for the first page of results. On failure, the promise is rejected with an [`ErrorInfo`](/docs/api/realtime-sdk/types#error-info) object that details the reason why it was rejected. - - +#### firstFirst @@ -624,13 +553,8 @@ Returns a new `PaginatedResult` for the first page of results. The method is asy -#### hasNextHasNexthas_next? - - - -`Boolean hasNext()` +#### hasNextHasNexthas_next? - `Boolean HasNext()` @@ -647,15 +571,10 @@ Returns a new `PaginatedResult` for the first page of results. The method is asy -Returns `true` if there are more pages available by calling `next``Next` and returns `false` if this page is the last page available. - -#### isLastIsLastlast? +Returns `true` if there are more pages available by calling `next``Next` and returns `false` if this page is the last page available. - - -`Boolean isLast()` +#### isLastIsLastlast? - `Boolean IsLast()` @@ -672,17 +591,9 @@ Returns `true` if there are more pages available by calling `next``Next` available. - -#### nextNext - - +Returns `true` if this page is the last page and returns `false` if there are more pages available by calling `next``Next` available. -`next(): Promise` - -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`](/docs/api/realtime-sdk/types#error-info) object that details the reason why it was rejected. - - +#### nextNext @@ -709,46 +620,8 @@ Returns a new [`PaginatedResult`](/docs/api/realtime-sdk/history#paginated-resul - - -#### current - -`current(): Promise` - -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`](/docs/api/realtime-sdk/types#error-info) object that details the reason why it was rejected. - - - #### Example - - - -```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()); -``` - - - - - - - -```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()); -``` - - - - diff --git a/src/pages/docs/api/realtime-sdk/messages.mdx b/src/pages/docs/api/realtime-sdk/messages.mdx index e1cebd93c9..da744571f7 100644 --- a/src/pages/docs/api/realtime-sdk/messages.mdx +++ b/src/pages/docs/api/realtime-sdk/messages.mdx @@ -12,47 +12,47 @@ redirect_from: We've updated the style and readability of our API references, starting with JavaScript. Check out the [Pub/Sub JavaScript SDK API references](/docs/pub-sub/api/javascript/realtime/message) in their new location. -## PropertiesAttributesMembers +## PropertiesAttributesMembers A `Message` represents an individual message that is sent to or received from Ably. -### nameName +### nameName The event name, if provided.
_Type: `String`_ -### dataData +### dataData -The message payload, if provided.
_Type: `String`, `StringBuffer`, `JSON Object``String`, `ByteArray`, `JSONObject`, `JSONArray``String`, `byte[]`, `plain C# object that can be serialized to JSON``String`, `Binary` (ASCII-8BIT String), `Hash`, `Array``NSString *`, `NSData *`, `NSDictionary *`, `NSArray *``String`, `NSData`, `Dictionary`, `Array``String`, `Map`, `List`_ +The message payload, if provided.
_Type: `String`, `ByteArray`, `JSONObject`, `JSONArray``String`, `byte[]`, `plain C# object that can be serialized to JSON``String`, `Binary` (ASCII-8BIT String), `Hash`, `Array``NSString *`, `NSData *`, `NSDictionary *`, `NSArray *``String`, `NSData`, `Dictionary`, `Array``String`, `Map`, `List`_ -### extrasExtras +### extrasExtras -Metadata and/or ancillary payloads, if provided. Valid payloads include [`push`](/docs/push/publish#payload), [`headers`](/docs/channels#metadata) (a map of strings to strings for arbitrary customer-supplied metadata), [`ephemeral`](/docs/pub-sub/advanced#ephemeral), and [`privileged`](/docs/platform/integrations/skip-integrations).
_Type: `JSONObject`, `JSONArray`plain C# object that can be converted to JSON`JSON Object``Hash`, `Array``Dictionary`, `Array``NSDictionary *`, `NSArray *`_ +Metadata and/or ancillary payloads, if provided. Valid payloads include [`push`](/docs/push/publish#payload), [`headers`](/docs/channels#metadata) (a map of strings to strings for arbitrary customer-supplied metadata), [`ephemeral`](/docs/pub-sub/advanced#ephemeral), and [`privileged`](/docs/platform/integrations/skip-integrations).
_Type: `JSONObject`, `JSONArray`plain C# object that can be converted to JSON`Hash`, `Array``Dictionary`, `Array``NSDictionary *`, `NSArray *`_ -### idId +### idId A Unique ID assigned by Ably to this message.
_Type: `String`_ -### clientIdClientIdclient_id +### clientIdClientIdclient_id The client ID of the publisher of this message.
_Type: `String`_ -### connectionIdConnectionIdconnection_id +### connectionIdConnectionIdconnection_id The connection ID of the publisher of this message.
_Type: `String`_ -### connectionKeyConnectionKeyconnection_key +### connectionKeyConnectionKeyconnection_key A connection key, which can optionally be included for a REST publish as part of the [publishing on behalf of a realtime client functionality](/docs/pub-sub/advanced#publish-on-behalf).
_Type: `String`_ -### timestampTimestamp +### timestampTimestamp -Timestamp when the message was first received by the Ably, as milliseconds since the epocha `Time` object.
_Type: `Integer``Long Integer``DateTimeOffset``Time``NSDate`_ +Timestamp when the message was first received by the Ably, as milliseconds since the epocha `Time` object.
_Type: `Integer``Long Integer``DateTimeOffset``Time``NSDate`_ -### encodingEncoding +### encodingEncoding This will typically be empty as all messages received from Ably are automatically decoded client-side using this value. However, if the message encoding cannot be processed, this attribute will contain the remaining transformations not applied to the `data` payload.
_Type: `String`_ - + ### action @@ -74,7 +74,7 @@ An object containing version metadata for messages that have been updated or del ### Message constructors -#### Message.fromEncoded +#### Message.fromEncoded `Message.fromEncoded(Object encodedMsg, ChannelOptions channelOptions?) -> Message` @@ -91,7 +91,7 @@ A static factory method to create a [`Message`](/docs/api/realtime-sdk/types#mes A [`Message`](/docs/api/realtime-sdk/types#message) object -#### Message.fromEncodedArray +#### Message.fromEncodedArray `Message.fromEncodedArray(Object[] encodedMsgs, ChannelOptions channelOptions?) -> Message[]` @@ -110,7 +110,7 @@ An `Array` of [`Message`](/docs/api/realtime-sdk/types#message) objects ## MessageAnnotations -#### PropertiesMembersAttributes +#### PropertiesMembersAttributes | Property | Description | Type | |----------|-------------|------| @@ -118,12 +118,12 @@ An `Array` of [`Message`](/docs/api/realtime-sdk/types#message) objects ## MessageVersion -#### PropertiesMembersAttributes +#### PropertiesMembersAttributes | Property | Description | Type | |----------|-------------|------| | serial | An Ably-generated ID that uniquely identifies this version of the message. Can be compared lexicographically to determine version ordering. For an original message with an action of `message.create`, this will be equal to the top-level `serial`. | `String` | -| timestamp | The time this version was created (when the update or delete operation was performed). For an original message, this will be equal to the top-level `timestamp`. | `Integer``Long Integer``DateTimeOffset``Time``NSDate` | +| timestamp | The time this version was created (when the update or delete operation was performed). For an original message, this will be equal to the top-level `timestamp`. | `Integer``Long Integer``DateTimeOffset``Time``NSDate` | | clientId | The client identifier of the user who performed the update or delete operation. Only present for `message.update` and `message.delete` actions. | `String` (optional) | | description | Optional description provided when the update or delete was performed. Only present for `message.update` and `message.delete` actions. | `String` (optional) | | metadata | Optional metadata provided when the update or delete was performed. Only present for `message.update` and `message.delete` actions. | `Object` (optional) | diff --git a/src/pages/docs/api/realtime-sdk/presence.mdx b/src/pages/docs/api/realtime-sdk/presence.mdx index e58fb64b67..811810c1a0 100644 --- a/src/pages/docs/api/realtime-sdk/presence.mdx +++ b/src/pages/docs/api/realtime-sdk/presence.mdx @@ -28,11 +28,11 @@ redirect_from: We've updated the style and readability of our API references, starting with JavaScript. Check out the [Pub/Sub JavaScript SDK API references](/docs/pub-sub/api/javascript/realtime/realtime-presence) in their new location. -## Presence PropertiesARTPresence PropertiesAbly::Realtime::Presence Attributesio.ably.lib.realtime.Presence MembersIO.Ably.Realtime.Presence Properties +## Presence PropertiesARTPresence PropertiesAbly::Realtime::Presence Attributesio.ably.lib.realtime.Presence MembersIO.Ably.Realtime.Presence Properties -The `Presence` object exposes the following public propertiesattributesmembers: +The `Presence` object exposes the following public propertiesattributesmembers: -### syncCompletesync_complete?SyncComplete +### syncCompletesync_complete?SyncComplete A `boolean` field indicating whether the presence member set is synchronized with server after a channel attach. @@ -40,7 +40,7 @@ When a channel is attached, the Ably service immediately synchronizes the presen ## Methods -### enterEnterAsync +### enterEnterAsync In order to enter and be present on a channel, the client must [be identified by having a client ID](https://faqs.ably.com/authenticated-and-identified-clients), [have permission to be present](https://faqs.ably.com/using-capabilities-to-manage-client-access-privileges-on-channels), and be attached to the channel. For simplicity, the library will implicitly attach to a channel when entering. Entering when already entered is treated as an [update](#update). @@ -99,22 +99,15 @@ Enter a presence channel without any data. If the channel is `initialized` (i.e. Enter a presence channel and provide data that is associated with the current present member. If the channel is `initialized` (i.e. no attempt to attach has yet been made for this channel), then calling `enter` will implicitly attach the channel. - - - -`enter(Object data?): Promise` - -Enter a presence channel with optional data that is associated with the current present member. If the channel is `initialized` (i.e. no attempt to attach has yet been made for this channel), then calling `enter` will implicitly attach the channel. - #### Parameters - + | Parameter | Description | Type | |-----------|-------------|------| -| data | data payload for the current present member. The supported payload types are Strings, JSON objects and arrays, buffers containing arbitrary binary data, and nullstrings, plain object convertible to json, binary data as byte arrays, and null. | `Object` | +| data | data payload for the current present member. The supported payload types are strings, plain object convertible to json, binary data as byte arrays, and null. | `Object` | @@ -127,13 +120,6 @@ Enter a presence channel with optional data that is associated with the current - - -#### Returns - -Returns a promise. On success, the promise resolves. On failure, the promise is rejected with an [ErrorInfo](/docs/api/realtime-sdk/types#error-info) object that details the reason why it was rejected. - - #### Callback result @@ -165,7 +151,7 @@ On successfully entering the channel, the registered success blocks for the [Def -### leaveLeave +### leaveLeave In order to leave the presence set of a channel, the client must have already [entered and been present](#enter). @@ -224,22 +210,15 @@ Leave a presence channel without emitting any data. Leave a presence channel and emit data that is associated with the current leaving member. - - - -`leave(Object data?): Promise` - -Leave a presence channel and emit an optional data that is associated with the current leaving member. - #### Parameters - + | Parameter | Description | Type | |-----------|-------------|------| -| data | data payload for the current present member. The supported payload types are Strings, JSON objects and arrays, buffers containing arbitrary binary data, and nullstrings, plain objects convertible to json, binary data as byte arrays, and null. | `Object` | +| data | data payload for the current present member. The supported payload types are strings, plain objects convertible to json, binary data as byte arrays, and null. | `Object` | @@ -252,13 +231,6 @@ Leave a presence channel and emit an optional data that is associated with the c - - -#### Returns - -Returns a promise. On success, the promise resolves. On failure, the promise is rejected with an [ErrorInfo](/docs/api/realtime-sdk/types#error-info) object that details the reason why it was rejected. - - #### Callback result @@ -290,21 +262,16 @@ On successfully leaving the channel, the registered success blocks for the [Defe -### updateUpdate +### updateUpdate -Clients can update their member data on the channel which will trigger a broadcast of this update to all presence subscribers. The [pre-requisites for](#update) `update``Update` are the same as for [`enter`](#enter).[`Enter`](#enter). If an attempt to `update``Update` is made before the client has entered the channel, the update is treated as an `enter``Enter`. +Clients can update their member data on the channel which will trigger a broadcast of this update to all presence subscribers. The [pre-requisites for](#update) `update``Update` are the same as for [`enter`](#enter).[`Enter`](#enter). If an attempt to `update``Update` is made before the client has entered the channel, the update is treated as an `enter``Enter`. -A callbackblockcompletion listener can optionally be passed in to be notified of success or failure to update the member data.

 +A callbackblockcompletion listener can optionally be passed in to be notified of success or failure to update the member data.

 `update(Object data, callback(ErrorInfo err))` - - - -`update(Object data?): Promise` - @@ -331,11 +298,11 @@ Update the current member's data and broadcast an update event to all subscriber #### Parameters - + | Parameter | Description | Type | |-----------|-------------|------| -| data | data payload for the current present member. The supported payload types are Strings, JSON objects and arrays, buffers containing arbitrary binary data, and nullstrings, plain objects convertible to json, binary data as byte arrays, and null. | `Object` | +| data | data payload for the current present member. The supported payload types are strings, plain objects convertible to json, binary data as byte arrays, and null. | `Object` | @@ -348,13 +315,6 @@ Update the current member's data and broadcast an update event to all subscriber - - -#### Returns - -Returns a promise. On success, the promise resolves. On failure, the promise is rejected with an [ErrorInfo](/docs/api/realtime-sdk/types#error-info) object that details the reason why it was rejected. - - #### Callback result @@ -386,7 +346,7 @@ On successfully updating the data, the registered success blocks for the [Deferr -### getGet +### getGet Get the current presence member set for this channel. Typically, this method returns the member set immediately as the member set is retained in memory by the client. However, by default this method will wait until the presence member set is synchronized, so if the synchronization is not yet complete following a channel being attached, this method will wait until the presence member set is synchronized. @@ -394,11 +354,6 @@ When a channel is attached, the Ably service immediately synchronizes the presen When a channel is `initialized` (i.e. no attempt to attach has yet been made for this channel), then calling `get` will implicitly attach the channel. - - -`get(Object params?): Promise` - - `get(Object options, callback(ErrorInfo err, PresenceMessage[] members))` @@ -427,15 +382,15 @@ When a channel is `initialized` (i.e. no attempt to attach has yet been made for Gets an array of members present on the channel as [PresenceMessage](#presence-message) objects. - + #### Parameters - + | Parameter | Description | Type | |-----------|-------------|------| -| paramsoptionsquery | an optional objectobjectset of parameters containing query parameters as specified below. | [`Param[]`](/docs/api/realtime-sdk/presence#param)`PaginatedRequestParams` | +| optionsquery | an optional objectset of parameters containing query parameters as specified below. | [`Param[]`](/docs/api/realtime-sdk/presence#param)`PaginatedRequestParams` | @@ -450,21 +405,14 @@ Gets an array of members present on the channel as [PresenceMessage](#presence-m -#### `options` parameters`params` parameters`ARTRealtimePresenceQuery` properties`GetOptions` properties +#### `options` parameters`ARTRealtimePresenceQuery` properties`GetOptions` properties | Property | Description | Type | |----------|-------------|------| -| clientId:client_id | when provided, will filter array of members returned that match the provided [clientId](/docs/api/realtime-sdk#client-id)[client_id](/docs/api/realtime-sdk#client-id)[ClientId](/docs/api/realtime-sdk#client-id) string | `String` | -| connectionId:connection_id | when provided, will filter array of members returned that match the provided [connectionId](/docs/api/realtime-sdk/connection#id)[ConnectionId](/docs/api/realtime-sdk/connection#id)[connection_id](/docs/api/realtime-sdk/connection#id) string | `String` | -| waitForSync:wait_for_sync | A boolean value that by default waits for the initial presence synchronization following channel attachment to complete before returning the members present. When false, the current list of members is returned without waiting for a complete synchronization.
_Default: true_ | `Boolean` | - - - -#### Returns +| clientId:client_id | when provided, will filter array of members returned that match the provided [clientId](/docs/api/realtime-sdk#client-id)[client_id](/docs/api/realtime-sdk#client-id)[ClientId](/docs/api/realtime-sdk#client-id) string | `String` | +| connectionId:connection_id | when provided, will filter array of members returned that match the provided [connectionId](/docs/api/realtime-sdk/connection#id)[ConnectionId](/docs/api/realtime-sdk/connection#id)[connection_id](/docs/api/realtime-sdk/connection#id) string | `String` | +| waitForSync:wait_for_sync | A boolean value that by default waits for the initial presence synchronization following channel attachment to complete before returning the members present. When false, the current list of members is returned without waiting for a complete synchronization.
_Default: true_ | `Boolean` | -Returns a promise. On success, the promise is fulfilled with an array of [PresenceMessage](#presence-message) objects corresponding to the current set of present members on the channel. On failure, the promise is rejected with an [ErrorInfo](/docs/api/realtime-sdk/types#error-info) object that details the reason why it was rejected. - - #### Callback result @@ -504,17 +452,12 @@ Failure to retrieve the current presence member set will trigger the `errback` c -### historyHistory +### historyHistory `history(Object options, callback(ErrorInfo err, PaginatedResult resultPage))` - - - -`history(Object params?): Promise>` - @@ -541,11 +484,11 @@ Gets a [paginated](#paginated-result) set of historical presence message events #### Parameters - + | Parameter | Description | Type | |-----------|-------------|------| -| paramsoptionsquery | an optional objectobjectPaginatedRequestParams object containing query parameters, as specified in the [presence history API documentation](/docs/storage-history/history#presence-history) | [`Param[]`](/docs/api/realtime-sdk/presence#param)`PaginatedRequestParams` | +| optionsquery | an optional objectPaginatedRequestParams object containing query parameters, as specified in the [presence history API documentation](/docs/storage-history/history#presence-history) | [`Param[]`](/docs/api/realtime-sdk/presence#param)`PaginatedRequestParams` | @@ -560,14 +503,6 @@ Gets a [paginated](#paginated-result) set of historical presence message events Further details of the supported `options` params, see [presence history API documentation](/docs/storage-history/history#presence-history). - - -#### Returns - -Returns a promise. On success, the promise is fulfilled with a [PaginatedResult](#paginated-result) object containing an array of [PresenceMessage](#presence-message) objects corresponding to the current page of results. On failure, the promise is rejected with an [ErrorInfo](/docs/api/realtime-sdk/types#error-info) object that details the reason why it was rejected. - - - #### Callback result @@ -612,15 +547,10 @@ Failure to retrieve the message history will trigger the `errback` callbacks of -### subscribeSubscribe +### subscribeSubscribe There are overloaded versions of this method: - - -`subscribe(listener(PresenceMessage)): Promise` - - `subscribe(listener(PresenceMessage))` @@ -647,17 +577,12 @@ There are overloaded versions of this method: -Subscribe to presence message events on this channel. The caller supplies a listener functionan implementation of the [PresenceListener](#presence-listener) interfacea blocka handler, which is called each time one or more presence events occurs such as a member entering or leaving a channel. +Subscribe to presence message events on this channel. The caller supplies a listener functionan implementation of the [PresenceListener](#presence-listener) interfacea blocka handler, which is called each time one or more presence events occurs such as a member entering or leaving a channel. `subscribe(String action, listener(PresenceMessage))` - - - -`subscribe(String action, listener(PresenceMessage)): Promise` - @@ -680,15 +605,10 @@ Subscribe to presence message events on this channel. The caller supplies -Subscribe to presence message events with a given [action](#presence-action) on this channel. The caller supplies a listener functionan implementation of the [PresenceListener](#presence-listener) interfacea blocka handler, which is called each time one or more presence events occurs such as a member entering or leaving a channel. - - - - +Subscribe to presence message events with a given [action](#presence-action) on this channel. The caller supplies a listener functionan implementation of the [PresenceListener](#presence-listener) interfacea blocka handler, which is called each time one or more presence events occurs such as a member entering or leaving a channel. -`subscribe(String[] actions, listener(PresenceMessage))` + - `void subscribe(PresenceMessage.Action[] actions, PresenceListener listener)` @@ -706,13 +626,13 @@ Subscribe a single listener to messages on this channel for multiple [action](#p #### Parameters - + | Parameter | Description | Type | |-----------|-------------|------| -| action | The presence [`action` event](#presence-action) to subscribe to | `String`[PresenceMessage.Action](#presence-action)[PresenceMessage::ACTION](#presence-action) action | -| actions | An argumentarray of [`action` events](#presence-action) to subscribe to | `String[]``*argument` | -| listenerlistener&block | is a function of the form `function(presenceMessage)` to be called for each matching presence message eventMessage listener to be notified for matching presence message eventyields matching presence message event when received on the channel | [`PresenceListener`](#presence-listener) | +| action | The presence [`action` event](#presence-action) to subscribe to | [PresenceMessage.Action](#presence-action)[PresenceMessage::ACTION](#presence-action) action | +| actions | An argumentarray of [`action` events](#presence-action) to subscribe to | `String[]``*argument` | +| listener&block | Message listener to be notified for matching presence message eventyields matching presence message event when received on the channel | [`PresenceListener`](#presence-listener) | @@ -725,34 +645,21 @@ Subscribe a single listener to messages on this channel for multiple [action](#p - - -#### Returns - -Returns a promise. On successful channel attachment, the promise is resolved. On failure, the promise is rejected with an [ErrorInfo](/docs/api/realtime-sdk/types#error-info) object that details the reason why it was rejected. - - - #### Considerations -* If the channel is `initialized` (i.e. no attempt to attach has yet been made for this channel), then calling `subscribe` will implicitly attach the channel. However, regardless of the implicit attach outcome, the listenerblockhandler will still be registered -* If `subscribe` is called more than once with the same listenerblockhandler, then duplicates will be registered. For example, if you `subscribe` twice with the same listenerblockhandler and a presence message is later received, the same listenerblockhandler will be invoked twice -* The registered listenerblockhandler remains active on the presence channel regardless of the underlying channel state. For example, if you call `subscribe` when the underlying channel is `attached` and it later becomes `detached` or even `failed`, when the channel is reattached and a presence message is received, the listenersblockshandlers originally registered will still be invoked. Listeners are only removed when calling [unsubscribe](#unsubscribe) or when the underlying channel is `released` using the `Realtime.channels.release(name)``Realtime.Channels.Release(name)` method +* If the channel is `initialized` (i.e. no attempt to attach has yet been made for this channel), then calling `subscribe` will implicitly attach the channel. However, regardless of the implicit attach outcome, the listenerblockhandler will still be registered +* If `subscribe` is called more than once with the same listenerblockhandler, then duplicates will be registered. For example, if you `subscribe` twice with the same listenerblockhandler and a presence message is later received, the same listenerblockhandler will be invoked twice +* The registered listenerblockhandler remains active on the presence channel regardless of the underlying channel state. For example, if you call `subscribe` when the underlying channel is `attached` and it later becomes `detached` or even `failed`, when the channel is reattached and a presence message is received, the listenersblockshandlers originally registered will still be invoked. Listeners are only removed when calling [unsubscribe](#unsubscribe) or when the underlying channel is `released` using the `Realtime.channels.release(name)``Realtime.Channels.Release(name)` method * If an exception is thrown in the subscribe listener and bubbles up to the event emitter, it will be caught and logged at `error` level, so as not to affect other listeners for the same event -### unsubscribeUnsubscribe +### unsubscribeUnsubscribe -There are sixthree overloaded versions of this method: +There are three overloaded versions of this method: `unsubscribe(String action, listener)` - - - -`unsubscribe(String action, listener)` - @@ -781,11 +688,6 @@ Unsubscribe the given listener from presence message events on this channel for `unsubscribe(listener)` - - - -`unsubscribe(listener)` - @@ -810,25 +712,9 @@ Unsubscribe the given listener from presence message events on this channel for Unsubscribe the given listener from presence message events on this channel. This removes an earlier subscription. - - -`unsubscribe(String[] actions, listener)` - -Unsubscribe the given listener from all presence actions in the array. - -`unsubscribe(String action)` - -Unsubscribe all listeners for a given [action](#presence-action). - -`unsubscribe(String[] actions)` - -Unsubscribe all listeners for all presence actions in the array. - - - - + `unsubscribe()` @@ -853,16 +739,6 @@ Unsubscribes all listeners to presence message events on this channel. This remo #### Parameters - - -| Parameter | Description | Type | -|-----------|-------------|------| -| action | The presence [`action` event](#presence-action) to unsubscribe from | `String` | -| actions | An array of actions to unsubscribe from | `String[]` | -| listener | is the callback listener function that was previously subscribed | | - - - | Parameter | Description | Type | @@ -872,9 +748,9 @@ Unsubscribes all listeners to presence message events on this channel. This remo -### enterCliententer_clientEnterClientAsync +### enterCliententer_clientEnterClientAsync -Enter this presence channel for the given `clientId``client_id``ClientId`. This method is provided to support typically server instances that act on behalf of multiple client IDs. See [Managing multiple client IDs](/docs/presence-occupancy/presence#multiple-client-ids) for more info. In order to be able to publish presence changes for arbitrary client IDs, the client library must have been instantiated either with an [API key](/docs/auth#api-keys) or with a [token bound to a wildcard client ID](https://faqs.ably.com/can-a-client-emulate-any-client-id-i.e.-authenticate-using-a-wildcard-client-id). +Enter this presence channel for the given `clientId``client_id``ClientId`. This method is provided to support typically server instances that act on behalf of multiple client IDs. See [Managing multiple client IDs](/docs/presence-occupancy/presence#multiple-client-ids) for more info. In order to be able to publish presence changes for arbitrary client IDs, the client library must have been instantiated either with an [API key](/docs/auth#api-keys) or with a [token bound to a wildcard client ID](https://faqs.ably.com/can-a-client-emulate-any-client-id-i.e.-authenticate-using-a-wildcard-client-id). @@ -933,21 +809,13 @@ Enter a presence channel on behalf of the provided - -`enterClient(String clientId, Object data?): Promise` - -Enter a presence channel on behalf of the provided `clientId` and provide an optional data that is associated with the current present member. If the channel is `initialized` (i.e. no attempt to attach has yet been made for this channel), then calling `enter` will implicitly attach the channel. - - - #### Parameters - + | Parameter | Description | Type | |-----------|-------------|------| -| data | data payload for the member. The supported payload types are Strings, JSON objects and arrays, buffers containing arbitrary binary data, and nullstrings, plain object convertible to json, binary data as byte arrays, and null. | `Object` | +| data | data payload for the member. The supported payload types are strings, plain object convertible to json, binary data as byte arrays, and null. | `Object` | @@ -960,14 +828,6 @@ Enter a presence channel on behalf of the provided `clientId` and provide an opt - - -#### Returns - - Returns a promise. On success, the promise resolves. On failure, the promise is rejected with an [ErrorInfo](/docs/api/realtime-sdk/types#error-info) object that details the reason why it was rejected. - - - #### Callback result @@ -1002,9 +862,9 @@ On successfully entering the channel, the registered success blocks for the [Def -### leaveClientleave_clientLeaveClientAsync +### leaveClientleave_clientLeaveClientAsync -Leave this presence channel for the given `clientId``client_id``ClientId`. This method is provided to support typically server instances that act on behalf of multiple client IDs. See [Managing multiple client IDs](/docs/presence-occupancy/presence#multiple-client-ids) for more info. In order to leave the presence set of a channel, the client must have already [entered and been present](#enter-client). +Leave this presence channel for the given `clientId``client_id``ClientId`. This method is provided to support typically server instances that act on behalf of multiple client IDs. See [Managing multiple client IDs](/docs/presence-occupancy/presence#multiple-client-ids) for more info. In order to leave the presence set of a channel, the client must have already [entered and been present](#enter-client). @@ -1058,21 +918,13 @@ Leave a presence channel on behalf of the provided - -`leaveClient(String clientId, Object data?): Promise` - -Leave a presence channel on behalf of the provided `clientId` and emit an optional data that is associated with the current leaving member. - - - #### Parameters - + | Parameter | Description | Type | |-----------|-------------|------| -| data | data payload for the member. The supported payload types are Strings, JSON objects and arrays, buffers containing arbitrary binary data, and nullstrings, plain object convertible to json, binary data as byte arrays, and null. | `Object` | +| data | data payload for the member. The supported payload types are strings, plain object convertible to json, binary data as byte arrays, and null. | `Object` | @@ -1085,14 +937,6 @@ Leave a presence channel on behalf of the provided `clientId` and emit an option - - -#### Returns - -Returns a promise. On success, the promise resolves. On failure, the promise is rejected with an [ErrorInfo](/docs/api/realtime-sdk/types#error-info) object that details the reason why it was rejected. - - - #### Callback result @@ -1127,23 +971,18 @@ On successfully leaving the channel, the registered success blocks for the [Defe -### updateClientupdate_clientUpdateClientAsync +### updateClientupdate_clientUpdateClientAsync -Clients can update the member data on behalf of the given `clientId``client_id``ClientId` which will trigger a broadcast of this update to all presence subscribers. This method is provided to support typically server instances that act on behalf of multiple client IDs. See [Managing multiple client IDs](/docs/presence-occupancy/presence#multiple-client-ids) for more info. If an attempt to update is made before the member has entered the channel, the update is treated as an enter. +Clients can update the member data on behalf of the given `clientId``client_id``ClientId` which will trigger a broadcast of this update to all presence subscribers. This method is provided to support typically server instances that act on behalf of multiple client IDs. See [Managing multiple client IDs](/docs/presence-occupancy/presence#multiple-client-ids) for more info. If an attempt to update is made before the member has entered the channel, the update is treated as an enter. - -A callbackblockcompletion listener can optionally be passed in to be notified of success or failure to update the member data. + +A callbackblockcompletion listener can optionally be passed in to be notified of success or failure to update the member data. `updateClient(String clientId, Object data, callback(ErrorInfo err))` - - - -`updateClient(String clientId, Object data?): Promise` - @@ -1166,15 +1005,15 @@ A callbackb -Update the member data on behalf of the provided `clientId``client_id``ClientId` and broadcast an update event to all subscribers. `data` may be `null`. If the channel is `initialized` (i.e. no attempt to attach has yet been made for this channel), then calling `enter` will implicitly attach the channel. +Update the member data on behalf of the provided `clientId``client_id``ClientId` and broadcast an update event to all subscribers. `data` may be `null`. If the channel is `initialized` (i.e. no attempt to attach has yet been made for this channel), then calling `enter` will implicitly attach the channel. #### Parameters - + | Parameter | Description | Type | |-----------|-------------|------| -| data | data payload for the member. The supported payload types are Strings, JSON objects and arrays, buffers containing arbitrary binary data, and nullstrings, plain object convertible to json, binary data as byte arrays, and null. | `Object` | +| data | data payload for the member. The supported payload types are strings, plain object convertible to json, binary data as byte arrays, and null. | `Object` | @@ -1187,14 +1026,6 @@ Update the member data on behalf of the provided - -#### Returns - -Returns a promise. On success, the promise resolves. On failure, the promise is rejected with an [ErrorInfo](/docs/api/realtime-sdk/types#error-info) object that details the reason why it was rejected. - - - #### Callback result @@ -1231,22 +1062,22 @@ On successfully updating the data, the registered success blocks for the [Deferr ## Related types -## PresenceMessageARTPresenceMessageAbly::Models::PresenceMessageio.ably.lib.types.PresenceMessageIO.Ably.PresenceMessage +## PresenceMessageARTPresenceMessageAbly::Models::PresenceMessageio.ably.lib.types.PresenceMessageIO.Ably.PresenceMessage A `PresenceMessage` represents an individual presence update that is sent to or received from Ably. -#### PropertiesMembersAttributes +#### PropertiesMembersAttributes | Property | Description | Type | |----------|-------------|------| -| actionactionAction | the event signified by a PresenceMessage. See [`Presence action`](/docs/api/realtime-sdk/types#presence-action)[`PresenceMessage.action`](/docs/api/realtime-sdk/types#presence-action)[`PresenceMessage.action`](/docs/api/realtime-sdk/types#presence-action)[`PresenceMessage::ACTION`](/docs/api/realtime-sdk/types#presence-action)[`PresenceMessage.action`](/docs/api/realtime-sdk/types#presence-action) | `enum { ABSENT, PRESENT, ENTER, LEAVE, UPDATE }``enum { Absent, Present, Enter, Leave, Update }``int enum { ABSENT, PRESENT, ENTER, LEAVE, UPDATE }``enum { :absent, :present, :enter, :leave, :update }``ARTPresenceAction` | -| dataData | The presence update payload, if provided | `String`, `ByteArray`, `JSONObject`, `JSONArray``String`, `byte[]`, plain C# object that can be converted to Json`String`, `StringBuffer`, `JSON Object``String`, `Binary` (ASCII-8BIT String), `Hash`, `Array``String`, `NSData`, `Dictionary`, `Array``NSString *`, `NSData *`, `NSDictionary *`, `NSArray *` | -| extrasExtras | Metadata and/or ancillary payloads, if provided. The only currently valid payloads for extras are the [`push`](/docs/push/publish#sub-channels), [`ref`](/docs/messages#interactions) and [`privileged`](/docs/platform/integrations/skip-integrations) objects. | `JSONObject`, `JSONArray`plain C# object that can be converted to Json`JSON Object``Hash`, `Array``Dictionary`, `Array``NSDictionary *`, `NSArray *``Map`, `List` | -| idId | Unique ID assigned by Ably to this presence update | `String` | -| clientIdclient_idClientId | The client ID of the publisher of this presence update | `String` | -| connectionIdconnection_idConnectionId | The connection ID of the publisher of this presence update | `String` | -| timestampTimestamp | Timestamp when the presence update was received by Ably, as milliseconds since the epoch. | `Integer``Long Integer``DateTimeOffset``Time``NSDate` | -| encodingEncoding | This will typically be empty as all presence updates received from Ably are automatically decoded client-side using this value. However, if the message encoding cannot be processed, this attribute will contain the remaining transformations not applied to the `data` payload | `String` | +| actionactionAction | the event signified by a PresenceMessage. See [`Presence action`](/docs/api/realtime-sdk/types#presence-action)[`PresenceMessage.action`](/docs/api/realtime-sdk/types#presence-action)[`PresenceMessage.action`](/docs/api/realtime-sdk/types#presence-action)[`PresenceMessage::ACTION`](/docs/api/realtime-sdk/types#presence-action)[`PresenceMessage.action`](/docs/api/realtime-sdk/types#presence-action) | `enum { ABSENT, PRESENT, ENTER, LEAVE, UPDATE }``enum { Absent, Present, Enter, Leave, Update }``enum { :absent, :present, :enter, :leave, :update }``ARTPresenceAction` | +| dataData | The presence update payload, if provided | `String`, `ByteArray`, `JSONObject`, `JSONArray``String`, `byte[]`, plain C# object that can be converted to Json`String`, `Binary` (ASCII-8BIT String), `Hash`, `Array``String`, `NSData`, `Dictionary`, `Array``NSString *`, `NSData *`, `NSDictionary *`, `NSArray *` | +| extrasExtras | Metadata and/or ancillary payloads, if provided. The only currently valid payloads for extras are the [`push`](/docs/push/publish#sub-channels), [`ref`](/docs/messages#interactions) and [`privileged`](/docs/platform/integrations/skip-integrations) objects. | `JSONObject`, `JSONArray`plain C# object that can be converted to Json`Hash`, `Array``Dictionary`, `Array``NSDictionary *`, `NSArray *``Map`, `List` | +| idId | Unique ID assigned by Ably to this presence update | `String` | +| clientIdclient_idClientId | The client ID of the publisher of this presence update | `String` | +| connectionIdconnection_idConnectionId | The connection ID of the publisher of this presence update | `String` | +| timestampTimestamp | Timestamp when the presence update was received by Ably, as milliseconds since the epoch. | `Integer``Long Integer``DateTimeOffset``Time``NSDate` | +| encodingEncoding | This will typically be empty as all presence updates received from Ably are automatically decoded client-side using this value. However, if the message encoding cannot be processed, this attribute will contain the remaining transformations not applied to the `data` payload | `String` | ### PresenceMessage constructors @@ -1284,25 +1115,7 @@ A static factory method to create an array of [`PresenceMessages`](/docs/api/rea An `Array` of [`PresenceMessage`](/docs/api/realtime-sdk/types#presence-message) objects -## Presence actionARTPresenceActionio.ably.lib.types.PresenceMessage.ActionAbly::Models::PresenceMessage::ACTIONIO.Ably.PresenceAction - - - -`Presence` `action` is a String with a value matching any of the [`Realtime Presence` states & events](/docs/presence-occupancy/presence#trigger-events). - - -```javascript -var PresenceActions = [ - 'absent', // (reserved for internal use) - 'present', - 'enter', - 'leave', - 'update' -] -``` - - - +## Presence actionARTPresenceActionio.ably.lib.types.PresenceMessage.ActionAbly::Models::PresenceMessage::ACTIONIO.Ably.PresenceAction @@ -1457,29 +1270,24 @@ public interface CompletionListener { -## PaginatedResultARTPaginatedResultAbly::Models::PaginatedResultio.ably.lib.types.PaginatedResultIO.Ably.PaginatedResult +## 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](/docs/api/rest-api/#pagination) is accompanied by metadata that indicates the relative queries available to the `PaginatedResult` object. -#### PropertiesMembersAttributes +#### PropertiesMembersAttributes | Property | Description | Type | |----------|-------------|------| -| itemsItems | contains the current page of results (for example an Array of [`Message`](#message) or [`PresenceMessage`](#presence-message) objects for a channel history request) | `Array ``List ` | +| itemsItems | contains the current page of results (for example an Array of [`Message`](#message) or [`PresenceMessage`](#presence-message) objects for a channel history request) | `Array ``List ` | ### Methods -#### firstFirst +#### firstFirst `first(callback(ErrorInfo err, PaginatedResult resultPage))` - - - -`first(): Promise` - @@ -1508,15 +1316,9 @@ Returns a new `PaginatedResult` for the first page of results. W - - -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`](/docs/api/realtime-sdk/types#error-info) object that details the reason why it was rejected. - - - -#### hasNextHasNexthas_next? +#### hasNextHasNexthas_next? - + `Boolean hasNext()` @@ -1532,11 +1334,11 @@ Returns a promise. On success, the promise is fulfilled with a new `PaginatedRes -Returns `true` if there are more pages available by calling `next``Next` and returns `false` if this page is the last page available. +Returns `true` if there are more pages available by calling `next``Next` and returns `false` if this page is the last page available. -#### isLastIsLastlast? +#### isLastIsLastlast? - + `Boolean isLast()` @@ -1552,19 +1354,14 @@ Returns `true` if there are more pages available by calling `next``Next` available. +Returns `true` if this page is the last page and returns `false` if there are more pages available by calling `next``Next` available. -#### nextNext +#### nextNext `next(callback(ErrorInfo err, PaginatedResult resultPage))` - - - -`next(): Promise` - @@ -1593,48 +1390,8 @@ Returns a new `PaginatedResult` loaded with the next page of results. If there a - - -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`](/docs/api/realtime-sdk/types#error-info) object that details the reason why it was rejected. - - - - - -#### current - -`current(): Promise` - -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`](/docs/api/realtime-sdk/types#error-info) object that details the reason why it was rejected. - - - #### Example - - -```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()); -``` - - - - - -```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()); -``` - - - ```java diff --git a/src/pages/docs/api/realtime-sdk/push-admin.mdx b/src/pages/docs/api/realtime-sdk/push-admin.mdx index 900d8e71c5..c5feeebef5 100644 --- a/src/pages/docs/api/realtime-sdk/push-admin.mdx +++ b/src/pages/docs/api/realtime-sdk/push-admin.mdx @@ -21,15 +21,15 @@ We've updated the style and readability of our API references, starting with Jav This object is accessible through `client.push.admin` and provides: -### Push Admin PropertiesPush::Admin Properties +### Push Admin PropertiesPush::Admin Properties -The push admin object exposes the following public propertiesattributesmembers: +The push admin object exposes the following public propertiesattributesmembers: -#### deviceRegistrationsdevice_registrations +#### deviceRegistrationsdevice_registrations The returned [`DeviceRegistrations`](#device-registrations-object) object provides functionality for registering, updating, listing and de-registering push devices. -#### channelSubscriptionschannel_subscriptions +#### channelSubscriptionschannel_subscriptions The returned [`PushChannelSubscriptions`](#push-channel-subscriptions) object provides functionality for subscribing, listing and unsubscribing individual devices or groups of [identified devices](/docs/auth/identified-clients) to push notifications published on channels. @@ -37,11 +37,6 @@ The returned [`PushChannelSubscriptions`](#push-channel-subscriptions) object pr #### publish - - -`publish(Object recipient, Object payload): Promise` - - `Deferrable publish(Hash recipient, Hash data) → yield` @@ -67,12 +62,12 @@ Publishes a push notification directly to a device or group of devices sharing a ##### Parameters - + | Parameter | Description | Type | |-----------|------|-------------| | recipient | Contains the push recipient details. See the [push notification publish REST API documentation](/docs/api/rest-api#push-publish) for details on the supported recipient fields | `Object` | -| payloaddata | Contains the push notification data. See the [push admin payload structure](/docs/push/publish#payload) for details on the supported push payload fields | `Object` | +| data | Contains the push notification data. See the [push admin payload structure](/docs/push/publish#payload) for details on the supported push payload fields | `Object` | @@ -106,13 +101,6 @@ Publishes a push notification directly to a device or group of devices sharing a - - -##### Returns - -Returns a promise. On success to publish the push notification, the promise resolves. On failure, the promise is rejected with an [`ErrorInfo`](/docs/api/realtime-sdk/types#error-info) object that details the reason why it was rejected. - - ##### Callback result @@ -139,21 +127,14 @@ On successful publish of the message, the `onSuccess` method of the [CompletionL -## PushDeviceRegistrations objectDeviceRegistrations object +## DeviceRegistrations object -This object is accessible through `client.push.admin.deviceRegistrations``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. +This object is accessible through `client.push.admin.deviceRegistrations``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 - - -`get(String deviceId): Promise` - -`get(DeviceDetails deviceDetails): Promise` - - `get(String deviceId) -> yields DeviceDetails` @@ -189,12 +170,12 @@ Obtain the `DeviceDetails` for a device registered for receiving push registrati ##### Parameters - + | Parameter | Description | Type | |-----------|------|-------------| | deviceId | The unique device ID String for the requested device | `String` | -| deviceDetailsdevice | A `DeviceDetails` object containing at a minimum the `deviceId` of the requested device | [`DeviceDetails`](#device-details) | +| device | A `DeviceDetails` object containing at a minimum the `deviceId` of the requested device | [`DeviceDetails`](#device-details) | @@ -208,13 +189,6 @@ Obtain the `DeviceDetails` for a device registered for receiving push registrati - - -##### Returns - -Returns a promise. On success, the promise is fulfilled with a [`DeviceDetails`](#device-details) object representing the device registered for push notifications. On failure, the promise is rejected with an [`ErrorInfo`](/docs/api/realtime-sdk/types#error-info) object that details the reason why it was rejected. - - ##### Callback result @@ -245,11 +219,6 @@ On successful publish of the message, the `onSuccess` method of the [CompletionL #### list - - -`list(Object params): Promise>` - - `Deferrable list(Hash params) → yields PaginatedResult` @@ -276,11 +245,11 @@ Retrieve all devices matching the params filter as a paginated list of [`DeviceD ##### Parameters - + | Parameter | Description | Type | |-----------|------|-------------| -| params | An object containing the query parameters as key value pairs as specified below | `Object`[`Param[]`](#param) | +| params | An object containing the query parameters as key value pairs as specified below | `Object`[`Param[]`](#param) | @@ -305,23 +274,6 @@ Retrieve all devices matching the params filter as a paginated list of [`DeviceD - - -| Property | Description | Type | -|----------|------|-------------| -| clientId | Optional filter to restrict to devices associated with that client identifier. Cannot be used with a `deviceId` param | `String` | -| deviceId | Optional filter to restrict to devices associated with that device identifier. Cannot be used with a `clientId` param | `String` | -| limit | _100_ maximum number of devices per page to retrieve, up to 1,000 | `Integer` | -| state | Optional filter by the state of the device. Must be one of `ACTIVE`, `FAILING` or `FAILED` | `String` | - -##### Returns - -Returns a promise. On success, the promise is fulfilled with a [`PaginatedResult`](/docs/api/realtime-sdk/types#paginated-result) encapsulating an array of [`DeviceDetails`](#device-details) objects corresponding to the current page of results. [`PaginatedResult`](/docs/api/realtime-sdk/types#paginated-result) supports pagination using [`next()`](/docs/api/realtime-sdk/types#paginated-result) and [`first()`](/docs/api/realtime-sdk/types#paginated-result) methods. - -On failure, the promise is rejected with an [`ErrorInfo`](/docs/api/realtime-sdk/types#error-info) object that details the reason why it was rejected. - - - ##### Callback result @@ -345,11 +297,6 @@ Failure to retrieve the devices will trigger the `errback` callbacks of the [`De #### save - - -`save(DeviceDetails deviceDetails): Promise` - - `Deferrable save(DeviceDetails device) → yields DeviceDetails` @@ -375,11 +322,11 @@ Register a new `DeviceDetails` object, or update an existing `DeviceDetails` obj ##### Parameters - + | Parameter | Description | Type | |-----------|------|-------------| -| deviceDetailsdevice | A `DeviceDetails` object | [`DeviceDetails`](#device-details) | +| device | A `DeviceDetails` object | [`DeviceDetails`](#device-details) | @@ -392,13 +339,6 @@ Register a new `DeviceDetails` object, or update an existing `DeviceDetails` obj - - -##### Returns - -Returns a promise. On success, the promise is fulfilled with a [`DeviceDetails`](#device-details) object representing the newly registered or updated device. On failure, the promise is rejected with an [`ErrorInfo`](/docs/api/realtime-sdk/types#error-info) object that details the reason why it was rejected. - - ##### Callback result @@ -422,13 +362,6 @@ Failure to create or update the device will trigger the `errback` callbacks of t #### remove - - -`remove(String deviceId): Promise` - -`remove(DeviceDetails deviceDetails): Promise` - - `remove(String deviceId)` @@ -462,12 +395,12 @@ Remove a device registered for receiving push registrations that matches the `de ##### Parameters - + | Parameter | Description | Type | |-----------|------|-------------| | deviceId | The unique device ID String for the device | `String` | -| deviceDetailsdevice | A `DeviceDetails` object containing at a minimum the `deviceId` of the device | [`DeviceDetails`](#device-details) | +| device | A `DeviceDetails` object containing at a minimum the `deviceId` of the device | [`DeviceDetails`](#device-details) | @@ -481,13 +414,6 @@ Remove a device registered for receiving push registrations that matches the `de - - -##### Returns - -Returns a promise. On success to delete the device, the promise resolves. Note that a request to delete a device that does not exist will result in a successful operation. On failure, the promise is rejected with an [`ErrorInfo`](/docs/api/realtime-sdk/types#error-info) object that details the reason why it was rejected. - - ##### Callback result @@ -509,13 +435,8 @@ Failure to delete the device will trigger the `errback` callbacks of the [`Defer -#### removeWhereremove_where - - +#### removeWhereremove_where -`removeWhere(Object params): Promise` - - `remove_where(Hash params) -> yield` @@ -541,11 +462,11 @@ Delete all devices matching the params filter. Requires `push-admin` permission. ##### Parameters - + | Parameter | Description | Type | |-----------|------|-------------| -| params | An object containing the filter parameters as key value pairs as specified below | `Object`[`Param[]`](#param) | +| params | An object containing the filter parameters as key value pairs as specified below | `Object`[`Param[]`](#param) | @@ -562,16 +483,9 @@ Delete all devices matching the params filter. Requires `push-admin` permission. | Property | Description | Type | |----------|------|-------------| -| clientId:client_id | Optional filter to restrict to devices associated with that client identifier. Cannot be used with a `deviceId``:device_id` param | `String` | -| deviceId:device_id | Optional filter to restrict to devices associated with that device identifier. Cannot be used with a `clientId``:client_id` param | `String` | - - - -##### Returns - -Returns a promise. On success to delete the device, the promise resolves. Note that a request that does match any existing devices will result in a successful operation. On failure, the promise is rejected with an [`ErrorInfo`](/docs/api/realtime-sdk/types#error-info) object that details the reason why it was rejected. +| clientId:client_id | Optional filter to restrict to devices associated with that client identifier. Cannot be used with a `deviceId``:device_id` param | `String` | +| deviceId:device_id | Optional filter to restrict to devices associated with that device identifier. Cannot be used with a `clientId``:client_id` param | `String` | - ##### Callback result @@ -595,17 +509,12 @@ Failure to delete the device will trigger the `errback` callbacks of the [`Defer ## PushChannelSubscriptions object -This object is accessible through `client.push.admin.channelSubscriptions``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. +This object is accessible through `client.push.admin.channelSubscriptions``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 - - -`list(Object params): Promise>` - - `Deferrable list(Hash params) -> yields PaginatedResult` @@ -631,11 +540,11 @@ Retrieve all push channel subscriptions that match the provided params filter as ##### Parameters - + | Parameter | Description | Type | |-----------|------|-------------| -| params | An object containing the query parameters as key value pairs as specified below | `Object`[`Param[]`](#param) | +| params | An object containing the query parameters as key value pairs as specified below | `Object`[`Param[]`](#param) | @@ -652,20 +561,11 @@ Retrieve all push channel subscriptions that match the provided params filter as | Property | Description | Type | |----------|------|-------------| -| channel:channel | Filter to restrict to subscriptions associated with that `channel` | `String` | -| clientId:client_id | Optional filter to restrict to devices associated with that client identifier. Cannot be used with a deviceId:device_id param | `String` | -| deviceId:device_id | Optional filter to restrict to devices associated with that device identifier. Cannot be used with a clientId:client_id param | `String` | -| limit:limit | _100_ maximum number of channel subscriptions per page to retrieve, up to 1,000 | `Integer` | - - - -##### Returns - -Returns a promise. On success, the promise is fulfilled with a [`PaginatedResult`](/docs/api/realtime-sdk/types#paginated-result) encapsulating an array of [`PushChannelSubscription`](#push-channel-subscription) objects corresponding to the current page of results. [`PaginatedResult`](/docs/api/realtime-sdk/types#paginated-result) supports pagination using [`next()`](/docs/api/realtime-sdk/types#paginated-result) and [`first()`](/docs/api/realtime-sdk/types#paginated-result) methods. - -On failure, the promise is rejected with an [`ErrorInfo`](/docs/api/realtime-sdk/types#error-info) object that details the reason why it was rejected. +| channel:channel | Filter to restrict to subscriptions associated with that `channel` | `String` | +| clientId:client_id | Optional filter to restrict to devices associated with that client identifier. Cannot be used with a deviceId:device_id param | `String` | +| deviceId:device_id | Optional filter to restrict to devices associated with that device identifier. Cannot be used with a clientId:client_id param | `String` | +| limit:limit | _100_ maximum number of channel subscriptions per page to retrieve, up to 1,000 | `Integer` | - ##### Callback result @@ -687,13 +587,8 @@ Failure to retrieve the channel subscriptions will trigger the `errback` callbac -#### listChannelslist_channels - - - -`listChannels(Object params): Promise>` +#### listChannelslist_channels - `Deferrable list_channels(Hash params) -> yields PaginatedResult` @@ -719,11 +614,11 @@ Retrieve a list of channels that have at least one device [subscribed to push no ##### Parameters - + | Parameter | Description | Type | |-----------|------|-------------| -| params | An object containing the query parameters as key value pairs as specified below | `Object`[`Param[]`](#param) | +| params | An object containing the query parameters as key value pairs as specified below | `Object`[`Param[]`](#param) | @@ -740,17 +635,8 @@ Retrieve a list of channels that have at least one device [subscribed to push no | Property | Description | Type | |----------|------|-------------| -| limit:limit | _100_ maximum number of channels per page to retrieve, up to 1,000 | `Integer` | - - - -##### Returns - -Returns a promise. On success, the promise is fulfilled with a [`PaginatedResult`](/docs/api/realtime-sdk/types#paginated-result) encapsulating an array of channel name `String` values corresponding to the current page of results. [`PaginatedResult`](/docs/api/realtime-sdk/types#paginated-result) supports pagination using [`next()`](/docs/api/realtime-sdk/types#paginated-result) and [`first()`](/docs/api/realtime-sdk/types#paginated-result) methods. - -On failure, the promise is rejected with an [`ErrorInfo`](/docs/api/realtime-sdk/types#error-info) object that details the reason why it was rejected. +| limit:limit | _100_ maximum number of channels per page to retrieve, up to 1,000 | `Integer` | - ##### Callback result @@ -774,11 +660,6 @@ Failure to retrieve the channels will trigger the `errback` callbacks of the [`D #### save - - -`save(PushChannelSubscription subscription): Promise` - - `save(PushChannelSubscription channel_subscription)` @@ -806,15 +687,8 @@ Subscribe a device or group of devices sharing a [client identifier](/docs/auth/ | Parameter | Description | Type | |-----------|------|-------------| -| channelSubscriptionsubscriptionchannel_subscription | A `PushChannelSubscription` object | [`PushChannelSubscription`](#push-channel-subscription) | - - +| channelSubscriptionchannel_subscription | A `PushChannelSubscription` object | [`PushChannelSubscription`](#push-channel-subscription) | -##### Returns - -Returns a promise. On success, the promise is fulfilled with a [`PushChannelSubscription`](#push-channel-subscription) object representing the newly subscribed or updated push channel subscription. On failure, the promise is rejected with an [`ErrorInfo`](/docs/api/realtime-sdk/types#error-info) object that details the reason why it was rejected. - - ##### Callback result @@ -827,11 +701,6 @@ On failure to create or update the channel subscription, `err` contains an [`Err #### remove - - -`remove(PushChannelSubscription subscription): Promise` - - `remove(PushChannelSubscription channel_subscription)` @@ -859,15 +728,8 @@ Unsubscribe a device or group of devices sharing a [client identifier](/docs/aut | Parameter | Description | Type | |-----------|------|-------------| -| channelSubscriptionsubscription`channel_subscription` | A `PushChannelSubscription` object | [`PushChannelSubscription`](#push-channel-subscription) | +| channelSubscription`channel_subscription` | A `PushChannelSubscription` object | [`PushChannelSubscription`](#push-channel-subscription) | - - -##### Returns - -Returns a promise. On success to unsubscribe, the promise resolves. On failure, the promise is rejected with an [`ErrorInfo`](/docs/api/realtime-sdk/types#error-info) object that details the reason why it was rejected. - - ##### Callback result @@ -878,13 +740,8 @@ When this operation fails, `err` contains an [`ErrorInfo`](/docs/api/realtime-sd -#### removeWhereremove_where +#### removeWhereremove_where - - -`removeWhere(Object params): Promise` - - `remove_where(Hash params)` @@ -912,23 +769,16 @@ Delete all push channel subscriptions matching the `params` filter. Requires `pu | Parameter | Description | Type | |-----------|------|-------------| -| params | An object containing the filter parameters as key value pairs as specified below | `Object`[`Param[]`](#param) | +| params | An object containing the filter parameters as key value pairs as specified below | `Object`[`Param[]`](#param) | ##### `params` properties | Property | Description | Type | |----------|------|-------------| -| channel:channel | Filter to restrict to subscriptions associated with that `channel` | `String` | -| clientId:client_id | Optional filter to restrict to devices associated with that client identifier. Cannot be used with `deviceId``:device_id` param | `String` | -| deviceId:device_id | Optional filter to restrict to devices associated with that device identifier. Cannot be used with `clientId``:client_id` param | `String` | - - - -##### Returns +| channel:channel | Filter to restrict to subscriptions associated with that `channel` | `String` | +| clientId:client_id | Optional filter to restrict to devices associated with that client identifier. Cannot be used with `deviceId``:device_id` param | `String` | +| deviceId:device_id | Optional filter to restrict to devices associated with that device identifier. Cannot be used with `clientId``:client_id` param | `String` | -Returns a promise. On success to unsubscribe, the promise resolves. On failure, the promise is rejected with an [`ErrorInfo`](/docs/api/realtime-sdk/types#error-info) object that details the reason why it was rejected. - - ##### Callback result @@ -941,7 +791,7 @@ When this operation fails, `err` contains an [`ErrorInfo`](/docs/api/realtime-sd ## Related types -### DeviceDetailsAbly::Models::DeviceDetails +### DeviceDetailsAbly::Models::DeviceDetails A `DeviceDetails` is a type encapsulating attributes of a device registered for push notifications. @@ -950,16 +800,16 @@ A `DeviceDetails` is a type encapsulating attributes of a device registered for | Property | Description | Type | |----------|------|-------------| | id | Unique identifier for the device generated by the device itself | `String` | -| clientIdclient_id | Optional trusted [client identifier](/docs/auth/identified-clients) for the device | `String` | -| formFactorform_factor | Form factor of the push device. Must be one of `phone`, `tablet`, `desktop`, `tv`, `watch`, `car` or `embedded``embedded` or `other` | `String` | -| metadata | Optional metadata object for this device. The metadata for a device may only be set by clients with `push-admin` privileges | `Object``Hash` | -| platform | Platform of the push device. Must be one of `ios` or `android``android` or `browser` | `String` | +| clientIdclient_id | Optional trusted [client identifier](/docs/auth/identified-clients) for the device | `String` | +| formFactorform_factor | Form factor of the push device. Must be one of `phone`, `tablet`, `desktop`, `tv`, `watch`, `car` or `embedded` | `String` | +| metadata | Optional metadata object for this device. The metadata for a device may only be set by clients with `push-admin` privileges | `Object``Hash` | +| platform | Platform of the push device. Must be one of `ios` or `android` | `String` | | deviceSecret | Secret value for the device | `String` | -| push.recipient | Push recipient details for this device. See the [REST API push publish documentation](/docs/api/rest-api#message-extras-push) for more details | `Object``Hash` | -| push.state | The current state of the push device being either `Active`, `Failing` or `Failed``ACTIVE`, `FAILING` or `FAILED` | `String` | -| push.errorReasonpush.errorpush.error_reason | When the device's state is failing or failed, this attribute contains the reason for the most recent failure | [`ErrorInfo`](/docs/api/realtime-sdk/types#error-info) | +| push.recipient | Push recipient details for this device. See the [REST API push publish documentation](/docs/api/rest-api#message-extras-push) for more details | `Object``Hash` | +| push.state | The current state of the push device being either `Active`, `Failing` or `Failed` | `String` | +| push.errorReasonpush.error_reason | When the device's state is failing or failed, this attribute contains the reason for the most recent failure | [`ErrorInfo`](/docs/api/realtime-sdk/types#error-info) | -### PushChannelAbly::Models::PushChannel +### PushChannelAbly::Models::PushChannel A `PushChannel` is a property of a [`RealtimeChannel`](/docs/api/realtime-sdk/channels#properties) or [`RestChannel`](/docs/api/rest-sdk/channels#properties). It provides [push devices](/docs/push) the ability to subscribe and unsubscribe to push notifications on channels. @@ -967,11 +817,6 @@ A `PushChannel` is a property of a [`RealtimeChannel`](/docs/api/realtime-sdk/ch ##### subscribeDevice - - -`subscribeDevice(): Promise` - - `subscribeDevice()` @@ -980,21 +825,8 @@ A `PushChannel` is a property of a [`RealtimeChannel`](/docs/api/realtime-sdk/ch Subscribe your device to the channel's push notifications. - - -###### Returns - -Returns a promise. On success, the promise resolves. On failure, the promise is rejected with an [`ErrorInfo`](/docs/api/realtime-sdk/types#error-info) object that details the reason why it was rejected. - - - ##### subscribeClient - - -`subscribeClient(): Promise` - - `subscribeClient()` @@ -1003,22 +835,8 @@ Returns a promise. On success, the promise resolves. On failure, the promise is [Subscribe all devices associated with your device's clientId](/docs/push/publish#sub-channels) to the channel's push notifications. - - -###### Returns - -Returns a promise. On success, the promise resolves. On failure, the promise is rejected with an [`ErrorInfo`](/docs/api/realtime-sdk/types#error-info) object that details the reason why it was rejected. - - - ##### unsubscribeDevice - - -`unsubscribeDevice(): Promise` - - - `unsubscribeDevice()` @@ -1027,21 +845,8 @@ Returns a promise. On success, the promise resolves. On failure, the promise is Unsubscribe your device from the channel's push notifications. - - -###### Returns - -Returns a promise. On success, the promise resolves. On failure, the promise is rejected with an [`ErrorInfo`](/docs/api/realtime-sdk/types#error-info) object that details the reason why it was rejected. - - - ##### unsubscribeClient - - -`unsubscribeClient(): Promise` - - `unsubscribeClient()` @@ -1050,21 +855,8 @@ Returns a promise. On success, the promise resolves. On failure, the promise is [Unsubscribe all devices associated with your device's clientId](/docs/push/publish#sub-channels) from the channel's push notifications. - - -###### Returns - -Returns a promise. On success, the promise resolves. On failure, the promise is rejected with an [`ErrorInfo`](/docs/api/realtime-sdk/types#error-info) object that details the reason why it was rejected. - - - ##### listSubscriptions - - -`listSubscriptions(Record params?): Promise>` - - `PaginatedResult listSubscriptions(String deviceId, String clientId, String deviceClientId, String channel)` @@ -1078,19 +870,6 @@ Returns a promise. On success, the promise resolves. On failure, the promise is 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](/docs/api/rest-api). - - -##### Parameters - -| 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` | - - - ##### Parameters @@ -1116,13 +895,6 @@ Lists push subscriptions on a channel specified by its channel name (`channel`). - - -##### 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`](/docs/api/realtime-sdk/types#error-info) object that details the reason why it was rejected. - - ##### Callback result @@ -1142,25 +914,25 @@ Failure to retrieve the message history will raise an [`AblyException`](/docs/ap -### PushChannelSubscriptionARTPushChannelSubscriptionChannelSubscriptionArt::Models::PushChannelSubscription +### PushChannelSubscriptionARTPushChannelSubscriptionChannelSubscriptionArt::Models::PushChannelSubscription An `PushChannelSubscription` is a type encapsulating the subscription of a device or group of devices sharing a [client identifier](/docs/auth/identified-clients) to a channel in order to receive push notifications. -#### PropertiesMembersAttributes +#### PropertiesMembersAttributes | Property | Description | Type | |----------|------|-------------| | channel | The channel that this push notification subscription is associated with | `String` | -| deviceIddevice_id | The device with this identifier is linked to this channel subscription. When present, `clientId``client_id` is never present | `String` | -| clientIdclient_id | Devices with this [client identifier](/docs/auth/identified-clients) are included in this channel subscription. When present, `deviceId``device_id` is never present | `String` | +| deviceIddevice_id | The device with this identifier is linked to this channel subscription. When present, `clientId``client_id` is never present | `String` | +| clientIdclient_id | Devices with this [client identifier](/docs/auth/identified-clients) are included in this channel subscription. When present, `deviceId``device_id` is never present | `String` | ### PushChannelSubscription constructors -#### PushChannelSubscription.forDevicePushChannelSubscription.for_client +#### PushChannelSubscription.forDevicePushChannelSubscription.for_client - + `PushChannelSubscription.forDevice(String channel, String deviceId) -> PushChannelSubscription` @@ -1178,15 +950,15 @@ A static factory method to create a `PushChannelSubscription` object for a chann | Parameter | Description | Type | |-----------|------|-------------| | channel | Channel name linked to this push channel subscription | `String` | -| deviceIddevice_id | The device with this identifier will be linked with this push channel subscription | `String` | +| deviceIddevice_id | The device with this identifier will be linked with this push channel subscription | `String` | ##### Returns A [`PushChannelSubscription`](/docs/api/realtime-sdk/types#push-channel-subscription) object -#### PushChannelSubscription.forClientPushChannelSubscription.for_client +#### PushChannelSubscription.forClientPushChannelSubscription.for_client - + `PushChannelSubscription.forClient(String channel, String clientId) -> PushChannelSubscription` @@ -1204,7 +976,7 @@ A static factory method to create a `PushChannelSubscription` object for a chann | Parameter | Description | Type | |-----------|------|-------------| | channel | Channel name linked to this push channel subscription | `String` | -| clientIdclient_id | Devices with this [client identifier](/docs/auth/identified-clients) are included in the new push channel subscription | `String` | +| clientIdclient_id | Devices with this [client identifier](/docs/auth/identified-clients) are included in the new push channel subscription | `String` | ##### Returns @@ -1212,25 +984,20 @@ A `PushChannelSubscription` object -### PaginatedResultARTPaginatedResultio.ably.lib.types.PaginatedResultAbly::Models::PaginatedResult +### PaginatedResultARTPaginatedResultio.ably.lib.types.PaginatedResultAbly::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](/docs/api/rest-api/#pagination) is accompanied by metadata that indicates the relative queries available to the `PaginatedResult` object. -#### PropertiesMembersAttributes +#### PropertiesMembersAttributes | 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 ``List ` | +| 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 ``List ` | #### Methods ##### first - - -`first(): Promise` - - `PaginatedResult first` @@ -1256,16 +1023,11 @@ A `PaginatedResult` is a type that represents a page of results for all message Returns a new `PaginatedResult` for the first page of results. When using the Realtime library, the `first` method returns a [Deferrable](/docs/api/realtime-sdk/types#deferrable) and yields a [PaginatedResult](#paginated-result). - - - -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`](/docs/api/realtime-sdk/types#error-info) object that details the reason why it was rejected. - ##### hasNext - + `Boolean hasNext()` @@ -1285,7 +1047,7 @@ Returns `true` if there are more pages available by calling `next` and returns ` ##### isLast - + `Boolean isLast()` @@ -1305,11 +1067,6 @@ Returns `true` if this page is the last page and returns `false` if there are mo ##### next - - - -`current(): Promise` - - - -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`](/docs/api/realtime-sdk/types#error-info) object that details the reason why it was rejected. +Returns a new `PaginatedResult` loaded with the next page of results. If there are no further pages, then `null``Null``None``nil` is returned. When using the Realtime library, the `first` method returns a [Deferrable](/docs/api/realtime-sdk/types#deferrable) and yields a [PaginatedResult](#paginated-result). ##### Example - - - -```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()); -``` - - - - - - -```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()); -``` - - - - diff --git a/src/pages/docs/api/realtime-sdk/push.mdx b/src/pages/docs/api/realtime-sdk/push.mdx index 8a10e9d693..3801975a1c 100644 --- a/src/pages/docs/api/realtime-sdk/push.mdx +++ b/src/pages/docs/api/realtime-sdk/push.mdx @@ -24,11 +24,6 @@ This object is accessible through `client.push` and provides to [push-compatible #### activate - - -`activate(registerCallback?(DeviceDetails device, callback(ErrorInfo | null err, DeviceDetails result)), updateFailedCallback?(ErrorInfo | null err)): Promise` - - `void activate()` @@ -44,31 +39,10 @@ This object is accessible through `client.push` and provides to [push-compatible Register the device for push. When the [activation process](/docs/push/configure/device#activate-devices) is completed, Ably will 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`call the `(void)didActivateAblyPush:(nullable ARTErrorInfo *)error``didActivateAblyPush(error: ARTErrorInfo?)` method from the `ARTPushRegistererDelegate`. - - - -[Activates the device](/docs/push/configure/web#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. - #### deactivate - - -`deactivate(deregisterCallback?(DeviceDetails device, callback(ErrorInfo | null err, String result))): Promise` - - `void deactivate()` @@ -84,49 +58,6 @@ Returns a promise. On successful device activation, the promise resolves. On fai Deregister the device for push. When the deactivation process is completed, Ably will 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`call the `(void)didDeactivateAblyPush:(nullable ARTErrorInfo *)error``didDeactivateAblyPush(error: ARTErrorInfo?)` method from the `ARTPushRegistererDelegate`. - - - -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. - - - - - -#### updateToken - -`updateToken(token: PushDeviceToken): Promise` - -Updates the device's push token after the underlying push platform has rotated it, and synchronizes the new token with Ably by updating the device registration. Call it from your platform's token refresh listener, for example `messaging().onTokenRefresh()` of `@react-native-firebase/messaging`, once [`activate()`](#activate) has completed. - - -```javascript -messaging().onTokenRefresh(async (token) => { - await client.push.updateToken({ transportType: 'fcm', token }); -}); -``` - - -##### Parameters - -| Parameter | Description | Type | -|-----------|-------------|------| -| token | The refreshed push token, in the same shape as returned by the `requestToken` callback of the `ably/react-native-push` plugin | [`PushDeviceToken`](#push-device-token) | - -##### Returns - -Returns a promise. The promise resolves once the updated registration has been synchronized with Ably. On failure, or if the device is not activated for push notifications, the promise is rejected with an [`ErrorInfo`](/docs/api/realtime-sdk/types#error-info) object that details the reason it was rejected. - @@ -147,23 +78,23 @@ The following table explains how to receive location push notifications: ## Related types -### DeviceDetailsARTDeviceDetails +### DeviceDetailsARTDeviceDetails A `DeviceDetails` is a type encapsulating attributes of a device registered for push notifications. -#### PropertiesMembers +#### PropertiesMembers | Property | Description | Type | |----------|-------------|------| | id | Unique identifier for the device generated by the device itself | `String` | | clientId | Optional trusted [client identifier](/docs/auth/identified-clients) for the device | `String` | -| formFactor | Form factor of the push device. Must be one of `phone`, `tablet`, `desktop`, `tv`, `watch`, `car` or `embedded``embedded` or `other` | `String` | +| formFactor | Form factor of the push device. Must be one of `phone`, `tablet`, `desktop`, `tv`, `watch`, `car` or `embedded` | `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` or `android``android` or `browser` | `String` | +| platform | Platform of the push device. Must be one of `ios` or `android` | `String` | | deviceSecret | Secret value for the device | `String` | | push.recipient | Push recipient details for this device. See the [REST API push publish documentation](/docs/api/rest-api#message-extras-push) for more details | `Object` | -| push.state | The current state of the push device being either `Active`, `Failing` or `Failed``ACTIVE`, `FAILING` or `FAILED` | `String` | -| push.errorReasonpush.error | When the device's state is failing or failed, this attribute contains the reason for the most recent failure | [`ErrorInfo`](/docs/api/realtime-sdk/types#error-info) | +| push.state | The current state of the push device being either `Active`, `Failing` or `Failed` | `String` | +| push.errorReason | When the device's state is failing or failed, this attribute contains the reason for the most recent failure | [`ErrorInfo`](/docs/api/realtime-sdk/types#error-info) | ### LocalDevice @@ -173,15 +104,9 @@ An extension of [`DeviceDetails`](#device-details). In addition to the - - -Contains the device identity token and secret of a device. - - +#### PropertiesMembers -#### PropertiesMembers - - + | Property | Description | Type | |----------|-------------|------| @@ -196,36 +121,6 @@ Contains the device identity token and secret of a device. |----------|-------------|------| | deviceIdentityToken | A unique identity token for the device | `String` | - - - -#### Methods - -##### listSubscriptions - -`listSubscriptions(): Promise<PaginatedResult<PushChannelSubscription>>` - -Retrieves push subscriptions active for the local device. - -##### Returns - -Returns a promise. On success, the promise is fulfilled with a [PaginatedResult](/docs/api/realtime-sdk/types#paginated-result) object containing an array of [PushChannelSubscription](/docs/api/realtime-sdk/types#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. - - - - - -### PushDeviceToken - -A `PushDeviceToken` is a push token obtained from the underlying push platform, along with the transport it belongs to. It has the same shape as the `ReactNativePushToken` accepted by the `ably/react-native-push` plugin's `requestToken` callback, and is the parameter type of [`updateToken()`](#update-token). - -#### Properties - -| Property | Description | Type | -|----------|-------------|------| -| transportType | The push transport the token belongs to: `fcm` for a Firebase Cloud Messaging registration token, or `apns` for a raw APNs device token | `String` | -| token | The token itself: an FCM registration token or an APNs device token | `String` | - ### PushChannel @@ -236,11 +131,6 @@ A `PushChannel` is a property of a [`RealtimeChannel`](/docs/api/realtime-sdk/ch ##### subscribeDevice - - -`subscribeDevice(): Promise` - - `subscribeDevice()` @@ -249,21 +139,8 @@ A `PushChannel` is a property of a [`RealtimeChannel`](/docs/api/realtime-sdk/ch Subscribe your device to the channel's push notifications. - - -##### Returns - -Returns a promise. On success, the promise resolves. On failure, the promise is rejected with an [`ErrorInfo`](/docs/api/realtime-sdk/types#error-info) object that details the reason why it was rejected. - - - #### subscribeClient - - -`subscribeClient(): Promise` - - `subscribeClient()` @@ -272,21 +149,8 @@ Returns a promise. On success, the promise resolves. On failure, the promise is [Subscribe all devices associated with your device's clientId](/docs/push/publish#sub-channels) to the channel's push notifications. - - -##### Returns - -Returns a promise. On success, the promise resolves. On failure, the promise is rejected with an [`ErrorInfo`](/docs/api/realtime-sdk/types#error-info) object that details the reason why it was rejected. - - - #### unsubscribeDevice - - -`unsubscribeDevice(): Promise` - - `unsubscribeDevice()` @@ -295,21 +159,8 @@ Returns a promise. On success, the promise resolves. On failure, the promise is Unsubscribe your device from the channel's push notifications. - - -##### Returns - -Returns a promise. On success, the promise resolves. On failure, the promise is rejected with an [`ErrorInfo`](/docs/api/realtime-sdk/types#error-info) object that details the reason why it was rejected. - - - #### unsubscribeClient - - -`unsubscribeClient(): Promise` - - `unsubscribeClient()` @@ -318,21 +169,8 @@ Returns a promise. On success, the promise resolves. On failure, the promise is [Unsubscribe all devices associated with your device's clientId](/docs/push/publish#sub-channels) from the channel's push notifications. - - -##### Returns - -Returns a promise. On success, the promise resolves. On failure, the promise is rejected with an [`ErrorInfo`](/docs/api/realtime-sdk/types#error-info) object that details the reason why it was rejected. - - - #### listSubscriptions - - -`listSubscriptions(Record params?): Promise>` - - `PaginatedResult listSubscriptions(String deviceId, String clientId, String deviceClientId, String channel)` @@ -348,17 +186,6 @@ Lists push subscriptions on a channel specified by its channel name (`channel`). ##### Parameters - - -| 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` | - - - | Parameter | Description | Type | @@ -380,13 +207,6 @@ Lists push subscriptions on a channel specified by its channel name (`channel`). - - -##### 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`](/docs/api/realtime-sdk/types#error-info) object that details the reason why it was rejected. - - ##### Callback result @@ -406,11 +226,11 @@ Failure to retrieve the message history will raise an [`AblyException`](/docs/ap -### PushChannelSubscriptionChannelSubscriptionARTPushChannelSubscription +### ChannelSubscriptionARTPushChannelSubscription A `PushChannelSubscription` is a type encapsulating the subscription of a device or group of devices sharing a [client identifier](/docs/auth/identified-clients) to a channel in order to receive push notifications. -#### PropertiesMembers +#### PropertiesMembers | Property | Description | Type | |----------|-------------|------| @@ -458,11 +278,11 @@ A `PushChannelSubscription` object -### PaginatedResultARTPaginatedResultio.ably.lib.types.PaginatedResult +### ARTPaginatedResultio.ably.lib.types.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 an [Ably REST API paginated query](/docs/api/rest-api/#pagination) is accompanied by metadata that indicates the relative queries available to the `PaginatedResult` object. -#### PropertiesMembers +#### PropertiesMembers | Property | Description | Type | |----------|-------------|------| @@ -472,11 +292,6 @@ A `PaginatedResult` is a type that represents a page of results for all message ##### first - - -`first(): Promise` - - `PaginatedResult first()` @@ -492,20 +307,10 @@ A `PaginatedResult` is a type that represents a page of results for all message Returns a new `PaginatedResult` for the first page of results. - - - -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`](/docs/api/realtime-sdk/types#error-info) object that details the reason why it was rejected. - ##### hasNext - - -`Boolean hasNext()` - - `Boolean hasNext()` @@ -527,11 +332,6 @@ Returns `true` if this page is the last page and returns `false` if there are mo ##### next - -`current(): Promise` - -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`](/docs/api/realtime-sdk/types#error-info) object that details the reason why it was rejected. +Returns a new `PaginatedResult` loaded with the next page of results. If there are no further pages, then `Null``nil` is returned. ##### Example - - - -```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()); -``` - - - - - - -```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()); -``` - - - diff --git a/src/pages/docs/api/realtime-sdk/statistics.mdx b/src/pages/docs/api/realtime-sdk/statistics.mdx index 15b55ae575..7179cb2000 100644 --- a/src/pages/docs/api/realtime-sdk/statistics.mdx +++ b/src/pages/docs/api/realtime-sdk/statistics.mdx @@ -16,12 +16,6 @@ We've updated the style and readability of our API references, starting with Jav ### stats - - -`stats(Object params?): Promise>` - - - `Deferrable stats(Hash options) → yields PaginatedResult` @@ -50,11 +44,11 @@ This call queries the [REST `/stats` API](/docs/api/rest-api#stats) and retrieve #### Parameters - + | Parameter | Description | Type | |-----------|-------------|------| -| queryparamsoptions | An optional object containing the query parameters used to specify which statistics are retrieved. If not specified the default parameters will be used | [`StatsRequestParams`](#stats-request-params)[`Param[]`](#param)Object | +| queryoptions | An optional object containing the query parameters | [`StatsRequestParams`](#stats-request-params)[`Param[]`](#param) | @@ -76,22 +70,10 @@ This call queries the [REST `/stats` API](/docs/api/rest-api#stats) and retrieve -#### `ARTStatsQuery` properties`StatsRequestParams` properties`params` properties`options` parameters +#### `ARTStatsQuery` properties`StatsRequestParams` properties`options` parameters The following options, as defined in the [REST `/stats` API](/docs/api/rest-api#stats) endpoint, are permitted: - - -| Property | Description | Type | -|----------|-------------|------| -| start | Earliest time in milliseconds since the epoch for any stats retrieved.
_Default: beginning of time_ | `Number` | -| end | Latest time in milliseconds since the epoch for any stats retrieved.
_Default: current time_ | `Number` | -| direction | `forwards` or `backwards`.
_Default: `backwards`_ | `String` | -| limit | Maximum number of stats to retrieve up to 1,000.
_Default: `100`_ | `Number` | -| unit | `minute`, `hour`, `day` or `month`. Based on the unit selected, the given start or end times are rounded down to the start of the relevant interval depending on the unit granularity of the query.
_Default: `minute`_ | [`StatsIntervalGranularity`](/docs/api/realtime-sdk/types#stats-granularity) | - - - | Property | Description | Type | @@ -140,14 +122,6 @@ The following options, as defined in the [REST `/stats` API](/docs/api/rest-api# - - -#### Returns - -Returns a promise. On success, the promise is fulfilled with a [PaginatedResult](/docs/api/realtime-sdk/types#paginated-result) object containing an array of [Stats](/docs/api/realtime-sdk/types#stats) objects. On failure, the promise is rejected with an [ErrorInfo](/docs/api/realtime-sdk/types#error-info) object. - - - #### Callback result @@ -194,7 +168,7 @@ Failure to retrieve the stats will trigger the errback callbacks of the [Deferra ## Related types -### ARTStats io.ably.lib.types.Stats Ably::Models::Stats IO.Ably.Stats Stats object +### ARTStats io.ably.lib.types.Stats Ably::Models::Stats IO.Ably.Stats A `Stats` object represents an application's statistics for the specified interval and time period. Ably aggregates statistics globally for all accounts and applications, and makes these available both through our [statistics API](/docs/metadata-stats/stats) as well as your [application dashboard](https://ably.com/dashboard). @@ -204,7 +178,7 @@ Please note that most attributes of the `Stats` type below contain references to -#### MembersAttributesProperties +#### MembersAttributesProperties @@ -283,18 +257,6 @@ Please note that most attributes of the `Stats` type below contain references to - - -| Property | Description | Type | -|----------|-------------|------| -| appId | The ID of the Ably application the statistics relate to | `String` | -| entries | The statistics for the requested time interval and time period. The `schema` property provides further information | `Partial>` | -| inProgress | Optional. For entries that are still in progress, such as the current month, the last sub-interval included in the stats entry. In the format `yyyy-mm-dd:hh:mm:ss` | `String` | -| intervalId | The UTC time period that the stats coverage begins at. If `unit` was requested as `minute` this will be in the format `YYYY-mm-dd:HH:MM`, if `hour` it will be `YYYY-mm-dd:HH`, if `day` it will be `YYYY-mm-dd:00` and if `month` it will be `YYYY-mm-01:00` | `String` | -| schema | The URL of a JSON schema describing the structure of the `Stats` object | `String` | - - - ### IO.Ably.StatsRequestParams @@ -313,37 +275,7 @@ Please note that most attributes of the `Stats` type below contain references to -### ARTStatsGranularity StatsIntervalGranularity - - -`StatsIntervalGranularity` is an enum specifying the granularity of a [Stats interval](/docs/api/rest-sdk/statistics#stats-type). - - - -```javascript -const StatsIntervalGranularity = [ - 'minute', - 'hour', - 'day', - 'month' -] -``` - - - - - -```nodejs -const StatsIntervalGranularity = [ - 'minute', - 'hour', - 'day', - 'month' -] -``` - - - +### ARTStatsGranularity StatsIntervalGranularity @@ -382,7 +314,6 @@ enum ARTStatsGranularity : UInt { - diff --git a/src/pages/docs/api/realtime-sdk/types.mdx b/src/pages/docs/api/realtime-sdk/types.mdx index 0d69a52afb..f9373d25c4 100644 --- a/src/pages/docs/api/realtime-sdk/types.mdx +++ b/src/pages/docs/api/realtime-sdk/types.mdx @@ -167,21 +167,21 @@ An extension of [`DeviceDetails`](/docs/api/realtime-sdk/types#device-details). -### ErrorInfoably.ErrorInfoIO.Ably.ErrorInfoio.ably.lib.types.ErrorInfoARTErrorInfoAbly::Models::ErrorInfo +### ErrorInfoably.ErrorInfoIO.Ably.ErrorInfoio.ably.lib.types.ErrorInfoARTErrorInfoAbly::Models::ErrorInfo An `ErrorInfo` is a type encapsulating error information containing an Ably-specific error code and generic status code. #### Properties - + | Property | Description | Type | |----------|-------------|------| -| codeCode | Ably error code (see [ably-common/protocol/errors.json](https://github.com/ably/ably-common/blob/main/protocol/errors.json)) | `Integer` | -| statusCodestatus_codeStatusCode | HTTP Status Code corresponding to this error, where applicable | `Integer` | -| messageMessage | Additional message information, where available | `String` | -| causeCause | Information pertaining to what caused the error where available | `ErrorInfo` | -| hrefHref | Ably may additionally include a URL to get more help on this error | `String` | +| codeCode | Ably error code (see [ably-common/protocol/errors.json](https://github.com/ably/ably-common/blob/main/protocol/errors.json)) | `Integer` | +| statusCodestatus_codeStatusCode | HTTP Status Code corresponding to this error, where applicable | `Integer` | +| messageMessage | Additional message information, where available | `String` | +| causeCause | Information pertaining to what caused the error where available | `ErrorInfo` | +| hrefHref | Ably may additionally include a URL to get more help on this error | `String` | @@ -205,48 +205,6 @@ One example of ErrorInfo nesting is [80019: Auth server rejecting request](/docs The following example demonstrates how to handle nested errors: - - - -```javascript -function handleError(error) { - console.log(`Main error: ${error.code} - ${error.message}`); - - // Check for nested error - if (error.cause) { - console.log(`Root cause: ${error.cause.code} - ${error.cause.message}`); - - // Handle further nesting if needed - if (error.cause.cause) { - console.log(`Deeper cause: ${error.cause.cause.code} - ${error.cause.cause.message}`); - } - } -} -``` - - - - - - -```nodejs -function handleError(error) { - console.log(`Main error: ${error.code} - ${error.message}`); - - // Check for nested error - if (error.cause) { - console.log(`Root cause: ${error.cause.code} - ${error.cause.message}`); - - // Handle further nesting if needed - if (error.cause.cause) { - console.log(`Deeper cause: ${error.cause.cause.code} - ${error.cause.cause.message}`); - } - } -} -``` - - - @@ -384,70 +342,52 @@ func handleError(err *ErrorInfo) { -### Message ARTMessage io.ably.lib.types.Message Ably::Models::Message IO.Ably.Message +### Message ARTMessage io.ably.lib.types.Message Ably::Models::Message IO.Ably.Message A `Message` represents an individual message that is sent to or received from Ably. -### nameName +### nameName The event name, if provided.
_Type: `String`_ -### data Data +### data Data The message payload, if provided. -_Type: `String`, `StringBuffer`, `JSON Object``String`, `ByteArray`, `JSONObject`, `JSONArray``String`, `Binary` (ASCII-8BIT String), `Hash`, `Array``NSString *`, `NSData *`, `NSDictionary *`, `NSArray *``String`, `NSData`, `Dictionary`, `Array``String`, `byte[]`, `plain C# object that can be serialized to JSON``String`, `Map`, `List`_ +_Type: `String`, `StringBuffer`, `JSON Object``String`, `ByteArray`, `JSONObject`, `JSONArray``String`, `Binary` (ASCII-8BIT String), `Hash`, `Array``NSString *`, `NSData *`, `NSDictionary *`, `NSArray *``String`, `NSData`, `Dictionary`, `Array``String`, `byte[]`, `plain C# object that can be serialized to JSON``String`, `Map`, `List`_ -### extras Extras +### extras Extras Metadata and/or ancillary payloads, if provided. Valid payloads include [`push`](/docs/push/publish#payload), `headers` (a map of strings to strings for arbitrary customer-supplied metadata), [`ephemeral`](/docs/pub-sub/advanced#ephemeral), and [`privileged`](/docs/platform/integrations/skip-integrations) objects. -_Type: `JSONObject`, `JSONArray``JSON Object``Hash`, `Array``Dictionary`, `Array``NSDictionary *`, `NSArray *``plain C# object that can be converted to JSON`_ +_Type: `JSONObject`, `JSONArray``JSON Object``Hash`, `Array``Dictionary`, `Array``NSDictionary *`, `NSArray *``plain C# object that can be converted to JSON`_ -### idId +### idId A Unique ID assigned by Ably to this message.
_Type: `String`_ -### clientIdClientIdclient_id +### clientIdClientIdclient_id The client ID of the publisher of this message.
_Type: `String`_ -### connectionIdConnectionIdconnection_id +### connectionIdConnectionIdconnection_id The connection ID of the publisher of this message.
_Type: `String`_ -### connectionKeyConnectionKeyconnection_key +### connectionKeyConnectionKeyconnection_key A connection key, which can optionally be included for a REST publish as part of the [publishing on behalf of a realtime client functionality](/docs/pub-sub/advanced#publish-on-behalf).
_Type: `String`_ -### timestampTimestamp +### timestampTimestamp -Timestamp when the message was first received by the Ably, as milliseconds since the epocha `Time` object. +Timestamp when the message was first received by the Ably, as milliseconds since the epocha `Time` object. -_Type: `Integer``Long Integer``Time``NSDate``DateTimeOffset``Integer`_ +_Type: `Integer``Long Integer``Time``NSDate``DateTimeOffset``Integer`_ -### encodingEncoding +### encodingEncoding This will typically be empty as all messages received from Ably are automatically decoded client-side using this value. However, if the message encoding cannot be processed, this attribute will contain the remaining transformations not applied to the `data` payload.
_Type: `String`_ - - -### action - -The action type of the message, one of the [`MessageAction`](/docs/api/realtime-sdk/types#message-action) enum values. - -_Type: `int enum { MESSAGE_CREATE, MESSAGE_UPDATE, MESSAGE_DELETE, META, MESSAGE_SUMMARY, MESSAGE_APPEND }`_ - -### serial - -A server-assigned identifier that will be the same in all future updates of this message. It can be used to add annotations to a message. Serial will only be set if you enable annotations in [rules](/docs/channels#rules).
_Type: `String`_ - -### annotations - -An object containing information about annotations that have been made to the object.
_Type: [`MessageAnnotations`](/docs/api/realtime-sdk/types#message-annotations)_ - - - ### Message constructors #### Message.fromEncoded @@ -484,47 +424,10 @@ A static factory method to create an array of [`Messages`](/docs/api/realtime-sd An `Array` of [`Message`](/docs/api/realtime-sdk/types#message) objects - - -### Message actionARTMessageActionio.ably.lib.types.Message.Action + - +### ARTMessageActionio.ably.lib.types.Message.Action -`Message` `action` is a String representing the action type of the message. - - - - -```javascript - const MessageActions = [ - 'message.create', - 'message.update', - 'message.delete', - 'meta', - 'message.summary' - 'message.append', - ] -``` - - - - - - -```nodejs - const MessageActions = [ - 'message.create', - 'message.update', - 'message.delete', - 'meta', - 'message.summary' - 'message.append', - ] -``` - - - - `io.ably.lib.types.Message.Action` is an enum representing the action type of the message. @@ -583,69 +486,45 @@ An `Array` of [`Message`](/docs/api/realtime-sdk/types#message) objects ### MessageAnnotations -#### PropertiesMembersAttributes +#### PropertiesMembersAttributes | Property | Description | Type | |----------|-------------|------| -| summary | An object whose keys are [annotation types](/docs/messages/annotations#annotation-types), and whose values are aggregated [summary entries](#summary-entry)summary entries for that annotation type. The structure of each value depends on the summarization method, for example a `total.v1` entry will have a `total` field, while a `flag.v1` entry will have `total` and `clientIds` fields. See [annotation summaries](/docs/messages/annotations#annotation-summaries) for details | `Record`[`Summary`](#summary)`NSDictionary``Dict[str, Dict]``Record` | +| summary | An object whose keys are [annotation types](/docs/messages/annotations#annotation-types), and whose values are aggregated [summary entries](#summary-entry)summary entries for that annotation type. The structure of each value depends on the summarization method, for example a `total.v1` entry will have a `total` field, while a `flag.v1` entry will have `total` and `clientIds` fields. See [annotation summaries](/docs/messages/annotations#annotation-summaries) for details | [`Summary`](#summary)`NSDictionary``Dict[str, Dict]``Record` | - + -### AnnotationARTAnnotationio.ably.lib.types.AnnotationAnnotation +### ARTAnnotationio.ably.lib.types.AnnotationAnnotation An `Annotation` represents an individual annotation event for a message — either an `annotation.create` or `annotation.delete`. The same type is used both for publishing an annotation and for receiving one. When publishing, only `type` is required; some annotation types additionally need `name` (and `count` for `multiple.v1`), and `data`, `extras`, and `encoding` are optional user-set fields. The other fields (`id`, `clientId`, `timestamp`, `serial`, `messageSerial`, `action`) are server- or SDK-populated, and are present on annotations received via [`channel.annotations.subscribe`](/docs/api/realtime-sdk/channels#annotations-subscribe) or [`channel.annotations.get`](/docs/api/realtime-sdk/channels#annotations-get). See the per-field descriptions below for details. -#### PropertiesMembersAttributes +#### PropertiesMembersAttributes | Property | Description | Type | |----------|-------------|------| | type | The [annotation type](/docs/messages/annotations#annotation-types) (for example `reactions:distinct.v1`). Required when publishing | `String` | | name | The name of the annotation, used by some annotation types for aggregation | `String` | -| count | An optional count, only relevant to the `multiple.v1` annotation type | `int``Integer``NSNumber` | -| data | An optional payload for the annotation. Available on individual annotations but not aggregated or included in [annotation summaries](/docs/messages/annotations#annotation-summaries) | `Any``Object` | -| extras | Metadata and/or ancillary payloads, if provided. Valid payloads include [`push`](/docs/push/publish#payload), `headers` (a map of strings to strings for arbitrary customer-supplied metadata), [`ephemeral`](/docs/pub-sub/advanced#ephemeral), and [`privileged`](/docs/platform/integrations/skip-integrations) objects | `JSONObject`, `JSONArray``JSON Object``Dictionary`, `Array``NSDictionary *`, `NSArray *` | +| count | An optional count, only relevant to the `multiple.v1` annotation type | `int``Integer``NSNumber` | +| data | An optional payload for the annotation. Available on individual annotations but not aggregated or included in [annotation summaries](/docs/messages/annotations#annotation-summaries) | `Any``Object` | +| extras | Metadata and/or ancillary payloads, if provided. Valid payloads include [`push`](/docs/push/publish#payload), `headers` (a map of strings to strings for arbitrary customer-supplied metadata), [`ephemeral`](/docs/pub-sub/advanced#ephemeral), and [`privileged`](/docs/platform/integrations/skip-integrations) objects | `JSONObject`, `JSONArray``JSON Object``Dictionary`, `Array``NSDictionary *`, `NSArray *` | | id | A unique ID assigned by Ably to this annotation. Server-set | `String` | -| clientIdclient_id | The client ID of the publisher of this annotation. Server-set, from the publishing client's connection | `String` | -| timestamp | The timestamp of when the annotation was received by Ably, as milliseconds since the Unix epoch. Server-set | `Integer``Long Integer``NSDate` | +| clientIdclient_id | The client ID of the publisher of this annotation. Server-set, from the publishing client's connection | `String` | +| timestamp | The timestamp of when the annotation was received by Ably, as milliseconds since the Unix epoch. Server-set | `Integer``Long Integer``NSDate` | | action | Whether this is an annotation being added or removed. Set automatically by the SDK when publishing or deleting | [`AnnotationAction`](#annotation-action) | | serial | This annotation's unique serial (lexicographically totally ordered). Server-set | `String` | -| messageSerialmessage_serial | The serial of the message that this annotation is annotating. Set automatically by the SDK from the [`Message`](#message) or `messageSerial` argument passed to publish/delete | `String` | +| messageSerialmessage_serial | The serial of the message that this annotation is annotating. Set automatically by the SDK from the [`Message`](#message) or `messageSerial` argument passed to publish/delete | `String` | | encoding | This is typically empty, as all annotations received from Ably are automatically decoded client-side using this value. However, if the annotation encoding cannot be processed, this attribute contains the remaining transformations not applied to the `data` payload | `String` | - + -### AnnotationActionARTAnnotationActionio.ably.lib.types.AnnotationActionAnnotationAction +### ARTAnnotationActionio.ably.lib.types.AnnotationActionAnnotationAction An enum identifying whether an annotation event is a creation or a deletion. - - - -```javascript - const AnnotationActions = [ - 'annotation.create', - 'annotation.delete', - ] -``` - - - - - - -```nodejs - const AnnotationActions = [ - 'annotation.create', - 'annotation.delete', - ] -``` - - - @@ -696,18 +575,6 @@ An enum identifying whether an annotation event is a creation or a deletion. - - -### GetAnnotationsParams - -The parameters object accepted by [`channel.annotations.get`](/docs/api/realtime-sdk/channels#annotations-get). - -| Property | Description | Type | -|----------|-------------|------| -| limit | An upper limit on the number of annotations returned. The default is 100, and the maximum is 1000 | `Integer` | - - - ### ARTAnnotationsQuery @@ -720,17 +587,12 @@ The query object accepted by [`channel.annotations.get`](/docs/api/realtime-sdk/ - + ### Summary entry types The values held in [`MessageAnnotations.summary`](#message-annotations) depend on the [summarization method](/docs/messages/annotations#annotation-types) of the annotation type. The shape of each entry corresponds to one of the following. - - -The TypeScript type [`SummaryEntry`](#summary-entry) is a union of these shapes. - - In Java, [`MessageAnnotations.summary`](#message-annotations) is exposed as a [`Summary`](#summary) object that holds the raw `JsonObject` for each annotation type. To extract a strongly-typed entry from the [`Summary`](#summary), use one of the static converters on the `Summary` class: @@ -763,35 +625,35 @@ In Python the summary is a plain `dict`. The shapes below describe the structure -#### SummaryClientIdListARTSummaryClientIdListio.ably.lib.types.SummaryClientIdListflag.v1 entry +#### ARTSummaryClientIdListio.ably.lib.types.SummaryClientIdListflag.v1 entry The summary entry for `flag.v1`, and the per-name value for `distinct.v1` and `unique.v1`. | Property | Description | Type | |----------|-------------|------| -| total | The total number of clients who have published an annotation with this name (or type, depending on context) | `Integer``int``NSInteger` | -| clientIds | A list of the clientIds of all clients who have published an annotation with this name (or type, depending on context) | `String[]``List``NSArray``List[str]` | -| clipped | Whether the list of clientIds has been clipped due to exceeding the maximum number of clients | `Boolean``boolean``BOOL` | +| total | The total number of clients who have published an annotation with this name (or type, depending on context) | `Integer``int``NSInteger` | +| clientIds | A list of the clientIds of all clients who have published an annotation with this name (or type, depending on context) | `List``NSArray``List[str]` | +| clipped | Whether the list of clientIds has been clipped due to exceeding the maximum number of clients | `Boolean``boolean``BOOL` | -#### SummaryClientIdCountsARTSummaryClientIdCountsio.ably.lib.types.SummaryClientIdCountsmultiple.v1 entry +#### ARTSummaryClientIdCountsio.ably.lib.types.SummaryClientIdCountsmultiple.v1 entry The per-name value for the `multiple.v1` annotation type. | Property | Description | Type | |----------|-------------|------| -| total | The sum of the counts from all clients who have published an annotation with this name | `Integer``int``NSInteger` | -| clientIds | A map from clientIds to the count each of those clients has contributed | `Record``Map``NSDictionary``Dict[str, int]` | -| totalUnidentifiedtotalUnidentified | The sum of counts contributed by unidentified clients (which are not included in the `clientIds` map) | `Integer``int``NSInteger` | -| clipped | Whether the `clientIds` map has been clipped due to exceeding the maximum number of clients | `Boolean``boolean``BOOL` | -| totalClientIdstotalClientIds | The total number of distinct identified clients (equal to the size of `clientIds` if `clipped` is false) | `Integer``int``NSInteger` | +| total | The sum of the counts from all clients who have published an annotation with this name | `Integer``int``NSInteger` | +| clientIds | A map from clientIds to the count each of those clients has contributed | `Map``NSDictionary``Dict[str, int]` | +| totalUnidentifiedtotalUnidentified | The sum of counts contributed by unidentified clients (which are not included in the `clientIds` map) | `Integer``int``NSInteger` | +| clipped | Whether the `clientIds` map has been clipped due to exceeding the maximum number of clients | `Boolean``boolean``BOOL` | +| totalClientIdstotalClientIds | The total number of distinct identified clients (equal to the size of `clientIds` if `clipped` is false) | `Integer``int``NSInteger` | -#### SummaryTotalARTSummaryTotalio.ably.lib.types.SummaryTotaltotal.v1 entry +#### ARTSummaryTotalio.ably.lib.types.SummaryTotaltotal.v1 entry The summary entry for the `total.v1` annotation type. | Property | Description | Type | |----------|-------------|------| -| total | The total number of annotations of this type that have been published for the message | `Integer``int``NSInteger` | +| total | The total number of annotations of this type that have been published for the message | `Integer``int``NSInteger` | @@ -813,38 +675,38 @@ Use the static converter methods listed [above](#summary-entry) (`Summary.asSumm Contains the result of a publish operation. -#### PropertiesMembersAttributes +#### PropertiesMembersAttributes | Property | Description | Type | |----------|-------------|------| -| serialsSerials | An array of message serials corresponding 1:1 to the messages that were published. A serial may be null if the message was discarded due to a configured conflation rule. | `String[]` | +| serialsSerials | An array of message serials corresponding 1:1 to the messages that were published. A serial may be null if the message was discarded due to a configured conflation rule. | `String[]` | ### UpdateDeleteResult Contains the result of an update, delete, or append message operation. -#### PropertiesMembersAttributes +#### PropertiesMembersAttributes | Property | Description | Type | |----------|-------------|------| -| versionSerialVersionSerial | The serial of the version of the updated, deleted, or appended message. Will be null if the message was superseded by a subsequent update before it could be published. | `String` | +| versionSerialVersionSerial | The serial of the version of the updated, deleted, or appended message. Will be null if the message was superseded by a subsequent update before it could be published. | `String` | -### PresenceMessageio.ably.lib.types.PresenceMessageAbly::Models::PresenceMessageARTPresenceMessageIO.Ably.PresenceMessage +### PresenceMessageio.ably.lib.types.PresenceMessageAbly::Models::PresenceMessageARTPresenceMessageIO.Ably.PresenceMessage A `PresenceMessage` represents an individual presence update that is sent to or received from Ably. -#### PropertiesMembers +#### PropertiesMembers | Property | Description | Type | |----------|-------------|------| -| actionAction | The event signified by a PresenceMessage. See [`PresenceMessage.action`](/docs/api/realtime-sdk/types#presence-action)[Presence action](/docs/api/realtime-sdk/types#presence-action)[`PresenceAction`](/docs/api/realtime-sdk/types#presence-action)[`PresenceMessage::ACTION`](/docs/api/realtime-sdk/types#presence-action)[`PresenceMessage.action`](/docs/api/realtime-sdk/types#presence-action)[`PresenceMessage::action`](/docs/api/realtime-sdk/types#presence-action) | `enum { ABSENT, PRESENT, ENTER, LEAVE, UPDATE }``int enum { ABSENT, PRESENT, ENTER, LEAVE, UPDATE }``enum { :absent, :present, :enter, :leave, :update }``ARTPresenceAction``enum { Absent, Present, Enter, Leave, Update }``const PresenceMessage::PresenceAbsent,PresencePresent,PresenceEnter,PresenceLeave,PresenceUpdate` | -| dataData | The presence update payload, if provided | `String`, `ByteArray`, `JSONObject`, `JSONArray``String`, `StringBuffer`, `JSON Object``String`, `Binary` (ASCII-8BIT String), `Hash`, `Array``String`, `Bytearray`, `Dict`, `List``String`, `NSData`, `Dictionary`, `Array``NSString *`, `NSData *`, `NSDictionary *`, `NSArray *``String`, `byte[]`, plain C# object that can be converted to Json`String`, `[]byte``String`, `Map`, `List` | -| extrasExtras | Metadata and/or ancillary payloads, if provided. The only currently valid payloads for extras are the [`push`](/docs/push/publish#sub-channels), [`ref`](/docs/messages#interactions) and [`privileged`](/docs/platform/integrations/skip-integrations) objects | `JSONObject`, `JSONArray``JSON Object``Hash`, `Array``Dict`, `List``Dictionary`, `Array``NSDictionary *`, `NSArray *`plain C# object that can be converted to Json`String`, `[]byte``Map`, `List` | -| idId | Unique ID assigned by Ably to this presence update | `String` | -| clientIdclient_idClientId | The client ID of the publisher of this presence update | `String` | -| connectionIdconnection_idConnectionId | The connection ID of the publisher of this presence update | `String` | -| timestampTimestamp | Timestamp when the presence update was received by Ably, as milliseconds since the epoch | `Integer``Long Integer``Time``NSDate``DateTimeOffset` | -| encodingEncoding | This will typically be empty as all presence updates received from Ably are automatically decoded client-side using this value. However, if the message encoding cannot be processed, this attribute will contain the remaining transformations not applied to the `data` payload | `String` | +| actionAction | The event signified by a PresenceMessage. See [`PresenceMessage.action`](/docs/api/realtime-sdk/types#presence-action)[`PresenceAction`](/docs/api/realtime-sdk/types#presence-action)[`PresenceMessage::ACTION`](/docs/api/realtime-sdk/types#presence-action)[`PresenceMessage.action`](/docs/api/realtime-sdk/types#presence-action)[`PresenceMessage::action`](/docs/api/realtime-sdk/types#presence-action) | `enum { ABSENT, PRESENT, ENTER, LEAVE, UPDATE }``int enum { ABSENT, PRESENT, ENTER, LEAVE, UPDATE }``enum { :absent, :present, :enter, :leave, :update }``ARTPresenceAction``enum { Absent, Present, Enter, Leave, Update }``const PresenceMessage::PresenceAbsent,PresencePresent,PresenceEnter,PresenceLeave,PresenceUpdate` | +| dataData | The presence update payload, if provided | `String`, `ByteArray`, `JSONObject`, `JSONArray``String`, `Binary` (ASCII-8BIT String), `Hash`, `Array``String`, `Bytearray`, `Dict`, `List``String`, `NSData`, `Dictionary`, `Array``NSString *`, `NSData *`, `NSDictionary *`, `NSArray *``String`, `byte[]`, plain C# object that can be converted to Json`String`, `[]byte``String`, `Map`, `List` | +| extrasExtras | Metadata and/or ancillary payloads, if provided. The only currently valid payloads for extras are the [`push`](/docs/push/publish#sub-channels), [`ref`](/docs/messages#interactions) and [`privileged`](/docs/platform/integrations/skip-integrations) objects | `JSONObject`, `JSONArray``Hash`, `Array``Dict`, `List``Dictionary`, `Array``NSDictionary *`, `NSArray *`plain C# object that can be converted to Json`String`, `[]byte``Map`, `List` | +| idId | Unique ID assigned by Ably to this presence update | `String` | +| clientIdclient_idClientId | The client ID of the publisher of this presence update | `String` | +| connectionIdconnection_idConnectionId | The connection ID of the publisher of this presence update | `String` | +| timestampTimestamp | Timestamp when the presence update was received by Ably, as milliseconds since the epoch | `Integer``Long Integer``Time``NSDate``DateTimeOffset` | +| encodingEncoding | This will typically be empty as all presence updates received from Ably are automatically decoded client-side using this value. However, if the message encoding cannot be processed, this attribute will contain the remaining transformations not applied to the `data` payload | `String` | ### PresenceMessage constructors @@ -882,42 +744,12 @@ A static factory method to create an array of [`PresenceMessages`](/docs/api/rea An `Array` of [`PresenceMessage`](/docs/api/realtime-sdk/types#presence-message) objects -### Presence actionARTPresenceActionio.ably.lib.types.PresenceMessage.ActionAbly::Models::PresenceMessage::ACTIONIO.Ably.PresenceAction +### Presence actionARTPresenceActionio.ably.lib.types.PresenceMessage.ActionAbly::Models::PresenceMessage::ACTIONIO.Ably.PresenceAction - + `Presence` `action` is a String with a value matching any of the [Realtime Presence states & events](/docs/presence-occupancy/presence#trigger-events). - - - -```javascript - var PresenceActions = [ - 'absent', // (reserved for internal use) - 'present', - 'enter', - 'leave', - 'update' - ] -``` - - - - - - -```nodejs - var PresenceActions = [ - 'absent', // (reserved for internal use) - 'present', - 'enter', - 'leave', - 'update' - ] -``` - - - @@ -1066,25 +898,20 @@ const ( -### PaginatedResultARTPaginatedResultio.ably.lib.types.PaginatedResultAbly::Models::PaginatedResultIO.Ably.PaginatedResult +### PaginatedResultARTPaginatedResultio.ably.lib.types.PaginatedResultAbly::Models::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](/docs/api/rest-api/#pagination) is accompanied by metadata that indicates the relative queries available to the `PaginatedResult` object. -#### PropertiesMembersAttributes +#### PropertiesMembersAttributes | Property | Description | Type | |----------|-------------|------| -| itemsItems | Contains the current page of results (for example an Array of [`Message`](#message) or [`PresenceMessage`](#presence-message) objects for a channel history request) | `Array ``List ` | +| itemsItems | Contains the current page of results (for example an Array of [`Message`](#message) or [`PresenceMessage`](#presence-message) objects for a channel history request) | `Array ``List ` | #### Methods -##### firstFirst - - - -`first(): Promise` +##### firstFirst - `PaginatedResult first` @@ -1116,15 +943,10 @@ A `PaginatedResult` is a type that represents a page of results for all message Returns a new `PaginatedResult` for the first page of results. When using the Realtime library, the `first` method returns a [`Deferrable`](/docs/api/realtime-sdk/types#deferrable) and yields a [`PaginatedResult`](#paginated-result).The method is asynchronous and returns a Task which needs to be awaited to get the [`PaginatedResult`](#paginated-result). - - -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`](/docs/api/realtime-sdk/types#error-info) object that details the reason why it was rejected. - +##### hasNextHasNexthas_next? -##### hasNextHasNexthas_next? - - + `Boolean hasNext()` @@ -1145,11 +967,11 @@ Returns a promise. On success, the promise is fulfilled with a new `PaginatedRes -Returns `true` if there are more pages available by calling `next``Next` and returns `false` if this page is the last page available. +Returns `true` if there are more pages available by calling `next``Next` and returns `false` if this page is the last page available. -##### isLastIsLastlast? +##### isLastIsLastlast? - + `Boolean isLast()` @@ -1170,15 +992,10 @@ Returns `true` if there are more pages available by calling `next``Next` available. - -##### nextNext +Returns `true` if this page is the last page and returns `false` if there are more pages available by calling `next``Next` available. - +##### nextNext -`next(): Promise` - - `PaginatedResult next` @@ -1211,51 +1028,8 @@ Returns a new `PaginatedResult` loaded with the next page of results. If there a - - -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`](/docs/api/realtime-sdk/types#error-info) object that details the reason why it was rejected. - -##### current - -`current(): Promise<"PaginatedResult":#paginated-result>` - -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`](/docs/api/realtime-sdk/types#error-info) object that details the reason why it was rejected. - - - #### Example - - - - - -```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()); -``` - - - - - - -```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()); -``` - - - - - - @@ -1372,27 +1146,21 @@ channel.history { paginatedResult, error in An `HttpPaginatedResponse` is a superset of [`PaginatedResult`](/docs/api/rest-sdk/types#paginated-result), which is a type that represents a page of results plus metadata indicating the relative queries available to it. `HttpPaginatedResponse` additionally carries information about the response to an HTTP request. It is used when [making custom HTTP requests](/docs/api/rest-sdk#request). -#### PropertiesMembersAttributes +#### PropertiesMembersAttributes | Property | Description | Type | |----------|-------------|------| -| itemsItems | Contains a page of results; for example, an array of [`Message`](#message) or [`PresenceMessage`](#presence-message) objects for a channel history request | `Array<>` | -| statusCodestatus_codeStatusCode | The HTTP status code of the response | `Number` | -| successSuccess | Whether the HTTP status code indicates success. This is equivalent to `200 <= statusCode < 300``200 <= status_code < 300``200 <= StatusCode < 300` | `Boolean` | -| headersHeaders | The headers of the response | `Object` | -| errorCodeerror_codeErrorCode | The error code if the `X-Ably-Errorcode` HTTP header is sent in the response | `Int``Number` | -| errorMessageerror_messageErrorMessage | The error message if the `X-Ably-Errormessage` HTTP header is sent in the response | `String` | - +| itemsItems | Contains a page of results; for example, an array of [`Message`](#message) or [`PresenceMessage`](#presence-message) objects for a channel history request | `Array<>` | +| statusCodestatus_codeStatusCode | The HTTP status code of the response | `Number` | +| successSuccess | Whether the HTTP status code indicates success. This is equivalent to `200 <= statusCode < 300``200 <= status_code < 300``200 <= StatusCode < 300` | `Boolean` | +| headersHeaders | The headers of the response | `Object` | +| errorCodeerror_codeErrorCode | The error code if the `X-Ably-Errorcode` HTTP header is sent in the response | `Int` | +| errorMessageerror_messageErrorMessage | The error message if the `X-Ably-Errormessage` HTTP header is sent in the response | `String` | #### Methods -##### firstFirst - - - -`first(): Promise` +##### firstFirst - `HttpPaginatedResponse first` @@ -1423,16 +1191,11 @@ An `HttpPaginatedResponse` is a superset of [`PaginatedResult`](/docs/api/rest-s Returns a new `HttpPaginatedResponse` for the first page of results. When using the Realtime library, the `first` method returns a [`Deferrable`](/docs/api/realtime-sdk/types#deferrable) and yields an [`HttpPaginatedResponse`](/docs/api/realtime-sdk/types#http-paginated-response).The method is asynchronous and returns a Task which needs to be awaited to get the [`HttpPaginatedResponse`](/docs/api/realtime-sdk/types#http-paginated-response). - - - -Returns a promise. On success, the promise is fulfilled with a new `HttpPaginatedResponse` for the first page of results. On failure, the promise is rejected with an [`ErrorInfo`](/docs/api/realtime-sdk/types#error-info) object that details the reason why it was rejected. - -##### hasNextHasNexthas_next? +##### hasNextHasNexthas_next? - + `Boolean hasNext()` @@ -1453,11 +1216,11 @@ Returns a promise. On success, the promise is fulfilled with a new `HttpPaginate -Returns `true` if there are more pages available by calling `next``Next` and returns `false` if this page is the last page available. +Returns `true` if there are more pages available by calling `next``Next` and returns `false` if this page is the last page available. -##### isLastIsLastlast? +##### isLastIsLastlast? - + `Boolean isLast()` @@ -1478,15 +1241,10 @@ Returns `true` if there are more pages available by calling `next``Next` available. - -##### nextNext +Returns `true` if this page is the last page and returns `false` if there are more pages available by calling `next``Next` available. - +##### nextNext -`next(): Promise` - - `HttpPaginatedResponse next` @@ -1517,21 +1275,6 @@ Returns `true` if this page is the last page and returns `false` if there are mo Returns a new `HttpPaginatedResponse` loaded with the next page of results. If there are no further pages, then `null`a blank HttpPaginatedResponse will be returned`nil` is returned. The method is asynchronous and return a Task which needs to be awaited to get the `HttpPaginatedResponse`When using the Realtime library, the `first` method returns a [`Deferrable`](/docs/api/realtime-sdk/types#deferrable) and yields an [`HttpPaginatedResponse`](/docs/api/realtime-sdk/types#http-paginated-response). - - - -Returns a promise. On success, the promise is fulfilled with a new `HttpPaginatedResponse` 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`](/docs/api/realtime-sdk/types#error-info) object that details the reason why it was rejected. - - - - - -##### current - -`current(): Promise` - -Returns a promise. On success, the promise is fulfilled with a new `HttpPaginatedResponse` loaded with the current page of results. On failure, the promise is rejected with an [`ErrorInfo`](/docs/api/realtime-sdk/types#error-info) object that details the reason why it was rejected. - #### Example @@ -1555,9 +1298,9 @@ Please note that `key` and `value` attributes are always strings. If an `Integer - + -### PushChannelSubscriptionAbly::Models::PushChannelSubscription +### Ably::Models::PushChannelSubscription An `PushChannelSubscription` is a type encapsulating the subscription of a device or group of devices sharing a [client identifier](/docs/auth/identified-clients) to a channel in order to receive push notifications. @@ -1566,8 +1309,8 @@ An `PushChannelSubscription` is a type encapsulating the subscription of a devic | Property | Description | Type | |----------|-------------|------| | channel | The channel that this push notification subscription is associated with | `String` | -| deviceIddevice_id | The device with this identifier is linked to this channel subscription. When present, `clientId``client_id` is never present | `String` | -| clientIdclient_id | Devices with this [client identifier](/docs/auth/identified-clients) are included in this channel subscription. When present, `deviceId``device_id` is never present | `String` | +| device_id | The device with this identifier is linked to this channel subscription. When present, `client_id` is never present | `String` | +| client_id | Devices with this [client identifier](/docs/auth/identified-clients) are included in this channel subscription. When present, `device_id` is never present | `String` | @@ -1629,19 +1372,19 @@ A `PushChannelSubscription` object -### TokenDetailsio.ably.lib.types.TokenDetailsARTTokenDetailsAbly::Models::TokenDetails +### TokenDetailsio.ably.lib.types.TokenDetailsARTTokenDetailsAbly::Models::TokenDetails `TokenDetails` is a type providing details of Ably Token string and its associated metadata. -#### PropertiesMembersAttributes +#### PropertiesMembersAttributes | Property | Description | Type | |----------|-------------|------| -| tokenToken | The [Ably Token](/docs/api/realtime-sdk/authentication#token-details) itself. A typical [Ably Token](/docs/api/realtime-sdk/authentication#token-details) string may appear like `{{TOKEN}}` | `String` | -| expiresExpires | The time (in milliseconds since the epoch)The time at which this token expires | `Integer``Long Integer``DateTimeOffset``Time``NSDate` | -| issuedIssued | The time (in milliseconds since the epoch)The time at which this token was issued | `Integer``Long Integer``DateTimeOffset``Time``NSDate` | -| capabilityCapability | The capability associated with this [Ably Token](/docs/api/realtime-sdk/authentication#token-details). The capability is a a JSON stringified canonicalized representation of the resource paths and associated operations. [Read more about authentication and capabilities](/docs/auth/capabilities) | `String``Capability` | -| clientIdclient_idClientId | The client ID, if any, bound to this [Ably Token](/docs/api/realtime-sdk/authentication#token-details). If a client ID is included, then the [Ably Token](/docs/api/realtime-sdk/authentication#token-details) authenticates its bearer as that client ID, and the [Ably Token](/docs/api/realtime-sdk/authentication#token-details) may only be used to perform operations on behalf of that client ID. The client is then considered to be an [identified client](/docs/auth/identified-clients) | `String` | +| tokenToken | The [Ably Token](/docs/api/realtime-sdk/authentication#token-details) itself. A typical [Ably Token](/docs/api/realtime-sdk/authentication#token-details) string may appear like `{{TOKEN}}` | `String` | +| expiresExpires | The time (in milliseconds since the epoch)The time at which this token expires | `Integer``Long Integer``DateTimeOffset``Time``NSDate` | +| issuedIssued | The time (in milliseconds since the epoch)The time at which this token was issued | `Integer``Long Integer``DateTimeOffset``Time``NSDate` | +| capabilityCapability | The capability associated with this [Ably Token](/docs/api/realtime-sdk/authentication#token-details). The capability is a a JSON stringified canonicalized representation of the resource paths and associated operations. [Read more about authentication and capabilities](/docs/auth/capabilities) | `String``Capability` | +| clientIdclient_idClientId | The client ID, if any, bound to this [Ably Token](/docs/api/realtime-sdk/authentication#token-details). If a client ID is included, then the [Ably Token](/docs/api/realtime-sdk/authentication#token-details) authenticates its bearer as that client ID, and the [Ably Token](/docs/api/realtime-sdk/authentication#token-details) may only be used to perform operations on behalf of that client ID. The client is then considered to be an [identified client](/docs/auth/identified-clients) | `String` | @@ -1664,9 +1407,9 @@ A `PushChannelSubscription` object ### TokenDetails constructors -#### TokenDetails.fromJsonTokenDetails.from_jsonTokenDetails.fromMap +#### TokenDetails.fromJsonTokenDetails.from_jsonTokenDetails.fromMap - + `TokenDetails.fromJson(String json) -> TokenDetails` @@ -1682,11 +1425,11 @@ A `PushChannelSubscription` object -A static factory methodnamed constructor to create a [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) from a deserialized `TokenDetails`-like object or a JSON stringified `TokenDetails`map. This method is provided to minimize bugs as a result of differing types by platform for fields such as `timestamp` or `ttl`. For example, in Ruby `ttl` in the `TokenDetails` object is exposed in seconds as that is idiomatic for the language, yet when serialized to JSON using `to_json` it is automatically converted to the Ably standard which is milliseconds. By using the `fromJson``fromMap` method when constructing a `TokenDetails`, Ably ensures that all fields are consistently serialized and deserialized across platforms. +A static factory methodnamed constructor to create a [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) from a deserialized `TokenDetails`-like object or a JSON stringified `TokenDetails`map. This method is provided to minimize bugs as a result of differing types by platform for fields such as `timestamp` or `ttl`. For example, in Ruby `ttl` in the `TokenDetails` object is exposed in seconds as that is idiomatic for the language, yet when serialized to JSON using `to_json` it is automatically converted to the Ably standard which is milliseconds. By using the `fromJson``fromMap` method when constructing a `TokenDetails`, Ably ensures that all fields are consistently serialized and deserialized across platforms. ##### Parameters - + | Parameter | Description | Type | |-----------|-------------|------| @@ -1705,11 +1448,11 @@ A static factory met A [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) object -### TokenRequestIO.Ably.TokenRequestably.TokenRequestio.ably.lib.types.TokenRequestARTTokenRequestAbly::Models::TokenRequest +### TokenRequestIO.Ably.TokenRequestably.TokenRequestio.ably.lib.types.TokenRequestARTTokenRequestAbly::Models::TokenRequest -`TokenRequest` is a type containing parameters for an Ably `TokenRequest`. [Ably Tokens](/docs/api/realtime-sdk/authentication#token-details) are requested using [`Auth#requestToken`](/docs/api/rest-sdk/authentication#request-token)[`Auth#request_token`](/docs/api/rest-sdk/authentication#request-token) +`TokenRequest` is a type containing parameters for an Ably `TokenRequest`. [Ably Tokens](/docs/api/realtime-sdk/authentication#token-details) are requested using [`Auth#requestToken`](/docs/api/rest-sdk/authentication#request-token)[`Auth#request_token`](/docs/api/rest-sdk/authentication#request-token) - + #### Properties @@ -1727,19 +1470,19 @@ A [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) object | Property | Description | Type | |----------|-------------|------| -| keyNamekey_nameKeyName | The key name of the key against which this request is made. The key name is public, whereas the key secret is private | `String` | -| ttlTtl | Requested time to live for the [Ably Token](/docs/api/realtime-sdk/authentication#token-details) in millisecondsin secondsas a `TimeSpan`. If the Ably `TokenRequest` is successful, the TTL of the returned [Ably Token](/docs/api/realtime-sdk/authentication#token-details) will be less than or equal to this value depending on application settings and the attributes of the issuing key. | `Integer``TimeSpan``NSTimeInterval` | -| timestampTimestamp | The timestamp of this request in milliseconds | `Integer``Long Integer``Time``DateTimeOffset``Integer` | -| capabilityCapability | Capability of the requested [Ably Token](/docs/api/realtime-sdk/authentication#token-details). If the Ably `TokenRequest` is successful, the capability of the returned [Ably Token](/docs/api/realtime-sdk/authentication#token-details) will be the intersection of this capability with the capability of the issuing key. The capability is a JSON stringified canonicalized representation of the resource paths and associated operations. [Read more about authentication and capabilities](/docs/auth) | `String` | -| clientIdclient_idClientId | The client ID to associate with the requested [Ably Token](/docs/api/realtime-sdk/authentication#token-details). When provided, the [Ably Token](/docs/api/realtime-sdk/authentication#token-details) may only be used to perform operations on behalf of that client ID | `String` | -| nonceNonce | An opaque nonce string of at least 16 characters | `String` | -| macMac | The Message Authentication Code for this request | `String` | +| keyNamekey_nameKeyName | The key name of the key against which this request is made. The key name is public, whereas the key secret is private | `String` | +| ttlTtl | Requested time to live for the [Ably Token](/docs/api/realtime-sdk/authentication#token-details) in millisecondsin secondsas a `TimeSpan`. If the Ably `TokenRequest` is successful, the TTL of the returned [Ably Token](/docs/api/realtime-sdk/authentication#token-details) will be less than or equal to this value depending on application settings and the attributes of the issuing key. | `Integer``TimeSpan``NSTimeInterval` | +| timestampTimestamp | The timestamp of this request in milliseconds | `Integer``Long Integer``Time``DateTimeOffset``Integer` | +| capabilityCapability | Capability of the requested [Ably Token](/docs/api/realtime-sdk/authentication#token-details). If the Ably `TokenRequest` is successful, the capability of the returned [Ably Token](/docs/api/realtime-sdk/authentication#token-details) will be the intersection of this capability with the capability of the issuing key. The capability is a JSON stringified canonicalized representation of the resource paths and associated operations. [Read more about authentication and capabilities](/docs/auth) | `String` | +| clientIdclient_idClientId | The client ID to associate with the requested [Ably Token](/docs/api/realtime-sdk/authentication#token-details). When provided, the [Ably Token](/docs/api/realtime-sdk/authentication#token-details) may only be used to perform operations on behalf of that client ID | `String` | +| nonceNonce | An opaque nonce string of at least 16 characters | `String` | +| macMac | The Message Authentication Code for this request | `String` | ### TokenRequest constructors -#### TokenRequest.fromJsonTokenRequest.fromMap +#### TokenRequest.fromJsonTokenRequest.fromMap - + `TokenRequest.fromJson(String json) -> TokenRequest` @@ -1755,11 +1498,11 @@ A [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) object -A static factory methodnamed constructor to create a [`TokenRequest`](/docs/api/realtime-sdk/types#token-request) from a deserialized `TokenRequest`-like object or a JSON stringified `TokenRequest`map. This method is provided to minimize bugs as a result of differing types by platform for fields such as `timestamp` or `ttl`. For example, in Ruby `ttl` in the `TokenRequest` object is exposed in seconds as that is idiomatic for the language, yet when serialized to JSON using `to_json` it is automatically converted to the Ably standard which is milliseconds. By using the `fromJson``fromMap` method when constructing a `TokenRequest`, Ably ensures that all fields are consistently serialized and deserialized across platforms. +A static factory methodnamed constructor to create a [`TokenRequest`](/docs/api/realtime-sdk/types#token-request) from a deserialized `TokenRequest`-like object or a JSON stringified `TokenRequest`map. This method is provided to minimize bugs as a result of differing types by platform for fields such as `timestamp` or `ttl`. For example, in Ruby `ttl` in the `TokenRequest` object is exposed in seconds as that is idiomatic for the language, yet when serialized to JSON using `to_json` it is automatically converted to the Ably standard which is milliseconds. By using the `fromJson``fromMap` method when constructing a `TokenRequest`, Ably ensures that all fields are consistently serialized and deserialized across platforms. ##### Parameters - + | Parameter | Description | Type | |-----------|-------------|------| @@ -1778,7 +1521,7 @@ A static factory met A [`TokenRequest`](/docs/api/realtime-sdk/types#token-request) object -### Stats objectARTStatsio.ably.lib.types.StatsAbly::Models::StatsIO.Ably.stats +### Stats objectARTStatsio.ably.lib.types.StatsAbly::Models::StatsIO.Ably.stats A `Stats` object represents an application's statistics for the specified interval and time period. Ably aggregates statistics globally for all accounts and applications, and makes these available both through our [statistics API](/docs/metadata-stats/stats) as well as your [application dashboard](https://ably.com/dashboard). @@ -1788,7 +1531,7 @@ Please note that most attributes of the `Stats` type below contain references to - + #### Properties @@ -1859,58 +1602,12 @@ Please note that most attributes of the `Stats` type below contain references to - - -| Property | Description | Type | -|----------|-------------|------| -| appId | The ID of the Ably application the statistics relate to | `String` | -| entries | The statistics for the requested time interval and time period. The `schema` property provides further information | `Partial>` | -| inProgress | Optional. For entries that are still in progress, such as the current month, the last sub-interval included in the stats entry. In the format `yyyy-mm-dd:hh:mm:ss` | `String` | -| intervalId | The UTC time period that the stats coverage begins at. If `unit` was requested as `minute` this will be in the format `YYYY-mm-dd:HH:MM`, if `hour` it will be `YYYY-mm-dd:HH`, if `day` it will be `YYYY-mm-dd:00` and if `month` it will be `YYYY-mm-01:00` | `String` | -| schema | The URL of a JSON schema describing the structure of the `Stats` object | `String` | - - - {/* - xchgProducer/xchg_producer/XchgProducer := Breakdown of messages have been sent or received through any Data Stream Exchange products associated with this app or account - Type: @XchgMessages@ */} {/* - xchgConsumer/xchg_consumer/XchgConsumer := Breakdown of messages have been sent or received by this app or account connecting to some Data Stream Exchange product as a consumer - Type: @XchgMessages@ */} - - -### StatsIntervalGranularityARTStatsGranularity - - - -`StatsIntervalGranularity` is an enum specifying the granularity of a [`Stats interval`](/docs/api/rest-sdk/statistics#stats-type). - - - - -```javascript -const StatsIntervalGranularity = [ - 'minute', - 'hour', - 'day', - 'month' -] -``` - - - - - - -```nodejs -const StatsIntervalGranularity = [ - 'minute', - 'hour', - 'day', - 'month' -] -``` - + - - +### StatsIntervalGranularityARTStatsGranularity @@ -1959,110 +1656,11 @@ public enum StatsIntervalGranularity ``` - - - -### BatchPublishSpec - -A `BatchPublishSpec` describes the messages that should be published by a batch publish operation, and the channels to which they should be published. - -#### Properties - -| Property | Description | Type | -|----------|-------------|------| -| channels | The names of the channels to publish the `messages` to | `String[]` | -| messages | An array of [`Message`](/docs/api/realtime-sdk/types#message) objects | [`Message[]`](/docs/api/realtime-sdk/types#message) | - -### BatchResult - -A `BatchResult` contains information about the results of a batch operation. - -#### Properties - -| Property | Description | Type | -|----------|-------------|------| -| successCount | The number of successful operations in the request | `Number` | -| failureCount | The number of unsuccessful operations in the request | `Number` | -| messages | An array of results for the batch operation (for example, an array of [`BatchPublishSuccessResult`](/docs/api/realtime-sdk/types#batch-publish-success-result) or [`BatchPublishFailureResult`](/docs/api/realtime-sdk/types#batch-publish-failure-result) for a channel batch publish request) | `Object[]` | - -### BatchPublishSuccessResult - -A `BatchPublishSuccessResult` contains information about the result of successful publishes to a channel requested by a single [`BatchPublishSpec`](/docs/api/realtime-sdk/types#batch-publish-spec). - -#### Properties - -| Property | Description | Type | -|----------|-------------|------| -| channel | The name of the channel the message(s) was published to | `String` | -| messageId | A unique ID prefixed to the `Message.id` of each published message | `String` | - -### BatchPublishFailureResult - -A `BatchPublishFailureResult` contains information about the result of unsuccessful publishes to a channel requested by a single [`BatchPublishSpec`](/docs/api/realtime-sdk/types#batch-publish-spec). - -#### Properties - -| Property | Description | Type | -|----------|-------------|------| -| channel | The name of the channel the message(s) failed to be published to | `String` | -| error | Describes the reason for which the message(s) failed to publish to the channel as an [`ErrorInfo`](/docs/api/realtime-sdk/types#error-info) object | [`ErrorInfo`](/docs/api/realtime-sdk/types#error-info) | - -### BatchPresenceSuccessResult - -A `BatchPresenceSuccessResult` contains information about the result of a successful batch presence request for a single channel. - -#### Properties - -| Property | Description | Type | -|----------|-------------|------| -| channel | The channel name the presence state was retrieved for | `String` | -| presence | An array of [`PresenceMessage`](/docs/api/realtime-sdk/types#presence-message) describing members present on the channel | [`PresenceMessage[]`](/docs/api/realtime-sdk/types#presence-message) | - -### BatchPresenceFailureResult - -A `BatchPresenceFailureResult` contains information about the result of an unsuccessful batch presence request for a single channel. - -#### Properties - -| Property | Description | Type | -|----------|-------------|------| -| channel | The channel name the presence state failed to be retrieved for | `String` | -| error | Describes the reason for which presence state could not be retrieved for the channel as an [`ErrorInfo`](/docs/api/realtime-sdk/types#error-info) object | [`ErrorInfo`](/docs/api/realtime-sdk/types#error-info) | - -### TokenRevocationSuccessResult - -A `TokenRevocationSuccessResult` contains information about the result of a successful token revocation request for a single target specifier. - -#### Properties - -| Property | Description | Type | -|----------|-------------|------| -| target | The target specifier | `String` | -| appliesAt | The time at which the token revocation will take effect, as a Unix timestamp in milliseconds | `Number` | -| issuedBefore | A Unix timestamp in milliseconds. Only tokens issued earlier than this time will be revoked | `Number` | - -### TokenRevocationFailureResult - -A `TokenRevocationFailureResult` contains information about the result of an unsuccessful token revocation request for a single target specifier. - -#### Properties - -| Property | Description | Type | -|----------|-------------|------| -| target | The target specifier | `String` | -| error | Describes the reason for which token revocation failed for the given `target` as an [`ErrorInfo`](/docs/api/realtime-sdk/types#error-info) object | [`ErrorInfo`](/docs/api/realtime-sdk/types#error-info) | - ## Other types -### AuthOptions ObjectARTAuthOptionsAuthOptions Hashio.ably.lib.rest.Auth.AuthOptionsIO.Ably.AuthOptions - - - -`AuthOptions` is a plain JavaScript object and is used when making [authentication](/docs/auth) requests. If passed in, an `authOptions` object will be used instead of (as opposed to supplementing or being merged with) the default values given when the library was instantiated. The following attributes are supported: - - +### AuthOptions ObjectARTAuthOptionsAuthOptions Hashio.ably.lib.rest.Auth.AuthOptionsIO.Ably.AuthOptions @@ -2076,7 +1674,7 @@ A `TokenRevocationFailureResult` contains information about the result of an uns - + #### Properties @@ -2094,23 +1692,17 @@ A `TokenRevocationFailureResult` contains information about the result of an uns | Property | Description | Type | |----------|-------------|------| -| authCallbackAuthCallback:auth_callback | A functionfunction with the form `function(tokenParams, callback(err, tokenOrTokenRequest))``TokenCallback` instanceproc / lambda (called synchronously in REST and Realtime but does not block EventMachine in the latter) which is called when a new token is required. The role of the callback is to obtain a fresh token, one of: an Ably Token string (in plain text format); a signed [`TokenRequest`](/docs/api/realtime-sdk/types#token-request); a [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) (in JSON format); an [Ably JWT](/docs/api/realtime-sdk/authentication#ably-jwt). See [our authentication documentation](/docs/auth) for details of the Ably TokenRequest format and associated API calls. | `Callable``TokenCallback``Proc``Func>` | -| authUrlAuthUrl:auth_url | A URL that the library may use to obtain a fresh token, one of: an Ably Token string (in plain text format); a signed [`TokenRequest`](/docs/api/realtime-sdk/types#token-request); a [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) (in JSON format); an [Ably JWT](/docs/api/realtime-sdk/authentication#ably-jwt). For example, this can be used by a client to obtain signed Ably TokenRequests from an application server. | `String``Uri``NSURL``String` | -| authMethodAuthMethod:auth_method | _`GET``:get`_ The HTTP verb to use for the request, either `GET``:get` or `POST``:post` | `String``Symbol``HttpMethod` | -| authHeadersAuthHeaders:auth_headers | A set of key value pair headers to be added to any request made to the authUrlAuthUrl:auth_url. Useful when an application requires these to be added to validate the request or implement the response. If the `authHeaders` object contains an `authorization` key, then `withCredentials` will be set on the xhr request. | `Object``Hash``Param[]``Dictionary``Map` | -| authParamsAuthParams:auth_params | A set of key value pair params to be added to any request made to the authUrlAuthUrl:auth_url. When the authMethodAuthMethod:auth_method is `GET`, query params are added to the URL, whereas when authMethodAuthMethod:auth_method is `POST`, the params are sent as URL encoded form data. Useful when an application require these to be added to validate the request or implement the response. | `Object``Hash``Param[]``Dictionary``NSArray``[NSURLQueryItem]/Array``Map` | -| tokenDetailsTokenDetails:token_details | An authenticated [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) object (most commonly obtained from an Ably Token Request response). This option is mostly useful for testing: since tokens are short-lived, in production you almost always want to use an authentication method that allows the client library to renew the token automatically when the previous one expires, such as authUrlAuthUrl:auth_url or authCallbackAuthCallback:auth_callback. Use this option if you wish to use Token authentication. Read more about [Token authentication](/docs/auth/token) | `TokenDetails` | -| keyKey:key | Optionally the [API key](/docs/auth#api-keys) to use can be specified as a full key string; if not, the API key passed into [`ClientOptions`](#client-options) when instancing the Realtime or REST library is used | `String` | -| queryTimeQueryTime:query_time | _false_ If true, the library will query the Ably servers for the current time when [issuing TokenRequests](/docs/auth/token) instead of relying on a locally-available time of day. Knowing the time accurately is needed to create valid signed Ably [TokenRequests](/docs/auth/token), so this option is useful for library instances on auth servers where for some reason the server clock cannot be kept synchronized through normal means, such as an [NTP daemon](https://en.wikipedia.org/wiki/Ntpd). The server is queried for the current time once per client library instance (which stores the offset from the local clock), so if using this option you should avoid instancing a new version of the library for each request. | `Boolean` | -| tokenToken:token | An authenticated token. This can either be a [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) object, a [`TokenRequest`](/docs/api/realtime-sdk/types#token-request) object, or token string (obtained from the tokenToken:token property of a [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) component of an Ably TokenRequest response, or a [JSON Web Token](https://tools.ietf.org/html/rfc7519) satisfying [the Ably requirements for JWTs](/docs/auth/token/jwt)). This option is mostly useful for testing: since tokens are short-lived, in production you almost always want to use an authentication method that allows the client library to renew the token automatically when the previous one expires, such as authUrlAuthUrl:auth_url or authCallbackAuthCallback:auth_callback. Read more about [Token authentication](/docs/auth/token) | `String`, `TokenDetails` or `TokenRequest` | - -### ClientOptions ObjectARTClientOptionsClientOptions Hashio.ably.types.ClientOptionsIO.Ably.ClientOptions - - - -`ClientOptions` is a plain JavaScript object and is used in the `Ably.Realtime` constructor's `options` argument. The following attributes can be defined on the object: - - +| authCallbackAuthCallback:auth_callback | A function`TokenCallback` instanceproc / lambda (called synchronously in REST and Realtime but does not block EventMachine in the latter) which is called when a new token is required. The role of the callback is to obtain a fresh token, one of: an Ably Token string (in plain text format); a signed [`TokenRequest`](/docs/api/realtime-sdk/types#token-request); a [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) (in JSON format); an [Ably JWT](/docs/api/realtime-sdk/authentication#ably-jwt). See [our authentication documentation](/docs/auth) for details of the Ably TokenRequest format and associated API calls. | `Callable``TokenCallback``Proc``Func>` | +| authUrlAuthUrl:auth_url | A URL that the library may use to obtain a fresh token, one of: an Ably Token string (in plain text format); a signed [`TokenRequest`](/docs/api/realtime-sdk/types#token-request); a [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) (in JSON format); an [Ably JWT](/docs/api/realtime-sdk/authentication#ably-jwt). For example, this can be used by a client to obtain signed Ably TokenRequests from an application server. | `String``Uri``NSURL``String` | +| authMethodAuthMethod:auth_method | _`GET``:get`_ The HTTP verb to use for the request, either `GET``:get` or `POST``:post` | `String``Symbol``HttpMethod` | +| authHeadersAuthHeaders:auth_headers | A set of key value pair headers to be added to any request made to the authUrlAuthUrl:auth_url. Useful when an application requires these to be added to validate the request or implement the response. | `Hash``Param[]``Dictionary``Map` | +| authParamsAuthParams:auth_params | A set of key value pair params to be added to any request made to the authUrlAuthUrl:auth_url. When the authMethodAuthMethod:auth_method is `GET`, query params are added to the URL, whereas when authMethodAuthMethod:auth_method is `POST`, the params are sent as URL encoded form data. Useful when an application require these to be added to validate the request or implement the response. | `Hash``Param[]``Dictionary``NSArray``[NSURLQueryItem]/Array``Map` | +| tokenDetailsTokenDetails:token_details | An authenticated [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) object (most commonly obtained from an Ably Token Request response). This option is mostly useful for testing: since tokens are short-lived, in production you almost always want to use an authentication method that allows the client library to renew the token automatically when the previous one expires, such as authUrlAuthUrl:auth_url or authCallbackAuthCallback:auth_callback. Use this option if you wish to use Token authentication. Read more about [Token authentication](/docs/auth/token) | `TokenDetails` | +| keyKey:key | Optionally the [API key](/docs/auth#api-keys) to use can be specified as a full key string; if not, the API key passed into [`ClientOptions`](#client-options) when instancing the Realtime or REST library is used | `String` | +| queryTimeQueryTime:query_time | _false_ If true, the library will query the Ably servers for the current time when [issuing TokenRequests](/docs/auth/token) instead of relying on a locally-available time of day. Knowing the time accurately is needed to create valid signed Ably [TokenRequests](/docs/auth/token), so this option is useful for library instances on auth servers where for some reason the server clock cannot be kept synchronized through normal means, such as an [NTP daemon](https://en.wikipedia.org/wiki/Ntpd). The server is queried for the current time once per client library instance (which stores the offset from the local clock), so if using this option you should avoid instancing a new version of the library for each request. | `Boolean` | +| tokenToken:token | An authenticated token. This can either be a [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) object, a [`TokenRequest`](/docs/api/realtime-sdk/types#token-request) object, or token string (obtained from the tokenToken:token property of a [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) component of an Ably TokenRequest response, or a [JSON Web Token](https://tools.ietf.org/html/rfc7519) satisfying [the Ably requirements for JWTs](/docs/auth/token/jwt)). This option is mostly useful for testing: since tokens are short-lived, in production you almost always want to use an authentication method that allows the client library to renew the token automatically when the previous one expires, such as authUrlAuthUrl:auth_url or authCallbackAuthCallback:auth_callback. Read more about [Token authentication](/docs/auth/token) | `String`, `TokenDetails` or `TokenRequest` | + +### ClientOptions ObjectARTClientOptionsClientOptions Hashio.ably.types.ClientOptionsIO.Ably.ClientOptions @@ -2123,7 +1715,7 @@ A `TokenRevocationFailureResult` contains information about the result of an uns `ART``ClientOptions` is used in the `AblyRealtime` constructor's `options` argument. - + #### Properties @@ -2139,43 +1731,6 @@ A `TokenRevocationFailureResult` contains information about the result of an uns - - -| Property | Description | Type | -|----------|-------------|------| -| key | The full key string, as obtained from the [application dashboard](https://ably.com/dashboard). Use this option if you wish to use Basic authentication, or wish to be able to issue Ably Tokens without needing to defer to a separate entity to sign Ably TokenRequests. Read more about [Basic authentication](/docs/auth/basic) | `String` | -| token | An authenticated [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) object, a [`TokenRequest`](/docs/api/realtime-sdk/types#token-request) object, or token string (obtained from the `token` property of a [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) component of an Ably TokenRequest response, or a [JSON Web Token](https://tools.ietf.org/html/rfc7519) satisfying [the Ably requirements for JWTs](/docs/auth/token/jwt)). This option is mostly useful for testing: since tokens are short-lived, in production you almost always want to use an authentication method that allows the client library to renew the token automatically when the previous one expires, such as `authUrl` or `authCallback`. Read more about [Token authentication](/docs/auth/token) | `String`, `TokenDetails` or `TokenRequest` | -| authCallback | A function with the form `function(tokenParams, callback(err, tokenOrTokenRequest))` which is called when a new token is required. The role of the callback is to obtain a fresh token, one of: an Ably Token string (in plain text format); a signed [`TokenRequest`](/docs/api/realtime-sdk/types#token-request); a [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) (in JSON format); an [Ably JWT](/docs/api/realtime-sdk/authentication#ably-jwt). See [our authentication documentation](/docs/auth) for details of the Ably TokenRequest format and associated API calls | `Callable` | -| authUrl | A URL that the library may use to obtain a fresh token, one of: an Ably Token string (in plain text format); a signed [`TokenRequest`](/docs/api/realtime-sdk/types#token-request); a [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) (in JSON format); an [Ably JWT](/docs/api/realtime-sdk/authentication#ably-jwt). For example, this can be used by a client to obtain signed Ably TokenRequests from an application server | `String` | -| authMethod | The HTTP verb to use for the request, either `GET` or `POST`
**Default:** `GET` | `String` | -| authHeaders | A set of key value pair headers to be added to any request made to the `authUrl`. Useful when an application requires these to be added to validate the request or implement the response. If the `authHeaders` object contains an `authorization` key, then `withCredentials` will be set on the xhr request | `Object` | -| authParams | A set of key value pair params to be added to any request made to the `authUrl`. When the `authMethod` is `GET`, query params are added to the URL, whereas when `authMethod` is `POST`, the params are sent as URL encoded form data. Useful when an application require these to be added to validate the request or implement the response | `Object` | -| tokenDetails | An authenticated [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) object (most commonly obtained from an Ably Token Request response). This option is mostly useful for testing: since tokens are short-lived, in production you almost always want to use an authentication method that allows the client library to renew the token automatically when the previous one expires, such as `authUrl` or `authCallback`. Use this option if you wish to use Token authentication. Read more about [Token authentication](/docs/auth/token) | `TokenDetails` | -| tls | A boolean value, indicating whether or not a TLS ("SSL") secure connection should be used. An insecure connection cannot be used with Basic authentication as it would lead to a possible compromise of the private API key while in transit. [Find out more about TLS](https://faqs.ably.com/are-messages-sent-to-and-received-from-ably-securely-using-tls)
**Default:** true | `Boolean` | -| clientId | A client ID, used for identifying this client when publishing messages or for presence purposes. The `clientId` can be any non-empty string. This option is primarily intended to be used in situations where the library is instantiated with a key; note that a `clientId` may also be implicit in a token used to instantiate the library; an error will be raised if a `clientId` specified here conflicts with the `clientId` implicit in the token. [Find out more about client identities](/docs/auth/identified-clients) | `String` | -| useTokenAuth | When true, forces [Token authentication](/docs/auth/token) to be used by the library. Please note that if a `clientId` is not specified in the [`ClientOptions`](/docs/api/realtime-sdk/types#client-options) or [`TokenParams`](/docs/api/realtime-sdk/types#token-params), then the Ably Token issued will be [anonymous](https://faqs.ably.com/authenticated-and-identified-clients)
**Default:** false | `Boolean` | -| endpoint | Enables [enterprise customers](https://ably.com/pricing) to use their own custom endpoints, which support dedicated, isolated clusters and regional message routing and storage constraints. See our [platform customization guide](/docs/platform/account/enterprise-customization) for more details
**Default:** null | `String` | -| environment | Deprecated, use `endpoint`. Enables [enterprise customers](https://ably.com/pricing) to use their own custom environments, which support dedicated, isolated clusters and regional message routing and storage constraints. See our [platform customization guide](/docs/platform/account/enterprise-customization) for more details
**Default:** null | `String` | -| idempotentRestPublishing | When true, enables idempotent publishing by assigning a unique message ID client-side, allowing the Ably servers to discard automatic publish retries following a failure such as a network fault. Enabled by default in all current Ably SDKs.
**Default:** true | `Boolean` | -| fallbackHosts | An array of fallback hosts to be used in the case of an error necessitating the use of an alternative host. When a custom environment is specified, the [fallback host functionality](https://faqs.ably.com/routing-around-network-and-dns-issues) is disabled. If your customer success manager has provided you with a set of custom fallback hosts, please specify them here
**Default:** `[a.ably-realtime.com, b.ably-realtime.com, c.ably-realtime.com, d.ably-realtime.com, e.ably-realtime.com]` | `String[]` | -| transportParams | Optional. Can be used to pass in arbitrary connection parameters, such as [`heartbeatInterval`](/docs/connect#heartbeats) and [`remainPresentFor`](/docs/presence-occupancy/presence#unstable-connections) | `Object` | -| useBinaryProtocol | If set to true, will enable the binary protocol (MessagePack) if it is supported. It's disabled by default on browsers for performance considerations (browsers are optimized for decoding JSON)If set to false, will forcibly disable the binary protocol (MessagePack). The binary protocol is used by default unless it is not supported. Find out more about the [benefits of binary encoding](https://faqs.ably.com/do-you-binary-encode-your-messages-for-greater-efficiency)
**Default:** falsetrue | `Boolean` | -| queueMessages | If false, this disables the default behavior whereby the library queues messages on a connection in the disconnected or connecting states. The default behavior allows applications to submit messages immediately upon instancing the library without having to wait for the connection to be established. Applications may use this option to disable queueing if they wish to have application-level control over the queueing under those conditions
**Default:** true | `Boolean` | -| echoMessages | If false, prevents messages originating from this connection being echoed back on the same connection
**Default:** true | `Boolean` | -| autoConnect | By default as soon as the client library is instantiated it will connect to Ably. You can optionally set this to false and explicitly connect to Ably when require using the [`connect`](/docs/api/realtime-sdk/connection#connect) method
**Default:** true | `Boolean` | -| logLevel | A number controlling the verbosity of the log output of the library. Valid values are: 0 (no logs), 1 (errors only), 2 (errors plus connection and channel state changes), 3 (high-level debug output), and 4 (full debug output) | `Integer` | -| logHandler | A function to handle each line of the library's log output. If `logHandler` is not specified, `console.log` is used
**Default:** `console.log` | `Callable` | -| transports | An optional array of transports to use, in descending order of preference. In the browser environment the available transports are: `web_socket`, `xhr_polling`The transports available in the Node.js client library are: `web_socket`, `xhr_polling`, `comet` | `String[]` | -| recover | This option allows a connection to inherit the state of a previous connection that may have existed under a different instance of the Realtime library. This might typically be used by clients of the browser library to ensure connection state can be preserved when the user refreshes the page. A recovery key string can be explicitly provided, or alternatively if a callback function is provided, the client library will automatically persist the recovery key between page reloads and call the callback when the connection is recoverable. The callback is then responsible for confirming whether the connection should be recovered or not. See [connection state recovery](/docs/connect/states) for further informationThis option allows a connection to inherit the state of a previous connection that may have existed under a different instance of the library by providing that connection's [`recoveryKey`](/docs/api/realtime-sdk/connection#recovery-key). This might typically be used by clients of an app to ensure connection state can be preserved following a reload. See [connection state recovery](/docs/connect/states) for further information and example code | `String`, `Callable``String` | -| closeOnUnload | When true, the client library will automatically send a close request to Ably whenever the `window beforeunload` event fires. By enabling this option, the close request sent to Ably ensures the connection state will not be retained and all channels associated with the connection will be detached. This is commonly used by developers who want presence leave events to fire immediately i.e. if a user navigates to another page or closes their browser, then enabling this option will result in the presence member leaving immediately. Without this option or an explicit call to the [`close`](/docs/api/realtime-sdk/connection#close) method of the [`Connection object`](/docs/api/realtime-sdk/connection), Ably expects that the abruptly disconnected connection could later be recovered and therefore does not immediately remove the user from presence. Instead, to avoid "twitchy" presence behavior an abruptly disconnected client is removed from channels in which they are present after 15 seconds, and the connection state is retained for two minutes
**Default:** true | `Boolean` | -| queryTime | If true, the library will query the Ably servers for the current time when [issuing TokenRequests](/docs/auth/token) instead of relying on a locally-available time of day. Knowing the time accurately is needed to create valid signed Ably [TokenRequests](/docs/api/realtime-sdk/authentication#request-token), so this option is useful for library instances on auth servers where for some reason the server clock cannot be kept synchronized through normal means, such as an [NTP daemon](https://en.wikipedia.org/wiki/Ntpd). The server is queried for the current time once per client library instance (which stores the offset from the local clock), so if using this option you should avoid instancing a new version of the library for each request
**Default:** false | `Boolean` | -| defaultTokenParams | When a [TokenParams](/docs/api/realtime-sdk/types#token-params) object is provided, it will override the client library defaults when issuing new Ably Tokens or Ably TokenRequests | [`TokenParams`](/docs/api/realtime-sdk/types#token-params) | -| disconnectedRetryTimeout | When the connection enters the `DISCONNECTED` state, after this delay in milliseconds, if the state is still `DISCONNECTED`, the client library will attempt to reconnect automatically
**Default:** 15,000ms | `Integer` | -| suspendedRetryTimeout | When the connection enters the `SUSPENDED` state, after this delay in milliseconds, if the state is still `SUSPENDED`, the client library will attempt to reconnect automatically
**Default:** 30,000ms | `Integer` | -| pushServiceWorkerUrl | A URL pointing to a service worker script which is used as the target for web push notifications | `String` | - - - | Property | Description | Type | @@ -2375,15 +1930,9 @@ A `TokenRevocationFailureResult` contains information about the result of an uns -### ChannelOptions ObjectARTChannelOptionsChannelOptions Hashio.ably.lib.types.ChannelOptionsIO.Ably.Rest.ChannelOptions - -Channel options are used for setting [channel parameters](/docs/channels/options) and [configuring encryption](/docs/channels/options/encryption). - - +### ChannelOptions ObjectARTChannelOptionsChannelOptions Hashio.ably.lib.types.ChannelOptionsIO.Ably.Rest.ChannelOptions -`ChannelOptions`, a plain JavaScript object, may optionally be specified when instancing a [`Channel`](/docs/channels), and this may be used to specify channel-specific options. The following attributes can be defined on the object: - - +Channel options are used for setting [channel parameters](/docs/channels/options) and [configuring encryption](/docs/channels/options/encryption). @@ -2403,7 +1952,7 @@ Channel options are used for - + #### Properties @@ -2419,12 +1968,12 @@ Channel options are used for - + | Property | Description | Type | |----------|-------------|------| -| paramsParams | Optional [parameters](/docs/channels/options) which specify behaviour of the channel. Supported params include [`rewind`](/docs/channels/options/rewind), [`delta`](/docs/channels/options/deltas), [`occupancy`](/docs/presence-occupancy/occupancy), and [`echo`](/docs/channels/options/echo). | `Map``JSON Object` | -| cipherCipherParams | Requests encryption for this channel when not null, and specifies encryption-related parameters (such as algorithm, chaining mode, key length and key). See [an example](/docs/api/realtime-sdk/encryption#getting-started) | [`CipherParams`](/docs/api/realtime-sdk/encryption#cipher-params) or an options object containing at a minimum a `key` or a `Param[]` list containing at a minimum a `key` or an options hash containing at a minimum a `key` | +| paramsParams | Optional [parameters](/docs/channels/options) which specify behaviour of the channel. Supported params include [`rewind`](/docs/channels/options/rewind), [`delta`](/docs/channels/options/deltas), [`occupancy`](/docs/presence-occupancy/occupancy), and [`echo`](/docs/channels/options/echo). | `Map``JSON Object` | +| cipherCipherParams | Requests encryption for this channel when not null, and specifies encryption-related parameters (such as algorithm, chaining mode, key length and key). See [an example](/docs/api/realtime-sdk/encryption#getting-started) | [`CipherParams`](/docs/api/realtime-sdk/encryption#cipher-params) or a `Param[]` list containing at a minimum a `key` or an options hash containing at a minimum a `key` | @@ -2471,27 +2020,7 @@ On success, the method returns a complete `ChannelOptions` object. Failure will -### ChannelStateARTRealtimeChannelStateChannel::STATE Enumio.ably.lib.realtime.ChannelState EnumIO.Ably.Realtime.ChannelState Enum - - - -`ChannelState` is a String with a value matching any of the [Realtime Channel states](/docs/channels/states). - - -```javascript -var ChannelStates = [ - 'initialized', - 'attaching', - 'attached', - 'detaching', - 'detached', - 'failed', - 'suspended' -] -``` - - - +### ChannelStateARTRealtimeChannelStateChannel::STATE Enumio.ably.lib.realtime.ChannelState EnumIO.Ably.Realtime.ChannelState Enum @@ -2658,28 +2187,7 @@ enum ChannelState { -### ChannelEventARTChannelEventChannel::EVENT Enumio.ably.lib.realtime.ChannelEvent EnumIO.Ably.Realtime.ChannelEvent Enum - - - -`ChannelEvent` is a String that can be emitted as an event on the `Channel` object; either a [ChannelState](/docs/channels/states) or an `update` event. - - -```javascript -var ChannelEvents = [ - 'initialized', - 'attaching', - 'attached', - 'detaching', - 'detached', - 'failed', - 'suspended', - 'update' -] -``` - - - +### ChannelEventARTChannelEventChannel::EVENT Enumio.ably.lib.realtime.ChannelEvent EnumIO.Ably.Realtime.ChannelEvent Enum @@ -2838,19 +2346,19 @@ enum ChannelEvent { -### ChannelStateChange ObjectARTRealtimeChannelStateChangeChannelStateChangeio.ably.lib.realtime.ConnectionStateListener.ChannelStateChangeIO.Ably.Realtime.ChannelStateChange +### ChannelStateChange ObjectARTRealtimeChannelStateChangeChannelStateChangeio.ably.lib.realtime.ConnectionStateListener.ChannelStateChangeIO.Ably.Realtime.ChannelStateChange -A `Ably::Models::ChannelStateChange``ChannelStateChange``ARTRealtimeChannelStateChange` is a type encapsulating state change information emitted by the [Channel](/docs/channels) object. See [Channel#on](/docs/api/realtime-sdk/channels#on) to register a listener for one or more events. +A `Ably::Models::ChannelStateChange``ChannelStateChange``ARTRealtimeChannelStateChange` is a type encapsulating state change information emitted by the [Channel](/docs/channels) object. See [Channel#on](/docs/api/realtime-sdk/channels#on) to register a listener for one or more events. #### Properties | Property | Description | Type | |----------|-------------|------| -| currentCurrent | The new current state | [`ChannelState`](/docs/api/realtime-sdk/types#channel-state)[`Channel::STATE`](/docs/api/realtime-sdk/types#channel-state) | -| previousPrevious | The previous state. (for the `update` event, this will be equal to the `current` state) | [`ChannelState`](/docs/api/realtime-sdk/types#channel-state)[`Channel::STATE`](/docs/api/realtime-sdk/types#channel-state) | -| eventEvent | The event that triggered this state change | [`ChannelEvent`](/docs/api/realtime-sdk/types#channel-event)[`Channel::EVENT`](/docs/api/realtime-sdk/types#channel-event) | -| reasonReason | An [`ErrorInfo`](/docs/api/realtime-sdk/types#error-info) containing any information relating to the transition | [`ErrorInfo`](/docs/api/realtime-sdk/types#error-info) | -| resumedResumed | A boolean indicated whether message continuity on this channel is preserved, see [Nonfatal channel errors](/docs/channels/states#non-fatal-errors) for more info. | `Boolean` | +| currentCurrent | The new current state | [`ChannelState`](/docs/api/realtime-sdk/types#channel-state)[`Channel::STATE`](/docs/api/realtime-sdk/types#channel-state) | +| previousPrevious | The previous state. (for the `update` event, this will be equal to the `current` state) | [`ChannelState`](/docs/api/realtime-sdk/types#channel-state)[`Channel::STATE`](/docs/api/realtime-sdk/types#channel-state) | +| eventEvent | The event that triggered this state change | [`ChannelEvent`](/docs/api/realtime-sdk/types#channel-event)[`Channel::EVENT`](/docs/api/realtime-sdk/types#channel-event) | +| reasonReason | An [`ErrorInfo`](/docs/api/realtime-sdk/types#error-info) containing any information relating to the transition | [`ErrorInfo`](/docs/api/realtime-sdk/types#error-info) | +| resumedResumed | A boolean indicated whether message continuity on this channel is preserved, see [Nonfatal channel errors](/docs/channels/states#non-fatal-errors) for more info. | `Boolean` | @@ -2869,22 +2377,22 @@ public interface ChannelStateListener { -### CipherParamsARTCipherParamsCipherParams Hashio.ably.lib.util.Crypto.CipherParamsIO.Ably.CipherParams +### CipherParamsARTCipherParamsCipherParams Hashio.ably.lib.util.Crypto.CipherParamsIO.Ably.CipherParams A `CipherParams` contains configuration options for a channel cipher, including algorithm, mode, key length and key. Ably client libraries currently support AES with CBC, PKCS#7 with a default key length of 256 bits. All implementations also support AES128. -Individual client libraries may support either instancing a `CipherParams` directly, using [`Crypto.getDefaultParams()`](/docs/api/realtime-sdk/encryption#get-default-params)[`Crypto.GetDefaultParams()`](/docs/api/realtime-sdk/encryption#get-default-params)[`Crypto.get_default_params()`](/docs/api/realtime-sdk/encryption#get-default-params), or generating one automatically when initializing a channel, as in [this example](/docs/channels/options/encryption). +Individual client libraries may support either instancing a `CipherParams` directly, using [`Crypto.getDefaultParams()`](/docs/api/realtime-sdk/encryption#get-default-params)[`Crypto.GetDefaultParams()`](/docs/api/realtime-sdk/encryption#get-default-params)[`Crypto.get_default_params()`](/docs/api/realtime-sdk/encryption#get-default-params), or generating one automatically when initializing a channel, as in [this example](/docs/channels/options/encryption). -#### PropertiesMembers +#### PropertiesMembers - + | Property | Description | Type | |----------|-------------|------| -| keyKey:key | A binary (`byte[]``ArrayBuffer` or `Uint8Array``Buffer`byte array`NSData`) or base64-encoded `NS``String` containing the secret key used for encryption and decryption | Binary or `String` | -| algorithm:algorithmAlgorithm | _AES_ The name of the algorithm in the default system provider, or the lower-cased version of it; eg "aes" or "AES" | `String` | -| :key_lengthkeyLengthKeyLength | _256_ The key length in bits of the cipher, either 128 or 256 | `Integer` | -| mode:modeMode | _CBC_ The cipher mode | `String``CipherMode` | +| keyKey:key | A binary (`byte[]`byte array`NSData`) or base64-encoded `NS``String` containing the secret key used for encryption and decryption | Binary or `String` | +| algorithm:algorithmAlgorithm | _AES_ The name of the algorithm in the default system provider, or the lower-cased version of it; eg "aes" or "AES" | `String` | +| :key_lengthkeyLengthKeyLength | _256_ The key length in bits of the cipher, either 128 or 256 | `Integer` | +| mode:modeMode | _CBC_ The cipher mode | `String``CipherMode` | @@ -2900,9 +2408,9 @@ Individual client libraries may support either instancing a `CipherParams` direc | Property | Description | Type | |----------|-------------|------| -| algorithm:algorithmAlgorithm | _AES_ The name of the algorithm in the default system provider, or the lower-cased version of it; eg "aes" or "AES" | `String` | -| :key_lengthkeyLengthKeyLength | _256_ The key length in bits of the cipher, either 128 or 256 | `Integer` | -| modeMode | _CBC_ The cipher mode | `String``CipherMode` | +| algorithm:algorithmAlgorithm | _AES_ The name of the algorithm in the default system provider, or the lower-cased version of it; eg "aes" or "AES" | `String` | +| :key_lengthkeyLengthKeyLength | _256_ The key length in bits of the cipher, either 128 or 256 | `Integer` | +| modeMode | _CBC_ The cipher mode | `String``CipherMode` | | keySpec | A `KeySpec` for the cipher key | `SecretKeySpec` | @@ -2936,28 +2444,7 @@ public interface CompletionListener { -### ConnectionStateARTRealtimeConnectionStateConnection::STATEio.ably.lib.realtime.ConnectionStateIO.Ably.Realtime.ConnectionState - - - -`ConnectionState` is a String with a value matching any of the [Realtime Connection states](/docs/connect/states). - - -```javascript -var ConnectionStates = [ - 'initialized', - 'connecting', - 'connected', - 'disconnected', - 'suspended', - 'closing', - 'closed', - 'failed' -] -``` - - - +### ConnectionStateARTRealtimeConnectionStateConnection::STATEio.ably.lib.realtime.ConnectionStateIO.Ably.Realtime.ConnectionState @@ -3137,29 +2624,7 @@ enum ConnectionState { -### ConnectionEventARTRealtimeConnectionEventConnection::EVENT Enumio.ably.lib.realtime.ConnectionEvent EnumIO.Ably.Realtime.ConnectionEvent Enum - - - -`ConnectionEvent` is a String that can be emitted as an event on the `Connection` object; either a [Realtime Connection state](/docs/connect/states) or an `update` event. - - -```javascript -var ConnectionEvents = [ - 'initialized', - 'connecting', - 'connected', - 'disconnected', - 'suspended', - 'closing', - 'closed', - 'failed', - 'update' -] -``` - - - +### ConnectionEventARTRealtimeConnectionEventConnection::EVENT Enumio.ably.lib.realtime.ConnectionEvent EnumIO.Ably.Realtime.ConnectionEvent Enum @@ -3346,7 +2811,6 @@ enum ConnectionEvent { - ### io.ably.lib.realtime.ConnectionStateListener @@ -3364,19 +2828,19 @@ public interface ConnectionStateListener { -### ConnectionStateChange ObjectARTConnectionStateChangeConnectionStateChangeio.ably.lib.realtime.ConnectionStateListener.ConnectionStateChangeIO.Ably.Realtime.ConnectionStateChange +### ConnectionStateChange ObjectARTConnectionStateChangeConnectionStateChangeio.ably.lib.realtime.ConnectionStateListener.ConnectionStateChangeIO.Ably.Realtime.ConnectionStateChange -A `io.ably.lib.realtime.ConnectionStateListener.ConnectionStateChange``Ably::Models::ConnectionStateChange``ARTConnectionStateChange``IO.Ably.Realtime.ConnectionStateChange``ConnectionStateChange` is a type encapsulating state change information emitted by the [Connection](/docs/api/realtime-sdk/connection) object. See [Connection#on](/docs/api/realtime-sdk/connection#on) to register a listener for one or more events. +A `io.ably.lib.realtime.ConnectionStateListener.ConnectionStateChange``Ably::Models::ConnectionStateChange``ARTConnectionStateChange``IO.Ably.Realtime.ConnectionStateChange``ConnectionStateChange` is a type encapsulating state change information emitted by the [Connection](/docs/api/realtime-sdk/connection) object. See [Connection#on](/docs/api/realtime-sdk/connection#on) to register a listener for one or more events. -#### PropertiesMembersAttributes +#### PropertiesMembersAttributes | Property | Description | Type | |----------|-------------|------| -| currentCurrent | The new state | [State `String`](/docs/api/realtime-sdk/types#connection-state)[`Connection::STATE`](/docs/api/realtime-sdk/types#connection-state)[`ConnectionState`](/docs/api/realtime-sdk/types#connection-state) | -| previousPrevious | The previous state. (for the `update` event, this will be equal to the `current` state) | [State `String`](/docs/api/realtime-sdk/types#connection-state)[`Connection::STATE`](/docs/api/realtime-sdk/types#connection-state)[`ConnectionState`](/docs/api/realtime-sdk/types#connection-state) | -| eventEvent | The event that triggered this state change | [`ConnectionEvent`](/docs/api/realtime-sdk/types#connection-event)[`Connection::EVENT`](/docs/api/realtime-sdk/types#connection-event) | -| reasonReason | An [`ErrorInfo`](/docs/api/realtime-sdk/types#error-info) containing any information relating to the transition | [`ErrorInfo`](/docs/api/realtime-sdk/types#error-info) | -| retryInretry_inRetryIn | Duration upon which the library will retry a connection where applicable, as millisecondssecondsa `Timespan` | `Integer``Timespan``Long Integer` | +| currentCurrent | The new state | [State `String`](/docs/api/realtime-sdk/types#connection-state)[`Connection::STATE`](/docs/api/realtime-sdk/types#connection-state)[`ConnectionState`](/docs/api/realtime-sdk/types#connection-state) | +| previousPrevious | The previous state. (for the `update` event, this will be equal to the `current` state) | [State `String`](/docs/api/realtime-sdk/types#connection-state)[`Connection::STATE`](/docs/api/realtime-sdk/types#connection-state)[`ConnectionState`](/docs/api/realtime-sdk/types#connection-state) | +| eventEvent | The event that triggered this state change | [`ConnectionEvent`](/docs/api/realtime-sdk/types#connection-event)[`Connection::EVENT`](/docs/api/realtime-sdk/types#connection-event) | +| reasonReason | An [`ErrorInfo`](/docs/api/realtime-sdk/types#error-info) containing any information relating to the transition | [`ErrorInfo`](/docs/api/realtime-sdk/types#error-info) | +| retryInretry_inRetryIn | Duration upon which the library will retry a connection where applicable, as millisecondssecondsa `Timespan` | `Integer``Timespan``Long Integer` | @@ -3413,25 +2877,6 @@ public interface MessageListener { - - -### LastConnectionDetails - -A `LastConnectionDetails` object provides details on the last connection in a browser environment persisted when the `window beforeunload` fired. This object is provided to the callback specified in the `recover` attribute of [`ClientOptions`](/docs/api/realtime-sdk/types#client-options). The callback in turn instructs the client library whether the connection should be recovered or not. See [connection state recovery](/docs/connect/states) for more information. - -Please note that as [`sessionStorage`](https://www.w3.org/TR/webstorage/) is used to persist the `LastConnectionDetails` between page reloads, it is only available for pages in the same origin and top-level browsing context. - -#### Properties - -| Property | Description | Type | -|----------|-------------|------| -| recoveryKey | An opaque string obtained from the [recoveryKey](/docs/api/realtime-sdk/connection#recovery-key) attribute of the [Connection object](/docs/api/realtime-sdk/connection) before the page was unloaded. This property is used by the library to recover the connection | `String` | -| disconnectedAt | The time at which the previous library was abruptly disconnected before the page was unloaded. This is represented as milliseconds since epoch | `Integer` | -| location | A clone of [`location`](https://www.w3.org/TR/html5/browsers.html#the-location-interface) object of the previous page's `document` object before the page was unloaded. A common use case for this attribute is to ensure that the previous page URL is the same as the current URL before allowing the connection to be recovered. For example, you may want the connection to be recovered only for page reloads, but not when a user navigates to a different page | `String` | -| clientId | The [`clientId`](/docs/api/realtime-sdk/authentication/#client-id) of the [client's Auth object](/docs/api/realtime-sdk/authentication) before the page was unloaded. A common use case for this attribute is to ensure that the current logged in user's `clientId` matches the previous connection's `clientId` before allowing the connection to be recovered. Ably prohibits changing a `clientId` for an existing connection, so any mismatch in `clientId` during a recover will result in the connection moving to the failed state | `String` | - - - ### io.ably.lib.realtime.Presence.PresenceListener @@ -3503,13 +2948,7 @@ Mark the `Deferrable` as succeeded and trigger all callbacks. See the [EventMach -### TokenParams ObjectARTTokenParamsTokenParams Hashio.ably.lib.rest.Auth.TokenParamsIO.Ably.TokenParams - - - -`TokenParams` is a plain JavaScript object and is used in the parameters of [token authentication](/docs/auth/token) requests, corresponding to the desired attributes of the [Ably Token](/docs/api/realtime-sdk/authentication#token-details). The following attributes can be defined on the object: - - +### TokenParams ObjectARTTokenParamsTokenParams Hashio.ably.lib.rest.Auth.TokenParamsIO.Ably.TokenParams @@ -3529,42 +2968,13 @@ Mark the `Deferrable` as succeeded and trigger all callbacks. See the [EventMach -#### PropertiesMembersAttributes - -| Property | Description | Type | -|----------|-------------|------| -| capabilityCapability:capability | JSON stringified capability of the [Ably Token](/docs/api/realtime-sdk/authentication#token-details). If the [Ably Token](/docs/api/realtime-sdk/authentication#token-details) request is successful, the capability of the returned [Ably Token](/docs/api/realtime-sdk/authentication#token-details) will be the intersection of this capability with the capability of the issuing key. [Find our more about how to use capabilities to manage access privileges for clients](/docs/auth/capabilities). | `String``Capability` | -| clientIdClientId:client_id | A client ID, used for identifying this client when publishing messages or for presence purposes. The `clientId``:client_id``ClientId` can be any non-empty string. This option is primarily intended to be used in situations where the library is instantiated with a key; note that a `clientId``:client_id``ClientId` may also be implicit in a token used to instantiate the library; an error will be raised if a `clientId``:client_id``ClientId` specified here conflicts with the `clientId``:client_id``ClientId` implicit in the token. [Find out more about client identities](/docs/auth/identified-clients) | `String` | -| nonceNonce:nonce | An optional opaque nonce string of at least 16 characters to ensure uniqueness of this request. Any subsequent request using the same nonce will be rejected. | `String` | -| timestampTimestamp:timestamp | The timestamp (in milliseconds since the epoch)The timestamp of this request. `timestamp`, in conjunction with the `nonce`, is used to prevent requests for [Ably Token](/docs/api/realtime-sdk/authentication#token-details) from being replayed. | `Integer``Long Integer``Time``NSDate``DateTimeOffset` | -| ttlTtl:ttl | _1 hour_ Requested time to live for the [Ably Token](/docs/api/realtime-sdk/authentication#token-details) being created in millisecondsin secondsas a `NSTimeInterval`as a `TimeSpan`. When omitted, the Ably REST API default of 60 minutes is applied by Ably | `Integer` (milliseconds)`Integer` (seconds)`NSTimeInterval``Long Integer``TimeSpan` | - - - -### TokenRevocationTargetSpecifier - -`TokenRevocationTargetSpecifier` - -A `TokenRevocationTargetSpecifier` describes which tokens should be affected by a token revocation request. - -#### Properties - -| Property | Description | Type | -|----------|-------------|------| -| type | The type of token revocation target specifier. Valid values include `clientId`, `revocationKey` and `channel` | `String` | -| value | The value of the token revocation target specifier | `String` | - -### TokenRevocationOptions - -`TokenRevocationOptions` - -A `TokenRevocationOptions` describes the additional options accepted by revoke tokens request. - -#### Properties +#### PropertiesMembersAttributes | Property | Description | Type | |----------|-------------|------| -| issuedBefore | An optional Unix timestamp in milliseconds where only tokens issued before this time are revoked. The default is the current time. Requests with an `issuedBefore` in the future, or more than an hour in the past, will be rejected | `Number` | -| allowReauthMargin | _false_ If true, permits a token renewal cycle to take place without needing established connections to be dropped, by postponing enforcement to 30 seconds in the future, and sending any existing connections a hint to obtain (and upgrade the connection to use) a new token. The default is `false`, meaning that the effect is near-immediate. | `Boolean` | +| capabilityCapability:capability | JSON stringified capability of the [Ably Token](/docs/api/realtime-sdk/authentication#token-details). If the [Ably Token](/docs/api/realtime-sdk/authentication#token-details) request is successful, the capability of the returned [Ably Token](/docs/api/realtime-sdk/authentication#token-details) will be the intersection of this capability with the capability of the issuing key. [Find our more about how to use capabilities to manage access privileges for clients](/docs/auth/capabilities). | `String``Capability` | +| clientIdClientId:client_id | A client ID, used for identifying this client when publishing messages or for presence purposes. The `clientId``:client_id``ClientId` can be any non-empty string. This option is primarily intended to be used in situations where the library is instantiated with a key; note that a `clientId``:client_id``ClientId` may also be implicit in a token used to instantiate the library; an error will be raised if a `clientId``:client_id``ClientId` specified here conflicts with the `clientId``:client_id``ClientId` implicit in the token. [Find out more about client identities](/docs/auth/identified-clients) | `String` | +| nonceNonce:nonce | An optional opaque nonce string of at least 16 characters to ensure uniqueness of this request. Any subsequent request using the same nonce will be rejected. | `String` | +| timestampTimestamp:timestamp | The timestamp (in milliseconds since the epoch)The timestamp of this request. `timestamp`, in conjunction with the `nonce`, is used to prevent requests for [Ably Token](/docs/api/realtime-sdk/authentication#token-details) from being replayed. | `Integer``Long Integer``Time``NSDate``DateTimeOffset` | +| ttlTtl:ttl | _1 hour_ Requested time to live for the [Ably Token](/docs/api/realtime-sdk/authentication#token-details) being created in millisecondsin secondsas a `NSTimeInterval`as a `TimeSpan`. When omitted, the Ably REST API default of 60 minutes is applied by Ably | `Integer` (milliseconds)`Integer` (seconds)`NSTimeInterval``Long Integer``TimeSpan` | - From 543674058f1cf749accfd986c540664fd468a1ac Mon Sep 17 00:00:00 2001 From: Mark Hulbert <39801222+m-hulbert@users.noreply.github.com> Date: Mon, 27 Jul 2026 17:28:11 +0100 Subject: [PATCH 6/7] Strip JavaScript and Node.js content from legacy REST SDK reference Same transformation as the Realtime SDK reference: javascript/nodejs removed from every list, JS/Node-only blocks and examples deleted. Also removes the now-orphaned DeriveOptions type from the Realtime channels page (getDerived was documented for JavaScript only) and the JS-only revokeTokens jump_to entry on the REST auth page. Co-Authored-By: Claude Fable 5 --- src/pages/docs/api/realtime-sdk/channels.mdx | 10 - src/pages/docs/api/rest-sdk.mdx | 546 +++------------ .../docs/api/rest-sdk/authentication.mdx | 446 ++---------- src/pages/docs/api/rest-sdk/channels.mdx | 330 ++------- src/pages/docs/api/rest-sdk/encryption.mdx | 108 +-- src/pages/docs/api/rest-sdk/history.mdx | 241 ++----- src/pages/docs/api/rest-sdk/messages.mdx | 24 +- src/pages/docs/api/rest-sdk/presence.mdx | 186 +---- src/pages/docs/api/rest-sdk/push-admin.mdx | 485 ++----------- src/pages/docs/api/rest-sdk/statistics.mdx | 86 +-- src/pages/docs/api/rest-sdk/types.mdx | 659 ++++-------------- 11 files changed, 551 insertions(+), 2570 deletions(-) diff --git a/src/pages/docs/api/realtime-sdk/channels.mdx b/src/pages/docs/api/realtime-sdk/channels.mdx index 6751492817..06c2978224 100644 --- a/src/pages/docs/api/realtime-sdk/channels.mdx +++ b/src/pages/docs/api/realtime-sdk/channels.mdx @@ -2118,16 +2118,6 @@ On success, the method returns a complete `ChannelOptions` object. Failure will -#### DeriveOptions - -Properties passed to [`getDerived()`](#get-derived) to filter the messages returned in a subscription to it. - -##### Parameters - -| Parameter | Description | Type | -|-----------|-------------|------| -| filter | The filter expression to use when creating or returning the derived channel. This is a [JMESPath](https://jmespath.org/) query | `String` | - #### io.ably.lib.realtime.ChannelStateListener diff --git a/src/pages/docs/api/rest-sdk.mdx b/src/pages/docs/api/rest-sdk.mdx index 11e4e5e1cc..ecd6751877 100644 --- a/src/pages/docs/api/rest-sdk.mdx +++ b/src/pages/docs/api/rest-sdk.mdx @@ -16,12 +16,6 @@ We've updated the style and readability of our API references, starting with Jav The Ably REST library constructor is overloaded allowing it to be instantiated using a [`ClientOptions`](#client-options) object, or more simply using a string containing an [API key](/docs/auth/basic) or [Token](/docs/auth/token). - - -`new Ably.Rest(String keyOrTokenId)` - - - `Ably::Rest.new(String key_or_token_id)` @@ -78,13 +72,7 @@ The Ably REST library constructor is overloaded allowing it to be instantiated u -This will instantiate the REST library with the provided API key or Token ID string. - - - -`new Ably.Rest(`[`ClientOptions`](#client-options)` clientOptions)` - - +This will instantiate the REST library with the provided API key or Token ID string. @@ -140,7 +128,7 @@ This will instantiate the REST library with the provided API key + This will instantiate the library using the specified [`ClientOptions`](#client-options). @@ -152,7 +140,6 @@ This will instantiate the library and create a new `Ably::Rest::Client` using th - The REST constructor is used to instantiate the library. The REST library may be instantiated multiple times with the same or different [`ClientOptions`](#client-options) in any given context. Except where specified otherwise, instances operate independently of one another. ### Authentication @@ -161,13 +148,13 @@ The REST library needs to have credentials to be able to authenticate with the A #### Basic Authentication -A private API key string for [`ClientOptions#key`](#client-options)[`ClientOptions#Key`](#client-options) or the constructor, as obtained from the [application dashboard](https://ably.com/dashboard), is required for [Basic Authentication](/docs/auth/basic). Use this option if you wish to use [Basic authentication](/docs/auth/basic), or if you want to be able to [request Ably Tokens](/docs/auth/token) without needing to defer to a separate entity to sign Ably TokenRequests. Note that initializing the library with a `key``Key` does not necessarily mean that the library will use Basic auth; using the private key it is also able to create and sign Ably TokenRequests and use token authentication when necessary. +A private API key string for [`ClientOptions#key`](#client-options)[`ClientOptions#Key`](#client-options) or the constructor, as obtained from the [application dashboard](https://ably.com/dashboard), is required for [Basic Authentication](/docs/auth/basic). Use this option if you wish to use [Basic authentication](/docs/auth/basic), or if you want to be able to [request Ably Tokens](/docs/auth/token) without needing to defer to a separate entity to sign Ably TokenRequests. Note that initializing the library with a `key``Key` does not necessarily mean that the library will use Basic auth; using the private key it is also able to create and sign Ably TokenRequests and use token authentication when necessary. #### Token Authentication -The [`ClientOptions#token`](#client-options)[`ClientOptions#Token`](#client-options) option takes a `token` string, and assumes that the Ably-compatible token has been obtained from some other instance that requested the token. Use the token option if you are provided with a token to use and you do not have a key (or do not have a key with the capabilities that you require). +The [`ClientOptions#token`](#client-options)[`ClientOptions#Token`](#client-options) option takes a `token` string, and assumes that the Ably-compatible token has been obtained from some other instance that requested the token. Use the token option if you are provided with a token to use and you do not have a key (or do not have a key with the capabilities that you require). -Since tokens are short-lived, it is rarely sufficient to start with a token without the means for refreshing it. The [`authUrl` and `authCallback` options](#client-options)[`:auth_url` and `:auth_callback` options](#client-options)[`auth_url` and `auth_callback` options](#client-options)[`AuthUrl` and `AuthCallback` options](#client-options) are provided to allow a user of the library to provide new Ably-compatible tokens or Ably TokenRequests to the library as required; using these options allows the library to be instantiated without a `key` or `token``Key` or `Token`, and an initial token will be obtained automatically when required. +Since tokens are short-lived, it is rarely sufficient to start with a token without the means for refreshing it. The [`authUrl` and `authCallback` options](#client-options)[`:auth_url` and `:auth_callback` options](#client-options)[`auth_url` and `auth_callback` options](#client-options)[`AuthUrl` and `AuthCallback` options](#client-options) are provided to allow a user of the library to provide new Ably-compatible tokens or Ably TokenRequests to the library as required; using these options allows the library to be instantiated without a `key` or `token``Key` or `Token`, and an initial token will be obtained automatically when required. Read more on [authentication](/docs/auth). @@ -187,40 +174,33 @@ All callbacks provided by you are dispatched to the main queue by default, allow +## AblyRest Propertiesio.ably.lib.AblyRest MembersAbly::Rest::Client AttributesARTRest Propertiesably.Rest Properties -## AblyRest PropertiesAbly.Rest Propertiesio.ably.lib.AblyRest MembersAbly::Rest::Client AttributesARTRest Propertiesably.Rest Properties +The REST client exposes the following public attributesmembersproperties: -The REST client exposes the following public attributesmembersproperties: - -### authAuth +### authAuth A reference to the [`Auth`](/docs/api/rest-sdk/authentication) authentication object configured for this client library. ### push -A reference to the [`Push`](/docs/push)[`ARTPush`](/docs/push) object in this client library. +A reference to the [`Push`](/docs/push)[`ARTPush`](/docs/push) object in this client library. ### device -A reference to the [`LocalDevice`](/docs/push/configure/device)[`ARTLocalDevice`](/docs/push/configure/device) object. +A reference to the [`LocalDevice`](/docs/push/configure/device)[`ARTLocalDevice`](/docs/push/configure/device) object. -### channelsChannels +### channelsChannels [`Channels`](/docs/channels) is a reference to the [`Channel`](/docs/channels) collection instance for this library indexed by the channel name. You can use the [`Get`](/docs/api/rest-sdk/channels#get) method of this to get a `Channel` instance. See [channels](/docs/channels) and [messages](/docs/messages/) for more information. -## AblyRest MethodsAbly.Rest Methodsio.ably.lib.AblyRest MethodsAbly::Rest::Client MethodsARTRest Methodsably.Rest Methods - -### statsStats +## AblyRest Methodsio.ably.lib.AblyRest MethodsAbly::Rest::Client MethodsARTRest Methodsably.Rest Methods - - -`stats(Object params?): Promise>` - - +### statsStats @@ -264,7 +244,6 @@ A reference to the + | Parameter | Description | |-----------|-------------| -| optionsqueryparams | An optional object`StatsRequestParams`[`Param[]`](#param) array containing the query parameters set of parameters used to specify which statistics are retrieved. If not specified the default parameters will be used | +| optionsquery | An optional object`StatsRequestParams`[`Param[]`](#param) array containing the query parameters | -#### options parametersARTStatsQuery propertiesStatsRequestParams propertiesparams properties +#### options parametersARTStatsQuery propertiesStatsRequestParams properties The following options, as defined in the [REST `/stats` API](/docs/api/rest-api#stats) endpoint, are permitted: | Parameter | Description | Type | Default | |-----------|-------------|------|---------| -| start:startStart | Earliest `DateTimeOffset` or `Time` or time in milliseconds since the epoch for any stats retrieved | `Long``Int` or `Time``DateTimeOffset``Number` | beginning of time | -| end:endEnd | Latest `DateTimeOffset` or `Time` or time in milliseconds since the epoch for any stats retrieved | `Long``Int` or `Time``DateTimeOffset``Number` | current time | -| direction:directionDirection | `:forwards` or `:backwards``forwards` or `backwards` | `String``Symbol``Direction` enum | backwards | -| limit:limitLimit | Maximum number of stats to retrieve up to 1,000 | `Integer``Number` | 100 | -| unit:unitUnit | `:minute`, `:hour`, `:day` or `:month`.`minute`, `hour`, `day` or `month`. Based on the unit selected, the given start or end times are rounded down to the start of the relevant interval depending on the unit granularity of the query | `String`[`StatsIntervalGranularity`](/docs/api/rest-sdk/types#stats-granularity)[`ARTStatsGranularity`](#stats-granularity)[`StatsIntervalGranularity`](/docs/api/rest-sdk/types#stats-granularity) enum | minute | - - - -#### Returns - -Returns a promise. On success, the promise is fulfilled with a [`PaginatedResult`](/docs/api/rest-sdk/types#paginated-result) object containing an array of [`Stats`](/docs/api/rest-sdk/types#stats) objects. On failure, the promise is rejected with an [`ErrorInfo`](/docs/api/rest-sdk/types#error-info) object. - - +| start:startStart | Earliest `DateTimeOffset` or `Time` or time in milliseconds since the epoch for any stats retrieved | `Long``Int` or `Time``DateTimeOffset` | beginning of time | +| end:endEnd | Latest `DateTimeOffset` or `Time` or time in milliseconds since the epoch for any stats retrieved | `Long``Int` or `Time``DateTimeOffset` | current time | +| direction:directionDirection | `:forwards` or `:backwards``forwards` or `backwards` | `String``Symbol``Direction` enum | backwards | +| limit:limitLimit | Maximum number of stats to retrieve up to 1,000 | `Integer` | 100 | +| unit:unitUnit | `:minute`, `:hour`, `:day` or `:month`.`minute`, `hour`, `day` or `month`. Based on the unit selected, the given start or end times are rounded down to the start of the relevant interval depending on the unit granularity of the query | `String`[`ARTStatsGranularity`](#stats-granularity)[`StatsIntervalGranularity`](/docs/api/rest-sdk/types#stats-granularity) enum | minute | @@ -349,14 +320,7 @@ Failure to retrieve the stats will raise an [`AblyException`](/docs/api/rest-sdk - -### timeTime - - - -`time(): Promise` - - +### timeTime @@ -400,16 +364,7 @@ Failure to retrieve the stats will raise an [`AblyException`](/docs/api/rest-sdk - -Obtains the time from the Ably service as a `Time` objecta `DateTimeOffset` objectmilliseconds since epoch. (Clients that do not have access to a sufficiently well maintained time source and wish to issue Ably [`TokenRequests`](/docs/api/rest-sdk/authentication#token-request) with a more accurate timestamp should use the `queryTime` [`clientOptions`](#client-options) instead of this method). - - - -#### Returns - -Returns a promise. On success, the promise is fulfilled with the time as milliseconds since the Unix epoch. On failure, the promise is rejected with an [`ErrorInfo`](#error-info) object. - - +Obtains the time from the Ably service as a `Time` objecta `DateTimeOffset` objectmilliseconds since epoch. (Clients that do not have access to a sufficiently well maintained time source and wish to issue Ably [`TokenRequests`](/docs/api/rest-sdk/authentication#token-request) with a more accurate timestamp should use the `queryTime` [`clientOptions`](#client-options) instead of this method). @@ -441,14 +396,7 @@ On failure to retrieve the Ably server time, `error` contains an [`ErrorInfo`](# - -### requestRequest - - - -`request(method, path, version, params?, body?, headers?): Promise` - - +### requestRequest @@ -490,19 +438,6 @@ Makes a REST request to a provided path. This is provided as a convenience for d #### Parameters - - -| Parameter | Description | Type | -|-----------|-------------|------| -| method | either `get`, `post`, `put`, `patch` or `delete` | String | -| path | the path to query | String | -| version | version of the REST API to use | Number | -| params | (optional) any querystring parameters needed | Object | -| body | (optional; for `post`, `put` and `patch` methods) the body of the request, as anything that can be serialized into JSON, such as an `Object` or `Array` | Serializable | -| headers | (optional) any headers needed. If provided, these will be mixed in with the default library headers | Object | - - - | Parameter | Description | Type | @@ -515,14 +450,6 @@ Makes a REST request to a provided path. This is provided as a convenience for d - - -#### Returns - -Returns a promise. On success, the promise is fulfilled with the [`HttpPaginatedResponse`](/docs/api/realtime-sdk/types#http-paginated-response) object returned by the HTTP request. The response object will contain an empty or JSON-encodable object. On failure, the promise is rejected with an [`ErrorInfo`](/docs/api/realtime-sdk/types#error-info) object. - - - #### Callback result @@ -555,110 +482,9 @@ Failure to obtain a response will raise an [`AblyException`](/docs/api/realtime- - - - -#### Example - - - - -```javascript -const response = await rest.request( - 'get', - '/channels/someChannel/messages', - 3, - { limit: 1, direction: 'forwards' }, -); -console.log('Success! status code was ' + response.statusCode); -console.log(response.items.length + ' items returned'); -if (response.hasNext()) { - const nextPage = await response.next(); - console.log(nextPage.items.length + ' more items returned'); -} -``` - - - - - - - -```nodejs -const response = await rest.request( - 'get', - '/channels/someChannel/messages', - 3, - { limit: 1, direction: 'forwards' }, -); -console.log('Success! status code was ' + response.statusCode); -console.log(response.items.length + ' items returned'); -if (response.hasNext()) { - const nextPage = await response.next(); - console.log(nextPage.items.length + ' more items returned'); -} -``` - - - - - - - - -### batchPublish - -There are two overloaded versions of this method: - -`batchPublish(BatchPublishSpec spec): Promise>` - -Publishes a [`BatchPublishSpec`](#batch-publish-spec) object to one or more channels, up to a maximum of 100 channels. - -`batchPublish(BatchPublishSpec[] specs): Promise[]>` - -Publishes one or more [`BatchPublishSpec`](#batch-publish-spec) objects to one or more channels, up to a maximum of 100 channels. - -#### Parameters - -| Parameter | Description | Type | -|-----------|-------------|------| -| spec | An object describing the messages to be batch published and to which channels | [`BatchPublishSpec`](#batch-publish-spec) | -| specs | An array of objects describing the messages to be batch published and to which channels | [`BatchPublishSpec[]`](#batch-publish-spec) | - -#### Returns - -Returns a promise. On success, the promise is fulfilled with a [`BatchResult`](#batch-result) object, or an array of [`BatchResult`](#batch-result) objects, containing information about the result of the batch publish operation for each channel. The successful results of specific channels are returned as [`BatchPublishSuccessResult`](#batch-publish-success-result) objects, whilst failures are [`BatchPublishFailureResult`](#batch-publish-failure-result) objects. If an array of [`BatchResult`](#batch-result) objects are returned, they are in the same order as the provided [`BatchPublishSpec`](#batch-publish-spec). On failure, the promise is rejected with an [`ErrorInfo`](/docs/api/rest-sdk/types#error-info) object. - - -### batchPresence - -`batchPresence(String[] channels): Promise[]>` - -Retrieves the presence state for one or more channels, up to a maximum of 100 channels. Presence state includes the [`clientId`](#client-options) of members and their current [`PresenceAction`](/docs/api/rest-sdk/presence#presence-action). - -#### Parameters - -| Parameter | Description | Type | -|-----------|-------------|------| -| channels | An array of one or more channel names, up to a maximum of 100 channels | `String[]` | - -#### Returns - -Returns a promise. On success, the promise is fulfilled with a [`BatchResult`](#batch-result) object containing information about the result of the batch presence request for each channel. The successful results of specific channels are returned as [`BatchPresenceSuccessResult`](#batch-presence-success-result) objects, whilst failures are [`BatchPresenceFailureResult`](#batch-presence-failure-result) objects. On failure, the promise is rejected with an [`ErrorInfo`](/docs/api/rest-sdk/types#error-info) object. - - - - - ## Related types -### ClientOptionsARTClientOptionsio.ably.types.ClientOptionsIO.Ably.ClientOptionsably.ClientOptions - - - -`ClientOptions` is a plain JavaScript object and is used in the `Ably.Rest` constructor's `options` argument. The following attributes can be defined on the object: - - +### ClientOptionsARTClientOptionsio.ably.types.ClientOptionsIO.Ably.ClientOptionsably.ClientOptions @@ -684,36 +510,6 @@ Returns a promise. On success, the promise is fulfilled with a [`BatchResult`](# - - -#### PropertiesMembersAttributesKeyword arguments - -| Parameter | Description | Type | -|-----------|-------------|------| -| keyKey:key | The full key string, as obtained from the [application dashboard](https://ably.com/dashboard). Use this option if you wish to use Basic authentication, or wish to be able to issue Ably Tokens without needing to defer to a separate entity to sign Ably TokenRequests. Read more about [Basic authentication](/docs/auth/basic) | `String` | -| tokenToken:token | An authenticated token. This can either be a [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) object, a [`TokenRequest`](/docs/api/realtime-sdk/types#token-request) object, or token string (obtained from the `token``Token` property of a [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) component of an Ably TokenRequest response, or a [JSON Web Token](https://tools.ietf.org/html/rfc7519) satisfying [the Ably requirements for JWTs](/docs/auth/token/jwt)). This option is mostly useful for testing: since tokens are short-lived, in production you almost always want to use an authentication method that allows the client library to renew the token automatically when the previous one expires, such as `authUrl`:auth_urlauth_url or `authCallback``AuthCallback``auth_callback``:auth_callback`. Read more about [Token authentication](/docs/auth/token) | `String`, `TokenDetails` or `TokenRequest` | -| authCallbackAuthCallbackauth_callback:auth_callback | A functionfunction with the form `function(tokenParams, callback(err, tokenOrTokenRequest))``TokenCallback` instancecallable (eg a lambda)proc / lambda (called synchronously in REST and Realtime but does not block EventMachine in the latter) which is called when a new token is required. The role of the callback is to obtain a fresh token, one of: an Ably Token string (in plain text format); a signed [`TokenRequest`](/docs/api/realtime-sdk/types#token-request); a [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) (in JSON format); an [Ably JWT](/docs/api/realtime-sdk/authentication#ably-jwt). See [our authentication documentation](/docs/auth) for details of the Ably TokenRequest format and associated API calls. | `Callable``TokenCallback``Proc` | -| authUrlAuthUrl:auth_urlauth_url | A URL that the library may use to obtain a fresh token, one of: an Ably Token string (in plain text format); a signed [`TokenRequest`](/docs/api/realtime-sdk/types#token-request); a [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) (in JSON format); an [Ably JWT](/docs/api/realtime-sdk/authentication#ably-jwt). For example, this can be used by a client to obtain signed Ably TokenRequests from an application server. | `String``NSURL` | -| authMethodAuthMethodauth_method:auth_method | The HTTP verb to use for the request, either `GET``:get` or `POST``:post`
_default: `GET``:get`_ | `String``Symbol` | -| authHeadersAuthHeadersauth_headers:auth_headers | A set of key value pair headers to be added to any request made to the `authUrl`. Useful when an application requires these to be added to validate the request or implement the response. If the `authHeaders` object contains an `authorization` key, then `withCredentials` will be set on the xhr request. | `Object``Dict``Hash``Associative Array``Param []``Map` | -| authParamsAuthParams:auth_paramsauth_params | A set of key value pair params to be added to any request made to the `authUrl`. When the `authMethod``AuthMethod` is `GET`, query params are added to the URL, whereas when `authMethod``AuthMethod` is `POST`, the params are sent as URL encoded form data. Useful when an application require these to be added to validate the request or implement the response. | `Object``Hash``Associative Array``Param[]``NSArray``[NSURLQueryItem]/Array``Map` | -| tokenDetailsTokenDetailstoken_details:token_details | An authenticated [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) object (most commonly obtained from an Ably Token Request response). This option is mostly useful for testing: since tokens are short-lived, in production you almost always want to use an authentication method that allows the client library to renew the token automatically when the previous one expires, such as `authUrl``AuthUrl``:auth_url``auth_url` or `authCallback`AuthCallback`auth_callback``:auth_callback`. Use this option if you wish to use Token authentication. Read more about [Token authentication](/docs/auth/token) | `TokenDetails` | -| tlsTls:tls | A boolean value, indicating whether or not a TLS ("SSL") secure connection should be used. An insecure connection cannot be used with Basic authentication as it would lead to a possible compromise of the private API key while in transit. [Find out more about TLS](https://faqs.ably.com/are-messages-sent-to-and-received-from-ably-securely-using-tls)
_default: true_ | `Boolean` | -| clientIdClientIdclient_id:client_id | A client ID, used for identifying this client when publishing messages or for presence purposes. The `clientId``client_id``ClientId` can be any non-empty string. This option is primarily intended to be used in situations where the library is instantiated with a key; note that a `clientId``client_id``ClientId` may also be implicit in a token used to instantiate the library; an error will be raised if a `clientId``client_id` specified here conflicts with the `clientId``client_id``ClientId` implicit in the token. [Find out more about client identities](/docs/auth/identified-clients) | `String` | -| useTokenAuthUseTokenAuthuse_token_auth:use_token_auth | When true, forces [Token authentication](/docs/auth/token) to be used by the library. Please note that if a `client_id``clientId` is not specified in the [`ClientOptions`](/docs/api/realtime-sdk/types#client-options) or [`TokenParams`](/docs/api/realtime-sdk/types#token-params), then the Ably Token issued will be [anonymous](https://faqs.ably.com/authenticated-and-identified-clients).
_default: false_ | `Boolean` | -| endpointEndpoint:endpoint | Enables [enterprise customers](https://ably.com/pricing) to use their own custom endpoints, which support dedicated, isolated clusters and regional message routing and storage constraints. See our [platform customization guide](/docs/platform/account/enterprise-customization) for more details.
_default: nullNullNonenil_ | `String` | -| environmentEnvironment:environment | Deprecated, use `endpoint`. Enables [enterprise customers](https://ably.com/pricing) to use their own custom environments, which support dedicated, isolated clusters and regional message routing and storage constraints. See our [platform customization guide](/docs/platform/account/enterprise-customization) for more details.
_default: nullNullNonenil_ | `String` | -| idempotentRestPublishingIdempotentRestPublishing:idempotent_rest_publishing | When true, enables idempotent publishing by assigning a unique message ID client-side, allowing the Ably servers to discard automatic publish retries following a failure such as a network fault. Enabled by default in all current Ably SDKs.
_default: true_ | `Boolean` | -| fallbackHostsFallbackHostsfallback_hosts:fallback_hosts | An array of fallback hosts to be used in the case of an error necessitating the use of an alternative host. When a custom environment is specified, the [fallback host functionality](https://faqs.ably.com/routing-around-network-and-dns-issues) is disabled. If your customer success manager has provided you with a set of custom fallback hosts, please specify them here.
_default: `[a.ably-realtime.com, b.ably-realtime.com, c.ably-realtime.com, d.ably-realtime.com, e.ably-realtime.com]`_ | `String []` | -| transportParamstransport_params:transport_params | Optional. Can be used to pass in arbitrary connection parameters, such as [`heartbeatInterval`](/docs/connect#heartbeats) and [`remainPresentFor`](/docs/presence-occupancy/presence#unstable-connections) | `Object``Dict``Hash``Associative Array``Param []``Map` | -| logLevellog_level | A number controlling the verbosity of the log output of the library. Valid values are: 0 (no logs), 1 (errors only), 2 (errors plus connection and channel state changes), 3 (high-level debug output), and 4 (full debug output). | `Integer` | -| logHandlerlog_handler | A function to handle each line of the library's log output. If `logHandler` is not specified, `console.log` is used. | `Callable` | -| transports | An optional array of transports to use, in descending order of preference. In the browser environment the available transports are: `web_socket`, `xhr_polling`. | `String[]` | -| useBinaryProtocoluse_binary_protocol | If set to true, will enable the binary protocol (MessagePack) if it is supported. It's disabled by default on browsers for performance considerations (browsers are optimized for decoding JSON). Find out more about the [benefits of binary encoding](https://faqs.ably.com/do-you-binary-encode-your-messages-for-greater-efficiency)
_default: false_ | `Boolean` | -| queryTimeQueryTime:query_timequery_time | If true, the library will query the Ably servers for the current time when [issuing TokenRequests](/docs/auth/token) instead of relying on a locally-available time of day. Knowing the time accurately is needed to create valid signed Ably [`TokenRequests`](/docs/api/rest-sdk/authentication#token-request), so this option is useful for library instances on auth servers where for some reason the server clock cannot be kept synchronized through normal means, such as an [NTP daemon](https://en.wikipedia.org/wiki/Ntpd). The server is queried for the current time once per client library instance (which stores the offset from the local clock), so if using this option you should avoid instancing a new version of the library for each request.
_default: false_ | `Boolean` | -| defaultTokenParamsdefault_token_params:default_token_paramsDefaultTokenParams | When a [`TokenParams`](/docs/api/rest-sdk/types#token-params) object is provided, it will override the client library defaults when issuing new [Ably Tokens](/docs/api/realtime-sdk/authentication#token-details) or [Ably `TokenRequests`](/docs/api/rest-sdk/authentication#token-request) | [`TokenParams`](/docs/api/rest-sdk/types#token-params) | - - #### Properties @@ -771,7 +567,6 @@ Returns a promise. On success, the promise is fulfilled with a [`BatchResult`](# | :query_time | If true, the library will query the Ably servers for the current time when [issuing TokenRequests](/docs/auth/token) instead of relying on a locally-available time of day. Knowing the time accurately is needed to create valid signed Ably [`TokenRequests`](/docs/api/rest-sdk/authentication#token-request), so this option is useful for library instances on auth servers where for some reason the server clock cannot be kept synchronized through normal means, such as an [NTP daemon](https://en.wikipedia.org/wiki/Ntpd). The server is queried for the current time once per client library instance (which stores the offset from the local clock), so if using this option you should avoid instancing a new version of the library for each request.
_default: false_ | `Boolean` | | :default_token_params | When a [`TokenParams`](/docs/api/rest-sdk/types#token-params) object is provided, it will override the client library defaults when issuing new [Ably Tokens](/docs/api/realtime-sdk/authentication#token-details) or [Ably `TokenRequests`](/docs/api/rest-sdk/authentication#token-request) | [`TokenParams`](/docs/api/rest-sdk/types#token-params) | - @@ -779,25 +574,25 @@ Returns a promise. On success, the promise is fulfilled with a [`BatchResult`](# | Parameter | Description | Type | |-----------|-------------|------| -| keyKey:key | The full key string, as obtained from the [application dashboard](https://ably.com/dashboard). Use this option if you wish to use Basic authentication, or wish to be able to issue Ably Tokens without needing to defer to a separate entity to sign Ably TokenRequests. Read more about [Basic authentication](/docs/auth/basic) | `String` | -| tokenToken:token | An authenticated token. This can either be a [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) object, a [`TokenRequest`](/docs/api/realtime-sdk/types#token-request) object, or token string (obtained from the `token``Token` property of a [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) component of an Ably TokenRequest response, or a [JSON Web Token](https://tools.ietf.org/html/rfc7519) satisfying [the Ably requirements for JWTs](/docs/auth/token/jwt)). This option is mostly useful for testing: since tokens are short-lived, in production you almost always want to use an authentication method that allows the client library to renew the token automatically when the previous one expires, such as `authUrl`:auth_urlauth_url or `authCallback``AuthCallback``auth_callback``:auth_callback`. Read more about [Token authentication](/docs/auth/token) | `String`, `TokenDetails` or `TokenRequest` | -| authCallbackAuthCallbackauth_callback:auth_callback | A functionfunction with the form `function(tokenParams, callback(err, tokenOrTokenRequest))``TokenCallback` instancecallable (eg a lambda)proc / lambda (called synchronously in REST and Realtime but does not block EventMachine in the latter) which is called when a new token is required. The role of the callback is to obtain a fresh token, one of: an Ably Token string (in plain text format); a signed [`TokenRequest`](/docs/api/realtime-sdk/types#token-request); a [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) (in JSON format); an [Ably JWT](/docs/api/realtime-sdk/authentication#ably-jwt). See [our authentication documentation](/docs/auth) for details of the Ably TokenRequest format and associated API calls. | `Callable``TokenCallback``Proc` | -| authUrlAuthUrl:auth_urlauth_url | A URL that the library may use to obtain a fresh token, one of: an Ably Token string (in plain text format); a signed [`TokenRequest`](/docs/api/realtime-sdk/types#token-request); a [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) (in JSON format); an [Ably JWT](/docs/api/realtime-sdk/authentication#ably-jwt). For example, this can be used by a client to obtain signed Ably TokenRequests from an application server. | `String``NSURL` | -| authMethodAuthMethodauth_method:auth_method | The HTTP verb to use for the request, either `GET``:get` or `POST``:post`
_default: `GET``:get`_ | `String``Symbol` | -| authHeadersAuthHeadersauth_headers:auth_headers | A set of key value pair headers to be added to any request made to the `authUrl`. Useful when an application requires these to be added to validate the request or implement the response. If the `authHeaders` object contains an `authorization` key, then `withCredentials` will be set on the xhr request. | `Object``Dict``Hash``Associative Array``Param []``Map` | -| authParamsAuthParams:auth_paramsauth_params | A set of key value pair params to be added to any request made to the `authUrl`. When the `authMethod``AuthMethod` is `GET`, query params are added to the URL, whereas when `authMethod``AuthMethod` is `POST`, the params are sent as URL encoded form data. Useful when an application require these to be added to validate the request or implement the response. | `Object``Hash``Associative Array``Param[]``NSArray``[NSURLQueryItem]/Array``Map` | -| tokenDetailsTokenDetailstoken_details:token_details | An authenticated [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) object (most commonly obtained from an Ably Token Request response). This option is mostly useful for testing: since tokens are short-lived, in production you almost always want to use an authentication method that allows the client library to renew the token automatically when the previous one expires, such as `authUrl``AuthUrl``:auth_url``auth_url` or `authCallback`AuthCallback`auth_callback``:auth_callback`. Use this option if you wish to use Token authentication. Read more about [Token authentication](/docs/auth/token) | `TokenDetails` | -| tlsTls:tls | A boolean value, indicating whether or not a TLS ("SSL") secure connection should be used. An insecure connection cannot be used with Basic authentication as it would lead to a possible compromise of the private API key while in transit. [Find out more about TLS](https://faqs.ably.com/are-messages-sent-to-and-received-from-ably-securely-using-tls)
_default: true_ | `Boolean` | -| clientIdClientIdclient_id:client_id | A client ID, used for identifying this client when publishing messages or for presence purposes. The `clientId``client_id``ClientId` can be any non-empty string. This option is primarily intended to be used in situations where the library is instantiated with a key; note that a `clientId``client_id``ClientId` may also be implicit in a token used to instantiate the library; an error will be raised if a `clientId``client_id` specified here conflicts with the `clientId``client_id``ClientId` implicit in the token. [Find out more about client identities](/docs/auth/identified-clients) | `String` | -| useTokenAuthUseTokenAuthuse_token_auth:use_token_auth | When true, forces [Token authentication](/docs/auth/token) to be used by the library. Please note that if a `client_id``clientId` is not specified in the [`ClientOptions`](/docs/api/realtime-sdk/types#client-options) or [`TokenParams`](/docs/api/realtime-sdk/types#token-params), then the Ably Token issued will be [anonymous](https://faqs.ably.com/authenticated-and-identified-clients).
_default: false_ | `Boolean` | -| endpointEndpoint:endpoint | Enables [enterprise customers](https://ably.com/pricing) to use their own custom endpoints, which support dedicated, isolated clusters and regional message routing and storage constraints. See our [platform customization guide](/docs/platform/account/enterprise-customization) for more details.
_default: nullNullNonenil_ | `String` | -| environmentEnvironment:environment | Deprecated, use `endpoint`. Enables [enterprise customers](https://ably.com/pricing) to use their own custom environments, which support dedicated, isolated clusters and regional message routing and storage constraints. See our [platform customization guide](/docs/platform/account/enterprise-customization) for more details.
_default: nullNullNonenil_ | `String` | -| idempotentRestPublishingIdempotentRestPublishing:idempotent_rest_publishing | When true, enables idempotent publishing by assigning a unique message ID client-side, allowing the Ably servers to discard automatic publish retries following a failure such as a network fault. Enabled by default in all current Ably SDKs.
_default: true_ | `Boolean` | -| fallbackHostsFallbackHostsfallback_hosts:fallback_hosts | An array of fallback hosts to be used in the case of an error necessitating the use of an alternative host. When a custom environment is specified, the [fallback host functionality](https://faqs.ably.com/routing-around-network-and-dns-issues) is disabled. If your customer success manager has provided you with a set of custom fallback hosts, please specify them here.
_default: `[a.ably-realtime.com, b.ably-realtime.com, c.ably-realtime.com, d.ably-realtime.com, e.ably-realtime.com]`_ | `String []` | -| transportParamstransport_params:transport_params | Optional. Can be used to pass in arbitrary connection parameters, such as [`heartbeatInterval`](/docs/connect#heartbeats) and [`remainPresentFor`](/docs/presence-occupancy/presence#unstable-connections) | `Object``Dict``Hash``Associative Array``Param []``Map` | -| useBinaryProtocoluse_binary_protocol | If set to true, will enable the binary protocol (MessagePack) if it is supported. It's disabled by default on browsers for performance considerations (browsers are optimized for decoding JSON). Find out more about the [benefits of binary encoding](https://faqs.ably.com/do-you-binary-encode-your-messages-for-greater-efficiency)
_default: false_ | `Boolean` | -| queryTimeQueryTime:query_timequery_time | If true, the library will query the Ably servers for the current time when [issuing TokenRequests](/docs/auth/token) instead of relying on a locally-available time of day. Knowing the time accurately is needed to create valid signed Ably [`TokenRequests`](/docs/api/rest-sdk/authentication#token-request), so this option is useful for library instances on auth servers where for some reason the server clock cannot be kept synchronized through normal means, such as an [NTP daemon](https://en.wikipedia.org/wiki/Ntpd). The server is queried for the current time once per client library instance (which stores the offset from the local clock), so if using this option you should avoid instancing a new version of the library for each request.
_default: false_ | `Boolean` | -| defaultTokenParamsdefault_token_params:default_token_paramsDefaultTokenParams | When a [`TokenParams`](/docs/api/rest-sdk/types#token-params) object is provided, it will override the client library defaults when issuing new [Ably Tokens](/docs/api/realtime-sdk/authentication#token-details) or [Ably `TokenRequests`](/docs/api/rest-sdk/authentication#token-request) | [`TokenParams`](/docs/api/rest-sdk/types#token-params) | +| keyKey:key | The full key string, as obtained from the [application dashboard](https://ably.com/dashboard). Use this option if you wish to use Basic authentication, or wish to be able to issue Ably Tokens without needing to defer to a separate entity to sign Ably TokenRequests. Read more about [Basic authentication](/docs/auth/basic) | `String` | +| tokenToken:token | An authenticated token. This can either be a [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) object, a [`TokenRequest`](/docs/api/realtime-sdk/types#token-request) object, or token string (obtained from the `token``Token` property of a [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) component of an Ably TokenRequest response, or a [JSON Web Token](https://tools.ietf.org/html/rfc7519) satisfying [the Ably requirements for JWTs](/docs/auth/token/jwt)). This option is mostly useful for testing: since tokens are short-lived, in production you almost always want to use an authentication method that allows the client library to renew the token automatically when the previous one expires, such as `authUrl`:auth_urlauth_url or `authCallback``AuthCallback``auth_callback``:auth_callback`. Read more about [Token authentication](/docs/auth/token) | `String`, `TokenDetails` or `TokenRequest` | +| authCallbackAuthCallbackauth_callback:auth_callback | A function`TokenCallback` instancecallable (eg a lambda)proc / lambda (called synchronously in REST and Realtime but does not block EventMachine in the latter) which is called when a new token is required. The role of the callback is to obtain a fresh token, one of: an Ably Token string (in plain text format); a signed [`TokenRequest`](/docs/api/realtime-sdk/types#token-request); a [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) (in JSON format); an [Ably JWT](/docs/api/realtime-sdk/authentication#ably-jwt). See [our authentication documentation](/docs/auth) for details of the Ably TokenRequest format and associated API calls. | `Callable``TokenCallback``Proc` | +| authUrlAuthUrl:auth_urlauth_url | A URL that the library may use to obtain a fresh token, one of: an Ably Token string (in plain text format); a signed [`TokenRequest`](/docs/api/realtime-sdk/types#token-request); a [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) (in JSON format); an [Ably JWT](/docs/api/realtime-sdk/authentication#ably-jwt). For example, this can be used by a client to obtain signed Ably TokenRequests from an application server. | `String``NSURL` | +| authMethodAuthMethodauth_method:auth_method | The HTTP verb to use for the request, either `GET``:get` or `POST``:post`
_default: `GET``:get`_ | `String``Symbol` | +| authHeadersAuthHeadersauth_headers:auth_headers | A set of key value pair headers to be added to any request made to the `authUrl`. Useful when an application requires these to be added to validate the request or implement the response. | `Object``Dict``Hash``Associative Array``Param []``Map` | +| authParamsAuthParams:auth_paramsauth_params | A set of key value pair params to be added to any request made to the `authUrl`. When the `authMethod``AuthMethod` is `GET`, query params are added to the URL, whereas when `authMethod``AuthMethod` is `POST`, the params are sent as URL encoded form data. Useful when an application require these to be added to validate the request or implement the response. | `Object``Hash``Associative Array``Param[]``NSArray``[NSURLQueryItem]/Array``Map` | +| tokenDetailsTokenDetailstoken_details:token_details | An authenticated [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) object (most commonly obtained from an Ably Token Request response). This option is mostly useful for testing: since tokens are short-lived, in production you almost always want to use an authentication method that allows the client library to renew the token automatically when the previous one expires, such as `authUrl``AuthUrl``:auth_url``auth_url` or `authCallback`AuthCallback`auth_callback``:auth_callback`. Use this option if you wish to use Token authentication. Read more about [Token authentication](/docs/auth/token) | `TokenDetails` | +| tlsTls:tls | A boolean value, indicating whether or not a TLS ("SSL") secure connection should be used. An insecure connection cannot be used with Basic authentication as it would lead to a possible compromise of the private API key while in transit. [Find out more about TLS](https://faqs.ably.com/are-messages-sent-to-and-received-from-ably-securely-using-tls)
_default: true_ | `Boolean` | +| clientIdClientIdclient_id:client_id | A client ID, used for identifying this client when publishing messages or for presence purposes. The `clientId``client_id``ClientId` can be any non-empty string. This option is primarily intended to be used in situations where the library is instantiated with a key; note that a `clientId``client_id``ClientId` may also be implicit in a token used to instantiate the library; an error will be raised if a `clientId``client_id` specified here conflicts with the `clientId``client_id``ClientId` implicit in the token. [Find out more about client identities](/docs/auth/identified-clients) | `String` | +| useTokenAuthUseTokenAuthuse_token_auth:use_token_auth | When true, forces [Token authentication](/docs/auth/token) to be used by the library. Please note that if a `client_id``clientId` is not specified in the [`ClientOptions`](/docs/api/realtime-sdk/types#client-options) or [`TokenParams`](/docs/api/realtime-sdk/types#token-params), then the Ably Token issued will be [anonymous](https://faqs.ably.com/authenticated-and-identified-clients).
_default: false_ | `Boolean` | +| endpointEndpoint:endpoint | Enables [enterprise customers](https://ably.com/pricing) to use their own custom endpoints, which support dedicated, isolated clusters and regional message routing and storage constraints. See our [platform customization guide](/docs/platform/account/enterprise-customization) for more details.
_default: nullNullNonenil_ | `String` | +| environmentEnvironment:environment | Deprecated, use `endpoint`. Enables [enterprise customers](https://ably.com/pricing) to use their own custom environments, which support dedicated, isolated clusters and regional message routing and storage constraints. See our [platform customization guide](/docs/platform/account/enterprise-customization) for more details.
_default: nullNullNonenil_ | `String` | +| idempotentRestPublishingIdempotentRestPublishing:idempotent_rest_publishing | When true, enables idempotent publishing by assigning a unique message ID client-side, allowing the Ably servers to discard automatic publish retries following a failure such as a network fault. Enabled by default in all current Ably SDKs.
_default: true_ | `Boolean` | +| fallbackHostsFallbackHostsfallback_hosts:fallback_hosts | An array of fallback hosts to be used in the case of an error necessitating the use of an alternative host. When a custom environment is specified, the [fallback host functionality](https://faqs.ably.com/routing-around-network-and-dns-issues) is disabled. If your customer success manager has provided you with a set of custom fallback hosts, please specify them here.
_default: `[a.ably-realtime.com, b.ably-realtime.com, c.ably-realtime.com, d.ably-realtime.com, e.ably-realtime.com]`_ | `String []` | +| transportParamstransport_params:transport_params | Optional. Can be used to pass in arbitrary connection parameters, such as [`heartbeatInterval`](/docs/connect#heartbeats) and [`remainPresentFor`](/docs/presence-occupancy/presence#unstable-connections) | `Object``Dict``Hash``Associative Array``Param []``Map` | +| useBinaryProtocoluse_binary_protocol | If set to true, will enable the binary protocol (MessagePack) if it is supported. It's disabled by default on browsers for performance considerations (browsers are optimized for decoding JSON). Find out more about the [benefits of binary encoding](https://faqs.ably.com/do-you-binary-encode-your-messages-for-greater-efficiency)
_default: false_ | `Boolean` | +| queryTimeQueryTime:query_timequery_time | If true, the library will query the Ably servers for the current time when [issuing TokenRequests](/docs/auth/token) instead of relying on a locally-available time of day. Knowing the time accurately is needed to create valid signed Ably [`TokenRequests`](/docs/api/rest-sdk/authentication#token-request), so this option is useful for library instances on auth servers where for some reason the server clock cannot be kept synchronized through normal means, such as an [NTP daemon](https://en.wikipedia.org/wiki/Ntpd). The server is queried for the current time once per client library instance (which stores the offset from the local clock), so if using this option you should avoid instancing a new version of the library for each request.
_default: false_ | `Boolean` | +| defaultTokenParamsdefault_token_params:default_token_paramsDefaultTokenParams | When a [`TokenParams`](/docs/api/rest-sdk/types#token-params) object is provided, it will override the client library defaults when issuing new [Ably Tokens](/docs/api/realtime-sdk/authentication#token-details) or [Ably `TokenRequests`](/docs/api/rest-sdk/authentication#token-request) | [`TokenParams`](/docs/api/rest-sdk/types#token-params) | @@ -806,27 +601,27 @@ Returns a promise. On success, the promise is fulfilled with a [`BatchResult`](# | Parameter | Description | Type | |-----------|-------------|------| -| keyKey:key | The full key string, as obtained from the [application dashboard](https://ably.com/dashboard). Use this option if you wish to use Basic authentication, or wish to be able to issue Ably Tokens without needing to defer to a separate entity to sign Ably TokenRequests. Read more about [Basic authentication](/docs/auth/basic) | `String` | -| tokenToken:token | An authenticated token. This can either be a [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) object, a [`TokenRequest`](/docs/api/realtime-sdk/types#token-request) object, or token string (obtained from the `token``Token` property of a [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) component of an Ably TokenRequest response, or a [JSON Web Token](https://tools.ietf.org/html/rfc7519) satisfying [the Ably requirements for JWTs](/docs/auth/token/jwt)). This option is mostly useful for testing: since tokens are short-lived, in production you almost always want to use an authentication method that allows the client library to renew the token automatically when the previous one expires, such as `authUrl`:auth_urlauth_url or `authCallback``AuthCallback``auth_callback``:auth_callback`. Read more about [Token authentication](/docs/auth/token) | `String`, `TokenDetails` or `TokenRequest` | -| authCallbackAuthCallbackauth_callback:auth_callback | A functionfunction with the form `function(tokenParams, callback(err, tokenOrTokenRequest))``TokenCallback` instancecallable (eg a lambda)proc / lambda (called synchronously in REST and Realtime but does not block EventMachine in the latter) which is called when a new token is required. The role of the callback is to obtain a fresh token, one of: an Ably Token string (in plain text format); a signed [`TokenRequest`](/docs/api/realtime-sdk/types#token-request); a [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) (in JSON format); an [Ably JWT](/docs/api/realtime-sdk/authentication#ably-jwt). See [our authentication documentation](/docs/auth) for details of the Ably TokenRequest format and associated API calls. | `Callable``TokenCallback``Proc` | -| authUrlAuthUrl:auth_urlauth_url | A URL that the library may use to obtain a fresh token, one of: an Ably Token string (in plain text format); a signed [`TokenRequest`](/docs/api/realtime-sdk/types#token-request); a [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) (in JSON format); an [Ably JWT](/docs/api/realtime-sdk/authentication#ably-jwt). For example, this can be used by a client to obtain signed Ably TokenRequests from an application server. | `String``NSURL` | -| authMethodAuthMethodauth_method:auth_method | The HTTP verb to use for the request, either `GET``:get` or `POST``:post`
_default: `GET``:get`_ | `String``Symbol` | -| authHeadersAuthHeadersauth_headers:auth_headers | A set of key value pair headers to be added to any request made to the `authUrl`. Useful when an application requires these to be added to validate the request or implement the response. If the `authHeaders` object contains an `authorization` key, then `withCredentials` will be set on the xhr request. | `Object``Dict``Hash``Associative Array``Param []``Map` | -| authParamsAuthParams:auth_paramsauth_params | A set of key value pair params to be added to any request made to the `authUrl`. When the `authMethod``AuthMethod` is `GET`, query params are added to the URL, whereas when `authMethod``AuthMethod` is `POST`, the params are sent as URL encoded form data. Useful when an application require these to be added to validate the request or implement the response. | `Object``Hash``Associative Array``Param[]``NSArray``[NSURLQueryItem]/Array``Map` | -| tokenDetailsTokenDetailstoken_details:token_details | An authenticated [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) object (most commonly obtained from an Ably Token Request response). This option is mostly useful for testing: since tokens are short-lived, in production you almost always want to use an authentication method that allows the client library to renew the token automatically when the previous one expires, such as `authUrl``AuthUrl``:auth_url``auth_url` or `authCallback`AuthCallback`auth_callback``:auth_callback`. Use this option if you wish to use Token authentication. Read more about [Token authentication](/docs/auth/token) | `TokenDetails` | -| tlsTls:tls | A boolean value, indicating whether or not a TLS ("SSL") secure connection should be used. An insecure connection cannot be used with Basic authentication as it would lead to a possible compromise of the private API key while in transit. [Find out more about TLS](https://faqs.ably.com/are-messages-sent-to-and-received-from-ably-securely-using-tls)
_default: true_ | `Boolean` | -| clientIdClientIdclient_id:client_id | A client ID, used for identifying this client when publishing messages or for presence purposes. The `clientId``client_id``ClientId` can be any non-empty string. This option is primarily intended to be used in situations where the library is instantiated with a key; note that a `clientId``client_id``ClientId` may also be implicit in a token used to instantiate the library; an error will be raised if a `clientId``client_id` specified here conflicts with the `clientId``client_id``ClientId` implicit in the token. [Find out more about client identities](/docs/auth/identified-clients) | `String` | -| useTokenAuthUseTokenAuthuse_token_auth:use_token_auth | When true, forces [Token authentication](/docs/auth/token) to be used by the library. Please note that if a `client_id``clientId` is not specified in the [`ClientOptions`](/docs/api/realtime-sdk/types#client-options) or [`TokenParams`](/docs/api/realtime-sdk/types#token-params), then the Ably Token issued will be [anonymous](https://faqs.ably.com/authenticated-and-identified-clients).
_default: false_ | `Boolean` | -| endpointEndpoint:endpoint | Enables [enterprise customers](https://ably.com/pricing) to use their own custom endpoints, which support dedicated, isolated clusters and regional message routing and storage constraints. See our [platform customization guide](/docs/platform/account/enterprise-customization) for more details.
_default: nullNullNonenil_ | `String` | -| environmentEnvironment:environment | Deprecated, use `endpoint`. Enables [enterprise customers](https://ably.com/pricing) to use their own custom environments, which support dedicated, isolated clusters and regional message routing and storage constraints. See our [platform customization guide](/docs/platform/account/enterprise-customization) for more details.
_default: nullNullNonenil_ | `String` | -| idempotentRestPublishingIdempotentRestPublishing:idempotent_rest_publishing | When true, enables idempotent publishing by assigning a unique message ID client-side, allowing the Ably servers to discard automatic publish retries following a failure such as a network fault. Enabled by default in all current Ably SDKs.
_default: true_ | `Boolean` | -| fallbackHostsFallbackHostsfallback_hosts:fallback_hosts | An array of fallback hosts to be used in the case of an error necessitating the use of an alternative host. When a custom environment is specified, the [fallback host functionality](https://faqs.ably.com/routing-around-network-and-dns-issues) is disabled. If your customer success manager has provided you with a set of custom fallback hosts, please specify them here.
_default: `[a.ably-realtime.com, b.ably-realtime.com, c.ably-realtime.com, d.ably-realtime.com, e.ably-realtime.com]`_ | `String []` | -| transportParamstransport_params:transport_params | Optional. Can be used to pass in arbitrary connection parameters, such as [`heartbeatInterval`](/docs/connect#heartbeats) and [`remainPresentFor`](/docs/presence-occupancy/presence#unstable-connections) | `Object``Dict``Hash``Associative Array``Param []``Map` | -| logLevellog_level | A number controlling the verbosity of the log output of the library. Valid values are: 0 (no logs), 1 (errors only), 2 (errors plus connection and channel state changes), 3 (high-level debug output), and 4 (full debug output). | `Integer` | -| logHandlerlog_handler | A function to handle each line of the library's log output. If `logHandler` is not specified, `console.log` is used. | `Callable` | -| useBinaryProtocoluse_binary_protocol | If set to true, will enable the binary protocol (MessagePack) if it is supported. It's disabled by default on browsers for performance considerations (browsers are optimized for decoding JSON). Find out more about the [benefits of binary encoding](https://faqs.ably.com/do-you-binary-encode-your-messages-for-greater-efficiency)
_default: false_ | `Boolean` | -| queryTimeQueryTime:query_timequery_time | If true, the library will query the Ably servers for the current time when [issuing TokenRequests](/docs/auth/token) instead of relying on a locally-available time of day. Knowing the time accurately is needed to create valid signed Ably [`TokenRequests`](/docs/api/rest-sdk/authentication#token-request), so this option is useful for library instances on auth servers where for some reason the server clock cannot be kept synchronized through normal means, such as an [NTP daemon](https://en.wikipedia.org/wiki/Ntpd). The server is queried for the current time once per client library instance (which stores the offset from the local clock), so if using this option you should avoid instancing a new version of the library for each request.
_default: false_ | `Boolean` | -| defaultTokenParamsdefault_token_params:default_token_paramsDefaultTokenParams | When a [`TokenParams`](/docs/api/rest-sdk/types#token-params) object is provided, it will override the client library defaults when issuing new [Ably Tokens](/docs/api/realtime-sdk/authentication#token-details) or [Ably `TokenRequests`](/docs/api/rest-sdk/authentication#token-request) | [`TokenParams`](/docs/api/rest-sdk/types#token-params) | +| keyKey:key | The full key string, as obtained from the [application dashboard](https://ably.com/dashboard). Use this option if you wish to use Basic authentication, or wish to be able to issue Ably Tokens without needing to defer to a separate entity to sign Ably TokenRequests. Read more about [Basic authentication](/docs/auth/basic) | `String` | +| tokenToken:token | An authenticated token. This can either be a [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) object, a [`TokenRequest`](/docs/api/realtime-sdk/types#token-request) object, or token string (obtained from the `token``Token` property of a [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) component of an Ably TokenRequest response, or a [JSON Web Token](https://tools.ietf.org/html/rfc7519) satisfying [the Ably requirements for JWTs](/docs/auth/token/jwt)). This option is mostly useful for testing: since tokens are short-lived, in production you almost always want to use an authentication method that allows the client library to renew the token automatically when the previous one expires, such as `authUrl`:auth_urlauth_url or `authCallback``AuthCallback``auth_callback``:auth_callback`. Read more about [Token authentication](/docs/auth/token) | `String`, `TokenDetails` or `TokenRequest` | +| authCallbackAuthCallbackauth_callback:auth_callback | A function`TokenCallback` instancecallable (eg a lambda)proc / lambda (called synchronously in REST and Realtime but does not block EventMachine in the latter) which is called when a new token is required. The role of the callback is to obtain a fresh token, one of: an Ably Token string (in plain text format); a signed [`TokenRequest`](/docs/api/realtime-sdk/types#token-request); a [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) (in JSON format); an [Ably JWT](/docs/api/realtime-sdk/authentication#ably-jwt). See [our authentication documentation](/docs/auth) for details of the Ably TokenRequest format and associated API calls. | `Callable``TokenCallback``Proc` | +| authUrlAuthUrl:auth_urlauth_url | A URL that the library may use to obtain a fresh token, one of: an Ably Token string (in plain text format); a signed [`TokenRequest`](/docs/api/realtime-sdk/types#token-request); a [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) (in JSON format); an [Ably JWT](/docs/api/realtime-sdk/authentication#ably-jwt). For example, this can be used by a client to obtain signed Ably TokenRequests from an application server. | `String``NSURL` | +| authMethodAuthMethodauth_method:auth_method | The HTTP verb to use for the request, either `GET``:get` or `POST``:post`
_default: `GET``:get`_ | `String``Symbol` | +| authHeadersAuthHeadersauth_headers:auth_headers | A set of key value pair headers to be added to any request made to the `authUrl`. Useful when an application requires these to be added to validate the request or implement the response. | `Object``Dict``Hash``Associative Array``Param []``Map` | +| authParamsAuthParams:auth_paramsauth_params | A set of key value pair params to be added to any request made to the `authUrl`. When the `authMethod``AuthMethod` is `GET`, query params are added to the URL, whereas when `authMethod``AuthMethod` is `POST`, the params are sent as URL encoded form data. Useful when an application require these to be added to validate the request or implement the response. | `Object``Hash``Associative Array``Param[]``NSArray``[NSURLQueryItem]/Array``Map` | +| tokenDetailsTokenDetailstoken_details:token_details | An authenticated [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) object (most commonly obtained from an Ably Token Request response). This option is mostly useful for testing: since tokens are short-lived, in production you almost always want to use an authentication method that allows the client library to renew the token automatically when the previous one expires, such as `authUrl``AuthUrl``:auth_url``auth_url` or `authCallback`AuthCallback`auth_callback``:auth_callback`. Use this option if you wish to use Token authentication. Read more about [Token authentication](/docs/auth/token) | `TokenDetails` | +| tlsTls:tls | A boolean value, indicating whether or not a TLS ("SSL") secure connection should be used. An insecure connection cannot be used with Basic authentication as it would lead to a possible compromise of the private API key while in transit. [Find out more about TLS](https://faqs.ably.com/are-messages-sent-to-and-received-from-ably-securely-using-tls)
_default: true_ | `Boolean` | +| clientIdClientIdclient_id:client_id | A client ID, used for identifying this client when publishing messages or for presence purposes. The `clientId``client_id``ClientId` can be any non-empty string. This option is primarily intended to be used in situations where the library is instantiated with a key; note that a `clientId``client_id``ClientId` may also be implicit in a token used to instantiate the library; an error will be raised if a `clientId``client_id` specified here conflicts with the `clientId``client_id``ClientId` implicit in the token. [Find out more about client identities](/docs/auth/identified-clients) | `String` | +| useTokenAuthUseTokenAuthuse_token_auth:use_token_auth | When true, forces [Token authentication](/docs/auth/token) to be used by the library. Please note that if a `client_id``clientId` is not specified in the [`ClientOptions`](/docs/api/realtime-sdk/types#client-options) or [`TokenParams`](/docs/api/realtime-sdk/types#token-params), then the Ably Token issued will be [anonymous](https://faqs.ably.com/authenticated-and-identified-clients).
_default: false_ | `Boolean` | +| endpointEndpoint:endpoint | Enables [enterprise customers](https://ably.com/pricing) to use their own custom endpoints, which support dedicated, isolated clusters and regional message routing and storage constraints. See our [platform customization guide](/docs/platform/account/enterprise-customization) for more details.
_default: nullNullNonenil_ | `String` | +| environmentEnvironment:environment | Deprecated, use `endpoint`. Enables [enterprise customers](https://ably.com/pricing) to use their own custom environments, which support dedicated, isolated clusters and regional message routing and storage constraints. See our [platform customization guide](/docs/platform/account/enterprise-customization) for more details.
_default: nullNullNonenil_ | `String` | +| idempotentRestPublishingIdempotentRestPublishing:idempotent_rest_publishing | When true, enables idempotent publishing by assigning a unique message ID client-side, allowing the Ably servers to discard automatic publish retries following a failure such as a network fault. Enabled by default in all current Ably SDKs.
_default: true_ | `Boolean` | +| fallbackHostsFallbackHostsfallback_hosts:fallback_hosts | An array of fallback hosts to be used in the case of an error necessitating the use of an alternative host. When a custom environment is specified, the [fallback host functionality](https://faqs.ably.com/routing-around-network-and-dns-issues) is disabled. If your customer success manager has provided you with a set of custom fallback hosts, please specify them here.
_default: `[a.ably-realtime.com, b.ably-realtime.com, c.ably-realtime.com, d.ably-realtime.com, e.ably-realtime.com]`_ | `String []` | +| transportParamstransport_params:transport_params | Optional. Can be used to pass in arbitrary connection parameters, such as [`heartbeatInterval`](/docs/connect#heartbeats) and [`remainPresentFor`](/docs/presence-occupancy/presence#unstable-connections) | `Object``Dict``Hash``Associative Array``Param []``Map` | +| logLevellog_level | A number controlling the verbosity of the log output of the library. Valid values are: 0 (no logs), 1 (errors only), 2 (errors plus connection and channel state changes), 3 (high-level debug output), and 4 (full debug output). | `Integer` | +| logHandlerlog_handler | A function to handle each line of the library's log output. If `logHandler` is not specified, `console.log` is used. | `Callable` | +| useBinaryProtocoluse_binary_protocol | If set to true, will enable the binary protocol (MessagePack) if it is supported. It's disabled by default on browsers for performance considerations (browsers are optimized for decoding JSON). Find out more about the [benefits of binary encoding](https://faqs.ably.com/do-you-binary-encode-your-messages-for-greater-efficiency)
_default: false_ | `Boolean` | +| queryTimeQueryTime:query_timequery_time | If true, the library will query the Ably servers for the current time when [issuing TokenRequests](/docs/auth/token) instead of relying on a locally-available time of day. Knowing the time accurately is needed to create valid signed Ably [`TokenRequests`](/docs/api/rest-sdk/authentication#token-request), so this option is useful for library instances on auth servers where for some reason the server clock cannot be kept synchronized through normal means, such as an [NTP daemon](https://en.wikipedia.org/wiki/Ntpd). The server is queried for the current time once per client library instance (which stores the offset from the local clock), so if using this option you should avoid instancing a new version of the library for each request.
_default: false_ | `Boolean` | +| defaultTokenParamsdefault_token_params:default_token_paramsDefaultTokenParams | When a [`TokenParams`](/docs/api/rest-sdk/types#token-params) object is provided, it will override the client library defaults when issuing new [Ably Tokens](/docs/api/realtime-sdk/authentication#token-details) or [Ably `TokenRequests`](/docs/api/rest-sdk/authentication#token-request) | [`TokenParams`](/docs/api/rest-sdk/types#token-params) | @@ -857,7 +652,6 @@ Returns a promise. On success, the promise is fulfilled with a [`BatchResult`](# - #### Properties @@ -888,7 +682,7 @@ Returns a promise. On success, the promise is fulfilled with a [`BatchResult`](# -### Stats object ARTStats io.ably.lib.types.Stats Ably::Models::Stats Ably\Models\Stats IO.Ably.Stats +### Stats object ARTStats io.ably.lib.types.Stats Ably::Models::Stats Ably\Models\Stats IO.Ably.Stats A `Stats` object represents an application's statistics for the specified interval and time period. Ably aggregates statistics globally for all accounts and applications, and makes these available both through our [statistics API](/docs/metadata-stats/stats) as well as your [application dashboard](https://ably.com/dashboard). @@ -896,8 +690,7 @@ A `Stats` object represents an application's statistics for the specified interv Please note that most attributes of the `Stats` type below contain references to further stats types. This documentation is not exhaustive for all stats types, and as such, links to the stats types below will take you to the [Ruby library stats documentation](https://www.rubydoc.info/gems/ably/Ably/Models/Stats) which contains exhaustive stats documentation. Ruby and Python however uses `under_score` case instead of the default `camelCase` in most languages, so please bear that in mind. - -#### PropertiesMembersAttributesKeyword arguments +#### PropertiesMembersAttributesKeyword arguments @@ -955,55 +748,9 @@ Please note that most attributes of the `Stats` type below contain references to - - -| Parameter | Description | Type | -|-----------|-------------|------| -| appId | The ID of the Ably application the statistics relate to. | `String` | -| entries | The statistics for the requested time interval and time period. The `schema` property provides further information | `Partial>` | -| inProgress | Optional. For entires that are still in progress, such as the current month, the last sub-interval included in the stats entry. In the format `yyyy-mm-dd:hh:mm:ss` | `String` | -| intervalId | The UTC time period that the stats coverage begins at. If `unit` was requested as `minute` this will be in the format `YYYY-mm-dd:HH:MM`, if `hour` it will be `YYYY-mm-dd:HH`, if `day` it will be `YYYY-mm-dd:00` and if `month` it will be `YYYY-mm-01:00` | `String` | -| schema | The URL of a JSON schema describing the structure of the `Stats` object | `String` | - - + - - -### ARTStatsGranularityStatsIntervalGranularityStatsIntervalGranularity - - - -`StatsIntervalGranularity` is an enum specifying the granularity of a [Stats interval](/docs/api/rest-sdk/statistics#stats-type). - - - - -```javascript -const StatsIntervalGranularity = [ - 'minute', - 'hour', - 'day', - 'month' -] -``` - - - - - - -```nodejs -const StatsIntervalGranularity = [ - 'minute', - 'hour', - 'day', - 'month' -] -``` - - - - +### ARTStatsGranularityStatsIntervalGranularity @@ -1063,18 +810,18 @@ public enum StatsIntervalGranularity An `HttpPaginatedResponse` is a superset of [PaginatedResult](/docs/api/rest-sdk/types#paginated-result), which is a type that represents a page of results plus metadata indicating the relative queries available to it. `HttpPaginatedResponse` additionally carries information about the response to an HTTP request. It is used when [making custom HTTP requests](/docs/api/rest-sdk#request). -#### PropertiesMembersAttributes +#### PropertiesMembersAttributes | Property | Description | Type | |----------|-------------|------| -| itemsItemsitems | Contains a page of results; for example, an array of [Message](#message) or [PresenceMessage](#presence-message) objects for a channel history request | `Array<>``List<>` | -| statusCodestatus_codeStatusCode | The HTTP status code of the response | `Number` | -| successSuccess | Whether the HTTP status code indicates success. This is equivalent to `200 <= statusCode < 300``200 <= status_code < 300``200 <= StatusCode < 300` | `Boolean` | -| headersHeaders | The headers of the response | `Object` | -| errorCodeerror_codeErrorCode | The error code if the `X-Ably-Errorcode` HTTP header is sent in the response | `Number``Int` | -| errorMessageerror_messageErrorMessage | The error message if the `X-Ably-Errormessage` HTTP header is sent in the response | `String` | +| itemsItemsitems | Contains a page of results; for example, an array of [Message](#message) or [PresenceMessage](#presence-message) objects for a channel history request | `Array<>``List<>` | +| statusCodestatus_codeStatusCode | The HTTP status code of the response | `Number` | +| successSuccess | Whether the HTTP status code indicates success. This is equivalent to `200 <= statusCode < 300``200 <= status_code < 300``200 <= StatusCode < 300` | `Boolean` | +| headersHeaders | The headers of the response | `Object` | +| errorCodeerror_codeErrorCode | The error code if the `X-Ably-Errorcode` HTTP header is sent in the response | `Int` | +| errorMessageerror_messageErrorMessage | The error message if the `X-Ably-Errormessage` HTTP header is sent in the response | `String` | @@ -1088,29 +835,21 @@ An `HttpPaginatedResponse` is a superset of [PaginatedResult](/docs/api/rest-sdk | error_message | The error message if the `X-Ably-Errormessage` HTTP header is sent in the response | `String` | - + | Property | Description | Type | |----------|-------------|------| -| statusCodestatus_codeStatusCode | The HTTP status code of the response | `Number` | -| successSuccess | Whether the HTTP status code indicates success. This is equivalent to `200 <= statusCode < 300``200 <= status_code < 300``200 <= StatusCode < 300` | `Boolean` | -| headersHeaders | The headers of the response | `Object` | -| errorCodeerror_codeErrorCode | The error code if the `X-Ably-Errorcode` HTTP header is sent in the response | `Number``Int` | -| errorMessageerror_messageErrorMessage | The error message if the `X-Ably-Errormessage` HTTP header is sent in the response | `String` | +| statusCodestatus_codeStatusCode | The HTTP status code of the response | `Number` | +| successSuccess | Whether the HTTP status code indicates success. This is equivalent to `200 <= statusCode < 300``200 <= status_code < 300``200 <= StatusCode < 300` | `Boolean` | +| headersHeaders | The headers of the response | `Object` | +| errorCodeerror_codeErrorCode | The error code if the `X-Ably-Errorcode` HTTP header is sent in the response | `Int` | +| errorMessageerror_messageErrorMessage | The error message if the `X-Ably-Errormessage` HTTP header is sent in the response | `String` | #### Methods -##### firstFirst - - - -`first(): Promise` - -Returns a promise. On success, the promise is fulfilled with a new `HttpPaginatedResponse` for the first page of results. On failure, the promise is rejected with an [ErrorInfo](/docs/api/realtime-sdk/types#error-info) object that details the reason why it was rejected. - - +##### firstFirst @@ -1168,10 +907,9 @@ Returns a new `HttpPaginatedResponse` for the first page of results. +##### hasNextHasNexthas_next?has_next -##### hasNextHasNexthas_next?has_next - - + `Boolean hasNext()` @@ -1219,11 +957,11 @@ Returns a new `HttpPaginatedResponse` for the first page of results. -Returns `true` if there are more pages available by calling `next``Next` and returns `false` if this page is the last page available. +Returns `true` if there are more pages available by calling `next``Next` and returns `false` if this page is the last page available. -##### isLastIsLastlast?is_last +##### isLastIsLastlast?is_last - + `Boolean isLast()` @@ -1271,23 +1009,9 @@ Returns `true` if there are more pages available by calling `next``Next` available. +Returns `true` if this page is the last page and returns `false` if there are more pages available by calling `next``Next` available. -##### nextNext - - - -`next(callback(err, resultPage))` - - - - - -`next(): Promise` - -Returns a promise. On success, the promise is fulfilled with a new `HttpPaginatedResponse` 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](/docs/api/realtime-sdk/types#error-info) object that details the reason why it was rejected. - - +##### nextNext @@ -1345,26 +1069,6 @@ Returns a new `HttpPaginatedResponse` loaded with the next page of results. If t - - -##### current - - - -`current(): Promise` - - - - - -`current(): Promise` - - - -Returns a promise. On success, the promise is fulfilled with a new `HttpPaginatedResponse` loaded with the current page of results. On failure, the promise is rejected with an [ErrorInfo](/docs/api/realtime-sdk/types#error-info) object that details the reason why it was rejected. - - - #### Example The `HttpPaginatedResponse` interface is a superset of `PaginatedResult`, see the [PaginatedResult example](/docs/api/rest-sdk/types/#paginated-result-example) @@ -1386,73 +1090,3 @@ Please note that `key` and `value` attributes are always strings. If an `Integer - - -### BatchPublishSpec - -A `BatchPublishSpec` describes the messages that should be published by a batch publish operation, and the channels to which they should be published. - -#### Properties - -| Property | Description | Type | -|----------|-------------|------| -| channels | The names of the channels to publish the `messages` to | `String[]` | -| messages | An array of [Message](/docs/api/realtime-sdk/types#message) objects | [`Message[]`](/docs/api/realtime-sdk/types#message) | - -### BatchResult - -A `BatchResult` contains information about the results of a batch operation. - -#### Properties - -| Property | Description | Type | -|----------|-------------|------| -| successCount | The number of successful operations in the request | `Number` | -| failureCount | The number of unsuccessful operations in the request | `Number` | -| messages | An array of results for the batch operation (for example, an array of [BatchPublishSuccessResult](/docs/api/realtime-sdk/types#batch-publish-success-result) or [BatchPublishFailureResult](/docs/api/realtime-sdk/types#batch-publish-failure-result) for a channel batch publish request) | `Object[]` | - -### BatchPublishSuccessResult - -A `BatchPublishSuccessResult` contains information about the result of successful publishes to a channel requested by a single [BatchPublishSpec](/docs/api/realtime-sdk/types#batch-publish-spec). - -#### Properties - -| Property | Description | Type | -|----------|-------------|------| -| channel | The name of the channel the message(s) was published to | `String` | -| messageId | A unique ID prefixed to the `Message.id` of each published message | `String` | - -### BatchPublishFailureResult - -A `BatchPublishFailureResult` contains information about the result of unsuccessful publishes to a channel requested by a single [BatchPublishSpec](/docs/api/realtime-sdk/types#batch-publish-spec). - -#### Properties - -| Property | Description | Type | -|----------|-------------|------| -| channel | The name of the channel the message(s) failed to be published to | `String` | -| error | Describes the reason for which the message(s) failed to publish to the channel as an [ErrorInfo](/docs/api/realtime-sdk/types#error-info) object | [`ErrorInfo`](/docs/api/realtime-sdk/types#error-info) | - -### BatchPresenceSuccessResult - -A `BatchPresenceSuccessResult` contains information about the result of a successful batch presence request for a single channel. - -#### Properties - -| Property | Description | Type | -|----------|-------------|------| -| channel | The channel name the presence state was retrieved for | `String` | -| presence | An array of [PresenceMessage](/docs/api/realtime-sdk/types#presence-message) describing members present on the channel | [`PresenceMessage[]`](/docs/api/realtime-sdk/types#presence-message) | - -### BatchPresenceFailureResult - -A `BatchPresenceFailureResult` contains information about the result of an unsuccessful batch presence request for a single channel. - -#### Properties - -| Property | Description | Type | -|----------|-------------|------| -| channel | The channel name the presence state failed to be retrieved for | `String` | -| error | Describes the reason for which presence state could not be retrieved for the channel as an [ErrorInfo](/docs/api/realtime-sdk/types#error-info) object | [`ErrorInfo`](/docs/api/realtime-sdk/types#error-info) | - - diff --git a/src/pages/docs/api/rest-sdk/authentication.mdx b/src/pages/docs/api/rest-sdk/authentication.mdx index 9517366258..f21edab281 100644 --- a/src/pages/docs/api/rest-sdk/authentication.mdx +++ b/src/pages/docs/api/rest-sdk/authentication.mdx @@ -12,7 +12,6 @@ jump_to: - authorize - createTokenRequest#create-token-request - requestToken#request-token - - revokeTokens#revoke-tokens Types: - Related Types#related-types redirect_from: @@ -35,27 +34,22 @@ In the documentation, references to Ably-compatible tokens typically refer eithe The principal use-case for the `Auth` object is to create Ably [`TokenRequest`](#token-request) objects with [`createTokenRequest`](#create-token-request) or obtain [Ably Tokens](#token-details) from Ably with [`requestToken`](#request-token), and then issue them to other "less trusted" clients. Typically, your servers should be the only devices to have a [private API key](/docs/auth#api-keys), and this private API key is used to securely sign Ably [`TokenRequest`](#token-request) objects or request [Ably Tokens](#token-details) from Ably. Clients are then issued with these short-lived [Ably Tokens](#token-details) or Ably [`TokenRequest`](#token-request) objects, and the libraries can then use these to authenticate with Ably. If you adopt this model, your private API key is never shared with clients directly. -A subsidiary use-case for the `Auth` object is to preemptively trigger renewal of a token or to acquire a new token with a revised set of capabilities by explicitly calling [`authorize`](#authorize)[`Authorize`](#authorize). +A subsidiary use-case for the `Auth` object is to preemptively trigger renewal of a token or to acquire a new token with a revised set of capabilities by explicitly calling [`authorize`](#authorize)[`Authorize`](#authorize). -The Auth object is available as the [`auth` field](/docs/api/rest-sdk#auth)[`auth` property](/docs/api/rest-sdk#auth)[`Auth` property](/docs/api/rest-sdk#auth)[`auth` attribute](/docs/api/rest-sdk#auth) of an [Ably REST client instance](/docs/api/rest-sdk#constructor). +The Auth object is available as the [`auth` field](/docs/api/rest-sdk#auth)[`auth` property](/docs/api/rest-sdk#auth)[`Auth` property](/docs/api/rest-sdk#auth)[`auth` attribute](/docs/api/rest-sdk#auth) of an [Ably REST client instance](/docs/api/rest-sdk#constructor). -## Auth PropertiesAbly\Auth Propertiesio.ably.lib.rest.Auth MembersAbly::Auth AttributesAuth AttributesARTAuth Properties +## Auth PropertiesAbly\Auth Propertiesio.ably.lib.rest.Auth MembersAbly::Auth AttributesAuth AttributesARTAuth Properties -The `ART``Auth` object exposes the following public propertiesattributesmembers: +The `ART``Auth` object exposes the following public propertiesattributesmembers: -### clientIdclient_idClientIdClientID +### clientIdclient_idClientIdClientID The client ID string, if any, configured for this client connection. See [identified clients](#identified-clients) for more information on trusted client identifiers. -## Auth Methodsio.ably.lib.rest.Auth MethodsAbly::Auth MethodsAbly\Auth MethodsARTAuth Methods +## Auth Methodsio.ably.lib.rest.Auth MethodsAbly::Auth MethodsAbly\Auth MethodsARTAuth Methods -### authorizeAuthorize +### authorizeAuthorize - - -`authorize(tokenParams?: TokenParams, authOptions?: AuthOptions): Promise` - - `TokenDetails authorize(TokenParams token_params, AuthOptions auth_options)` @@ -92,18 +86,18 @@ The client ID string, if any, configured for this client connection. See [identi -Instructs the library to get a new token immediately using the specified `token_params` and `auth_options``tokenParams` and `authOptions``TokenParams` and `AuthOptions` (or if none specified, the client library defaults). Also stores any `token_params` and `auth_options``tokenParams` and `authOptions``TokenParams` and `AuthOptions` passed in as the new defaults, to be used for all subsequent implicit or explicit token requests. +Instructs the library to get a new token immediately using the specified `token_params` and `auth_options``tokenParams` and `authOptions``TokenParams` and `AuthOptions` (or if none specified, the client library defaults). Also stores any `token_params` and `auth_options``tokenParams` and `authOptions``TokenParams` and `AuthOptions` passed in as the new defaults, to be used for all subsequent implicit or explicit token requests. -Any `token_params` and `auth_options``tokenParams` and `authOptions``TokenParams` and `AuthOptions` objects passed in will entirely replace (as opposed to being merged with) the currently saved `token_params` and `auth_options``tokenParams` and `authOptions`. +Any `token_params` and `auth_options``tokenParams` and `authOptions``TokenParams` and `AuthOptions` objects passed in will entirely replace (as opposed to being merged with) the currently saved `token_params` and `auth_options``tokenParams` and `authOptions`. #### Parameters - + | Parameter | Description | Type | |-----------|-------------|------| -| token_paramstokenParamsTokenParams | An optional object containing the [Ably Token parameters](#token-params)An optional [`TokenParams`](#token-params) object containing the token parametersAn optional Dict containing the [Ably Token parameters](#token-params)An optional set of key value pairs containing the [Ably Token parameters](#token-params)An optional set of key value pairs in an associative array containing the [Ably Token parameters](#token-params) for the authorization request | [`TokenParams`](#token-params) | -| auth_optionsauthOptionsAuthOptions | An optional object containing the [authentication options](#auth-options)An optional [`AuthOptions`](#auth-options) object containing the authentication optionsAn optional Dict containing the [authentication options](#auth-options)An optional set of key value pairs containing the [authentication options](#auth-options)An optional set of key value pairs in an associative array containing the [authentication options](#auth-options) for the authorization request | [`AuthOptions`](#auth-options) | +| token_paramstokenParamsTokenParams | An optional object containing the [Ably Token parameters](#token-params)An optional [`TokenParams`](#token-params) object containing the token parametersAn optional Dict containing the [Ably Token parameters](#token-params)An optional set of key value pairs containing the [Ably Token parameters](#token-params)An optional set of key value pairs in an associative array containing the [Ably Token parameters](#token-params) for the authorization request | [`TokenParams`](#token-params) | +| auth_optionsauthOptionsAuthOptions | An optional object containing the [authentication options](#auth-options)An optional [`AuthOptions`](#auth-options) object containing the authentication optionsAn optional Dict containing the [authentication options](#auth-options)An optional set of key value pairs containing the [authentication options](#auth-options)An optional set of key value pairs in an associative array containing the [authentication options](#auth-options) for the authorization request | [`AuthOptions`](#auth-options) | @@ -116,17 +110,6 @@ Any `token_params` and `auth_options` - -#### Returns - -Returns a promise. - -On success, the promise is fulfilled with the a [`TokenDetails`](#token-details) object containing the details of the new or existing [Ably Token](#token-details) along with the `token` string. - -On failure to obtain an token, the promise is rejected with an [`ErrorInfo`](/docs/api/rest-sdk/types#error-info) object with the error response as defined in the [Ably REST API](/docs/api/rest-api#common) documentation. - - #### Callback result @@ -159,34 +142,6 @@ Failure to obtain a token will raise an [`AblyException`](#ably-exception). #### Example - - - -```javascript -try { - const tokenDetails = await client.auth.authorize({ clientId: 'bob' }); - console.log('Success; token: ' + tokenDetails.token); -} catch (error) { - console.log('An error occurred; err = ' + error.message); -} -``` - - - - - - -```nodejs -try { - const tokenDetails = await client.auth.authorize({ clientId: 'bob' }); - console.log('Success; token: ' + tokenDetails.token); -} catch (error) { - console.log('An error occurred; err = ' + error.message); -} -``` - - - @@ -300,13 +255,8 @@ fmt.Println(token) -### createTokenRequestCreateTokenRequestcreate_token_request +### createTokenRequestCreateTokenRequestcreate_token_request - - -`createTokenRequest(tokenParams?: TokenParams, authOptions?: AuthOptions): Promise` - - `TokenRequest create_token_request(TokenParams token_params, AuthOptions auth_options)` @@ -343,20 +293,20 @@ fmt.Println(token) -Creates and signs an Ably [`TokenRequest`](#request-token) based on the specified `token_params` and `auth_options``tokenParams` and `authOptions``TokenParams` and `AuthOptions``tokenParams` and `authOptions`. Note this can only be used when the [API `key`](/docs/auth#api-keys) value is available locally, due to it being required to sign the Ably [`TokenRequest`](#request-token). Otherwise, Ably [`TokenRequests`](#request-token) must be obtained from the key owner. Use this to generate Ably [`TokenRequests`](#request-token) in order to implement an [Ably Token](#token-details) request callback for use by other clients. +Creates and signs an Ably [`TokenRequest`](#request-token) based on the specified `token_params` and `auth_options``tokenParams` and `authOptions``TokenParams` and `AuthOptions``tokenParams` and `authOptions`. Note this can only be used when the [API `key`](/docs/auth#api-keys) value is available locally, due to it being required to sign the Ably [`TokenRequest`](#request-token). Otherwise, Ably [`TokenRequests`](#request-token) must be obtained from the key owner. Use this to generate Ably [`TokenRequests`](#request-token) in order to implement an [Ably Token](#token-details) request callback for use by other clients. -Both `auth_options` and `token_params``authOptions` and `tokenParams``AuthOptions` and `TokenParams``authOptions` and `tokenParams` are optional. When omitted or `null``Null``None``nil`, the default Ably-compatible token parameters and authentication options for the client library are used, as specified in the `ClientOptions` when the client library was instantiated, or later updated with an explicit [`authorize`](#authorize)[`Authorize`](#authorize) request. Values passed in will be used instead of (rather than being merged with) the default values. +Both `auth_options` and `token_params``authOptions` and `tokenParams``AuthOptions` and `TokenParams``authOptions` and `tokenParams` are optional. When omitted or `null``Null``None``nil`, the default Ably-compatible token parameters and authentication options for the client library are used, as specified in the `ClientOptions` when the client library was instantiated, or later updated with an explicit [`authorize`](#authorize)[`Authorize`](#authorize) request. Values passed in will be used instead of (rather than being merged with) the default values. To understand why an Ably [`TokenRequest`](#request-token) may be issued to clients in favor of an [Ably Token](#token-details), see [Token Authentication explained](/docs/auth/token). #### Parameters - + | Parameter | Description | Type | |-----------|-------------|------| -| token_paramstokenParamsTokenParams | An optional object containing the [token parameters](#token-params)An optional [`TokenParams`](#token-params) object containing the token parametersAn optional Dict containing the [token parameters](#token-params)An optional set of key value pairs containing the [token parameters](#token-params)An optional set of key value pairs in an associative array containing the [token parameters](#token-params)An optional [`TokenParams`](#token-params) object containing the token parameters for the Ably [`TokenRequest`](#request-token) | [`TokenParams`](#token-params) | -| auth_options[auth options]authOptionsAuthOptions | An optional object containing the [authentication options](#auth-options)An optional [`AuthOptions`](#auth-options) object containing the authentication optionsVarious keyword arguments with the [authentication options](#auth-options)An optional set of key value pairs containing the [authentication options](#auth-options)An optional set of key value pairs in an associative array containing the [authentication options](#auth-options) for the [Ably Token](#token-details) Request | [`AuthOptions`](#auth-options) | +| token_paramstokenParamsTokenParams | An optional object containing the [token parameters](#token-params)An optional [`TokenParams`](#token-params) object containing the token parametersAn optional Dict containing the [token parameters](#token-params)An optional set of key value pairs containing the [token parameters](#token-params)An optional set of key value pairs in an associative array containing the [token parameters](#token-params)An optional [`TokenParams`](#token-params) object containing the token parameters for the Ably [`TokenRequest`](#request-token) | [`TokenParams`](#token-params) | +| auth_options[auth options]authOptionsAuthOptions | An optional object containing the [authentication options](#auth-options)An optional [`AuthOptions`](#auth-options) object containing the authentication optionsVarious keyword arguments with the [authentication options](#auth-options)An optional set of key value pairs containing the [authentication options](#auth-options)An optional set of key value pairs in an associative array containing the [authentication options](#auth-options) for the [Ably Token](#token-details) Request | [`AuthOptions`](#auth-options) | @@ -369,17 +319,6 @@ To understand why an Ably [`TokenRequest`](#request-token) may be issued to clie - - -#### Returns - -Returns a promise. - -On success, the promise is fulfilled with a [`TokenRequest`](#token-request) JSON object. - -On failure to issue a [`TokenRequest`](#token-request), the promise is rejected with an [`ErrorInfo`](/docs/api/rest-sdk/types#error-info) object with the error response as defined in the [Ably REST API](/docs/api/rest-api#common) documentation. - - #### Callback result @@ -412,20 +351,6 @@ Failure to issue a [`TokenRequest`](#token-request) will raise an [`AblyExceptio #### Example - - - -```javascript -try { - const tokenRequest = await client.auth.createTokenRequest({ clientId: 'bob' }); - console.log('Success; token request = ' + tokenRequest); -} catch (error) { - console.log('An error occurred; err = ' + error.message); -} -``` - - - @@ -539,13 +464,8 @@ fmt.Println(tokenRequest) -### requestTokenrequest_tokenRequestToken - - - -`requestToken(tokenParams?: TokenParams, authOptions?: AuthOptions): Promise` +### requestTokenrequest_tokenRequestToken - `TokenDetails request_token(TokenParams token_params, AuthOptions auth_options)` @@ -582,20 +502,20 @@ fmt.Println(tokenRequest) -Calls the [`requestToken` REST API endpoint](/docs/api/rest-api#request-token)[`RequestToken` REST API endpoint](/docs/api/rest-api#request-token) to obtain an [Ably Token](#token-details) according to the specified `token_params` and `auth_options``tokenParams` and `authOptions``tokenParams` and `authOptions`. +Calls the [`requestToken` REST API endpoint](/docs/api/rest-api#request-token)[`RequestToken` REST API endpoint](/docs/api/rest-api#request-token) to obtain an [Ably Token](#token-details) according to the specified `token_params` and `auth_options``tokenParams` and `authOptions``tokenParams` and `authOptions`. -Both `auth_options` and `token_params``authOptions` and `tokenParams``authOptions` and `tokenParams` are optional. When omitted or `null``Null``None``nil``null`, the default token parameters and authentication options for the client library are used, as specified in the `ClientOptions` when the client library was instantiated, or later updated with an explicit [`authorize`](#authorize)[`Authorize`](#authorize) request. Values passed in will be used instead of (rather than being merged with) the default values. +Both `auth_options` and `token_params``authOptions` and `tokenParams``authOptions` and `tokenParams` are optional. When omitted or `null``Null``None``nil``null`, the default token parameters and authentication options for the client library are used, as specified in the `ClientOptions` when the client library was instantiated, or later updated with an explicit [`authorize`](#authorize)[`Authorize`](#authorize) request. Values passed in will be used instead of (rather than being merged with) the default values. To understand why an Ably [`TokenRequest`](#request-token) may be issued to clients in favor of an [Ably Token](#token-details), see [Token Authentication explained](/docs/auth/token). #### Parameters - + | Parameter | Description | Type | |-----------|-------------|------| -| token_paramstokenParamstokenParams | An optional object containing the [token parameters](#token-params)An optional Dict containing the [token parameters](#token-params)An optional [`TokenParams`](#token-params) object containing the token parametersAn optional set of key value pairs containing the [token parameters](#token-params)An optional set of key value pairs in an associative array containing the [token parameters](#token-params)An optional object containing the [token parameters](#token-params) for the requested [Ably Token](#token-details) | [`TokenParams`](#token-params) | -| [auth options]auth_optionsauthOptions | An optional object containing the [authentication options](#auth-options)Various keyword arguments with the [authentication options](#auth-options)An optional [`AuthOptions`](#auth-options) object containing the authentication optionsAn optional set of key value pairs containing the [authentication options](#auth-options)An optional set of key value pairs in an associative array containing the [authentication options](#auth-options)An optional object containing the [authentication options](#auth-options) for the requested [Ably Token](#token-details) | [`AuthOptions`](#auth-options) | +| token_paramstokenParamstokenParams | An optional object containing the [token parameters](#token-params)An optional Dict containing the [token parameters](#token-params)An optional [`TokenParams`](#token-params) object containing the token parametersAn optional set of key value pairs containing the [token parameters](#token-params)An optional set of key value pairs in an associative array containing the [token parameters](#token-params)An optional object containing the [token parameters](#token-params) for the requested [Ably Token](#token-details) | [`TokenParams`](#token-params) | +| [auth options]auth_optionsauthOptions | An optional object containing the [authentication options](#auth-options)Various keyword arguments with the [authentication options](#auth-options)An optional [`AuthOptions`](#auth-options) object containing the authentication optionsAn optional set of key value pairs containing the [authentication options](#auth-options)An optional set of key value pairs in an associative array containing the [authentication options](#auth-options)An optional object containing the [authentication options](#auth-options) for the requested [Ably Token](#token-details) | [`AuthOptions`](#auth-options) | @@ -608,18 +528,6 @@ To understand why an Ably [`TokenRequest`](#request-token) may be issued to clie - - -#### Returns - -Returns a promise. - -On success, the promise is fulfilled with a [`TokenDetails`](#token-details) object containing the details of the new [Ably Token](#token-details) along with the `token` string. - -On failure to obtain an [Ably Token](#token-details), the promise is rejected with an [`ErrorInfo`](/docs/api/rest-sdk/types#error-info) object with the error response as defined in the [Ably REST API](/docs/api/rest-api#common) documentation. - - - #### Callback result @@ -648,35 +556,6 @@ Failure to obtain an [Ably Token](#token-details) will raise an [`AblyException` #### Example - - - -```javascript -try { - const tokenDetails = await client.auth.requestToken({ clientId: 'bob'}); - console.log('Success; token = ' + tokenDetails.token); -} catch (error) { - console.log('An error occurred; err = ' + error.message); -} -``` - - - - - - -```nodejs -try { - const tokenDetails = await client.auth.requestToken({ clientId: 'bob'}); - console.log('Success; token = ' + tokenDetails.token); -} catch (error) { - console.log('An error occurred; err = ' + error.message); -} -``` - - - - @@ -796,70 +675,9 @@ fmt.Println(token) - - -### revokeTokens - -`revokeTokens(TokenRevocationTargetSpecifier[] specifiers, TokenRevocationOptions options?): Promise>` - -Calls the [`revokeTokens` REST API endpoint](/docs/api/rest-api#revoke-tokens) to revoke tokens specified by the provided array of [`TokenRevocationTargetSpecifier`](#token-revocation-target-specifier). - -Only tokens issued by an API key that had revocable tokens enabled before the token was issued can be revoked. See the [token revocation docs](/docs/auth/revocation) for more information. - -#### Parameters - -| Parameter | Description | Type | -|-----------|-------------|------| -| specifiers | an array of [`TokenRevocationTargetSpecifier`](#token-revocation-target-specifier) objects | [`TokenRevocationTargetSpecifier[]`](#token-revocation-target-specifier) | -| options | an optional set of options which are used to modify the revocation request | [`TokenRevocationOptions`](#token-revocation-options) | - -#### Returns - -Returns a promise. - -On success, the promise is fulfilled with a [`BatchResult`](#batch-result) containing information about the result of the token revocation request for each provided [`TokenRevocationTargetSpecifier`](#token-revocation-target-specifier). - -On failure, the promise is rejected with an [`ErrorInfo`](/docs/api/rest-sdk/types#error-info) object with the error response as defined in the [Ably REST API](/docs/api/rest-api#common) documentation. - -#### Example - - - - -```javascript -try { - const response = await client.auth.revokeTokens([{ type: 'clientId', value: 'bob' }]); - console.log('Revocation successful; revoked tokens: ' + response.results.length); -} catch (error) { - console.log('An error occurred; err = ' + error.message); -} -``` - - - - - - -```nodejs -try { - const response = await client.auth.revokeTokens([{ type: 'clientId', value: 'bob' }]); - console.log('Revocation successful; revoked tokens: ' + response.results.length); -} catch (error) { - console.log('An error occurred; err = ' + error.message); -} -``` - - - - - ## Related types -### AuthOptions ObjectAuthOptions Hashio.ably.lib.rest.Auth.AuthOptions - - -`AuthOptions` is a plain JavaScript object and is used when making [authentication](/docs/auth) requests. If passed in, an `authOptions` object will be used instead of (as opposed to supplementing or being merged with) the default values given when the library was instantiated. The following attributes are supported: - +### AuthOptions ObjectAuthOptions Hashio.ably.lib.rest.Auth.AuthOptions `AuthOptions` is a Hash object and is used when making [authentication](/docs/auth) requests. These options will supplement or override the corresponding options given when the library was instantiated. The following key symbol values can be added to the Hash: @@ -881,33 +699,33 @@ try { `ARTAuthOptions` is used when making [authentication](/docs/auth) requests. These options will supplement or override the corresponding options given when the library was instantiated. -#### PropertiesMembersAttributes +#### PropertiesMembersAttributes | Name | Description | Type | |------|-------------|------| -| authCallbackAuthCallbackauth_callback:auth_callback | A functionfunction with the form `function(tokenParams, callback(err, tokenOrTokenRequest))``TokenCallback` instancecallable (eg a lambda)proc / lambda (called synchronously in REST and Realtime but does not block EventMachine in the latter)function which is called when a new token is required. The role of the callback is to obtain a fresh token, one of: an Ably Token string (in plain text format); a signed [`TokenRequest`](/docs/api/realtime-sdk/types#token-request); a [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) (in JSON format); an [Ably JWT](/docs/api/realtime-sdk/authentication#ably-jwt). See [our authentication documentation](/docs/auth) for details of the Ably TokenRequest format and associated API calls. | `Callable``TokenCallback``Proc``Func>``Callable``Callable` | -| authUrlAuthUrl:auth_urlauth_url | A URL that the library may use to obtain a fresh token, one of: an Ably Token string (in plain text format); a signed [`TokenRequest`](/docs/api/realtime-sdk/types#token-request); a [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) (in JSON format); an [Ably JWT](/docs/api/realtime-sdk/authentication#ably-jwt). For example, this can be used by a client to obtain signed Ably TokenRequests from an application server. | `String``Uri``NSURL` | -| authMethodAuthMethodauth_method:auth_method | _`GET``:get`_ The HTTP verb to use for the request, either `GET``:get` or `POST``:post` | `String``Symbol``HttpMethod` | -| authHeadersAuthHeadersauth_headers:auth_headers | A set of key value pair headers to be added to any request made to the authUrlAuthUrlAuthUrl. Useful when an application requires these to be added to validate the request or implement the response. If the `authHeaders` object contains an `authorization` key, then `withCredentials` will be set on the xhr request. | `Object``Dict``Hash``Associative Array``Param []``Dictionary` | -| authParamsAuthParams:auth_paramsauth_params | A set of key value pair params to be added to any request made to the authUrlAuthUrl. When the authMethodAuthMethod is `GET`, query params are added to the URL, whereas when authMethodAuthMethod is `POST`, the params are sent as URL encoded form data. Useful when an application require these to be added to validate the request or implement the response. | `Object``Hash``Associative Array``Param[]``Dictionary``NSArray``[NSURLQueryItem]/Array``Object` | -| tokenDetailsTokenDetailstoken_details:token_details | An authenticated [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) object (most commonly obtained from an Ably Token Request response). This option is mostly useful for testing: since tokens are short-lived, in production you almost always want to use an authentication method that allows the client library to renew the token automatically when the previous one expires, such as authUrlAuthUrl:auth_urlauth_url or authCallbackAuthCallbackauth_callback:auth_callback. Use this option if you wish to use Token authentication. Read more about [Token authentication](/docs/auth/token) | `TokenDetails` | -| keyKey:keykey | Optionally the [API key](/docs/auth#api-keys) to use can be specified as a full key string; if not, the API key passed into [`ClientOptions`](#client-options) when instancing the Realtime or REST library is used | `String` | -| queryTimeQueryTime:query_timequery_time | _false_ If true, the library will query the Ably servers for the current time when [issuing TokenRequests](/docs/auth/token) instead of relying on a locally-available time of day. Knowing the time accurately is needed to create valid signed Ably [TokenRequests](/docs/auth/token), so this option is useful for library instances on auth servers where for some reason the server clock cannot be kept synchronized through normal means, such as an [NTP daemon](https://en.wikipedia.org/wiki/Ntpd). The server is queried for the current time once per client library instance (which stores the offset from the local clock), so if using this option you should avoid instancing a new version of the library for each request. | `Boolean` | -| tokenToken:tokentoken | An authenticated token. This can either be a [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) object, a [`TokenRequest`](/docs/api/realtime-sdk/types#token-request) object, or token string (obtained from the tokenTokentokentoken property of a [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) component of an Ably TokenRequest response, or a [JSON Web Token](https://tools.ietf.org/html/rfc7519) satisfying [the Ably requirements for JWTs](/docs/auth/token/jwt)). This option is mostly useful for testing: since tokens are short-lived, in production you almost always want to use an authentication method that allows the client library to renew the token automatically when the previous one expires, such as authUrlAuthUrl:auth_urlauth_url or authCallbackAuthCallbackauth_callback:auth_callback. Read more about [Token authentication](/docs/auth/token) | `String`, `TokenDetails` or `TokenRequest` | - -### TokenDetails ObjectARTTokenDetailsio.ably.lib.types.TokenDetailsAbly::Models::TokenDetails +| authCallbackAuthCallbackauth_callback:auth_callback | A function`TokenCallback` instancecallable (eg a lambda)proc / lambda (called synchronously in REST and Realtime but does not block EventMachine in the latter)function which is called when a new token is required. The role of the callback is to obtain a fresh token, one of: an Ably Token string (in plain text format); a signed [`TokenRequest`](/docs/api/realtime-sdk/types#token-request); a [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) (in JSON format); an [Ably JWT](/docs/api/realtime-sdk/authentication#ably-jwt). See [our authentication documentation](/docs/auth) for details of the Ably TokenRequest format and associated API calls. | `Callable``TokenCallback``Proc``Func>``Callable``Callable` | +| authUrlAuthUrl:auth_urlauth_url | A URL that the library may use to obtain a fresh token, one of: an Ably Token string (in plain text format); a signed [`TokenRequest`](/docs/api/realtime-sdk/types#token-request); a [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) (in JSON format); an [Ably JWT](/docs/api/realtime-sdk/authentication#ably-jwt). For example, this can be used by a client to obtain signed Ably TokenRequests from an application server. | `String``Uri``NSURL` | +| authMethodAuthMethodauth_method:auth_method | _`GET``:get`_ The HTTP verb to use for the request, either `GET``:get` or `POST``:post` | `String``Symbol``HttpMethod` | +| authHeadersAuthHeadersauth_headers:auth_headers | A set of key value pair headers to be added to any request made to the authUrlAuthUrlAuthUrl. Useful when an application requires these to be added to validate the request or implement the response. | `Object``Dict``Hash``Associative Array``Param []``Dictionary` | +| authParamsAuthParams:auth_paramsauth_params | A set of key value pair params to be added to any request made to the authUrlAuthUrl. When the authMethodAuthMethod is `GET`, query params are added to the URL, whereas when authMethodAuthMethod is `POST`, the params are sent as URL encoded form data. Useful when an application require these to be added to validate the request or implement the response. | `Object``Hash``Associative Array``Param[]``Dictionary``NSArray``[NSURLQueryItem]/Array``Object` | +| tokenDetailsTokenDetailstoken_details:token_details | An authenticated [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) object (most commonly obtained from an Ably Token Request response). This option is mostly useful for testing: since tokens are short-lived, in production you almost always want to use an authentication method that allows the client library to renew the token automatically when the previous one expires, such as authUrlAuthUrl:auth_urlauth_url or authCallbackAuthCallbackauth_callback:auth_callback. Use this option if you wish to use Token authentication. Read more about [Token authentication](/docs/auth/token) | `TokenDetails` | +| keyKey:keykey | Optionally the [API key](/docs/auth#api-keys) to use can be specified as a full key string; if not, the API key passed into [`ClientOptions`](#client-options) when instancing the Realtime or REST library is used | `String` | +| queryTimeQueryTime:query_timequery_time | _false_ If true, the library will query the Ably servers for the current time when [issuing TokenRequests](/docs/auth/token) instead of relying on a locally-available time of day. Knowing the time accurately is needed to create valid signed Ably [TokenRequests](/docs/auth/token), so this option is useful for library instances on auth servers where for some reason the server clock cannot be kept synchronized through normal means, such as an [NTP daemon](https://en.wikipedia.org/wiki/Ntpd). The server is queried for the current time once per client library instance (which stores the offset from the local clock), so if using this option you should avoid instancing a new version of the library for each request. | `Boolean` | +| tokenToken:tokentoken | An authenticated token. This can either be a [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) object, a [`TokenRequest`](/docs/api/realtime-sdk/types#token-request) object, or token string (obtained from the tokenTokentokentoken property of a [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) component of an Ably TokenRequest response, or a [JSON Web Token](https://tools.ietf.org/html/rfc7519) satisfying [the Ably requirements for JWTs](/docs/auth/token/jwt)). This option is mostly useful for testing: since tokens are short-lived, in production you almost always want to use an authentication method that allows the client library to renew the token automatically when the previous one expires, such as authUrlAuthUrl:auth_urlauth_url or authCallbackAuthCallbackauth_callback:auth_callback. Read more about [Token authentication](/docs/auth/token) | `String`, `TokenDetails` or `TokenRequest` | + +### TokenDetails ObjectARTTokenDetailsio.ably.lib.types.TokenDetailsAbly::Models::TokenDetails `TokenDetails` is a type providing details of Ably Token string and its associated metadata. -#### PropertiesMembersAttributes +#### PropertiesMembersAttributes | Name | Description | Type | |------|-------------|------| -| tokenToken | The [Ably Token](/docs/api/realtime-sdk/authentication#token-details) itself. A typical [Ably Token](/docs/api/realtime-sdk/authentication#token-details) string may appear like `{{TOKEN}}` | `String` | -| expiresExpires | The time (in milliseconds since the epoch)The time at which this token expires | `Integer``Long Integer``DateTimeOffset``Time``NSDate` | -| issuedIssued | The time (in milliseconds since the epoch)The time at which this token was issued | `Integer``Long Integer``DateTimeOffset``Time``NSDate` | -| capabilityCapability | The capability associated with this [Ably Token](/docs/api/realtime-sdk/authentication#token-details). The capability is a a JSON stringified canonicalized representation of the resource paths and associated operations. [Read more about authentication and capabilities](/docs/auth/capabilities) | `String``Capability` | -| clientIdclient_idClientId | The client ID, if any, bound to this [Ably Token](/docs/api/realtime-sdk/authentication#token-details). If a client ID is included, then the [Ably Token](/docs/api/realtime-sdk/authentication#token-details) authenticates its bearer as that client ID, and the [Ably Token](/docs/api/realtime-sdk/authentication#token-details) may only be used to perform operations on behalf of that client ID. The client is then considered to be an [identified client](/docs/auth/identified-clients) | `String` | +| tokenToken | The [Ably Token](/docs/api/realtime-sdk/authentication#token-details) itself. A typical [Ably Token](/docs/api/realtime-sdk/authentication#token-details) string may appear like `{{TOKEN}}` | `String` | +| expiresExpires | The time (in milliseconds since the epoch)The time at which this token expires | `Integer``Long Integer``DateTimeOffset``Time``NSDate` | +| issuedIssued | The time (in milliseconds since the epoch)The time at which this token was issued | `Integer``Long Integer``DateTimeOffset``Time``NSDate` | +| capabilityCapability | The capability associated with this [Ably Token](/docs/api/realtime-sdk/authentication#token-details). The capability is a a JSON stringified canonicalized representation of the resource paths and associated operations. [Read more about authentication and capabilities](/docs/auth/capabilities) | `String``Capability` | +| clientIdclient_idClientId | The client ID, if any, bound to this [Ably Token](/docs/api/realtime-sdk/authentication#token-details). If a client ID is included, then the [Ably Token](/docs/api/realtime-sdk/authentication#token-details) authenticates its bearer as that client ID, and the [Ably Token](/docs/api/realtime-sdk/authentication#token-details) may only be used to perform operations on behalf of that client ID. The client is then considered to be an [identified client](/docs/auth/identified-clients) | `String` | ### Methods @@ -938,9 +756,9 @@ try { ### TokenDetails constructors -#### TokenDetails.fromJsonTokenDetails.from_json +#### TokenDetails.fromJsonTokenDetails.from_json - + `TokenDetails.fromJson(String json) -> TokenDetails` @@ -960,11 +778,7 @@ A static factory method to create a [`TokenDetails`](/docs/api/realtime-sdk/type A [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) object -### TokenParams ObjectARTTokenParamsTokenParams Hashio.ably.lib.rest.Auth.TokenParams - - -`TokenParams` is a plain JavaScript object and is used in the parameters of [token authentication](/docs/auth/token) requests, corresponding to the desired attributes of the [Ably Token](/docs/api/realtime-sdk/authentication#token-details). The following attributes can be defined on the object: - +### TokenParams ObjectARTTokenParamsTokenParams Hashio.ably.lib.rest.Auth.TokenParams `TokenParams` is a Hash object and is used in the parameters of [token authentication](/docs/auth/token) requests, corresponding to the desired attributes of the [Ably Token](/docs/api/realtime-sdk/authentication#token-details). The following key symbol values can be added to the Hash: @@ -986,37 +800,37 @@ A [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) object `ARTTokenParams` is used in the parameters of [token authentication](/docs/auth/token) requests, corresponding to the desired attributes of the [Ably Token](/docs/api/realtime-sdk/authentication#token-details). -#### PropertiesMembersAttributes +#### PropertiesMembersAttributes | Name | Description | Type | |------|-------------|------| -| capabilityCapability:capability | JSON stringified capability of the [Ably Token](/docs/api/realtime-sdk/authentication#token-details). If the [Ably Token](/docs/api/realtime-sdk/authentication#token-details) request is successful, the capability of the returned [Ably Token](/docs/api/realtime-sdk/authentication#token-details) will be the intersection of this capability with the capability of the issuing key. [Find our more about how to use capabilities to manage access privileges for clients](/docs/auth/capabilities). | `String``Capability` | -| clientIdClientIdclient_id:client_id | A client ID, used for identifying this client when publishing messages or for presence purposes. The clientIdclient_idClientId can be any non-empty string. This option is primarily intended to be used in situations where the library is instantiated with a key; note that a clientIdclient_idClientId may also be implicit in a token used to instantiate the library; an error will be raised if a clientIdclient_idClientId specified here conflicts with the clientIdclient_idClientId implicit in the token. [Find out more about client identities](/docs/auth/identified-clients) | `String` | -| nonceNonce:nonce | An optional opaque nonce string of at least 16 characters to ensure uniqueness of this request. Any subsequent request using the same nonce will be rejected. | `String` | -| timestampTimestamp:timestamp | The timestamp (in milliseconds since the epoch)The timestamp of this request. `timestamp`, in conjunction with the `nonce`, is used to prevent requests for [Ably Token](/docs/api/realtime-sdk/authentication#token-details) from being replayed. | `Integer``Long Integer``Time``NSDate``DateTimeOffset` | -| ttlTtl:ttl | _1 hour_ Requested time to live for the [Ably Token](/docs/api/realtime-sdk/authentication#token-details) being created in millisecondsin secondsas a `NSTimeInterval`as a `TimeSpan`. When omitted, the Ably REST API default of 60 minutes is applied by Ably | `Integer` (milliseconds)`Integer` (seconds)`NSTimeInterval``Long Integer``TimeSpan` | +| capabilityCapability:capability | JSON stringified capability of the [Ably Token](/docs/api/realtime-sdk/authentication#token-details). If the [Ably Token](/docs/api/realtime-sdk/authentication#token-details) request is successful, the capability of the returned [Ably Token](/docs/api/realtime-sdk/authentication#token-details) will be the intersection of this capability with the capability of the issuing key. [Find our more about how to use capabilities to manage access privileges for clients](/docs/auth/capabilities). | `String``Capability` | +| clientIdClientIdclient_id:client_id | A client ID, used for identifying this client when publishing messages or for presence purposes. The clientIdclient_idClientId can be any non-empty string. This option is primarily intended to be used in situations where the library is instantiated with a key; note that a clientIdclient_idClientId may also be implicit in a token used to instantiate the library; an error will be raised if a clientIdclient_idClientId specified here conflicts with the clientIdclient_idClientId implicit in the token. [Find out more about client identities](/docs/auth/identified-clients) | `String` | +| nonceNonce:nonce | An optional opaque nonce string of at least 16 characters to ensure uniqueness of this request. Any subsequent request using the same nonce will be rejected. | `String` | +| timestampTimestamp:timestamp | The timestamp (in milliseconds since the epoch)The timestamp of this request. `timestamp`, in conjunction with the `nonce`, is used to prevent requests for [Ably Token](/docs/api/realtime-sdk/authentication#token-details) from being replayed. | `Integer``Long Integer``Time``NSDate``DateTimeOffset` | +| ttlTtl:ttl | _1 hour_ Requested time to live for the [Ably Token](/docs/api/realtime-sdk/authentication#token-details) being created in millisecondsin secondsas a `NSTimeInterval`as a `TimeSpan`. When omitted, the Ably REST API default of 60 minutes is applied by Ably | `Integer` (milliseconds)`Integer` (seconds)`NSTimeInterval``Long Integer``TimeSpan` | -### TokenRequest ObjectARTTokenRequestAbly::Models::TokenRequestio.ably.lib.rest.Auth.TokenRequest +### TokenRequest ObjectARTTokenRequestAbly::Models::TokenRequestio.ably.lib.rest.Auth.TokenRequest -`TokenRequest` is a type containing parameters for an Ably `TokenRequest`. [Ably Tokens](/docs/api/realtime-sdk/authentication#token-details) are requested using [Auth#requestToken](/docs/api/rest-sdk/authentication#request-token)[Auth#request_token](/docs/api/rest-sdk/authentication#request-token) +`TokenRequest` is a type containing parameters for an Ably `TokenRequest`. [Ably Tokens](/docs/api/realtime-sdk/authentication#token-details) are requested using [Auth#requestToken](/docs/api/rest-sdk/authentication#request-token)[Auth#request_token](/docs/api/rest-sdk/authentication#request-token) -#### PropertiesMembersAttributes +#### PropertiesMembersAttributes | Name | Description | Type | |------|-------------|------| -| keyNamekey_nameKeyName | The key name of the key against which this request is made. The key name is public, whereas the key secret is private | `String` | -| ttlTtl | Requested time to live for the [Ably Token](/docs/api/realtime-sdk/authentication#token-details) in millisecondsin secondsas a `TimeSpan`. If the Ably `TokenRequest` is successful, the TTL of the returned [Ably Token](/docs/api/realtime-sdk/authentication#token-details) will be less than or equal to this value depending on application settings and the attributes of the issuing key. | `Integer``TimeSpan``NSTimeInterval``Integer` | -| timestampTimestamp | The timestamp of this request in milliseconds | `Integer``Long Integer``Time``DateTimeOffset``NSDate` | -| capabilityCapability | Capability of the requested [Ably Token](/docs/api/realtime-sdk/authentication#token-details). If the Ably `TokenRequest` is successful, the capability of the returned [Ably Token](/docs/api/realtime-sdk/authentication#token-details) will be the intersection of this capability with the capability of the issuing key. The capability is a JSON stringified canonicalized representation of the resource paths and associated operations. [Read more about authentication and capabilities](/docs/auth) | `String` | -| clientIdclient_idClientId | The client ID to associate with the requested [Ably Token](/docs/api/realtime-sdk/authentication#token-details). When provided, the [Ably Token](/docs/api/realtime-sdk/authentication#token-details) may only be used to perform operations on behalf of that client ID | `String` | -| nonceNonce | An opaque nonce string of at least 16 characters | `String` | -| macMac | The Message Authentication Code for this request | `String` | +| keyNamekey_nameKeyName | The key name of the key against which this request is made. The key name is public, whereas the key secret is private | `String` | +| ttlTtl | Requested time to live for the [Ably Token](/docs/api/realtime-sdk/authentication#token-details) in millisecondsin secondsas a `TimeSpan`. If the Ably `TokenRequest` is successful, the TTL of the returned [Ably Token](/docs/api/realtime-sdk/authentication#token-details) will be less than or equal to this value depending on application settings and the attributes of the issuing key. | `Integer``TimeSpan``NSTimeInterval``Integer` | +| timestampTimestamp | The timestamp of this request in milliseconds | `Integer``Long Integer``Time``DateTimeOffset``NSDate` | +| capabilityCapability | Capability of the requested [Ably Token](/docs/api/realtime-sdk/authentication#token-details). If the Ably `TokenRequest` is successful, the capability of the returned [Ably Token](/docs/api/realtime-sdk/authentication#token-details) will be the intersection of this capability with the capability of the issuing key. The capability is a JSON stringified canonicalized representation of the resource paths and associated operations. [Read more about authentication and capabilities](/docs/auth) | `String` | +| clientIdclient_idClientId | The client ID to associate with the requested [Ably Token](/docs/api/realtime-sdk/authentication#token-details). When provided, the [Ably Token](/docs/api/realtime-sdk/authentication#token-details) may only be used to perform operations on behalf of that client ID | `String` | +| nonceNonce | An opaque nonce string of at least 16 characters | `String` | +| macMac | The Message Authentication Code for this request | `String` | ### TokenRequest constructors -#### TokenRequest.fromJsonTokenRequest.from_json +#### TokenRequest.fromJsonTokenRequest.from_json - + `TokenRequest.fromJson(String json) -> TokenRequest` @@ -1055,135 +869,3 @@ The Ably JWT must be signed with the secret part of your [Ably API key](/docs/au We recommend you use one of the many [JWT libraries available for simplicity](https://jwt.io/) when creating your JWTs. - - -The following is an example of creating an Ably JWT: - - - - -```javascript - var header = { - "typ":"JWT", - "alg":"HS256", - "kid": "{{API_KEY_NAME}}" - }; - var currentTime = Math.round(Date.now()/1000); - var claims = { - "iat": currentTime, /* current time in seconds */ - "exp": currentTime + 3600, /* time of expiration in seconds */ - "x-ably-capability": "{\"*\":[\"*\"]}" - }; - var base64Header = btoa(header); - var base64Claims = btoa(claims); - /* Apply the hash specified in the header */ - var signature = hash((base64Header + "." + base64Claims), "{{API_KEY_SECRET}}"); - var ablyJwt = base64Header + "." + base64Claims + "." + signature; -``` - - - - - - -```nodejs - var header = { - "typ":"JWT", - "alg":"HS256", - "kid": "{{API_KEY_NAME}}" - }; - var currentTime = Math.round(Date.now()/1000); - var claims = { - "iat": currentTime, /* current time in seconds */ - "exp": currentTime + 3600, /* time of expiration in seconds */ - "x-ably-capability": "{\"*\":[\"*\"]}" - }; - var base64Header = btoa(header); - var base64Claims = btoa(claims); - /* Apply the hash specified in the header */ - var signature = hash((base64Header + "." + base64Claims), "{{API_KEY_SECRET}}"); - var ablyJwt = base64Header + "." + base64Claims + "." + signature; -``` - - - - -*Note:* At present Ably does not support asymmetric signatures based on a keypair belonging to a third party. - - - - -### BatchResult - -A `BatchResult` contains information about the results of a batch operation. - -#### Properties - -| Property | Description | Type | -|----------|-------------|------| -| successCount | The number of successful operations in the request | `Number` | -| failureCount | The number of unsuccessful operations in the request | `Number` | -| messages | An array of results for the batch operation (for example, an array of [`BatchPublishSuccessResult`](/docs/api/realtime-sdk/types#batch-publish-success-result) or [`BatchPublishFailureResult`](/docs/api/realtime-sdk/types#batch-publish-failure-result) for a channel batch publish request) | `Object[]` | - - - -### TokenRevocationTargetSpecifier - -A `TokenRevocationTargetSpecifier` describes which tokens should be affected by a token revocation request. - - - -#### Properties - -| Property | Description | Type | -|----------|-------------|------| -| type | The type of token revocation target specifier. Valid values include `clientId`, `revocationKey` and `channel` | `String` | -| value | The value of the token revocation target specifier | `String` | - - - -### TokenRevocationOptions - -A `TokenRevocationOptions` describes the additional options accepted by revoke tokens request. - - - -#### Properties - -| Property | Description | Type | -|----------|-------------|------| -| issuedBefore | An optional Unix timestamp in milliseconds where only tokens issued before this time are revoked. The default is the current time. Requests with an `issuedBefore` in the future, or more than an hour in the past, will be rejected | `Number` | -| allowReauthMargin | _false_ If true, permits a token renewal cycle to take place without needing established connections to be dropped, by postponing enforcement to 30 seconds in the future, and sending any existing connections a hint to obtain (and upgrade the connection to use) a new token. The default is `false`, meaning that the effect is near-immediate. | `Boolean` | - - - -### TokenRevocationSuccessResult - -A `TokenRevocationSuccessResult` contains information about the result of a successful token revocation request for a single target specifier. - - - -#### Properties - -| Property | Description | Type | -|----------|-------------|------| -| target | The target specifier | `Number` | -| appliesAt | The time at which the token revocation will take effect, as a Unix timestamp in milliseconds | `Number` | -| issuedBefore | A Unix timestamp in milliseconds. Only tokens issued earlier than this time will be revoked | `Number` | - - - -### TokenRevocationFailureResult - -A `TokenRevocationFailureResult` contains information about the result of an unsuccessful token revocation request for a single target specifier. - - - -#### Properties - -| Property | Description | Type | -|----------|-------------|------| -| target | The target specifier | `String` | -| error | Describes the reason for which token revocation failed for the given `target` as an [`ErrorInfo`](/docs/api/realtime-sdk/types#error-info) object | [`ErrorInfo`](/docs/api/realtime-sdk/types#error-info) | - - diff --git a/src/pages/docs/api/rest-sdk/channels.mdx b/src/pages/docs/api/rest-sdk/channels.mdx index 38e799b008..ea02c24db0 100644 --- a/src/pages/docs/api/rest-sdk/channels.mdx +++ b/src/pages/docs/api/rest-sdk/channels.mdx @@ -18,9 +18,9 @@ The `Channels` object, accessed from the [rest library client constructor](/docs ### Channels Methods -#### getGet +#### getGet - + `Channel get(String channelName, ChannelOptions channelOptions)` @@ -40,9 +40,9 @@ The `Channels` object, accessed from the [rest library client constructor](/docs Creates a new [Channel](#properties) object if none for the channel exists, or returns the existing channel object. -#### releaseRelease +#### releaseRelease - + `release(String channelName)` @@ -74,15 +74,15 @@ After release, calling `channels.get(channelName)` returns a fresh channel objec The Channel object, created via the [Channels](#channels-object) object, is used to interact with a specific channel. -### Channel PropertiesChannel AttributesAbly\Channel PropertiesARTRestChannel PropertiesAbly::Rest::Channel Attributesio.ably.lib.rest.Channel MembersIO.Ably.Rest.RestChannel MembersChannel Methods +### Channel PropertiesChannel AttributesAbly\Channel PropertiesARTRestChannel PropertiesAbly::Rest::Channel Attributesio.ably.lib.rest.Channel MembersIO.Ably.Rest.RestChannel MembersChannel Methods -The `Channel` object exposes the following public propertiesattributesmembers: +The `Channel` object exposes the following public propertiesattributesmembers: -#### nameName +#### nameName The name `String` unique to this channel. -#### presencePresence +#### presencePresence Provides access to the [REST Presence](/docs/presence-occupancy/presence) object for this channel which can be used to get members present on the channel, or retrieve presence event history. @@ -90,7 +90,7 @@ Provides access to the [REST Presence](/docs/presence-occupancy/presence) object Provides access to the [PushChannel](/docs/api/realtime-sdk/push#push-channel) object for this channel which can be used to access members present on the channel, or participate in presence. - + #### annotations @@ -98,24 +98,12 @@ Provides access to the [`RestAnnotations`](#rest-annotations) object for this ch - -#### object - -Provides access to the [RestObject](/docs/liveobjects/rest-sdk-usage) for this channel which can be used to read and modify LiveObjects on a channel using the REST SDK. - - ### Channel Methods -#### publishPublish +#### publishPublish There are two overloaded versions of this method: - - -`publish(String name, Object data, PublishOptions options?) Promise` - - - `publish(String name, Object data)` @@ -162,20 +150,6 @@ Publish a single message on this channel based on a given event name and payload It is also possible to publish a message to multiple channels at once using our [batch publish feature](/docs/messages/batch#batch-publish). - - -`publish(Message message, PublishOptions options?): Promise` - -Publish a single message on this channel. - - - - - -`publish(Message[] messages, PublishOptions options?): Promise` - - - `publish(Message[] messages)` @@ -229,16 +203,6 @@ The entire `messages` array is published atomically. This means that: #### Parameters - - -| Parameter | Description | Type | -|-----------|-------------|------| -| data | Data payload for the message. The supported payload types are Strings, objects or arrays capable of JSON representation, buffers containing arbitrary binary data, and null. (Note that if sending a binary, that binary should be the entire payload; an object with a binary field within it may not be correctly encoded) | `Object` | -| messages | An array of message objects to publish | [`Message []`](#message) | -| options | Optional parameters to provide to the publish operation | [`PublishOptions`](#publish-options) | - - - | Parameter | Description | Type | @@ -306,14 +270,6 @@ The entire `messages` array is published atomically. This means that: - - -#### Returns - -Returns a promise. On success, the promise resolves. On failure, the promise is rejected with an [`ErrorInfo`](#error-info) object that details the reason why it was rejected. - - - #### Callback result @@ -356,7 +312,7 @@ The function throws `ably.AblyException` if an error has occurred. - + ### history @@ -368,12 +324,6 @@ The function throws `ably.AblyException` if an error has occurred. - - -`history(Object params?): Promise>` - - - `PaginatedResult history(Hash options)` @@ -420,11 +370,11 @@ Gets a [paginated](#paginated-result) set of historical messages for this channe #### Parameters - + | Parameter | Description | Type | |-----------|-------------|------| -| paramsquery[`Param[]`](#param) optionsparams | An optional object containing the query parametersOptional keyword arguments containing the query parametersAn optional set of key value pairs containing the query parametersAn optional Associative Array containing the query parameters, as specified in the [message history API documentation](/docs/api/rest-sdk/history#channel-history) | Object | +| paramsquery[`Param[]`](#param) optionsparams | An optional object containing the query parametersOptional keyword arguments containing the query parametersAn optional set of key value pairs containing the query parametersAn optional Associative Array containing the query parameters, as specified in the [message history API documentation](/docs/api/rest-sdk/history#channel-history) | Object | @@ -437,14 +387,6 @@ Gets a [paginated](#paginated-result) set of historical messages for this channe - - -#### Returns - -Returns a promise. On success, the promise is fulfilled with a [`PaginatedResult`](#paginated-result) object containing an array of messages. On failure, the promise is rejected with an [`ErrorInfo`](#error-info) object that details the reason why it was rejected. - - - #### Callback result @@ -487,14 +429,10 @@ On failure to retrieve message history, the `error` contains an [`ErrorInfo`](#e - + #### getMessage - -`getMessage(serialOrMessage: string | Message): Promise` - - `Message getMessage(String serial)` @@ -513,16 +451,6 @@ See [updating and deleting messages: retrieving the latest version](/docs/messag ##### Parameters - -| Parameter | Description | Type | -|-----------|-------------|------| -| serialOrMessage | Either the serial identifier string of the message to retrieve, or a [`Message`](/docs/api/realtime-sdk/messages) object containing a populated `serial` field | `string` or [`Message`](/docs/api/realtime-sdk/messages) | - -##### Returns - -Returns a promise which, upon success, will be fulfilled with a [`Message`](/docs/api/realtime-sdk/messages) object representing the latest version of the message. Upon failure, the promise will be rejected with an [`ErrorInfo`](/docs/api/realtime-sdk/types#error-info) object which explains the error. - - | Parameter | Description | Type | |-----------|-------------|------| @@ -560,10 +488,6 @@ On failure, the callback receives an [`ARTErrorInfo`](/docs/api/realtime-sdk/typ #### updateMessage - -`updateMessage(message: Message, operation?: MessageOperation, params?: Record): Promise` - - `UpdateDeleteResult updateMessage(Message message, MessageOperation operation)` @@ -586,7 +510,7 @@ See [updating and deleting messages: updates](/docs/messages/updates-deletes#upd ##### Parameters - + | Parameter | Description | Type | |-----------|-------------|------| @@ -607,12 +531,6 @@ See [updating and deleting messages: updates](/docs/messages/updates-deletes#upd - -##### Returns - -Returns a promise which, upon success, will be fulfilled with an [`UpdateDeleteResult`](/docs/api/realtime-sdk/types#update-delete-result) object containing the new version of the message. Upon failure, the promise will be rejected with an [`ErrorInfo`](/docs/api/realtime-sdk/types#error-info) object which explains the error. - - ##### Returns @@ -629,10 +547,6 @@ On failure, the callback receives an [`ARTErrorInfo`](/docs/api/realtime-sdk/typ #### deleteMessage - -`deleteMessage(message: Message, operation?: MessageOperation, params?: Record): Promise` - - `UpdateDeleteResult deleteMessage(Message message, MessageOperation operation)` @@ -651,7 +565,7 @@ See [updating and deleting messages: deletes](/docs/messages/updates-deletes#del ##### Parameters - + | Parameter | Description | Type | |-----------|-------------|------| @@ -672,12 +586,6 @@ See [updating and deleting messages: deletes](/docs/messages/updates-deletes#del - -##### Returns - -Returns a promise which, upon success, will be fulfilled with an [`UpdateDeleteResult`](/docs/api/realtime-sdk/types#update-delete-result) object containing the new version of the message. Upon failure, the promise will be rejected with an [`ErrorInfo`](/docs/api/realtime-sdk/types#error-info) object which explains the error. - - ##### Returns @@ -694,10 +602,6 @@ On failure, the callback receives an [`ARTErrorInfo`](/docs/api/realtime-sdk/typ #### appendMessage - -`appendMessage(message: Message, operation?: MessageOperation, params?: Record): Promise` - - `UpdateDeleteResult appendMessage(Message message, MessageOperation operation)` @@ -718,7 +622,7 @@ See [updating and deleting messages: appends](/docs/messages/updates-deletes#app ##### Parameters - + | Parameter | Description | Type | |-----------|-------------|------| @@ -739,12 +643,6 @@ See [updating and deleting messages: appends](/docs/messages/updates-deletes#app - -##### Returns - -Returns a promise which, upon success, will be fulfilled with an [`UpdateDeleteResult`](/docs/api/realtime-sdk/types#update-delete-result) object containing the new version of the message. Upon failure, the promise will be rejected with an [`ErrorInfo`](/docs/api/realtime-sdk/types#error-info) object which explains the error. - - ##### Returns @@ -761,10 +659,6 @@ On failure, the callback receives an [`ARTErrorInfo`](/docs/api/realtime-sdk/typ #### getMessageVersions - -`getMessageVersions(serialOrMessage: string | Message, params?: Record): Promise>` - - `PaginatedResult getMessageVersions(String serial, Param[] params)` @@ -783,12 +677,12 @@ See [updating and deleting messages: versions](/docs/messages/updates-deletes#ve ##### Parameters - + | Parameter | Description | Type | |-----------|-------------|------| | serialOrMessage | Either the serial identifier string of the message whose versions are to be retrieved, or a [`Message`](/docs/api/realtime-sdk/messages) object containing a populated `serial` field | `string` or [`Message`](/docs/api/realtime-sdk/messages) | -| params | Optional parameters sent as part of the query string | `Record``Param[]` (optional) | +| params | Optional parameters sent as part of the query string | `Param[]` (optional) | @@ -801,12 +695,6 @@ See [updating and deleting messages: versions](/docs/messages/updates-deletes#ve - -##### Returns - -Returns a promise which, upon success, will be fulfilled with a [`PaginatedResult`](#paginated-result) object containing an array of [`Message`](/docs/api/realtime-sdk/messages) objects representing all versions of the message. Upon failure, the promise will be rejected with an [`ErrorInfo`](/docs/api/realtime-sdk/types#error-info) object which explains the error. - - ##### Returns @@ -825,23 +713,16 @@ On failure to retrieve message versions, the callback receives an [`ARTErrorInfo - + -## RestAnnotationsARTRestAnnotationsio.ably.lib.rest.RestAnnotationsRestAnnotations +## ARTRestAnnotationsio.ably.lib.rest.RestAnnotationsRestAnnotations The `RestAnnotations` object, accessed from the [annotations](#channel-annotations) property of a `Channel`, is used to publish, delete, and retrieve [annotations](/docs/messages/annotations) on messages over REST. See the [annotations documentation](/docs/messages/annotations) for an overview of annotation concepts and types. ### RestAnnotations Methods -#### publish - - - -`publish(Message message, Annotation annotation): Promise` - -`publish(String messageSerial, Annotation annotation): Promise` +#### publish - `void publish(Message message, Annotation annotation)` @@ -872,18 +753,11 @@ Publishes an [`Annotation`](/docs/api/realtime-sdk/types#annotation) for a messa | Parameter | Description | Type | |-----------|-------------|------| -| msg_or_serialmessage or messageSerial | The message to annotate, identified either by a [`Message`](#message) instance or by its `serial` | [`ARTMessage`](#message) or `String`[`Message`](#message) or `String` | -| annotation | The annotation to publish. Must include at least the `type` | [`ARTAnnotation`](/docs/api/realtime-sdk/types#annotation)[`Annotation`](/docs/api/realtime-sdk/types#annotation) | - -#### delete - - - -`delete(Message message, Annotation annotation): Promise` +| msg_or_serialmessage or messageSerial | The message to annotate, identified either by a [`Message`](#message) instance or by its `serial` | [`ARTMessage`](#message) or `String`[`Message`](#message) or `String` | +| annotation | The annotation to publish. Must include at least the `type` | [`ARTAnnotation`](/docs/api/realtime-sdk/types#annotation)[`Annotation`](/docs/api/realtime-sdk/types#annotation) | -`delete(String messageSerial, Annotation annotation): Promise` +#### delete - `void delete(Message message, Annotation annotation)` @@ -914,15 +788,8 @@ Publishes an annotation removal request for a message. The `action` is set autom The parameters are the same as for [`publish`](#annotations-publish). -#### get - - - -`get(Message message, GetAnnotationsParams? params): Promise>` - -`get(String messageSerial, GetAnnotationsParams? params): Promise>` +#### get - `PaginatedResult get(Message message, Param[] params)` @@ -957,8 +824,8 @@ Retrieves a [paginated result](#paginated-result) containing all individual [`An | Parameter | Description | Type | |-----------|-------------|------| -| msg_or_serialmessage or messageSerial | The message to retrieve annotations for, identified either by a [`Message`](#message) instance or by its `serial` | [`ARTMessage`](#message) or `String`[`Message`](#message) or `String` | -| queryparams | An optional set of restrictions on which annotations to retrieve, in particular a `limit` | [`GetAnnotationsParams`](/docs/api/realtime-sdk/types#get-annotations-params)[`Param[]`](/docs/api/rest-sdk/types#param)[`ARTAnnotationsQuery`](/docs/api/realtime-sdk/types#annotations-query)`dict` | +| msg_or_serialmessage or messageSerial | The message to retrieve annotations for, identified either by a [`Message`](#message) instance or by its `serial` | [`ARTMessage`](#message) or `String`[`Message`](#message) or `String` | +| queryparams | An optional set of restrictions on which annotations to retrieve, in particular a `limit` | [`Param[]`](/docs/api/rest-sdk/types#param)[`ARTAnnotationsQuery`](/docs/api/realtime-sdk/types#annotations-query)`dict` | ##### Returns @@ -968,47 +835,47 @@ A [`PaginatedResult`](#paginated-result) containing an array of [`Annotation`](/ ## Related types -### MessageARTMessageAbly::Models::MessageAbly\Models\Messageio.ably.lib.types.MessageIO.Ably.Message +### MessageARTMessageAbly::Models::MessageAbly\Models\Messageio.ably.lib.types.MessageIO.Ably.Message A `Message` represents an individual message that is sent to or received from Ably. -#### nameName +#### nameName The event name, if provided.
_Type: `String`_ -#### dataData +#### dataData -The message payload, if provided.
_Type: `String`, `StringBuffer`, `JSON Object``String`, `ByteArray`, `JSONObject`, `JSONArray``String`, `byte[]`, `plain C# object that can be serialized to JSON``String`, `Binary` (ASCII-8BIT String), `Hash`, `Array``String`, `Bytearray`, `Dict`, `List``String`, `Binary String`, `Associative Array`, `Array``NSString *`, `NSData *`, `NSDictionary *`, `NSArray *``String`, `NSData`, `Dictionary`, `Array``String`, `Map`, `List`_ +The message payload, if provided.
_Type: `String`, `StringBuffer`, `JSON Object``String`, `ByteArray`, `JSONObject`, `JSONArray``String`, `byte[]`, `plain C# object that can be serialized to JSON``String`, `Binary` (ASCII-8BIT String), `Hash`, `Array``String`, `Bytearray`, `Dict`, `List``String`, `Binary String`, `Associative Array`, `Array``NSString *`, `NSData *`, `NSDictionary *`, `NSArray *``String`, `NSData`, `Dictionary`, `Array``String`, `Map`, `List`_ -#### extrasExtras +#### extrasExtras -Metadata and/or ancillary payloads, if provided. Valid payloads include [`push`](/docs/push/publish#payload), [`headers`](/docs/pub-sub/advanced#headers) (a map of strings to strings for arbitrary customer-supplied metadata), [`ephemeral`](/docs/pub-sub/advanced#ephemeral), and [`privileged`](/docs/platform/integrations/skip-integrations) objects.
_Type: `JSONObject`, `JSONArray`plain C# object that can be converted to JSON`JSON Object``Hash`, `Array``Dict`, `List``Dictionary`, `Array``NSDictionary *`, `NSArray *``Associative Array`, `Array`_ +Metadata and/or ancillary payloads, if provided. Valid payloads include [`push`](/docs/push/publish#payload), [`headers`](/docs/pub-sub/advanced#headers) (a map of strings to strings for arbitrary customer-supplied metadata), [`ephemeral`](/docs/pub-sub/advanced#ephemeral), and [`privileged`](/docs/platform/integrations/skip-integrations) objects.
_Type: `JSONObject`, `JSONArray`plain C# object that can be converted to JSON`JSON Object``Hash`, `Array``Dict`, `List``Dictionary`, `Array``NSDictionary *`, `NSArray *``Associative Array`, `Array`_ -#### idId +#### idId A Unique ID assigned by Ably to this message.
_Type: `String`_ -#### clientIdClientIdclient_id +#### clientIdClientIdclient_id The client ID of the publisher of this message.
_Type: `String`_ -#### connectionIdConnectionIdconnection_id +#### connectionIdConnectionIdconnection_id The connection ID of the publisher of this message.
_Type: `String`_ -#### connectionKeyConnectionKeyconnection_key +#### connectionKeyConnectionKeyconnection_key A connection key, which can optionally be included for a REST publish as part of the [publishing on behalf of a realtime client functionality](/docs/pub-sub/advanced#publish-on-behalf).
_Type: `String`_ -#### timestampTimestamp +#### timestampTimestamp -Timestamp when the message was first received by the Ably, as milliseconds since the epocha `Time` object.
_Type: `Integer``Long Integer``DateTimeOffset``Time``NSDate`_ +Timestamp when the message was first received by the Ably, as milliseconds since the epocha `Time` object.
_Type: `Integer``Long Integer``DateTimeOffset``Time``NSDate`_ -#### encodingEncoding +#### encodingEncoding This will typically be empty as all messages received from Ably are automatically decoded client-side using this value. However, if the message encoding cannot be processed, this attribute will contain the remaining transformations not applied to the `data` payload.
_Type: `String`_ - + ### action @@ -1064,15 +931,9 @@ A static factory method to create an array of [`Messages`](/docs/api/realtime-sd An `Array` of [`Message`](/docs/api/realtime-sdk/types#message) objects -### ChannelOptions ObjectARTChannelOptionsChannelOptions HashChannelOptions keyword argumentsChannelOptions Arrayio.ably.lib.types.ChannelOptionsIO.Ably.ChannelOptions - -Channel options are used for setting [channel parameters](/docs/channels/options) and [configuring encryption](/docs/channels/options/encryption). - - - -`ChannelOptions`, a plain JavaScript object, may optionally be specified when instancing a [`Channel`](/docs/channels), and this may be used to specify channel-specific options. The following attributes can be defined on the object: +### ChannelOptions ObjectARTChannelOptionsChannelOptions HashChannelOptions keyword argumentsChannelOptions Arrayio.ably.lib.types.ChannelOptionsIO.Ably.ChannelOptions - +Channel options are used for setting [channel parameters](/docs/channels/options) and [configuring encryption](/docs/channels/options/encryption). @@ -1098,22 +959,22 @@ Channel options are used for -#### PropertiesMembersAttributes +#### MembersAttributes | Parameter | Description | Type | |-----------|-------------|------| -| :cipherCipherParamscipher | Requests encryption for this channel when not null, and specifies encryption-related parameters (such as algorithm, chaining mode, key length and key). See [an example](/docs/channels/options/encryption) | [`CipherParams`](/docs/api/realtime-sdk/encryption#cipher-params) or an options object containing at a minimum a `key` or a `Param[]` list containing at a minimum a `key` or an options hash containing at a minimum a `key` or an Associative Array containing at a minimum a `key` | +| :cipherCipherParamscipher | Requests encryption for this channel when not null, and specifies encryption-related parameters (such as algorithm, chaining mode, key length and key). See [an example](/docs/channels/options/encryption) | [`CipherParams`](/docs/api/realtime-sdk/encryption#cipher-params) or an options object containing at a minimum a `key` or a `Param[]` list containing at a minimum a `key` or an options hash containing at a minimum a `key` or an Associative Array containing at a minimum a `key` | - + | Parameter | Description | Type | |-----------|-------------|------| -| paramsParams | Optional [parameters](/docs/channels/options) which specify behaviour of the channel | `Map``JSON Object` | -| cipherCipherParams | Requests encryption for this channel when not null, and specifies encryption-related parameters (such as algorithm, chaining mode, key length and key). See [an example](/docs/api/realtime-sdk/encryption#getting-started) | [`CipherParams`](/docs/api/realtime-sdk/encryption#cipher-params) or an options object containing at a minimum a `key` or a `Param[]` list containing at a minimum a `key` or an options hash containing at a minimum a `key` or an Associative Array containing at a minimum a `key` | +| paramsParams | Optional [parameters](/docs/channels/options) which specify behaviour of the channel | `Map``JSON Object` | +| cipherCipherParams | Requests encryption for this channel when not null, and specifies encryption-related parameters (such as algorithm, chaining mode, key length and key). See [an example](/docs/api/realtime-sdk/encryption#getting-started) | [`CipherParams`](/docs/api/realtime-sdk/encryption#cipher-params) or a `Param[]` list containing at a minimum a `key` or an options hash containing at a minimum a `key` or an Associative Array containing at a minimum a `key` | @@ -1139,20 +1000,6 @@ On success, the method returns a complete `ChannelOptions` object. Failure will - - -### PublishOptions - -Options passed to a [`publish()`](#publish) operation to customize its behavior. - -#### Parameters - -| Parameter | Description | Type | -|-----------|-------------|------| -| quickAck | Reduces the latency of REST publishes, though provides a [slightly lower quality of service](https://faqs.ably.com/why-are-some-rest-publishes-on-a-channel-slow-and-then-typically-faster-on-subsequent-publishes) | `Boolean` | - - - ### PaginatedRequestParams @@ -1171,25 +1018,19 @@ Options passed to a [`publish()`](#publish) operation to customize its behavior. -### PaginatedResultARTPaginatedResultAbly::Models::PaginatedResultAbly\Models\PaginatedResultio.ably.lib.types.PaginatedResultIO.Ably.PaginatedResult +### PaginatedResultARTPaginatedResultAbly::Models::PaginatedResultAbly\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](/docs/api/rest-api/#pagination) is accompanied by metadata that indicates the relative queries available to the `PaginatedResult` object. -#### PropertiesMembersAttributes +#### MembersAttributes | Property | Description | Type | |----------|-------------|------| -| itemsItems | contains the current page of results (for example an Array of [`Message`](#message) or [`PresenceMessage`](#presence-message) objects for a channel history request) | `Array ``List ` | +| itemsItems | contains the current page of results (for example an Array of [`Message`](#message) or [`PresenceMessage`](#presence-message) objects for a channel history request) | `Array ``List ` | #### Methods -##### firstFirst - - - -`first(): Promise` - - +##### firstFirst @@ -1238,15 +1079,10 @@ A `PaginatedResult` is a type that represents a page of results for all message Returns a new `PaginatedResult` for the first page of results. When using the Realtime library, the `first` method returns a [Deferrable](/docs/api/realtime-sdk/types#deferrable) and yields a [`PaginatedResult`](#paginated-result).The method is asynchronous and returns a Task which needs to be awaited to get the [`PaginatedResult`](#paginated-result). - -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`](/docs/api/realtime-sdk/types#error-info) object that details the reason why it was rejected. - - +##### hasNextHasNexthas_next?has_next -##### hasNextHasNexthas_next?has_next - - + `Boolean hasNext()` @@ -1270,11 +1106,11 @@ Returns a promise. On success, the promise is fulfilled with a new `PaginatedRes -Returns `true` if there are more pages available by calling `next``Next` and returns `false` if this page is the last page available. +Returns `true` if there are more pages available by calling `next``Next` and returns `false` if this page is the last page available. -##### isLastIsLastlast?is_last +##### isLastIsLastlast?is_last - + `Boolean isLast()` @@ -1298,15 +1134,9 @@ Returns `true` if there are more pages available by calling `next``Next` available. - -##### nextNext - - - -`next(): Promise` +Returns `true` if this page is the last page and returns `false` if there are more pages available by calling `next``Next` available. - +##### nextNext @@ -1350,48 +1180,10 @@ Returns `true` if this page is the last page and returns `false` if there are mo -Returns a new `PaginatedResult` loaded with the next page of results. If there are no further pages, then `null`a blank PaginatedResult will be returned`Null``None``nil` is returned. The method is asynchronous and return a Task which needs to be awaited to get the `PaginatedResult`When using the Realtime library, the `first` method returns a [Deferrable](/docs/api/realtime-sdk/types#deferrable) and yields a [`PaginatedResult`](#paginated-result). - - - -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`](/docs/api/realtime-sdk/types#error-info) object that details the reason why it was rejected. - -##### current - -`current(): Promise` - -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`](/docs/api/realtime-sdk/types#error-info) object that details the reason why it was rejected. - - +Returns a new `PaginatedResult` loaded with the next page of results. If there are no further pages, then `null`a blank PaginatedResult will be returned`Null``None``nil` is returned. The method is asynchronous and return a Task which needs to be awaited to get the `PaginatedResult`When using the Realtime library, the `first` method returns a [Deferrable](/docs/api/realtime-sdk/types#deferrable) and yields a [`PaginatedResult`](#paginated-result). ##### Example - - - -```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()); -``` - - - - - - -```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()); -``` - - - diff --git a/src/pages/docs/api/rest-sdk/encryption.mdx b/src/pages/docs/api/rest-sdk/encryption.mdx index 5c6191c113..b89331db37 100644 --- a/src/pages/docs/api/rest-sdk/encryption.mdx +++ b/src/pages/docs/api/rest-sdk/encryption.mdx @@ -19,17 +19,11 @@ redirect_from: We've updated the style and readability of our API references, starting with JavaScript. Check out the [Pub/Sub JavaScript SDK API references](/docs/pub-sub/api/javascript/rest/crypto) in their new location. -The `Ably.Rest.Crypto``Ably::Util::Crypto``Ably\Utils\Crypto``ably.util.crypto``io.ably.lib.util.crypto``ARTCrypto``IO.Ably.Encryption.Crypto` object exposes the following public methods: +The `Ably.Rest.Crypto``Ably::Util::Crypto``Ably\Utils\Crypto``ably.util.crypto``io.ably.lib.util.crypto``ARTCrypto``IO.Ably.Encryption.Crypto` object exposes the following public methods: ## Methods -### getDefaultParamsget_default_paramsget_default_paramsGetDefaultParamsDefaultCipherParams - - - -`Crypto.getDefaultParams(Object params): CipherParams` - - +### getDefaultParamsget_default_paramsget_default_paramsGetDefaultParamsDefaultCipherParams @@ -73,48 +67,26 @@ The `Ably.Rest.Crypto``Ably -This call obtains a [`CipherParams`](#cipher-params) object using the values passed in (which must be a subset of `CipherParams` fields that at a minimum includes a `key`), filling in any unspecified fields with default values, and checks that the result is a valid and self-consistent.This call takes a key, an initialization vector (iv) and a Cipher mode. There is also on override which accepts the `key` and `iv` as base64 encoded strings. It will validate the passed values and generate `CipherParams`returns a [`CipherParams`](#cipher-params) object with fields set to default values. This generates random secret key and initialization vector (iv) values.

+This call obtains a [`CipherParams`](#cipher-params) object using the values passed in (which must be a subset of `CipherParams` fields that at a minimum includes a `key`), filling in any unspecified fields with default values, and checks that the result is a valid and self-consistent.This call takes a key, an initialization vector (iv) and a Cipher mode. There is also on override which accepts the `key` and `iv` as base64 encoded strings. It will validate the passed values and generate `CipherParams`returns a [`CipherParams`](#cipher-params) object with fields set to default values. This generates random secret key and initialization vector (iv) values.

-You will rarely need to call this yourself, since the client library will handle it for you if you specify `cipher` params when initializing a channel (as in the example [at the top](/docs/channels/options/encryption)) or when setting channel options with `channel#setOptions`. +You will rarely need to call this yourself, since the client library will handle it for you if you specify `cipher` params when initializing a channel (as in the example [at the top](/docs/channels/options/encryption)). - + #### Parameters | Parameter | Description | Type | |-----------|-------------|------| -| paramsarguments | The cipher paramsarguments that you want to specify. It must at a minimum include a `key`, which should be either a binary (`byte[]``ArrayBuffer` or `Uint8Array``Buffer`byte array`NSData`) or a base64-encoded `NS``String`. | Object | +| paramsarguments | The cipher paramsarguments that you want to specify. It must at a minimum include a `key`, which should be either a binary (`byte[]`byte array`NSData`) or a base64-encoded `NS``String`. | Object | #### Returns -On success, the method returns a complete [`CipherParams`](#cipher-params) object. Failure will raise an [`AblyException`](/docs/api/rest-sdk/types#ably-exception)exception. +On success, the method returns a complete [`CipherParams`](#cipher-params) object. Failure will raise an [`AblyException`](/docs/api/rest-sdk/types#ably-exception)exception. #### Example - - - -```javascript -const cipherParams = Ably.Rest.Crypto.getDefaultParams({ key: }); -const channelOpts = { cipher: cipherParams }; -const channel = rest.channels.get('{{RANDOM_CHANNEL_NAME}}', channelOpts); -``` - - - - - - -```nodejs -const cipherParams = Ably.Rest.Crypto.getDefaultParams({ key: }); -const channelOpts = { cipher: cipherParams }; -const channel = rest.channels.get('{{RANDOM_CHANNEL_NAME}}', channelOpts); -``` - - - @@ -202,18 +174,8 @@ params, err := Crypto.DefaultCipherParams() -### generateRandomKeygenerate_random_keygenerate_random_keyGenerateRandomKey - - - -`Crypto.generateRandomKey(Number keyLength?): Promise` - - - - -`Crypto.generateRandomKey(Number keyLength?): Promise` +### generateRandomKeygenerate_random_keygenerate_random_keyGenerateRandomKey - `byte array Crypto.generate_random_key(Int key_length?)` @@ -254,11 +216,11 @@ This call obtains a randomly-generated binary key of the specified key length + | Parameter | Description | Type | |-----------|-------------|------| -| keyLengthkey_length | Optional with the length of key to generate. For AES, this should be either 128 or 256. If unspecified, defaults to 256. | numberInt | +| keyLengthkey_length | Optional with the length of key to generate. For AES, this should be either 128 or 256. If unspecified, defaults to 256. | Int | @@ -271,13 +233,6 @@ This call obtains a randomly-generated binary key of the specified key length - - -#### Returns - -Returns a promise. On success, the promise is fulfilled with the generated key as an `ArrayBuffer`a `Buffer`. On failure, the promise is rejected with an [`ErrorInfo`](/docs/api/rest-sdk/types#error-info) object that details the reason why it was rejected. - - #### Returns @@ -288,16 +243,6 @@ On success, the method returns the generated key as a `byte[]` a #### Example - - - -```javascript -const key = await Ably.Rest.Crypto.generateRandomKey(256); -const channel = rest.channels.get('{{RANDOM_CHANNEL_NAME}}', { cipher: { key: key } }); -``` - - - @@ -384,15 +329,10 @@ key, err := Crypto.GenerateRandonKey(256) ## Related types -### ChannelOptions ObjectARTChannelOptionsChannelOptions HashChannelOptions DictChannelOptions ArrayIO.Ably.ChannelOptionsio.ably.lib.types.ChannelOptions - -Channel options are used for setting [channel parameters](/docs/channels/options) and [configuring encryption](/docs/channels/options/encryption). +### ChannelOptions ObjectARTChannelOptionsChannelOptions HashChannelOptions DictChannelOptions ArrayIO.Ably.ChannelOptionsio.ably.lib.types.ChannelOptions - +Channel options are used for setting [channel parameters](/docs/channels/options) and [configuring encryption](/docs/channels/options/encryption). -`ChannelOptions`, a plain JavaScript object, may optionally be specified when instancing a [`Channel`](/docs/channels), and this may be used to specify channel-specific options. The following attributes can be defined on the object: - - `ChannelOptions`, a Hash object, may optionally be specified when instancing a [`Channel`](/docs/channels), and this may be used to specify channel-specific options. The following key symbol values can be added to the Hash: @@ -414,7 +354,7 @@ Channel options are used for -#### PropertiesMembers +#### PropertiesMembers @@ -424,12 +364,12 @@ Channel options are used for - + | Property | Description | Type | |----------|-------------|------| -| paramsParams | Optional [parameters](/docs/channels/options) which specify behaviour of the channel. | `Map``JSON Object` | -| cipherCipherParams | Requests encryption for this channel when not null, and specifies encryption-related parameters (such as algorithm, chaining mode, key length and key). See [an example](/docs/api/realtime-sdk/encryption#getting-started) | [`CipherParams`](/docs/api/realtime-sdk/encryption#cipher-params) or an options object containing at a minimum a `key` or a [`Param[]`](#param) list containing at a minimum a `key` | +| paramsParams | Optional [parameters](/docs/channels/options) which specify behaviour of the channel. | `Map``JSON Object` | +| cipherCipherParams | Requests encryption for this channel when not null, and specifies encryption-related parameters (such as algorithm, chaining mode, key length and key). See [an example](/docs/api/realtime-sdk/encryption#getting-started) | [`CipherParams`](/docs/api/realtime-sdk/encryption#cipher-params) or a [`Param[]`](#param) list containing at a minimum a `key` | @@ -457,22 +397,22 @@ On success, the method returns a complete `ChannelOptions` object. Failure will -### CipherParamsARTCipherParamsCipherParams HashCipherParams DictCipherParams ArrayIO.Ably.CipherParamsio.ably.lib.util.Crypto.CipherParams +### CipherParamsARTCipherParamsCipherParams HashCipherParams DictCipherParams ArrayIO.Ably.CipherParamsio.ably.lib.util.Crypto.CipherParams A `CipherParams` contains configuration options for a channel cipher, including algorithm, mode, key length and key. Ably client libraries currently support AES with CBC, PKCS#7 with a default key length of 256 bits. All implementations also support AES128. -Individual client libraries may support either instancing a `CipherParams` directly, using [`Crypto.getDefaultParams()`](/docs/api/realtime-sdk/encryption#get-default-params)[`Crypto.GetDefaultParams()`](/docs/api/realtime-sdk/encryption#get-default-params)[`Crypto.get_default_params()`](/docs/api/realtime-sdk/encryption#get-default-params), or generating one automatically when initializing a channel, as in [this example](/docs/channels/options/encryption). +Individual client libraries may support either instancing a `CipherParams` directly, using [`Crypto.getDefaultParams()`](/docs/api/realtime-sdk/encryption#get-default-params)[`Crypto.GetDefaultParams()`](/docs/api/realtime-sdk/encryption#get-default-params)[`Crypto.get_default_params()`](/docs/api/realtime-sdk/encryption#get-default-params), or generating one automatically when initializing a channel, as in [this example](/docs/channels/options/encryption). -#### PropertiesMembers +#### PropertiesMembers - + | Property | Description | Type | |----------|-------------|------| -| keyKey:key | A binary (`byte[]``ArrayBuffer` or `Uint8Array``Buffer`byte array`NSData`) or base64-encoded `NS``String` containing the secret key used for encryption and decryption | | -| algorithm:algorithmAlgorithm | The name of the algorithm in the default system provider, or the lower-cased version of it; eg "aes" or "AES"
default: _AES_ | `String` | -| key_length:key_lengthkeyLengthKeyLength | The key length in bits of the cipher, either 128 or 256
default: _256_ | `Integer` | -| modeMode | The cipher mode
default: _CBC_ | `String``CipherMode` | +| keyKey:key | A binary (`byte[]`byte array`NSData`) or base64-encoded `NS``String` containing the secret key used for encryption and decryption | | +| algorithm:algorithmAlgorithm | The name of the algorithm in the default system provider, or the lower-cased version of it; eg "aes" or "AES"
default: _AES_ | `String` | +| key_length:key_lengthkeyLengthKeyLength | The key length in bits of the cipher, either 128 or 256
default: _256_ | `Integer` | +| modeMode | The cipher mode
default: _CBC_ | `String``CipherMode` | diff --git a/src/pages/docs/api/rest-sdk/history.mdx b/src/pages/docs/api/rest-sdk/history.mdx index f187ea584c..8c8d1d661f 100644 --- a/src/pages/docs/api/rest-sdk/history.mdx +++ b/src/pages/docs/api/rest-sdk/history.mdx @@ -24,13 +24,8 @@ The [Rest `Channel` object](/docs/channels) exposes the following public method ### Methods -### historyHistory +### historyHistory - - -`history(Object params?): Promise>` - - `PaginatedResult history(Hash option)` @@ -71,11 +66,11 @@ Gets a [paginated](#paginated-result) set of historical messages for this channe #### Parameters - + | Parameter | Description | Type | |-----------|-------------|------| -| paramsqueryoptionoption | an optional object containing the query parametersoptional keyword arguments containing the query parametersan optional set of key value pairs containing the query parametersan Associate Array containing the query parametersan optional object containing the query parameters, as specified below. | Object[`Param[]`](#param)[`PaginatedRequestParams`](#paginated-request-params)Object | +| queryoptionoption | optional keyword arguments containing the query parametersan optional set of key value pairs containing the query parametersan Associate Array containing the query parametersan optional object containing the query parameters, as specified below. | [`Param[]`](#param)[`PaginatedRequestParams`](#paginated-request-params)Object | @@ -88,22 +83,14 @@ Gets a [paginated](#paginated-result) set of historical messages for this channe -#### `params` parameters`ARTDataQuery` properties[`PaginatedRequestParams`](#paginated-request-params) properties`options` parameters +#### `ARTDataQuery` properties[`PaginatedRequestParams`](#paginated-request-params) properties`options` parameters | Parameter | Description | Type | |-----------|-------------|------| -| start:startStartstart | _beginning of time_ earliest `DateTimeOffset` or `Time` or time in milliseconds since the epoch for any messages retrieved | `Number``Int` or `Time``DateTimeOffset``Long`Long | -| end:endEndend | _current time_ latest `DateTimeOffset` or `Time` or time in milliseconds since the epoch for any messages retrieved | `Number``Int` or `Time``DateTimeOffset``Long`Long | -| direction:directionDirectiondirection | _backwards_ `:forwards` or `:backwards``forwards` or `backwards`forwards or backwards | `String``Symbol``Direction` enum | -| limit:limitLimitlimit | _100_ maximum number of messages to retrieve per page, up to 1,000 | `Number``Integer` | - - - -#### Returns - -Returns a promise. On success, the promise is fulfilled with a [`PaginatedResult`](#paginated-result) encapsulating an array of [`Message`](#message) 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`](/docs/api/realtime-sdk/types#error-info) object that details the reason why it was rejected. - - +| start:startStartstart | _beginning of time_ earliest `DateTimeOffset` or `Time` or time in milliseconds since the epoch for any messages retrieved | `Int` or `Time``DateTimeOffset``Long`Long | +| end:endEndend | _current time_ latest `DateTimeOffset` or `Time` or time in milliseconds since the epoch for any messages retrieved | `Int` or `Time``DateTimeOffset``Long`Long | +| direction:directionDirectiondirection | _backwards_ `:forwards` or `:backwards``forwards` or `backwards`forwards or backwards | `String``Symbol``Direction` enum | +| limit:limitLimitlimit | _100_ maximum number of messages to retrieve per page, up to 1,000 | `Integer` | @@ -153,13 +140,8 @@ Failure to retrieve the message history will raise an [`AblyException`](/docs/ap ### Methods -### historyHistory - - +### historyHistory -`history(Object params?): Promise>` - - `PaginatedResult history(Hash option)` @@ -200,11 +182,11 @@ Gets a [paginated](#paginated-result) set of historical presence events for this #### Parameters - + | Parameter | Description | Type | |-----------|-------------|------| -| paramsoption[`PaginatedRequestParams`](#paginated-request-params) queryoption | an optional object containing the query parametersoptional keyword arguments containing the query parametersan optional set of key value pairs containing the query parametersan Associate Array containing the query parameters, as specified below. | Object[`Param[]`](#param)[`PaginatedRequestParams`](#paginated-request-params)Object | +| option[`PaginatedRequestParams`](#paginated-request-params) queryoption | an optional object containing the query parametersoptional keyword arguments containing the query parametersan optional set of key value pairs containing the query parametersan Associate Array containing the query parameters, as specified below. | [`Param[]`](#param)[`PaginatedRequestParams`](#paginated-request-params)Object | @@ -217,22 +199,14 @@ Gets a [paginated](#paginated-result) set of historical presence events for this -#### `params` parameters`ARTDataQuery` properties[`PaginatedRequestParams`](#paginated-request-params) properties`options` parameters +#### `ARTDataQuery` properties[`PaginatedRequestParams`](#paginated-request-params) properties`options` parameters | Parameter | Description | Type | |-----------|-------------|------| -| start:startStartstart | _beginning of time_ earliest `DateTimeOffset` or `Time` or time in milliseconds since the epoch for any presence events retrieved | `Number``Int` or `Time``DateTimeOffset``Long`Long | -| end:endEndend | _current time_ latest `DateTimeOffset` or `Time` or time in milliseconds since the epoch for any presence events retrieved | `Number``Int` or `Time``DateTimeOffset``Long`Long | -| direction:directionDirectiondirection | _backwards_ `:forwards` or `:backwards``forwards` or `backwards`forwards or backwards | `String``Symbol``Direction` enum | -| limit:limitLimitlimit | _100_ maximum number of presence events to retrieve up to 1,000 | `Number``Integer` | - - - -#### Returns - -Returns a promise. On success, the promise is fulfilled with a [`PaginatedResult`](#paginated-result) encapsulating an array of [`PresenceMessage`](#presence-message) 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`](/docs/api/realtime-sdk/types#error-info) object that details the reason why it was rejected. - - +| start:startStartstart | _beginning of time_ earliest `DateTimeOffset` or `Time` or time in milliseconds since the epoch for any presence events retrieved | `Int` or `Time``DateTimeOffset``Long`Long | +| end:endEndend | _current time_ latest `DateTimeOffset` or `Time` or time in milliseconds since the epoch for any presence events retrieved | `Int` or `Time``DateTimeOffset``Long`Long | +| direction:directionDirectiondirection | _backwards_ `:forwards` or `:backwards``forwards` or `backwards`forwards or backwards | `String``Symbol``Direction` enum | +| limit:limitLimitlimit | _100_ maximum number of presence events to retrieve up to 1,000 | `Integer` | @@ -278,62 +252,46 @@ Failure to retrieve the presence event history will raise an [`AblyException`](/ ## Related types -### MessageARTMessageAbly::Models::Message Enumio.ably.lib.types.MessageIO.Ably.Message +### MessageARTMessageAbly::Models::Message Enumio.ably.lib.types.MessageIO.Ably.Message A `Message` represents an individual message that is sent to or received from Ably. -### nameName +### nameName The event name, if provided.
_Type: `String`_ -### dataData +### dataData -The message payload, if provided.
_Type: `String`, `StringBuffer`, `JSON Object``String`, `ByteArray`, `JSONObject`, `JSONArray``String`, `byte[]`, `plain C# object that can be serialized to JSON``String`, `Binary` (ASCII-8BIT String), `Hash`, `Array``String`, `Bytearray`, `Dict`, `List``String`, `Binary String`, `Associative Array`, `Array``NSString *`, `NSData *`, `NSDictionary *`, `NSArray *``String`, `NSData`, `Dictionary`, `Array`_ +The message payload, if provided.
_Type: `String`, `StringBuffer`, `JSON Object``String`, `ByteArray`, `JSONObject`, `JSONArray``String`, `byte[]`, `plain C# object that can be serialized to JSON``String`, `Binary` (ASCII-8BIT String), `Hash`, `Array``String`, `Bytearray`, `Dict`, `List``String`, `Binary String`, `Associative Array`, `Array``NSString *`, `NSData *`, `NSDictionary *`, `NSArray *``String`, `NSData`, `Dictionary`, `Array`_ -### extrasExtras +### extrasExtras -Metadata and/or ancillary payloads, if provided. Valid payloads include [`push`](/docs/push/publish#payload), `headers` (a map of strings to strings for arbitrary customer-supplied metadata), [`ephemeral`](/docs/pub-sub/advanced#ephemeral), and [`privileged`](/docs/platform/integrations/skip-integrations) objects.
_Type: `JSONObject`, `JSONArray`plain C# object that can be converted to JSON`JSON Object``Hash`, `Array``Dict`, `List``Dictionary`, `Array``NSDictionary *`, `NSArray *``Associative Array`, `Array``String`, `[]byte`_ +Metadata and/or ancillary payloads, if provided. Valid payloads include [`push`](/docs/push/publish#payload), `headers` (a map of strings to strings for arbitrary customer-supplied metadata), [`ephemeral`](/docs/pub-sub/advanced#ephemeral), and [`privileged`](/docs/platform/integrations/skip-integrations) objects.
_Type: `JSONObject`, `JSONArray`plain C# object that can be converted to JSON`Hash`, `Array``Dict`, `List``Dictionary`, `Array``NSDictionary *`, `NSArray *``Associative Array`, `Array``String`, `[]byte`_ -### idId +### idId A Unique ID assigned by Ably to this message.
_Type: `String`_ -### clientIdclient_idClientId +### clientIdclient_idClientId The client ID of the publisher of this message.
_Type: `String`_ -### connectionIdconnection_idConnectionId +### connectionIdconnection_idConnectionId The connection ID of the publisher of this message.
_Type: `String`_ -### connectionKeyConnectionKeyconnection_key +### connectionKeyConnectionKeyconnection_key A connection key, which can optionally be included for a REST publish as part of the [publishing on behalf of a realtime client functionality](/docs/pub-sub/advanced#publish-on-behalf).
_Type: `String`_ -### timestampTimestamp +### timestampTimestamp -Timestamp when the message was first received by the Ably, as milliseconds since the epocha `Time` object.
_Type: `Integer``Long Integer``DateTimeOffset``Time``NSDate`Integer_ +Timestamp when the message was first received by the Ably, as milliseconds since the epocha `Time` object.
_Type: `Integer``Long Integer``DateTimeOffset``Time``NSDate`Integer_ -### encodingEncoding +### encodingEncoding This will typically be empty as all messages received from Ably are automatically decoded client-side using this value. However, if the message encoding cannot be processed, this attribute will contain the remaining transformations not applied to the `data` payload.
_Type: `String`_ - - -### action - -The action type of the message, one of the [`MessageAction`](/docs/api/realtime-sdk/types#message-action) enum values.
_Type: `int enum { MESSAGE_CREATE, MESSAGE_UPDATE, MESSAGE_DELETE, META, MESSAGE_SUMMARY }`_ - -### serial - -A server-assigned identifier that will be the same in all future updates of this message. It can be used to add annotations to a message. Serial will only be set if you enable annotations in [rules](/docs/channels#rules).
_Type: `String`_ - -### annotations - -An object containing information about annotations that have been made to the object.
_Type: [`MessageAnnotations`](/docs/api/realtime-sdk/types#message-annotations)_ - - - ### Message constructors #### Message.fromEncoded @@ -370,22 +328,22 @@ A static factory method to create an array of [`Messages`](/docs/api/realtime-sd An `Array` of [`Message`](/docs/api/realtime-sdk/types#message) objects -### PresenceMessageARTPresenceMessageAbly::Models::PresenceMessage Enumio.ably.lib.types.PresenceMessageIO.Ably.PresenceMessage +### PresenceMessageARTPresenceMessageAbly::Models::PresenceMessage Enumio.ably.lib.types.PresenceMessageIO.Ably.PresenceMessage A `PresenceMessage` represents an individual presence update that is sent to or received from Ably. -#### PropertiesMembersAttributes +#### PropertiesMembersAttributes | Property | Description | Type | |----------|-------------|------| -| actionActionAction | the event signified by a PresenceMessage. See [`PresenceMessage.action`](/docs/api/realtime-sdk/types#presence-action)the event signified by a PresenceMessage. See [`PresenceMessage.action`](/docs/api/realtime-sdk/types#presence-action)the event signified by a PresenceMessage. See [`Presence action`](/docs/api/realtime-sdk/types#presence-action)the event signified by a PresenceMessage. See [`PresenceAction`](/docs/api/realtime-sdk/types#presence-action)the event signified by a PresenceMessage. See [`PresenceMessage::ACTION`](/docs/api/realtime-sdk/types#presence-action)the event signified by a PresenceMessage. See [`PresenceMessage::ACTION`](/docs/api/realtime-sdk/types#presence-action)the event signified by a PresenceMessage. See [`PresenceMessage.action`](/docs/api/realtime-sdk/types#presence-action)the event signified by a PresenceMessage. See [`PresenceMessage::action`](/docs/api/realtime-sdk/types#presence-action) | `enum { ABSENT, PRESENT, ENTER, LEAVE, UPDATE }``enum { Absent, Present, Enter, Leave, Update }``int enum { ABSENT, PRESENT, ENTER, LEAVE, UPDATE }``int enum { ABSENT, PRESENT, ENTER, LEAVE, UPDATE }``enum { :absent, :present, :enter, :leave, :update }``const PresenceMessage::ABSENT,PRESENT,ENTER,LEAVE,UPDATE``ARTPresenceAction``const PresenceMessage::PresenceAbsent,PresencePresent,PresenceEnter,PresenceLeave,PresenceUpdate` | -| dataData | The presence update payload, if provided | `String`, `ByteArray`, `JSONObject`, `JSONArray``String`, `byte[]`, plain C# object that can be converted to Json`String`, `StringBuffer`, `JSON Object``String`, `[]byte``String`, `Binary` (ASCII-8BIT String), `Hash`, `Array``String`, `Bytearray`, `Dict`, `List``String`, `NSData`, `Dictionary`, `Array``NSString *`, `NSData *`, `NSDictionary *`, `NSArray *``String`, `Binary String`, `Associative Array`, `Array` | -| extrasExtras | Metadata and/or ancillary payloads, if provided. The only currently valid payloads for extras are the [`push`](/docs/push/publish#sub-channels), [`ref`](/docs/messages#interactions) and [`privileged`](/docs/platform/integrations/skip-integrations) objects. | `JSONObject`, `JSONArray`plain C# object that can be converted to Json`String`, `[]byte``JSON Object``Hash`, `Array``Dict`, `List``Dictionary`, `Array``NSDictionary *`, `NSArray *``Associative Array`, `Array` | -| idId | Unique ID assigned by Ably to this presence update | `String` | -| clientIdclient_idClientId | The client ID of the publisher of this presence update | `String` | -| connectionIdconnection_idConnectionId | The connection ID of the publisher of this presence update | `String` | -| timestampTimestamp | Timestamp when the presence update was received by Ably, as milliseconds since the epoch. | `Integer``Long Integer``DateTimeOffset``Time``NSDate`Integer | -| encodingEncoding | This will typically be empty as all presence updates received from Ably are automatically decoded client-side using this value. However, if the message encoding cannot be processed, this attribute will contain the remaining transformations not applied to the `data` payload | `String` | +| actionActionAction | the event signified by a PresenceMessage. See [`PresenceMessage.action`](/docs/api/realtime-sdk/types#presence-action)the event signified by a PresenceMessage. See [`PresenceMessage.action`](/docs/api/realtime-sdk/types#presence-action)the event signified by a PresenceMessage. See [`PresenceAction`](/docs/api/realtime-sdk/types#presence-action)the event signified by a PresenceMessage. See [`PresenceMessage::ACTION`](/docs/api/realtime-sdk/types#presence-action)the event signified by a PresenceMessage. See [`PresenceMessage::ACTION`](/docs/api/realtime-sdk/types#presence-action)the event signified by a PresenceMessage. See [`PresenceMessage.action`](/docs/api/realtime-sdk/types#presence-action)the event signified by a PresenceMessage. See [`PresenceMessage::action`](/docs/api/realtime-sdk/types#presence-action) | `enum { ABSENT, PRESENT, ENTER, LEAVE, UPDATE }``enum { Absent, Present, Enter, Leave, Update }``int enum { ABSENT, PRESENT, ENTER, LEAVE, UPDATE }``enum { :absent, :present, :enter, :leave, :update }``const PresenceMessage::ABSENT,PRESENT,ENTER,LEAVE,UPDATE``ARTPresenceAction``const PresenceMessage::PresenceAbsent,PresencePresent,PresenceEnter,PresenceLeave,PresenceUpdate` | +| dataData | The presence update payload, if provided | `String`, `ByteArray`, `JSONObject`, `JSONArray``String`, `byte[]`, plain C# object that can be converted to Json`String`, `[]byte``String`, `Binary` (ASCII-8BIT String), `Hash`, `Array``String`, `Bytearray`, `Dict`, `List``String`, `NSData`, `Dictionary`, `Array``NSString *`, `NSData *`, `NSDictionary *`, `NSArray *``String`, `Binary String`, `Associative Array`, `Array` | +| extrasExtras | Metadata and/or ancillary payloads, if provided. The only currently valid payloads for extras are the [`push`](/docs/push/publish#sub-channels), [`ref`](/docs/messages#interactions) and [`privileged`](/docs/platform/integrations/skip-integrations) objects. | `JSONObject`, `JSONArray`plain C# object that can be converted to Json`String`, `[]byte``Hash`, `Array``Dict`, `List``Dictionary`, `Array``NSDictionary *`, `NSArray *``Associative Array`, `Array` | +| idId | Unique ID assigned by Ably to this presence update | `String` | +| clientIdclient_idClientId | The client ID of the publisher of this presence update | `String` | +| connectionIdconnection_idConnectionId | The connection ID of the publisher of this presence update | `String` | +| timestampTimestamp | Timestamp when the presence update was received by Ably, as milliseconds since the epoch. | `Integer``Long Integer``DateTimeOffset``Time``NSDate`Integer | +| encodingEncoding | This will typically be empty as all presence updates received from Ably are automatically decoded client-side using this value. However, if the message encoding cannot be processed, this attribute will contain the remaining transformations not applied to the `data` payload | `String` | ### PresenceMessage constructors @@ -423,44 +381,7 @@ A static factory method to create an array of [`PresenceMessages`](/docs/api/rea An `Array` of [`PresenceMessage`](/docs/api/realtime-sdk/types#presence-message) objects -### Presence actionPresenceActionARTPresenceActionio.ably.lib.types.PresenceMessage.ActionAbly::Models::PresenceMessage::ACTIONIO.Ably.PresenceAction - - - -`Presence` `action` is a String with a value matching any of the [`Realtime Presence` states & events](/docs/presence-occupancy/presence#trigger-events). - - - - -```javascript - var PresenceActions = [ - 'absent', // (reserved for internal use) - 'present', - 'enter', - 'leave', - 'update' - ] -``` - - - - - - -```nodejs - var PresenceActions = [ - 'absent', // (reserved for internal use) - 'present', - 'enter', - 'leave', - 'update' - ] -``` - - - - - +### Presence actionPresenceActionARTPresenceActionio.ably.lib.types.PresenceMessage.ActionAbly::Models::PresenceMessage::ACTIONIO.Ably.PresenceAction @@ -659,25 +580,19 @@ const ( -### PaginatedResultARTPaginatedResultAbly::Models::PaginatedResultio.ably.lib.types.PaginatedResultIO.Ably.PaginatedResult +### 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](/docs/api/rest-api/#pagination) is accompanied by metadata that indicates the relative queries available to the `PaginatedResult` object. -#### PropertiesMembersAttributes +#### PropertiesMembersAttributes | Property | Description | Type | |----------|-------------|------| -| itemsItemsItemsitems | contains the current page of results (for example an Array of [`Message`](#message) or [`PresenceMessage`](#presence-message) objects for a channel history request) | `Array ``List ``Array ``List ` | +| itemsItemsItemsitems | contains the current page of results (for example an Array of [`Message`](#message) or [`PresenceMessage`](#presence-message) objects for a channel history request) | `Array ``List ``Array ``List ` | #### Methods -##### firstFirst - - - -`first(): Promise` - - +##### firstFirst @@ -721,22 +636,15 @@ A `PaginatedResult` is a type that represents a page of results for all message - Returns a new `PaginatedResult` for the first page of results. When using the Realtime library, the `first` method returns a [Deferrable](/docs/api/realtime-sdk/types#deferrable) and yields a [PaginatedResult](#paginated-result).The method is asynchronous and returns a Task which needs to be awaited to get the [PaginatedResult](#paginated-result). - +##### hasNextHasNexthas_next?has_next -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`](/docs/api/realtime-sdk/types#error-info) object that details the reason why it was rejected. - - - -##### hasNextHasNexthas_next?has_next - - + `Boolean hasNext()` @@ -766,11 +674,11 @@ Returns a promise. On success, the promise is fulfilled with a new `PaginatedRes -Returns `true` if there are more pages available by calling `next``Next` and returns `false` if this page is the last page available. +Returns `true` if there are more pages available by calling `next``Next` and returns `false` if this page is the last page available. -##### isLastIsLastlast?is_last +##### isLastIsLastlast?is_last - + `Boolean isLast()` @@ -800,15 +708,9 @@ Returns `true` if there are more pages available by calling `next``Next` available. - -##### nextNext +Returns `true` if this page is the last page and returns `false` if there are more pages available by calling `next``Next` available. - - -`next(): Promise` - - +##### nextNext @@ -858,49 +760,8 @@ Returns a new `PaginatedResult` loaded with the next page of results. If there a - - -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`](/docs/api/realtime-sdk/types#error-info) object that details the reason why it was rejected. - - - - -##### current - -`current(): Promise` - -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`](/docs/api/realtime-sdk/types#error-info) object that details the reason why it was rejected. - - - #### Example - - - -```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()); -``` - - - - - - -```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()); -``` - - - diff --git a/src/pages/docs/api/rest-sdk/messages.mdx b/src/pages/docs/api/rest-sdk/messages.mdx index 9ca9ba2c93..523ce7e9c5 100644 --- a/src/pages/docs/api/rest-sdk/messages.mdx +++ b/src/pages/docs/api/rest-sdk/messages.mdx @@ -20,11 +20,11 @@ The event name, if provided.
_Type: `String`_ ### data -The message payload, if provided.
_Type: `String`, `StringBuffer`, `JSON Object``String`, `ByteArray`, `JSONObject`, `JSONArray``String`, `byte[]`, `plain C# object that can be serialized to JSON``String`, `Binary` (ASCII-8BIT String), `Hash`, `Array``String`, `Bytearray`, `Dict`, `List``String`, `Binary String`, `Associative Array`, `Array``NSString *`, `NSData *`, `NSDictionary *`, `NSArray *``String`, `NSData`, `Dictionary`, `Array``String`, `Map`, `List`_ +The message payload, if provided.
_Type: `String`, `StringBuffer`, `JSON Object``String`, `ByteArray`, `JSONObject`, `JSONArray``String`, `byte[]`, `plain C# object that can be serialized to JSON``String`, `Binary` (ASCII-8BIT String), `Hash`, `Array``String`, `Bytearray`, `Dict`, `List``String`, `Binary String`, `Associative Array`, `Array``NSString *`, `NSData *`, `NSDictionary *`, `NSArray *``String`, `NSData`, `Dictionary`, `Array``String`, `Map`, `List`_ ### extras -Metadata and/or ancillary payloads, if provided. Valid payloads include [`push`](/docs/push/publish#payload), `headers` (a map of strings to strings for arbitrary customer-supplied metadata), [`ephemeral`](/docs/pub-sub/advanced#ephemeral), and [`privileged`](/docs/platform/integrations/skip-integrations) objects.
_Type: `JSON Object``JSONObject`, `JSONArray`plain C# object that can be converted to JSON`Hash`, `Array``Dict`, `List``Dictionary`, `Array``NSDictionary *`, `NSArray *``Associative Array`, `Array`_ +Metadata and/or ancillary payloads, if provided. Valid payloads include [`push`](/docs/push/publish#payload), `headers` (a map of strings to strings for arbitrary customer-supplied metadata), [`ephemeral`](/docs/pub-sub/advanced#ephemeral), and [`privileged`](/docs/platform/integrations/skip-integrations) objects.
_Type: `JSON Object``JSONObject`, `JSONArray`plain C# object that can be converted to JSON`Hash`, `Array``Dict`, `List``Dictionary`, `Array``NSDictionary *`, `NSArray *``Associative Array`, `Array`_ ### id @@ -44,28 +44,12 @@ A connection key, which can optionally be included for a REST publish as part of ### timestamp -Timestamp when the message was first received by the Ably, as milliseconds since the epocha `Time` object
_Type: `Integer``Long Integer``DateTimeOffset``Time``NSDate`_ +Timestamp when the message was first received by the Ably, as milliseconds since the epocha `Time` object
_Type: `Integer``Long Integer``DateTimeOffset``Time``NSDate`_ ### encoding This will typically be empty as all messages received from Ably are automatically decoded client-side using this value. However, if the message encoding cannot be processed, this attribute will contain the remaining transformations not applied to the `data` payload.
_Type: `String`_ - - -#### action - -The action type of the message, one of the [`MessageAction`](/docs/api/realtime-sdk/types#message-action) enum values.
_Type: `int enum { MESSAGE_CREATE, MESSAGE_UPDATE, MESSAGE_DELETE, META, MESSAGE_SUMMARY }`_ - -#### serial - -A server-assigned identifier that will be the same in all future updates of this message. It can be used to add annotations to a message. Serial will only be set if you enable annotations in [rules](/docs/channels#rules) .
_Type: `String`_ - -#### annotations - -An object containing information about annotations that have been made to the object.
_Type: [`MessageAnnotations`](/docs/api/realtime-sdk/types#message-annotations)_ - - - ## Message constructors ### Message.fromEncoded @@ -109,7 +93,7 @@ An `Array` of [`Message`](/docs/api/realtime-sdk/types#message) objects | Property | Description | Type | |----------|-------------|------| | serial | An Ably-generated ID that uniquely identifies this version of the message. Can be compared lexicographically to determine version ordering. For an original message with an action of `message.create`, this will be equal to the top-level `serial`. | `String` | -| timestamp | The time this version was created (when the update or delete operation was performed). For an original message, this will be equal to the top-level `timestamp`. | `Integer``Long Integer``DateTimeOffset``Time``NSDate` | +| timestamp | The time this version was created (when the update or delete operation was performed). For an original message, this will be equal to the top-level `timestamp`. | `Integer``Long Integer``DateTimeOffset``Time``NSDate` | | clientId | The client identifier of the user who performed the update or delete operation. Only present for `message.update` and `message.delete` actions. | `String` (optional) | | description | Optional description provided when the update or delete was performed. Only present for `message.update` and `message.delete` actions. | `String` (optional) | | metadata | Optional metadata provided when the update or delete was performed. Only present for `message.update` and `message.delete` actions. | `Object` (optional) | diff --git a/src/pages/docs/api/rest-sdk/presence.mdx b/src/pages/docs/api/rest-sdk/presence.mdx index 404a6ec8e0..8677c909d1 100644 --- a/src/pages/docs/api/rest-sdk/presence.mdx +++ b/src/pages/docs/api/rest-sdk/presence.mdx @@ -20,16 +20,10 @@ We've updated the style and readability of our API references, starting with Jav ## Methods -### getGet +### getGet Get the current presence member set for this channel. In the REST client library this method directly queries [Ably's REST presence API](/docs/api/rest-api#presence) - - -`get(Object params?): Promise` - - - `PaginatedResult get(Hash options)` @@ -80,7 +74,7 @@ Get the current presence member set for this channel. In the REST client librar Gets an array of members present on the channel as [`PresenceMessage`](#presence-message) objects. - + #### Parameters @@ -93,30 +87,23 @@ Gets an array of members present on the channel as [`PresenceMessage`](#presence - + | Name | Description | |------|-------------| -| paramsquery[`Param[]`](#param) optionsoptions | an optional object containing query parametersoptional keyword arguments containing the query parametersan optional set of symbol key and value pairs containing the query parametersan optional Associate Array containing the query parameters as specified below. | +| query[`Param[]`](#param) optionsoptions | an optional object containing query parametersoptional keyword arguments containing the query parametersan optional set of symbol key and value pairs containing the query parametersan optional Associate Array containing the query parameters as specified below. | -#### `options` parameters`params` parameters`ARTPresenceQuery` propertiesArguments +#### `options` parameters`ARTPresenceQuery` propertiesArguments | Name | Description | |------|-------------| -| clientIdclient_id:client_id| when provided, will filter array of members returned that match the provided [`clientId`](/docs/api/rest-sdk#client-options)[`client_id`](/docs/api/rest-sdk#client-options)[`ClientId`](/docs/api/rest-sdk#client-options) string | -| connectionIdconnection_id:connection_id | when provided, will filter array of members returned that match the provided [`connectionId`](/docs/api/realtime-sdk/connection#id)[`ConnectionId`](/docs/api/realtime-sdk/connection#id)[`connection_id`](/docs/api/realtime-sdk/connection#id) string | - - +| clientIdclient_id:client_id| when provided, will filter array of members returned that match the provided [`clientId`](/docs/api/rest-sdk#client-options)[`client_id`](/docs/api/rest-sdk#client-options)[`ClientId`](/docs/api/rest-sdk#client-options) string | +| connectionIdconnection_id:connection_id | when provided, will filter array of members returned that match the provided [`connectionId`](/docs/api/realtime-sdk/connection#id)[`ConnectionId`](/docs/api/realtime-sdk/connection#id)[`connection_id`](/docs/api/realtime-sdk/connection#id) string | -#### Returns - -Returns a promise. On success, the promise is fulfilled with an array of [`PresenceMessage`](#presence-message) objects corresponding to the current set of present members on the channel. On failure, the promise is rejected with an [`ErrorInfo`](/docs/api/rest-sdk/types#error-info) object that details the reason why it was rejected. - - #### Returns @@ -141,13 +128,8 @@ Failure to retrieve the current presence member, the `error` contains an [`Error -### historyHistory +### historyHistory - - -`history(Object params?): Promise>` - - `PaginatedResult history(Hash options)` @@ -197,21 +179,14 @@ Gets a [paginated](#paginated-result) set of historical presence message events - + | Parameter | Description | Type | |-----------|-------------|------| -| paramsquery[`Param[]`](#param) optionsoptions | an optional object containing query parametersoptional keyword arguments containing the query parametersan optional set of key value pairs containing query parametersan optional Associate Array containing the query parameters, as specified in the [presence history API documentation](/docs/storage-history/history#presence-history). | Object[`PaginatedRequestParams`](#paginated-request-params)[`Param[]`](#param)Object | +| query[`Param[]`](#param) optionsoptions | an optional object containing query parametersoptional keyword arguments containing the query parametersan optional set of key value pairs containing query parametersan optional Associate Array containing the query parameters, as specified in the [presence history API documentation](/docs/storage-history/history#presence-history). | [`PaginatedRequestParams`](#paginated-request-params)[`Param[]`](#param)Object | - - -#### Returns - -Returns a promise. On success, the promise is fulfilled with a [`PaginatedResult`](#paginated-result) object containing an array of [`PresenceMessage`](#presence-message) objects corresponding to the current page of results. On failure, the promise is rejected with an [`ErrorInfo`](/docs/api/rest-sdk/types#error-info) object that details the reason why it was rejected. - - #### Callback result @@ -249,22 +224,22 @@ Upon failure to retrieve the message history, the `error` contains an [`ErrorInf ## Related types -### PresenceMessageARTPresenceMessageAbly::Models::PresenceMessageio.ably.lib.types.PresenceMessageIO.Ably.PresenceMessage +### PresenceMessageARTPresenceMessageAbly::Models::PresenceMessageio.ably.lib.types.PresenceMessageIO.Ably.PresenceMessage A `PresenceMessage` represents an individual presence update that is sent to or received from Ably. -#### PropertiesMembersAttributes +#### PropertiesMembersAttributes | Property | Description | Type | |----------|-------------|------| -| actionActionAction | the event signified by a PresenceMessage. See [`PresenceMessage.action`](/docs/api/realtime-sdk/types#presence-action)the event signified by a PresenceMessage. See [`PresenceMessage.action`](/docs/api/realtime-sdk/types#presence-action)the event signified by a PresenceMessage. See [`Presence action`](/docs/api/realtime-sdk/types#presence-action)the event signified by a PresenceMessage. See [`PresenceAction`](/docs/api/realtime-sdk/types#presence-action)the event signified by a PresenceMessage. See [`PresenceMessage::ACTION`](/docs/api/realtime-sdk/types#presence-action)the event signified by a PresenceMessage. See [`PresenceMessage::ACTION`](/docs/api/realtime-sdk/types#presence-action)the event signified by a PresenceMessage. See [`PresenceMessage.action`](/docs/api/realtime-sdk/types#presence-action)the event signified by a PresenceMessage. See [`PresenceMessage::action`](/docs/api/realtime-sdk/types#presence-action) | `enum { ABSENT, PRESENT, ENTER, LEAVE, UPDATE }``enum { Absent, Present, Enter, Leave, Update }``int enum { ABSENT, PRESENT, ENTER, LEAVE, UPDATE }``int enum { ABSENT, PRESENT, ENTER, LEAVE, UPDATE }``enum { :absent, :present, :enter, :leave, :update }``const PresenceMessage::ABSENT,PRESENT,ENTER,LEAVE,UPDATE``ARTPresenceAction``const PresenceMessage::PresenceAbsent,PresencePresent,PresenceEnter,PresenceLeave,PresenceUpdate` | -| dataData | The presence update payload, if provided | `String`, `ByteArray`, `JSONObject`, `JSONArray``String`, `byte[]`, plain C# object that can be converted to Json`String`, `StringBuffer`, `JSON Object``String`, `[]byte``String`, `Binary` (ASCII-8BIT String), `Hash`, `Array``String`, `Bytearray`, `Dict`, `List``String`, `NSData`, `Dictionary`, `Array``NSString *`, `NSData *`, `NSDictionary *`, `NSArray *``String`, `Binary String`, `Associative Array`, `Array` | -| extrasExtras | Metadata and/or ancillary payloads, if provided. The only currently valid payloads for extras are the [`push`](/docs/push/publish#sub-channels), [`ref`](/docs/messages#interactions) and [`privileged`](/docs/platform/integrations/skip-integrations) objects. | `JSONObject`, `JSONArray`plain C# object that can be converted to Json`String`, `[]byte``JSON Object``Hash`, `Array``Dict`, `List``Dictionary`, `Array``NSDictionary *`, `NSArray *``Associative Array`, `Array``Map`, `List` | -| idId | Unique ID assigned by Ably to this presence update | `String` | -| clientIdclient_idClientId | The client ID of the publisher of this presence update | `String` | -| connectionIdconnection_idConnectionId | The connection ID of the publisher of this presence update | `String` | -| timestampTimestamp | Timestamp when the presence update was received by Ably, as milliseconds since the epoch. | `Integer``Long Integer``DateTimeOffset``Time``NSDate` | -| encodingEncoding | This will typically be empty as all presence updates received from Ably are automatically decoded client-side using this value. However, if the message encoding cannot be processed, this attribute will contain the remaining transformations not applied to the `data` payload | `String` | +| actionActionAction | the event signified by a PresenceMessage. See [`PresenceMessage.action`](/docs/api/realtime-sdk/types#presence-action)the event signified by a PresenceMessage. See [`PresenceMessage.action`](/docs/api/realtime-sdk/types#presence-action)the event signified by a PresenceMessage. See [`PresenceAction`](/docs/api/realtime-sdk/types#presence-action)the event signified by a PresenceMessage. See [`PresenceMessage::ACTION`](/docs/api/realtime-sdk/types#presence-action)the event signified by a PresenceMessage. See [`PresenceMessage::ACTION`](/docs/api/realtime-sdk/types#presence-action)the event signified by a PresenceMessage. See [`PresenceMessage.action`](/docs/api/realtime-sdk/types#presence-action)the event signified by a PresenceMessage. See [`PresenceMessage::action`](/docs/api/realtime-sdk/types#presence-action) | `enum { ABSENT, PRESENT, ENTER, LEAVE, UPDATE }``enum { Absent, Present, Enter, Leave, Update }``int enum { ABSENT, PRESENT, ENTER, LEAVE, UPDATE }``enum { :absent, :present, :enter, :leave, :update }``const PresenceMessage::ABSENT,PRESENT,ENTER,LEAVE,UPDATE``ARTPresenceAction``const PresenceMessage::PresenceAbsent,PresencePresent,PresenceEnter,PresenceLeave,PresenceUpdate` | +| dataData | The presence update payload, if provided | `String`, `ByteArray`, `JSONObject`, `JSONArray``String`, `byte[]`, plain C# object that can be converted to Json`String`, `[]byte``String`, `Binary` (ASCII-8BIT String), `Hash`, `Array``String`, `Bytearray`, `Dict`, `List``String`, `NSData`, `Dictionary`, `Array``NSString *`, `NSData *`, `NSDictionary *`, `NSArray *``String`, `Binary String`, `Associative Array`, `Array` | +| extrasExtras | Metadata and/or ancillary payloads, if provided. The only currently valid payloads for extras are the [`push`](/docs/push/publish#sub-channels), [`ref`](/docs/messages#interactions) and [`privileged`](/docs/platform/integrations/skip-integrations) objects. | `JSONObject`, `JSONArray`plain C# object that can be converted to Json`String`, `[]byte``Hash`, `Array``Dict`, `List``Dictionary`, `Array``NSDictionary *`, `NSArray *``Associative Array`, `Array``Map`, `List` | +| idId | Unique ID assigned by Ably to this presence update | `String` | +| clientIdclient_idClientId | The client ID of the publisher of this presence update | `String` | +| connectionIdconnection_idConnectionId | The connection ID of the publisher of this presence update | `String` | +| timestampTimestamp | Timestamp when the presence update was received by Ably, as milliseconds since the epoch. | `Integer``Long Integer``DateTimeOffset``Time``NSDate` | +| encodingEncoding | This will typically be empty as all presence updates received from Ably are automatically decoded client-side using this value. However, if the message encoding cannot be processed, this attribute will contain the remaining transformations not applied to the `data` payload | `String` | ### PresenceMessage constructors @@ -302,44 +277,7 @@ A static factory method to create an array of [`PresenceMessages`](/docs/api/rea An `Array` of [`PresenceMessage`](/docs/api/realtime-sdk/types#presence-message) objects -### Presence actionPresenceActionARTPresenceActionio.ably.lib.types.PresenceMessage.ActionAbly::Models::PresenceMessage::ACTIONIO.Ably.PresenceAction - - - -`Presence` `action` is a String with a value matching any of the [`Realtime Presence` states & events](/docs/presence-occupancy/presence#trigger-events). - - - - -```javascript - var PresenceActions = [ - 'absent', // (reserved for internal use) - 'present', - 'enter', - 'leave', - 'update' - ] -``` - - - - - - -```nodejs - var PresenceActions = [ - 'absent', // (reserved for internal use) - 'present', - 'enter', - 'leave', - 'update' - ] -``` - - - - - +### Presence actionPresenceActionARTPresenceActionio.ably.lib.types.PresenceMessage.ActionAbly::Models::PresenceMessage::ACTIONIO.Ably.PresenceAction @@ -538,25 +476,19 @@ const ( -### PaginatedResultARTPaginatedResultAbly::Models::PaginatedResultio.ably.lib.types.PaginatedResultIO.Ably.PaginatedResult +### 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](/docs/api/rest-api/#pagination) is accompanied by metadata that indicates the relative queries available to the `PaginatedResult` object. -#### PropertiesMembersAttributes +#### PropertiesMembersAttributes | Property | Description | Type | |----------|-------------|------| -| itemsItemsItemsitems | contains the current page of results (for example an Array of `Message` or `PresenceMessage` objects for a channel history request) | `Array ``List ``Array ``List ` | +| itemsItemsItemsitems | contains the current page of results (for example an Array of `Message` or `PresenceMessage` objects for a channel history request) | `Array ``List ``Array ``List ` | #### Methods -##### firstFirst - - - -`first(): Promise` - - +##### firstFirst @@ -600,22 +532,15 @@ A `PaginatedResult` is a type that represents a page of results for all message - Returns a new `PaginatedResult` for the first page of results. When using the Realtime library, the `first` method returns a [Deferrable](/docs/api/realtime-sdk/types#deferrable) and yields a [PaginatedResult](#paginated-result).The method is asynchronous and returns a Task which needs to be awaited to get the [PaginatedResult](#paginated-result). - - -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`](/docs/api/realtime-sdk/types#error-info) object that details the reason why it was rejected. - - - -##### hasNextHasNexthas_next?has_next +##### hasNextHasNexthas_next?has_next - + `Boolean hasNext()` @@ -645,11 +570,11 @@ Returns a promise. On success, the promise is fulfilled with a new `PaginatedRes -Returns `true` if there are more pages available by calling `next``Next` and returns `false` if this page is the last page available. +Returns `true` if there are more pages available by calling `next``Next` and returns `false` if this page is the last page available. -##### isLastIsLastlast?is_last +##### isLastIsLastlast?is_last - + `Boolean isLast()` @@ -679,15 +604,9 @@ Returns `true` if there are more pages available by calling `next``Next` available. +Returns `true` if this page is the last page and returns `false` if there are more pages available by calling `next``Next` available. -##### nextNext - - - -`next(): Promise` - - +##### nextNext @@ -737,49 +656,8 @@ Returns a new `PaginatedResult` loaded with the next page of results. If there a - - -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`](/docs/api/realtime-sdk/types#error-info) object that details the reason why it was rejected. - - - - -##### current - -`current(): Promise` - -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`](/docs/api/realtime-sdk/types#error-info) object that details the reason why it was rejected. - - - #### Example - - - -```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()); -``` - - - - - - -```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()); -``` - - - diff --git a/src/pages/docs/api/rest-sdk/push-admin.mdx b/src/pages/docs/api/rest-sdk/push-admin.mdx index 56431ef320..670f7098e3 100644 --- a/src/pages/docs/api/rest-sdk/push-admin.mdx +++ b/src/pages/docs/api/rest-sdk/push-admin.mdx @@ -23,27 +23,21 @@ We've updated the style and readability of our API references, starting with Jav This object is accessible through `client.push.admin` and provides: -### Push Admin PropertiesPush::Admin Properties +### Push Admin PropertiesPush::Admin Properties -The push admin object exposes the following public properties: +The push admin object exposes the following public properties: -#### deviceRegistrationsdevice_registrations +#### deviceRegistrationsdevice_registrations The returned [`DeviceRegistrations`](#device-registrations-object) object provides functionality for registering, updating, listing and de-registering push devices. -#### channelSubscriptionschannel_subscriptions +#### channelSubscriptionschannel_subscriptions The returned [`PushChannelSubscriptions`](#push-channel-subscriptions) object provides functionality for subscribing, listing and unsubscribing individual devices or groups of [identified devices](/docs/auth/identified-clients) to push notifications published on channels. ### Methods -#### publish - - - -`publish(Object recipient, Object payload): Promise` - - +#### publish @@ -73,15 +67,6 @@ Publishes a push notification directly to a device or group of devices sharing a ##### Parameters - - -| Parameter | Description | Type | -|-----------|-------------|------| -| recipient | an object containing the push recipient details. See the [push notification publish REST API documentation](/docs/api/rest-api#push-publish) for details on the supported recipient fields | Object | -| payload | an object containing the push notification data. See the [push admin payload structure](/docs/push/publish#payload) for details on the supported push payload fields | Object | - - - | Parameter | Description | Type | @@ -121,14 +106,6 @@ Publishes a push notification directly to a device or group of devices sharing a - - -##### Returns - -Returns a promise. On success to publish the push notification, the promise resolves. On failure, the promise is rejected with an [`ErrorInfo`](/docs/api/realtime-sdk/types#error-info) object that details the reason why it was rejected. - - - ##### Callback result @@ -157,19 +134,13 @@ On successful publish of the message, the `onSuccess` method of the [CompletionL -## PushDeviceRegistrations objectDeviceRegistrations object +## DeviceRegistrations object -This object is accessible through `client.push.admin.deviceRegistrations``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. +This object is accessible through `client.push.admin.deviceRegistrations``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 - - - -`get(String deviceId): Promise` - - +#### get @@ -201,12 +172,6 @@ This object is accessible through - -`get(DeviceDetails deviceDetails): Promise` - - - `Deferrable get(DeviceDetails device) -> yields DeviceDetails` @@ -217,12 +182,12 @@ Obtain the `DeviceDetails` for a device registered for receiving push registrati ##### Parameters - + | Parameter | Description | Type | |-----------|-------------|------| | deviceId | the unique device ID String for the requested device | String | -| deviceDetailsdevice | a [`DeviceDetails`](#device-details) object containing at a minimum the `deviceId` of the requested device | Object | +| device | a [`DeviceDetails`](#device-details) object containing at a minimum the `deviceId` of the requested device | Object | @@ -236,14 +201,6 @@ Obtain the `DeviceDetails` for a device registered for receiving push registrati - - -##### Returns - -Returns a promise. On success, the promise is fulfilled with a [`DeviceDetails`](#device-details) object representing the device registered for push notifications. On failure, the promise is rejected with an [`ErrorInfo`](/docs/api/realtime-sdk/types#error-info) object that details the reason why it was rejected. - - - ##### Callback result @@ -274,13 +231,7 @@ On successful publish of the message, the `onSuccess` method of the [CompletionL -#### list - - - -`list(Object params): Promise>` - - +#### list @@ -310,11 +261,11 @@ Retrieve all devices matching the params filter as a paginated list of [`DeviceD ##### Parameters - + | Parameter | Description | Type | |-----------|-------------|------| -| paramsparams | an object containing the query parameters as key value pairs as specified below. | Object[`Param[]`](#param) | +| paramsparams | an object containing the query parameters as key value pairs as specified below. | Object[`Param[]`](#param) | @@ -349,27 +300,6 @@ Retrieve all devices matching the params filter as a paginated list of [`DeviceD - - -| Parameter | Description | Type | -|-----------|-------------|------| -| clientId | optional filter to restrict to devices associated with that client identifier. Cannot be used with a `deviceId` param | String | -| deviceId | optional filter to restrict to devices associated with that device identifier. Cannot be used with a `clientId` param | String | -| limit | maximum number of devices per page to retrieve, up to 1,000
_default: 100_ | Integer | -| state | optional filter by the state of the device. Must be one of `ACTIVE`, `FAILING` or `FAILED` | String | - - - - - -##### Returns - -Returns a promise. On success, the promise is fulfilled with a [`PaginatedResult`](/docs/api/realtime-sdk/types#paginated-result) encapsulating an array of [`DeviceDetails`](#device-details) objects corresponding to the current page of results. [`PaginatedResult`](/docs/api/realtime-sdk/types#paginated-result) supports pagination using [`next()`](/docs/api/realtime-sdk/types#paginated-result) and [`first()`](/docs/api/realtime-sdk/types#paginated-result) methods. - -On failure, the promise is rejected with an [`ErrorInfo`](/docs/api/realtime-sdk/types#error-info) object that details the reason why it was rejected. - - - ##### Callback result @@ -392,13 +322,7 @@ Failure to retrieve the devices will trigger the `errback` callbacks of the [`De -#### save - - - -`save(DeviceDetails deviceDetails): Promise` - - +#### save @@ -428,11 +352,11 @@ Register a new `DeviceDetails` object, or update an existing `DeviceDetails` obj ##### Parameters - + | Parameter | Description | Type | |-----------|-------------|------| -| deviceDetailsdevice | a [`DeviceDetails`](#device-details) object | Object | +| device | a [`DeviceDetails`](#device-details) object | Object | @@ -445,14 +369,6 @@ Register a new `DeviceDetails` object, or update an existing `DeviceDetails` obj - - -##### Returns - -Returns a promise. On success, the promise is fulfilled with a [`DeviceDetails`](#device-details) object representing the newly registered or updated device. On failure, the promise is rejected with an [`ErrorInfo`](/docs/api/realtime-sdk/types#error-info) object that details the reason why it was rejected. - - - ##### Callback result @@ -475,15 +391,7 @@ Failure to create or update the device will trigger the `errback` callbacks of t -#### remove - - - -`remove(String deviceId): Promise` - -`remove(DeviceDetails deviceDetails): Promise` - - +#### remove @@ -519,12 +427,12 @@ Remove a device registered for receiving push registrations that matches the `de ##### Parameters - + | Parameter | Description | Type | |-----------|-------------|------| | deviceId | the unique device ID String for the device | String | -| deviceDetailsdevice | a [`DeviceDetails`](#device-details) object containing at a minimum the `deviceId` of the device | Object | +| device | a [`DeviceDetails`](#device-details) object containing at a minimum the `deviceId` of the device | Object | @@ -538,14 +446,6 @@ Remove a device registered for receiving push registrations that matches the `de - - -##### Returns - -Returns a promise. On success to delete the device, the promise resolves. Note that a request to delete a device that does not exist will result in a successful operation. On failure, the promise is rejected with an [`ErrorInfo`](/docs/api/realtime-sdk/types#error-info) object that details the reason why it was rejected. - - - ##### Callback result @@ -568,13 +468,7 @@ Failure to delete the device will trigger the `errback` callbacks of the [`Defer -#### removeWhereremove_where - - - -`removeWhere(Object params): Promise` - - +#### removeWhereremove_where @@ -604,11 +498,11 @@ Delete all devices matching the params filter. Requires `push-admin` permission. ##### Parameters - + | Parameter | Description | Type | |-----------|-------------|------| -| paramsparams | an object containing the filter parameters as key value pairs as specified below. | Object[`Param[]`](#param) | +| paramsparams | an object containing the filter parameters as key value pairs as specified below. | Object[`Param[]`](#param) | @@ -625,16 +519,8 @@ Delete all devices matching the params filter. Requires `push-admin` permission. | Parameter | Description | Type | |-----------|-------------|------| -| clientId:client_id | optional filter to restrict to devices associated with that client identifier. Cannot be used with a `deviceId``:device_id` param | String | -| deviceId:device_id | optional filter to restrict to devices associated with that device identifier. Cannot be used with a `clientId``:client_id` param | String | - - - -##### Returns - -Returns a promise. On success to delete the device, the promise resolves. Note that a request that does match any existing devices will result in a successful operation. On failure, the promise is rejected with an [`ErrorInfo`](/docs/api/realtime-sdk/types#error-info) object that details the reason why it was rejected. - - +| clientId:client_id | optional filter to restrict to devices associated with that client identifier. Cannot be used with a `deviceId``:device_id` param | String | +| deviceId:device_id | optional filter to restrict to devices associated with that device identifier. Cannot be used with a `clientId``:client_id` param | String | @@ -660,17 +546,11 @@ Failure to delete the device will trigger the `errback` callbacks of the [`Defer ## PushChannelSubscriptions object -This object is accessible through `client.push.admin.channelSubscriptions``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. +This object is accessible through `client.push.admin.channelSubscriptions``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 - - - -`list(Object params): Promise>` - - +#### list @@ -700,11 +580,11 @@ Retrieve all push channel subscriptions that match the provided params filter as ##### Parameters - + | Parameter | Description | Type | |-----------|-------------|------| -| paramsparams | an object containing the query parameters as key value pairs as specified below. | Object[`Param[]`](#param) | +| paramsparams | an object containing the query parameters as key value pairs as specified below. | Object[`Param[]`](#param) | @@ -721,20 +601,10 @@ Retrieve all push channel subscriptions that match the provided params filter as | Parameter | Description | Type | |-----------|-------------|------| -| channel:channel | filter to restrict to subscriptions associated with that `channel` | String | -| clientId:client_id | optional filter to restrict to devices associated with that client identifier. Cannot be used with a `deviceId``:device_id` param | String | -| deviceId:device_id | optional filter to restrict to devices associated with that device identifier. Cannot be used with a `clientId``:client_id` param | String | -| limit:limit | maximum number of channel subscriptions per page to retrieve, up to 1,000
_default: 100_ | Integer | - - - -##### Returns - -Returns a promise. On success, the promise is fulfilled with a [`PaginatedResult`](/docs/api/realtime-sdk/types#paginated-result) encapsulating an array of [`PushChannelSubscription`](#push-channel-subscription) objects corresponding to the current page of results. [`PaginatedResult`](/docs/api/realtime-sdk/types#paginated-result) supports pagination using [`next()`](/docs/api/realtime-sdk/types#paginated-result) and [`first()`](/docs/api/realtime-sdk/types#paginated-result) methods. - -On failure, the promise is rejected with an [`ErrorInfo`](/docs/api/realtime-sdk/types#error-info) object that details the reason why it was rejected. - - +| channel:channel | filter to restrict to subscriptions associated with that `channel` | String | +| clientId:client_id | optional filter to restrict to devices associated with that client identifier. Cannot be used with a `deviceId``:device_id` param | String | +| deviceId:device_id | optional filter to restrict to devices associated with that device identifier. Cannot be used with a `clientId``:client_id` param | String | +| limit:limit | maximum number of channel subscriptions per page to retrieve, up to 1,000
_default: 100_ | Integer | @@ -758,13 +628,7 @@ Failure to retrieve the channel subscriptions will trigger the `errback` callbac -#### listChannelslist_channels - - - -`listChannels(Object params): Promise>` - - +#### listChannelslist_channels @@ -794,11 +658,11 @@ Retrieve a list of channels that have at least one device [subscribed to push no ##### Parameters - + | Parameter | Description | Type | |-----------|-------------|------| -| paramsparams | an object containing the query parameters as key value pairs as specified below. | Object[`Param[]`](#param) | +| paramsparams | an object containing the query parameters as key value pairs as specified below. | Object[`Param[]`](#param) | @@ -814,17 +678,7 @@ Retrieve a list of channels that have at least one device [subscribed to push no | Parameter | Description | Type | |-----------|-------------|------| -| limit:limit | maximum number of channels per page to retrieve, up to 1,000
_default: 100_ | Integer | - - - -##### Returns - -Returns a promise. On success, the promise is fulfilled with a [`PaginatedResult`](/docs/api/realtime-sdk/types#paginated-result) encapsulating an array of channel name `String` values corresponding to the current page of results. [`PaginatedResult`](/docs/api/realtime-sdk/types#paginated-result) supports pagination using [`next()`](/docs/api/realtime-sdk/types#paginated-result) and [`first()`](/docs/api/realtime-sdk/types#paginated-result) methods. - -On failure, the promise is rejected with an [`ErrorInfo`](/docs/api/realtime-sdk/types#error-info) object that details the reason why it was rejected. - - +| limit:limit | maximum number of channels per page to retrieve, up to 1,000
_default: 100_ | Integer | @@ -848,13 +702,7 @@ Failure to retrieve the channels will trigger the `errback` callbacks of the [`D -#### save - - - -`save(PushChannelSubscription subscription): Promise` - - +#### save @@ -886,15 +734,7 @@ Subscribe a device or group of devices sharing a [client identifier](/docs/auth/ | Parameter | Description | Type | |-----------|-------------|------| -| subscriptionchannelSubscriptionchannel_subscription | a [`PushChannelSubscription`](#push-channel-subscription) object | Object | - - - -##### Returns - -Returns a promise. On success, the promise is fulfilled with a [`PushChannelSubscription`](#push-channel-subscription) object representing the newly subscribed or updated push channel subscription. On failure, the promise is rejected with an [`ErrorInfo`](/docs/api/realtime-sdk/types#error-info) object that details the reason why it was rejected. - - +| channelSubscriptionchannel_subscription | a [`PushChannelSubscription`](#push-channel-subscription) object | Object | @@ -906,13 +746,7 @@ On failure to create or update the channel subscription, `err` contains an [`Err -#### remove - - - -`remove(PushChannelSubscription subscription): Promise` - - +#### remove @@ -944,15 +778,7 @@ Unsubscribe a device or group of devices sharing a [client identifier](/docs/aut | Parameter | Description | Type | |-----------|-------------|------| -| subscriptionchannelSubscriptionchannel_subscription | a [`PushChannelSubscription`](#push-channel-subscription) object | Object | - - - -##### Returns - -Returns a promise. On success to unsubscribe, the promise resolves. On failure, the promise is rejected with an [`ErrorInfo`](/docs/api/realtime-sdk/types#error-info) object that details the reason why it was rejected. - - +| channelSubscriptionchannel_subscription | a [`PushChannelSubscription`](#push-channel-subscription) object | Object | @@ -964,13 +790,7 @@ When this operation fails, `err` contains an [`ErrorInfo`](/docs/api/realtime-sd -#### removeWhereremove_where - - - -`removeWhere(Object params): Promise` - - +#### removeWhereremove_where @@ -1002,23 +822,15 @@ Delete all push channel subscriptions matching the `params` filter. Requires `pu | Parameter | Description | Type | |-----------|-------------|------| -| paramsparams | an object containing the filter parameters as key value pairs as specified below. | Object[`Param[]`](#param) | +| paramsparams | an object containing the filter parameters as key value pairs as specified below. | Object[`Param[]`](#param) | ##### `params` properties | Parameter | Description | Type | |-----------|-------------|------| -| channel:channel | filter to restrict to subscriptions associated with that `channel` | String | -| clientId:client_id | optional filter to restrict to devices associated with that client identifier. Cannot be used with `deviceId``:device_id` param | String | -| deviceId:device_id | optional filter to restrict to devices associated with that device identifier. Cannot be used with `clientId``:client_id` param | String | - - - -##### Returns - -Returns a promise. On success to unsubscribe, the promise resolves. On failure, the promise is rejected with an [`ErrorInfo`](/docs/api/realtime-sdk/types#error-info) object that details the reason why it was rejected. - - +| channel:channel | filter to restrict to subscriptions associated with that `channel` | String | +| clientId:client_id | optional filter to restrict to devices associated with that client identifier. Cannot be used with `deviceId``:device_id` param | String | +| deviceId:device_id | optional filter to restrict to devices associated with that device identifier. Cannot be used with `clientId``:client_id` param | String | @@ -1032,109 +844,47 @@ When this operation fails, `err` contains an [`ErrorInfo`](/docs/api/realtime-sd ## Related types -### DeviceDetailsAbly::Models::DeviceDetailsARTDeviceDetails +### DeviceDetailsAbly::Models::DeviceDetailsARTDeviceDetails A `DeviceDetails` is a type encapsulating attributes of a device registered for push notifications. -#### PropertiesAttributes +#### PropertiesAttributes | Property | Description | Type | |----------|-------------|------| | id | unique identifier for the device generated by the device itself | String | -| clientIdclient_id | optional trusted [client identifier](/docs/auth/identified-clients) for the device | String | -| formFactorform_factor | form factor of the push device. Must be one of `phone`, `tablet`, `desktop`, `tv`, `watch`, `car` or `embedded`or `other` | String | -| metadata | optional metadata object for this device. The metadata for a device may only be set by clients with `push-admin` privileges | ObjectArrayHash | -| platform | platform of the push device. Must be one of `ios` or `android`or `browser` | String | -| deviceSecret | Secret value for the device. | String | -| push.recipient | push recipient details for this device. See the [REST API push publish documentation](/docs/api/rest-api#message-extras-push) for more details | ObjectArrayHash | -| push.state | the current state of the push device being either `Active`, `Failing` or `Failed``ACTIVE`, `FAILING` or `FAILED` | String | -| push.errorReasonpush.errorpush.error_reason | when the device's state is failing or failed, this attribute contains the reason for the most recent failure | [`ErrorInfo`](/docs/api/realtime-sdk/types#error-info) | +| clientIdclient_id | optional trusted [client identifier](/docs/auth/identified-clients) for the device | String | +| formFactorform_factor | form factor of the push device. Must be one of `phone`, `tablet`, `desktop`, `tv`, `watch`, `car` or `embedded` | String | +| metadata | optional metadata object for this device. The metadata for a device may only be set by clients with `push-admin` privileges | ObjectArrayHash | +| platform | platform of the push device. Must be one of `ios` or `android` | String | +| deviceSecret | Secret value for the device. | String | +| push.recipient | push recipient details for this device. See the [REST API push publish documentation](/docs/api/rest-api#message-extras-push) for more details | ObjectArrayHash | +| push.state | the current state of the push device being either `Active`, `Failing` or `Failed` | String | +| push.errorReasonpush.error_reason | when the device's state is failing or failed, this attribute contains the reason for the most recent failure | [`ErrorInfo`](/docs/api/realtime-sdk/types#error-info) | -### PushChannelAbly::Models::PushChannel +### PushChannelAbly::Models::PushChannel A `PushChannel` is a property of a [`RealtimeChannel`](/docs/api/realtime-sdk/channels#properties) or [`RestChannel`](/docs/api/rest-sdk/channels#properties). It provides [push devices](/docs/push) the ability to subscribe and unsubscribe to push notifications on channels. #### Methods -##### subscribeDevice - - - -`subscribeDevice(): Promise` - - +##### subscribeDevice Subscribe your device to the channel's push notifications. - - -##### Returns - -Returns a promise. On success, the promise resolves. On failure, the promise is rejected with an [`ErrorInfo`](/docs/api/realtime-sdk/types#error-info) object that details the reason why it was rejected. - - - -##### subscribeClient - - - -`subscribeClient(): Promise` - - +##### subscribeClient [Subscribe all devices associated with your device's clientId](/docs/push/publish#sub-channels) to the channel's push notifications. - - -##### Returns - -Returns a promise. On success, the promise resolves. On failure, the promise is rejected with an [`ErrorInfo`](/docs/api/realtime-sdk/types#error-info) object that details the reason why it was rejected. - - - -##### unsubscribeDevice - - - -`unsubscribeDevice(): Promise` - - +##### unsubscribeDevice Unsubscribe your device from the channel's push notifications. - - -##### Returns - -Returns a promise. On success, the promise resolves. On failure, the promise is rejected with an [`ErrorInfo`](/docs/api/realtime-sdk/types#error-info) object that details the reason why it was rejected. - - - -##### unsubscribeClient - - - -`unsubscribeClient(): Promise` - - +##### unsubscribeClient [Unsubscribe all devices associated with your device's clientId](/docs/push/publish#sub-channels) from the channel's push notifications. - - -##### Returns - -Returns a promise. On success, the promise resolves. On failure, the promise is rejected with an [`ErrorInfo`](/docs/api/realtime-sdk/types#error-info) object that details the reason why it was rejected. - - - -##### listSubscriptions - - - -`listSubscriptions(Record params?): Promise>` - - +##### listSubscriptions @@ -1173,25 +923,6 @@ Lists push subscriptions on a channel specified by its channel name (`channel`). - - -| 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\ | - - - - - -##### 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`](/docs/api/realtime-sdk/types#error-info) object that details the reason why it was rejected. - - - ##### Callback result @@ -1212,17 +943,17 @@ Failure to retrieve the message history will raise an [`AblyException`](/docs/ap -### PushChannelSubscriptionAbly::Models::PushChannelSubscriptionChannelSubscriptionARTPushChannelSubscription +### PushChannelSubscriptionAbly::Models::PushChannelSubscriptionChannelSubscriptionARTPushChannelSubscription An `PushChannelSubscription` is a type encapsulating the subscription of a device or group of devices sharing a [client identifier](/docs/auth/identified-clients) to a channel in order to receive push notifications. -#### PropertiesAttributes +#### PropertiesAttributes | Property | Description | Type | |----------|-------------|------| | channel | the channel that this push notification subscription is associated with | String | -| deviceIddevice_id | the device with this identifier is linked to this channel subscription. When present, `clientId``client_id` is never present | String | -| clientIdclient_id | devices with this [client identifier](/docs/auth/identified-clients) are included in this channel subscription. When present, `deviceId``device_id` is never present | String | +| deviceIddevice_id | the device with this identifier is linked to this channel subscription. When present, `clientId``client_id` is never present | String | +| clientIdclient_id | devices with this [client identifier](/docs/auth/identified-clients) are included in this channel subscription. When present, `deviceId``device_id` is never present | String | @@ -1276,7 +1007,7 @@ A static factory method to create a `PushChannelSubscription` object for a chann | Parameter | Description | Type | |-----------|-------------|------| | channel | channel name linked to this push channel subscription | String | -| clientIdclient_id | devices with this [client identifier](/docs/auth/identified-clients) are included in the new push channel subscription | String | +| clientIdclient_id | devices with this [client identifier](/docs/auth/identified-clients) are included in the new push channel subscription | String | ##### Returns @@ -1284,25 +1015,19 @@ A `PushChannelSubscription` object -### PaginatedResultARTPaginatedResultAbly::Models::PaginatedResultio.ably.lib.types.PaginatedResult +### PaginatedResultARTPaginatedResultAbly::Models::PaginatedResultio.ably.lib.types.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](/docs/api/rest-api/#pagination) is accompanied by metadata that indicates the relative queries available to the `PaginatedResult` object. -#### PropertiesAttributesMembers +#### PropertiesAttributesMembers | 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 ` | +| 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 ` | #### Methods -##### first - - - -`first(): Promise` - - +##### first @@ -1334,15 +1059,9 @@ Returns a new `PaginatedResult` for the first page of results. W - +##### hasNexthas_next? -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`](/docs/api/realtime-sdk/types#error-info) object that details the reason why it was rejected. - - - -##### hasNexthas_next? - - + `Boolean hasNext()` @@ -1354,11 +1073,11 @@ Returns a promise. On success, the promise is fulfilled with a new `PaginatedRes -Returns `true` if there are more pages available by calling `next` and returns `false` if this page is the last page available. +Returns `true` if there are more pages available by calling `next` and returns `false` if this page is the last page available. -##### isLastlast? +##### isLastlast? - + `Boolean isLast()` @@ -1370,15 +1089,9 @@ Returns `true` if there are more pages available by calling `next` available. - -##### next - - - -`next(): Promise` +Returns `true` if this page is the last page and returns `false` if there are more pages available by calling `next` available. - +##### next @@ -1410,52 +1123,8 @@ Returns a new `PaginatedResult` loaded with the next page of results. If there a - - -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`](/docs/api/realtime-sdk/types#error-info) object that details the reason why it was rejected. - - - - - -##### current - -`current(): Promise` - -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`](/docs/api/realtime-sdk/types#error-info) object that details the reason why it was rejected. - - - #### Example - - - -```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()); -``` - - - - - - - -```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()); -``` - - - - diff --git a/src/pages/docs/api/rest-sdk/statistics.mdx b/src/pages/docs/api/rest-sdk/statistics.mdx index 3455087776..94a678f160 100644 --- a/src/pages/docs/api/rest-sdk/statistics.mdx +++ b/src/pages/docs/api/rest-sdk/statistics.mdx @@ -12,13 +12,8 @@ redirect_from: We've updated the style and readability of our API references, starting with JavaScript. Check out the [Pub/Sub JavaScript SDK API references](/docs/pub-sub/api/javascript/rest/rest-client#stats) in their new location. -### statsStats +### statsStats - - -`stats(Object params?): Promise>` - - `PaginatedResult stats(Hash options)` @@ -59,11 +54,11 @@ This call queries the [REST `/stats` API](/docs/api/rest-api#stats) and retrieve #### Parameters - + | Parameter | Description | Type | |-----------|-------------|------| -| queryparamsoptions | An optional object containing the query parameters used to specify which statistics are retrieved. If not specified the default parameters will be used | [`StatsRequestParams`](#stats-request-params)[`Param[]`](#param)ObjectkwargsArray`*PaginateParams` | +| queryoptions | An optional object containing the query parameters | [`StatsRequestParams`](#stats-request-params)[`Param[]`](#param)kwargsArray`*PaginateParams` | @@ -85,25 +80,17 @@ This call queries the [REST `/stats` API](/docs/api/rest-api#stats) and retrieve -#### `ARTStatsQuery` properties`StatsRequestParams` properties`params` properties`options` parameters +#### `ARTStatsQuery` properties`StatsRequestParams` properties`options` parameters The following options, as defined in the [REST `/stats` API](/docs/api/rest-api#stats) endpoint, are permitted: | Property | Description | Type | |----------|-------------|------| -| Start:startstart | Earliest `DateTimeOffset` or `Time` or time in milliseconds since the epoch for any stats retrieved.
_Default: beginning of time_ | `Number``Int` or `Time``Long``DateTimeOffset` | -| End:endend | Latest `DateTimeOffset` or `Time` or time in milliseconds since the epoch for any stats retrieved.
_Default: current time_ | `Number``Int` or `Time``Long``DateTimeOffset` | -| Direction:directiondirection | `:forwards` or `:backwards``forwards` or `backwards``forwards` or `backwards`.
_Default: `backwards`_ | `String``Symbol``Direction` enum | -| Limit:limitlimit | Maximum number of stats to retrieve up to 1,000.
_Default: `100`_ | `Number``Integer` | -| Unit:unitunit | `:minute`, `:hour`, `:day` or `:month``Minute`, `Hour`, `Day` or `Month``minute`, `hour`, `day` or `month`. Based on the unit selected, the given start or end times are rounded down to the start of the relevant interval depending on the unit granularity of the query.
_Default: `Minute``:minute``minute`_ | [`StatsIntervalGranularity`](/docs/api/rest-sdk/types#stats-granularity)`Symbol``String`[`ARTStatsGranularity`](#stats-granularity)[`StatsIntervalGranularity`](/docs/api/rest-sdk/types#stats-granularity) enum | - - - -#### Returns - -Returns a promise. On success, the promise is fulfilled with a [PaginatedResult](/docs/api/rest-sdk/types#paginated-result) object containing an array of [Stats](/docs/api/rest-sdk/types#stats) objects. On failure, the promise is rejected with an [ErrorInfo](/docs/api/rest-sdk/types#error-info) object. - - +| Start:startstart | Earliest `DateTimeOffset` or `Time` or time in milliseconds since the epoch for any stats retrieved.
_Default: beginning of time_ | `Int` or `Time``Long``DateTimeOffset` | +| End:endend | Latest `DateTimeOffset` or `Time` or time in milliseconds since the epoch for any stats retrieved.
_Default: current time_ | `Int` or `Time``Long``DateTimeOffset` | +| Direction:directiondirection | `:forwards` or `:backwards``forwards` or `backwards``forwards` or `backwards`.
_Default: `backwards`_ | `String``Symbol``Direction` enum | +| Limit:limitlimit | Maximum number of stats to retrieve up to 1,000.
_Default: `100`_ | `Integer` | +| Unit:unitunit | `:minute`, `:hour`, `:day` or `:month``Minute`, `Hour`, `Day` or `Month``minute`, `hour`, `day` or `month`. Based on the unit selected, the given start or end times are rounded down to the start of the relevant interval depending on the unit granularity of the query.
_Default: `Minute``:minute``minute`_ | `Symbol``String`[`ARTStatsGranularity`](#stats-granularity)[`StatsIntervalGranularity`](/docs/api/rest-sdk/types#stats-granularity) enum | @@ -139,7 +126,7 @@ Failure to retrieve the stats will raise an [AblyException](/docs/api/rest-sdk/t ## Related types -### ARTStatsio.ably.lib.types.StatsAbly::Models::StatsAbly\Models\StatsIO.Ably.StatsStats object +### ARTStatsio.ably.lib.types.StatsAbly::Models::StatsAbly\Models\StatsIO.Ably.StatsStats object A `Stats` object represents an application's statistics for the specified interval and time period. Ably aggregates statistics globally for all accounts and applications, and makes these available both through our [statistics API](/docs/metadata-stats/stats) as well as your [application dashboard](https://ably.com/dashboard). @@ -149,7 +136,7 @@ Please note that most attributes of the `Stats` type below contain references to -#### MembersAttributesKeyword argumentsProperties +#### MembersAttributesKeyword argumentsProperties @@ -171,18 +158,6 @@ Please note that most attributes of the `Stats` type below contain references to - - -| Property | Description | Type | -|----------|-------------|------| -| appId | the ID of the Ably application the statistics relate to. | `String` | -| entries | The statistics for the requested time interval and time period. The `schema` property provides further information | `Partial>` | -| inProgress | Optional. For entires that are still in progress, such as the current month, the last sub-interval included in the stats entry. In the format `yyyy-mm-dd:hh:mm:ss` | `String` | -| intervalId | The UTC time period that the stats coverage begins at. If `unit` was requested as `minute` this will be in the format `YYYY-mm-dd:HH:MM`, if `hour` it will be `YYYY-mm-dd:HH`, if `day` it will be `YYYY-mm-dd:00` and if `month` it will be `YYYY-mm-01:00` | `String` | -| schema | The URL of a JSON schema describing the structure of the `Stats` object | `String` | - - - ### IO.Ably.StatsRequestParams @@ -202,44 +177,9 @@ Please note that most attributes of the `Stats` type below contain references to - - -### ARTStatsGranularityStatsIntervalGranularity - - + -`StatsIntervalGranularity` is an enum specifying the granularity of a [`Stats` interval](/docs/api/rest-sdk/statistics#stats-type). - - - - -```javascript - const StatsIntervalGranularity = [ - 'minute', - 'hour', - 'day', - 'month' - ] -``` - - - - - - -```nodejs - const StatsIntervalGranularity = [ - 'minute', - 'hour', - 'day', - 'month' - ] -``` - - - - - +### ARTStatsGranularityStatsIntervalGranularity diff --git a/src/pages/docs/api/rest-sdk/types.mdx b/src/pages/docs/api/rest-sdk/types.mdx index daeda03462..6364978346 100644 --- a/src/pages/docs/api/rest-sdk/types.mdx +++ b/src/pages/docs/api/rest-sdk/types.mdx @@ -118,21 +118,21 @@ The `occupancy` attribute contains the `metrics` attribute, which contains the f | objectPublishers | The number of connections that are authorised to publish updates to objects on the channel | `integer` | | objectSubscribers | The number of connections that are authorised to subscribe to objects on the channel | `integer` | -### ErrorInfoARTErrorInfoio.ably.lib.types.ErrorInfoAbly::Models::ErrorInfoAbly\Models\ErrorInfoIO.Ably.ErrorInfoably.ErrorInfo +### ErrorInfoARTErrorInfoio.ably.lib.types.ErrorInfoAbly::Models::ErrorInfoAbly\Models\ErrorInfoIO.Ably.ErrorInfoably.ErrorInfo An `ErrorInfo` is a type encapsulating error information containing an Ably-specific error code and generic status code. -#### PropertiesMembersAttributes +#### PropertiesMembersAttributes - + | Parameter | Description | Type | |-----------|-------------|------| -| codeCode | Ably error code (see [ably-common/protocol/errors.json](https://github.com/ably/ably-common/blob/main/protocol/errors.json)) | `Integer` | -| statusCodestatus_codeStatusCode | HTTP Status Code corresponding to this error, where applicable | `Integer` | -| messageMessage | Additional message information, where available | `String` | -| causeCause | Information pertaining to what caused the error where available | `ErrorInfo` | -| hrefHref | Ably may additionally include a URL to get more help on this error | `String` | +| codeCode | Ably error code (see [ably-common/protocol/errors.json](https://github.com/ably/ably-common/blob/main/protocol/errors.json)) | `Integer` | +| statusCodestatus_codeStatusCode | HTTP Status Code corresponding to this error, where applicable | `Integer` | +| messageMessage | Additional message information, where available | `String` | +| causeCause | Information pertaining to what caused the error where available | `ErrorInfo` | +| hrefHref | Ably may additionally include a URL to get more help on this error | `String` | @@ -157,48 +157,6 @@ One example of ErrorInfo nesting is [80019: Auth server rejecting request](/docs The following example demonstrates how to handle nested errors: - - - -```javascript -function handleError(error) { - console.log(`Main error: ${error.code} - ${error.message}`); - - // Check for nested error - if (error.cause) { - console.log(`Root cause: ${error.cause.code} - ${error.cause.message}`); - - // Handle further nesting if needed - if (error.cause.cause) { - console.log(`Deeper cause: ${error.cause.cause.code} - ${error.cause.cause.message}`); - } - } -} -``` - - - - - - -```nodejs -function handleError(error) { - console.log(`Main error: ${error.code} - ${error.message}`); - - // Check for nested error - if (error.cause) { - console.log(`Root cause: ${error.cause.code} - ${error.cause.message}`); - - // Handle further nesting if needed - if (error.cause.cause) { - console.log(`Deeper cause: ${error.cause.cause.code} - ${error.cause.cause.message}`); - } - } -} -``` - - - @@ -371,62 +329,46 @@ func handleError(err *ErrorInfo) { -### MessageARTMessageio.ably.lib.types.MessageAbly::Models::MessageAbly\Models\MessageIO.Ably.Message +### MessageARTMessageio.ably.lib.types.MessageAbly::Models::MessageAbly\Models\MessageIO.Ably.Message A `Message` represents an individual message that is sent to or received from Ably. -#### nameName +#### nameName The event name, if provided.
_Type: `String`_ -#### dataData +#### dataData -The message payload, if provided.
_Type: `String`, `StringBuffer`, `JSON Object``String`, `ByteArray`, `JSONObject`, `JSONArray``String`, `byte[]`, plain C# object that can be serialized to JSON`String`, `Binary` (ASCII-8BIT String), `Hash`, `Array``String`, `Bytearray`, `Dict`, `List``String`, `Binary String`, `Associative Array`, `Array``NSString *`, `NSData *`, `NSDictionary *`, `NSArray *``String`, `NSData`, `Dictionary`, `Array``String`, `Map`, `List`_ +The message payload, if provided.
_Type: `String`, `StringBuffer`, `JSON Object``String`, `ByteArray`, `JSONObject`, `JSONArray``String`, `byte[]`, plain C# object that can be serialized to JSON`String`, `Binary` (ASCII-8BIT String), `Hash`, `Array``String`, `Bytearray`, `Dict`, `List``String`, `Binary String`, `Associative Array`, `Array``NSString *`, `NSData *`, `NSDictionary *`, `NSArray *``String`, `NSData`, `Dictionary`, `Array``String`, `Map`, `List`_ -#### extrasExtras +#### extrasExtras -Metadata and/or ancillary payloads, if provided. Valid payloads include [`push`](/docs/push/publish#payload), `headers` (a map of strings to strings for arbitrary customer-supplied metadata), [`ephemeral`](/docs/pub-sub/advanced#ephemeral), and [`privileged`](/docs/platform/integrations/skip-integrations) objects.
_Type: `JSONObject`, `JSONArray`plain C# object that can be converted to JSON`JSON Object``Hash`, `Array``Dict`, `List``Dictionary`, `Array``NSDictionary *`, `NSArray *``Associative Array`, `Array``JSON Object`_ +Metadata and/or ancillary payloads, if provided. Valid payloads include [`push`](/docs/push/publish#payload), `headers` (a map of strings to strings for arbitrary customer-supplied metadata), [`ephemeral`](/docs/pub-sub/advanced#ephemeral), and [`privileged`](/docs/platform/integrations/skip-integrations) objects.
_Type: `JSONObject`, `JSONArray`plain C# object that can be converted to JSON`Hash`, `Array``Dict`, `List``Dictionary`, `Array``NSDictionary *`, `NSArray *``Associative Array`, `Array``JSON Object`_ -#### idId +#### idId A Unique ID assigned by Ably to this message.
_Type: `String`_ -#### clientIdClientIdclient_id +#### clientIdClientIdclient_id The client ID of the publisher of this message.
_Type: `String`_ -#### connectionIdConnectionIdconnection_id +#### connectionIdConnectionIdconnection_id The connection ID of the publisher of this message.
_Type: `String`_ -#### connectionKeyConnectionKeyconnection_key +#### connectionKeyConnectionKeyconnection_key A connection key, which can optionally be included for a REST publish as part of the [publishing on behalf of a realtime client functionality](/docs/pub-sub/advanced#publish-on-behalf).
_Type: `String`_ -#### timestampTimestamp +#### timestampTimestamp -Timestamp when the message was first received by the Ably, as milliseconds since the epocha `Time` object.
_Type: `Integer``Long Integer``DateTimeOffset``Time``NSDate`_ +Timestamp when the message was first received by the Ably, as milliseconds since the epocha `Time` object.
_Type: `Integer``Long Integer``DateTimeOffset``Time``NSDate`_ -#### encodingEncoding +#### encodingEncoding This will typically be empty as all messages received from Ably are automatically decoded client-side using this value. However, if the message encoding cannot be processed, this attribute will contain the remaining transformations not applied to the `data` payload.
_Type: `String`_ - - -#### action - -The action type of the message, one of the [`MessageAction`](/docs/api/realtime-sdk/types#message-action) enum values.
_Type: `int enum { MESSAGE_CREATE, MESSAGE_UPDATE, MESSAGE_DELETE, META, MESSAGE_SUMMARY, MESSAGE_APPEND }`_ - -#### serial - -A server-assigned identifier that will be the same in all future updates of this message. It can be used to add annotations to a message. Serial will only be set if you enable annotations in [rules](/docs/channels#rules).
_Type: `String`_ - -#### annotations - -An object containing information about annotations that have been made to the object.
_Type: [`MessageAnnotations`](/docs/api/realtime-sdk/types#message-annotations)_ - - - ### Message constructors #### Message.fromEncoded @@ -463,22 +405,22 @@ A static factory method to create an array of [`Messages`](/docs/api/realtime-sd An `Array` of [`Message`](/docs/api/realtime-sdk/types#message) objects -### PresenceMessageARTPresenceMessageio.ably.lib.types.PresenceMessageAbly::Models::PresenceMessageAbly\Models\PresenceMessageIO.Ably.PresenceMessage +### PresenceMessageARTPresenceMessageio.ably.lib.types.PresenceMessageAbly::Models::PresenceMessageAbly\Models\PresenceMessageIO.Ably.PresenceMessage A `PresenceMessage` represents an individual presence update that is sent to or received from Ably. -#### PropertiesMembersAttributes +#### PropertiesMembersAttributes | Parameter | Description | Type | |-----------|-------------|------| -| actionAction | The event signified by a PresenceMessage. See [`PresenceMessage.action`](/docs/api/realtime-sdk/types#presence-action)[`PresenceMessage.action`](/docs/api/realtime-sdk/types#presence-action)[`Presence action`](/docs/api/realtime-sdk/types#presence-action)[`PresenceAction`](/docs/api/realtime-sdk/types#presence-action)[`PresenceMessage::ACTION`](/docs/api/realtime-sdk/types#presence-action)[`PresenceMessage::ACTION`](/docs/api/realtime-sdk/types#presence-action)[`PresenceMessage.action`](/docs/api/realtime-sdk/types#presence-action)[`PresenceMessage::action`](/docs/api/realtime-sdk/types#presence-action)[`Presence action`](/docs/api/realtime-sdk/types#presence-action) | `enum { ABSENT, PRESENT, ENTER, LEAVE, UPDATE }``enum { Absent, Present, Enter, Leave, Update }``int enum { ABSENT, PRESENT, ENTER, LEAVE, UPDATE }``int enum { ABSENT, PRESENT, ENTER, LEAVE, UPDATE }``enum { :absent, :present, :enter, :leave, :update }``const PresenceMessage::ABSENT,PRESENT,ENTER,LEAVE,UPDATE``ARTPresenceAction``const PresenceMessage::PresenceAbsent,PresencePresent,PresenceEnter,PresenceLeave,PresenceUpdate` | -| dataData | The presence update payload, if provided | `String`, `ByteArray`, `JSONObject`, `JSONArray``String`, `byte[]`, plain C# object that can be converted to Json`String`, `StringBuffer`, `JSON Object``String`, `[]byte``String`, `Binary` (ASCII-8BIT String), `Hash`, `Array``String`, `Bytearray`, `Dict`, `List``String`, `NSData`, `Dictionary`, `Array``NSString *`, `NSData *`, `NSDictionary *`, `NSArray *``String`, `Binary String`, `Associative Array`, `Array``String`, `StringBuffer`, `JSON Object` | -| extrasExtras | Metadata and/or ancillary payloads, if provided. The only currently valid payloads for extras are the [`push`](/docs/push/publish#sub-channels), [`ref`](/docs/messages#interactions) and [`privileged`](/docs/platform/integrations/skip-integrations) objects | `JSONObject`, `JSONArray`plain C# object that can be converted to Json`String`, `[]byte``JSON Object``Hash`, `Array``Dict`, `List``Dictionary`, `Array``NSDictionary *`, `NSArray *``Associative Array`, `Array``Map`, `List` | -| idId | Unique ID assigned by Ably to this presence update | `String` | -| clientIdclient_idClientId | The client ID of the publisher of this presence update | `String` | -| connectionIdconnection_idConnectionId | The connection ID of the publisher of this presence update | `String` | -| timestampTimestamp | Timestamp when the presence update was received by Ably, as milliseconds since the epoch | `Integer``Long Integer``DateTimeOffset``Time``NSDate``Integer` | -| encodingEncoding | This will typically be empty as all presence updates received from Ably are automatically decoded client-side using this value. However, if the message encoding cannot be processed, this attribute will contain the remaining transformations not applied to the `data` payload | `String` | +| actionAction | The event signified by a PresenceMessage. See [`PresenceMessage.action`](/docs/api/realtime-sdk/types#presence-action)[`PresenceMessage.action`](/docs/api/realtime-sdk/types#presence-action)[`PresenceAction`](/docs/api/realtime-sdk/types#presence-action)[`PresenceMessage::ACTION`](/docs/api/realtime-sdk/types#presence-action)[`PresenceMessage::ACTION`](/docs/api/realtime-sdk/types#presence-action)[`PresenceMessage.action`](/docs/api/realtime-sdk/types#presence-action)[`PresenceMessage::action`](/docs/api/realtime-sdk/types#presence-action)[`Presence action`](/docs/api/realtime-sdk/types#presence-action) | `enum { ABSENT, PRESENT, ENTER, LEAVE, UPDATE }``enum { Absent, Present, Enter, Leave, Update }``int enum { ABSENT, PRESENT, ENTER, LEAVE, UPDATE }``int enum { ABSENT, PRESENT, ENTER, LEAVE, UPDATE }``enum { :absent, :present, :enter, :leave, :update }``const PresenceMessage::ABSENT,PRESENT,ENTER,LEAVE,UPDATE``ARTPresenceAction``const PresenceMessage::PresenceAbsent,PresencePresent,PresenceEnter,PresenceLeave,PresenceUpdate` | +| dataData | The presence update payload, if provided | `String`, `ByteArray`, `JSONObject`, `JSONArray``String`, `byte[]`, plain C# object that can be converted to Json`String`, `[]byte``String`, `Binary` (ASCII-8BIT String), `Hash`, `Array``String`, `Bytearray`, `Dict`, `List``String`, `NSData`, `Dictionary`, `Array``NSString *`, `NSData *`, `NSDictionary *`, `NSArray *``String`, `Binary String`, `Associative Array`, `Array``String`, `StringBuffer`, `JSON Object` | +| extrasExtras | Metadata and/or ancillary payloads, if provided. The only currently valid payloads for extras are the [`push`](/docs/push/publish#sub-channels), [`ref`](/docs/messages#interactions) and [`privileged`](/docs/platform/integrations/skip-integrations) objects | `JSONObject`, `JSONArray`plain C# object that can be converted to Json`String`, `[]byte``Hash`, `Array``Dict`, `List``Dictionary`, `Array``NSDictionary *`, `NSArray *``Associative Array`, `Array``Map`, `List` | +| idId | Unique ID assigned by Ably to this presence update | `String` | +| clientIdclient_idClientId | The client ID of the publisher of this presence update | `String` | +| connectionIdconnection_idConnectionId | The connection ID of the publisher of this presence update | `String` | +| timestampTimestamp | Timestamp when the presence update was received by Ably, as milliseconds since the epoch | `Integer``Long Integer``DateTimeOffset``Time``NSDate``Integer` | +| encodingEncoding | This will typically be empty as all presence updates received from Ably are automatically decoded client-side using this value. However, if the message encoding cannot be processed, this attribute will contain the remaining transformations not applied to the `data` payload | `String` | ### PresenceMessage constructors @@ -516,42 +458,8 @@ A static factory method to create an array of [`PresenceMessages`](/docs/api/rea An `Array` of [`PresenceMessage`](/docs/api/realtime-sdk/types#presence-message) objects -### Presence actionARTPresenceActionio.ably.lib.types.PresenceMessage.ActionAbly::Models::PresenceMessage::ACTIONAbly\Models\PresenceMessage ActionIO.Ably.PresenceAction - - -`Presence` `action` is a String with a value matching any of the [`Realtime Presence` states & events](/docs/presence-occupancy/presence#trigger-events). - - - - -```javascript - var PresenceActions = [ - 'absent', // (reserved for internal use) - 'present', - 'enter', - 'leave', - 'update' - ] -``` - +### Presence actionARTPresenceActionio.ably.lib.types.PresenceMessage.ActionAbly::Models::PresenceMessage::ACTIONAbly\Models\PresenceMessage ActionIO.Ably.PresenceAction - - - - -```nodejs - var PresenceActions = [ - 'absent', // (reserved for internal use) - 'present', - 'enter', - 'leave', - 'update' - ] -``` - - - - `io.ably.lib.types.PresenceMessage.Action` is an enum representing all the [`Realtime Presence` states & events](/docs/presence-occupancy/presence#trigger-events). @@ -727,25 +635,20 @@ const ( -### PaginatedResultARTPaginatedResultio.ably.lib.types.PaginatedResultAbly::Models::PaginatedResultAbly\Models\PaginatedResultIO.Ably.PaginatedResult +### PaginatedResultARTPaginatedResultio.ably.lib.types.PaginatedResultAbly::Models::PaginatedResultAbly\Models\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](/docs/api/rest-api/#pagination) is accompanied by metadata that indicates the relative queries available to the `PaginatedResult` object. -#### PropertiesMembersAttributes +#### PropertiesMembersAttributes | Parameter | Description | Type | |-----------|-------------|------| -| itemsItems | Contains the current page of results (for example an Array of [`Message`](#message) or [`PresenceMessage`](#presence-message) objects for a channel history request) | `Array``List` | +| itemsItems | Contains the current page of results (for example an Array of [`Message`](#message) or [`PresenceMessage`](#presence-message) objects for a channel history request) | `Array``List` | #### Methods -##### firstFirst - - - -`first(): Promise` +##### firstFirst - `PaginatedResult first` @@ -792,15 +695,10 @@ A `PaginatedResult` is a type that represents a page of results for all message Returns a new `PaginatedResult` for the first page of results. When using the Realtime library, the `first` method returns a [Deferrable](/docs/api/realtime-sdk/types#deferrable) and yields a [PaginatedResult](#paginated-result).The method is asynchronous and returns a Task which needs to be awaited to get the [PaginatedResult](#paginated-result). - - -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`](/docs/api/realtime-sdk/types#error-info) object that details the reason why it was rejected. - +##### hasNextHasNexthas_next?has_next -##### hasNextHasNexthas_next?has_next - - + `Boolean hasNext()` @@ -826,11 +724,11 @@ Returns a promise. On success, the promise is fulfilled with a new `PaginatedRes -Returns `true` if there are more pages available by calling `next``Next` and returns `false` if this page is the last page available. +Returns `true` if there are more pages available by calling `next``Next` and returns `false` if this page is the last page available. -##### isLastIsLastlast?is_last +##### isLastIsLastlast?is_last - + ` Boolean isLast()` @@ -856,15 +754,10 @@ Returns `true` if there are more pages available by calling `next``Next` available. - -##### nextNext +Returns `true` if this page is the last page and returns `false` if there are more pages available by calling `next``Next` available. - +##### nextNext -`next(): Promise` - - `PaginatedResult next` @@ -910,51 +803,10 @@ Returns `true` if this page is the last page and returns `false` if there are mo Returns a new `PaginatedResult` loaded with the next page of results. If there are no further pages, then `null`a blank PaginatedResult will be returned`Null``None``nil` is returned. The method is asynchronous and return a Task which needs to be awaited to get the `PaginatedResult`When using the Realtime library, the `first` method returns a [Deferrable](/docs/api/realtime-sdk/types#deferrable) and yields a [PaginatedResult](#paginated-result). - - - -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`](/docs/api/realtime-sdk/types#error-info) object that details the reason why it was rejected. - - - - - -##### current - -`current(): Promise<[PaginatedResult](#paginated-result>)` - -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`](/docs/api/realtime-sdk/types#error-info) object that details the reason why it was rejected. - #### Example - - - -```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()); -``` - - - - - - -```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()); -``` - - - @@ -1099,16 +951,16 @@ channel.history { paginatedResult, error in An `HttpPaginatedResponse` is a superset of [`PaginatedResult`](/docs/api/rest-sdk/types#paginated-result), which is a type that represents a page of results plus metadata indicating the relative queries available to it. `HttpPaginatedResponse` additionally carries information about the response to an HTTP request. It is used when [making custom HTTP requests](/docs/api/rest-sdk#request). -#### PropertiesMembersAttributes +#### PropertiesMembersAttributes - + | Parameter | Description | Type | |-----------|-------------|------| | statusCode | The HTTP status code of the response | `Number` | | success | Whether the HTTP status code indicates success. This is equivalent to `200 <= statusCode < 300` | `Boolean` | | headers | The headers of the response | `Object` | -| errorCode | The error code if the `X-Ably-Errorcode` HTTP header is sent in the response | `Number``Int` | +| errorCode | The error code if the `X-Ably-Errorcode` HTTP header is sent in the response | `Int` | | errorMessage | The error message if the `X-Ably-Errormessage` HTTP header is sent in the response | `String` | @@ -1116,35 +968,30 @@ An `HttpPaginatedResponse` is a superset of [`PaginatedResult`](/docs/api/rest-s | Parameter | Description | Type | |-----------|-------------|------| -| itemsItems | Contains a page of results; for example, an array of [`Message`](#message) or [`PresenceMessage`](#presence-message) objects for a channel history request | `Array``List` | -| statusCodestatus_codeStatusCode | The HTTP status code of the response | `Number` | -| successSuccess | Whether the HTTP status code indicates success. This is equivalent to `200 <= statusCode < 300``200 <= status_code < 300``200 <= StatusCode < 300` | `Boolean` | -| headersHeaders | The headers of the response | `Object` | -| errorCodeerror_codeErrorCode | The error code if the `X-Ably-Errorcode` HTTP header is sent in the response | `Number``Int` | -| errorMessageerror_messageErrorMessage | The error message if the `X-Ably-Errormessage` HTTP header is sent in the response | `String` | +| itemsItems | Contains a page of results; for example, an array of [`Message`](#message) or [`PresenceMessage`](#presence-message) objects for a channel history request | `Array``List` | +| statusCodestatus_codeStatusCode | The HTTP status code of the response | `Number` | +| successSuccess | Whether the HTTP status code indicates success. This is equivalent to `200 <= statusCode < 300``200 <= status_code < 300``200 <= StatusCode < 300` | `Boolean` | +| headersHeaders | The headers of the response | `Object` | +| errorCodeerror_codeErrorCode | The error code if the `X-Ably-Errorcode` HTTP header is sent in the response | `Int` | +| errorMessageerror_messageErrorMessage | The error message if the `X-Ably-Errormessage` HTTP header is sent in the response | `String` | | Parameter | Description | Type | |-----------|-------------|------| -| statusCodestatus_codeStatusCode | The HTTP status code of the response | `Number` | -| successSuccess | Whether the HTTP status code indicates success. This is equivalent to `200 <= statusCode < 300``200 <= status_code < 300``200 <= StatusCode < 300` | `Boolean` | -| headersHeaders | The headers of the response | `Object` | -| errorCodeerror_codeErrorCode | The error code if the `X-Ably-Errorcode` HTTP header is sent in the response | `Number``Int` | -| errorMessageerror_messageErrorMessage | The error message if the `X-Ably-Errormessage` HTTP header is sent in the response | `String` | +| statusCodestatus_codeStatusCode | The HTTP status code of the response | `Number` | +| successSuccess | Whether the HTTP status code indicates success. This is equivalent to `200 <= statusCode < 300``200 <= status_code < 300``200 <= StatusCode < 300` | `Boolean` | +| headersHeaders | The headers of the response | `Object` | +| errorCodeerror_codeErrorCode | The error code if the `X-Ably-Errorcode` HTTP header is sent in the response | `Int` | +| errorMessageerror_messageErrorMessage | The error message if the `X-Ably-Errormessage` HTTP header is sent in the response | `String` | #### Methods -##### firstFirst - - - -`first(): Promise` +##### firstFirst - `HttpPaginatedResponse first` @@ -1190,16 +1037,11 @@ An `HttpPaginatedResponse` is a superset of [`PaginatedResult`](/docs/api/rest-s Returns a new `HttpPaginatedResponse` for the first page of results. When using the Realtime library, the `first` method returns a [Deferrable](/docs/api/realtime-sdk/types#deferrable) and yields an [`HttpPaginatedResponse`](/docs/api/realtime-sdk/types#http-paginated-response).The method is asynchronous and returns a Task which needs to be awaited to get the `HttpPaginatedResponse`. - - - -Returns a promise. On success, the promise is fulfilled with a new `HttpPaginatedResponse` for the first page of results. On failure, the promise is rejected with an [`ErrorInfo`](/docs/api/realtime-sdk/types#error-info) object that details the reason why it was rejected. - -##### hasNextHasNexthas_next?has_next +##### hasNextHasNexthas_next?has_next - + `Boolean hasNext()` @@ -1225,11 +1067,11 @@ Returns a promise. On success, the promise is fulfilled with a new `HttpPaginate -Returns `true` if there are more pages available by calling `next``Next` and returns `false` if this page is the last page available. +Returns `true` if there are more pages available by calling `next``Next` and returns `false` if this page is the last page available. -##### isLastIsLastlast?is_last +##### isLastIsLastlast?is_last - + `Boolean isLast()` @@ -1255,15 +1097,10 @@ Returns `true` if there are more pages available by calling `next``Next` available. +Returns `true` if this page is the last page and returns `false` if there are more pages available by calling `next``Next` available. -##### nextNext +##### nextNext - - -`next(): Promise` - - `HttpPaginatedResponse next` @@ -1309,17 +1146,6 @@ Next() (HttpPaginatedResponse, error)` Returns a new `HttpPaginatedResponse` loaded with the next page of results. If there are no further pages, then `null`a blank HttpPaginatedResponse will be returned`Null``None``nil` is returned. The method is asynchronous and return a Task which needs to be awaited to get the `HttpPaginatedResponse`When using the Realtime library, the `first` method returns a [Deferrable](/docs/api/realtime-sdk/types#deferrable) and yields an [HttpPaginatedResponse](/docs/api/realtime-sdk/types#http-paginated-response). - - - -Returns a promise. On success, the promise is fulfilled with a new `HttpPaginatedResponse` 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`](/docs/api/realtime-sdk/types#error-info) object that details the reason why it was rejected. - -##### current - -`current(): Promise` - -Returns a promise. On success, the promise is fulfilled with a new `HttpPaginatedResponse` loaded with the current page of results. On failure, the promise is rejected with an [`ErrorInfo`](/docs/api/realtime-sdk/types#error-info) object that details the reason why it was rejected. - ##### Example @@ -1346,19 +1172,19 @@ Please note that `key` and `value` attributes are always strings. If an `Integer -### TokenDetailsARTTokenDetialsio.ably.lib.types.TokenDetailsAbly::Models::TokenDetailsAbly\Models\TokenDetailsIO.Ably.TokenDetails +### TokenDetailsARTTokenDetialsio.ably.lib.types.TokenDetailsAbly::Models::TokenDetailsAbly\Models\TokenDetailsIO.Ably.TokenDetails `TokenDetails` is a type providing details of Ably Token string and its associated metadata. -#### PropertiesMembersAttributes +#### PropertiesMembersAttributes | Parameter | Description | Type | |-----------|-------------|------| -| tokenToken | The [Ably Token](/docs/api/realtime-sdk/authentication#token-details) itself. A typical [Ably Token](/docs/api/realtime-sdk/authentication#token-details) string may appear like `{{TOKEN}}` | `String` | -| expiresExpires | The time (in milliseconds since the epoch)The time at which this token expires | `Integer``Long Integer``DateTimeOffset``Time``NSDate` | -| issuedIssued | The time (in milliseconds since the epoch)The time at which this token was issued | `Integer``Long Integer``DateTimeOffset``Time``NSDate` | -| capabilityCapability | The capability associated with this [Ably Token](/docs/api/realtime-sdk/authentication#token-details). The capability is a a JSON stringified canonicalized representation of the resource paths and associated operations. [Read more about authentication and capabilities](/docs/auth/capabilities) | `String``Capability` | -| clientIdclient_idClientId | The client ID, if any, bound to this [Ably Token](/docs/api/realtime-sdk/authentication#token-details). If a client ID is included, then the [Ably Token](/docs/api/realtime-sdk/authentication#token-details) authenticates its bearer as that client ID, and the [Ably Token](/docs/api/realtime-sdk/authentication#token-details) may only be used to perform operations on behalf of that client ID. The client is then considered to be an [identified client](/docs/auth/identified-clients) | `String` | +| tokenToken | The [Ably Token](/docs/api/realtime-sdk/authentication#token-details) itself. A typical [Ably Token](/docs/api/realtime-sdk/authentication#token-details) string may appear like `{{TOKEN}}` | `String` | +| expiresExpires | The time (in milliseconds since the epoch)The time at which this token expires | `Integer``Long Integer``DateTimeOffset``Time``NSDate` | +| issuedIssued | The time (in milliseconds since the epoch)The time at which this token was issued | `Integer``Long Integer``DateTimeOffset``Time``NSDate` | +| capabilityCapability | The capability associated with this [Ably Token](/docs/api/realtime-sdk/authentication#token-details). The capability is a a JSON stringified canonicalized representation of the resource paths and associated operations. [Read more about authentication and capabilities](/docs/auth/capabilities) | `String``Capability` | +| clientIdclient_idClientId | The client ID, if any, bound to this [Ably Token](/docs/api/realtime-sdk/authentication#token-details). If a client ID is included, then the [Ably Token](/docs/api/realtime-sdk/authentication#token-details) authenticates its bearer as that client ID, and the [Ably Token](/docs/api/realtime-sdk/authentication#token-details) may only be used to perform operations on behalf of that client ID. The client is then considered to be an [identified client](/docs/auth/identified-clients) | `String` | @@ -1390,9 +1216,9 @@ Please note that `key` and `value` attributes are always strings. If an `Integer ### TokenDetails constructors -#### TokenDetails.fromJsonTokenDetails.from_jsonTokenDetails.fromMap +#### TokenDetails.fromJsonTokenDetails.from_jsonTokenDetails.fromMap - + `TokenDetails.fromJson(String json) -> TokenDetails` @@ -1408,11 +1234,11 @@ Please note that `key` and `value` attributes are always strings. If an `Integer -A static factory methodnamed constructor to create a [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) from a deserialized `TokenDetails`-like object or a JSON stringified `TokenDetails`map. This method is provided to minimize bugs as a result of differing types by platform for fields such as `timestamp` or `ttl`. For example, in Ruby `ttl` in the `TokenDetails` object is exposed in seconds as that is idiomatic for the language, yet when serialized to JSON using `to_json` it is automatically converted to the Ably standard which is milliseconds. By using the `fromJson``fromMap` method when constructing a `TokenDetails`, Ably ensures that all fields are consistently serialized and deserialized across platforms. +A static factory methodnamed constructor to create a [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) from a deserialized `TokenDetails`-like object or a JSON stringified `TokenDetails`map. This method is provided to minimize bugs as a result of differing types by platform for fields such as `timestamp` or `ttl`. For example, in Ruby `ttl` in the `TokenDetails` object is exposed in seconds as that is idiomatic for the language, yet when serialized to JSON using `to_json` it is automatically converted to the Ably standard which is milliseconds. By using the `fromJson``fromMap` method when constructing a `TokenDetails`, Ably ensures that all fields are consistently serialized and deserialized across platforms. ##### Parameters - + | Parameter | Description | Type | |-----------|-------------|------| @@ -1431,27 +1257,27 @@ A static A [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) object -### TokenRequestAbly\Models\TokenRequestARTTokenRequestio.ably.lib.types.TokenRequestAbly::Models::TokenRequestIO.Ably.TokenRequest +### TokenRequestAbly\Models\TokenRequestARTTokenRequestio.ably.lib.types.TokenRequestAbly::Models::TokenRequestIO.Ably.TokenRequest -`TokenRequest` is a type containing parameters for an Ably `TokenRequest`. [Ably Tokens](/docs/api/realtime-sdk/authentication#token-details) are requested using [Auth#requestToken](/docs/api/rest-sdk/authentication#request-token)[Auth#request_token](/docs/api/rest-sdk/authentication#request-token) +`TokenRequest` is a type containing parameters for an Ably `TokenRequest`. [Ably Tokens](/docs/api/realtime-sdk/authentication#token-details) are requested using [Auth#requestToken](/docs/api/rest-sdk/authentication#request-token)[Auth#request_token](/docs/api/rest-sdk/authentication#request-token) -#### PropertiesMembersAttributes +#### PropertiesMembersAttributes | Parameter | Description | Type | |-----------|-------------|------| -| keyNamekey_nameKeyName | The key name of the key against which this request is made. The key name is public, whereas the key secret is private | `String` | -| ttlTtl | Requested time to live for the [Ably Token](/docs/api/realtime-sdk/authentication#token-details) in millisecondsin secondsas a `TimeSpan`. If the Ably `TokenRequest` is successful, the TTL of the returned [Ably Token](/docs/api/realtime-sdk/authentication#token-details) will be less than or equal to this value depending on application settings and the attributes of the issuing key. | `Integer``TimeSpan``NSTimeInterval` | -| timestampTimestamp | The timestamp of this request in milliseconds | `Integer``Long Integer``Time``DateTimeOffset``NSDate` | -| capabilityCapability | Capability of the requested [Ably Token](/docs/api/realtime-sdk/authentication#token-details). If the Ably `TokenRequest` is successful, the capability of the returned [Ably Token](/docs/api/realtime-sdk/authentication#token-details) will be the intersection of this capability with the capability of the issuing key. The capability is a JSON stringified canonicalized representation of the resource paths and associated operations. [Read more about authentication and capabilities](/docs/auth) | `String` | -| clientIdclient_idClientId | The client ID to associate with the requested [Ably Token](/docs/api/realtime-sdk/authentication#token-details). When provided, the [Ably Token](/docs/api/realtime-sdk/authentication#token-details) may only be used to perform operations on behalf of that client ID | `String` | -| nonceNonce | An opaque nonce string of at least 16 characters | `String` | -| macMac | The Message Authentication Code for this request | `String` | +| keyNamekey_nameKeyName | The key name of the key against which this request is made. The key name is public, whereas the key secret is private | `String` | +| ttlTtl | Requested time to live for the [Ably Token](/docs/api/realtime-sdk/authentication#token-details) in millisecondsin secondsas a `TimeSpan`. If the Ably `TokenRequest` is successful, the TTL of the returned [Ably Token](/docs/api/realtime-sdk/authentication#token-details) will be less than or equal to this value depending on application settings and the attributes of the issuing key. | `Integer``TimeSpan``NSTimeInterval` | +| timestampTimestamp | The timestamp of this request in milliseconds | `Integer``Long Integer``Time``DateTimeOffset``NSDate` | +| capabilityCapability | Capability of the requested [Ably Token](/docs/api/realtime-sdk/authentication#token-details). If the Ably `TokenRequest` is successful, the capability of the returned [Ably Token](/docs/api/realtime-sdk/authentication#token-details) will be the intersection of this capability with the capability of the issuing key. The capability is a JSON stringified canonicalized representation of the resource paths and associated operations. [Read more about authentication and capabilities](/docs/auth) | `String` | +| clientIdclient_idClientId | The client ID to associate with the requested [Ably Token](/docs/api/realtime-sdk/authentication#token-details). When provided, the [Ably Token](/docs/api/realtime-sdk/authentication#token-details) may only be used to perform operations on behalf of that client ID | `String` | +| nonceNonce | An opaque nonce string of at least 16 characters | `String` | +| macMac | The Message Authentication Code for this request | `String` | ### TokenRequest constructors -#### TokenRequest.fromJsonTokenRequest.from_jsonTokenRequest.fromMap +#### TokenRequest.fromJsonTokenRequest.from_jsonTokenRequest.fromMap - + `TokenRequest.fromJson(String json) -> TokenRequest` @@ -1467,11 +1293,11 @@ A [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) object -A static factory methodnamed constructor to create a [`TokenRequest`](/docs/api/realtime-sdk/types#token-request) from a deserialized `TokenRequest`-like object or a JSON stringified `TokenRequest`map. This method is provided to minimize bugs as a result of differing types by platform for fields such as `timestamp` or `ttl`. For example, in Ruby `ttl` in the `TokenRequest` object is exposed in seconds as that is idiomatic for the language, yet when serialized to JSON using `to_json` it is automatically converted to the Ably standard which is milliseconds. By using the `fromJson``fromMap` method when constructing a `TokenRequest`, Ably ensures that all fields are consistently serialized and deserialized across platforms. +A static factory methodnamed constructor to create a [`TokenRequest`](/docs/api/realtime-sdk/types#token-request) from a deserialized `TokenRequest`-like object or a JSON stringified `TokenRequest`map. This method is provided to minimize bugs as a result of differing types by platform for fields such as `timestamp` or `ttl`. For example, in Ruby `ttl` in the `TokenRequest` object is exposed in seconds as that is idiomatic for the language, yet when serialized to JSON using `to_json` it is automatically converted to the Ably standard which is milliseconds. By using the `fromJson``fromMap` method when constructing a `TokenRequest`, Ably ensures that all fields are consistently serialized and deserialized across platforms. ##### Parameters - + | Parameter | Description | Type | |-----------|-------------|------| @@ -1490,7 +1316,7 @@ A static A [`TokenRequest`](/docs/api/realtime-sdk/types#token-request) object -### Stats objectARTStatsio.ably.lib.types.StatsAbly::Models::StatsAbly\Models\StatsIO.Ably.Stats +### Stats objectARTStatsio.ably.lib.types.StatsAbly::Models::StatsAbly\Models\StatsIO.Ably.Stats A `Stats` object represents an application's statistics for the specified interval and time period. Ably aggregates statistics globally for all accounts and applications, and makes these available both through our [statistics API](/docs/metadata-stats/stats) as well as your [application dashboard](https://ably.com/dashboard). @@ -1500,7 +1326,7 @@ Please note that most attributes of the `Stats` type below contain references to -##### PropertiesMembersAttributesKeyword arguments +##### PropertiesMembersAttributesKeyword arguments @@ -1556,55 +1382,10 @@ Please note that most attributes of the `Stats` type below contain references to | pushPush | Detailed stats on push notifications, see [our Push documentation](/push) for more details | `PushStats` | - - -| Parameter | Description | Type | -|-----------|-------------|------| -| appId | The ID of the Ably application the statistics relate to. | `String` | -| entries | The statistics for the requested time interval and time period. The `schema` property provides further information | `Partial>` | -| inProgress | Optional. For entries that are still in progress, such as the current month, the last sub-interval included in the stats entry. In the format `yyyy-mm-dd:hh:mm:ss` | `String` | -| intervalId | The UTC time period that the stats coverage begins at. If `unit` was requested as `minute` this will be in the format `YYYY-mm-dd:HH:MM`, if `hour` it will be `YYYY-mm-dd:HH`, if `day` it will be `YYYY-mm-dd:00` and if `month` it will be `YYYY-mm-01:00` | `String` | -| schema | The URL of a JSON schema describing the structure of the `Stats` object | `String` | - - - - - -### StatsIntervalGranularityARTStatsGranularity - - - -`StatsIntervalGranularity` is an enum specifying the granularity of a [`Stats interval`](/docs/api/rest-sdk/statistics#stats-type). - - - - -```javascript - const StatsIntervalGranularity = [ - 'minute', - 'hour', - 'day', - 'month' - ] -``` - - - - - -```nodejs - const StatsIntervalGranularity = [ - 'minute', - 'hour', - 'day', - 'month' - ] -``` - + - - +### StatsIntervalGranularityARTStatsGranularity @@ -1676,109 +1457,10 @@ Please note that most attributes of the `Stats` type below contain references to - - -### BatchPublishSpec - -A `BatchPublishSpec` describes the messages that should be published by a batch publish operation, and the channels to which they should be published. - -#### Properties - -| Parameter | Description | Type | -|-----------|-------------|------| -| channels | The names of the channels to publish the `messages` to | `String[]` | -| messages | An array of [`Message`](/docs/api/realtime-sdk/types#message) objects | [`Message[]`](/docs/api/realtime-sdk/types#message) | - -### BatchResult - -A `BatchResult` contains information about the results of a batch operation. - -#### Properties - -| Parameter | Description | Type | -|-----------|-------------|------| -| successCount | The number of successful operations in the request | `Number` | -| failureCount | The number of unsuccessful operations in the request | `Number` | -| messages | An array of results for the batch operation (for example, an array of [`BatchPublishSuccessResult`](/docs/api/realtime-sdk/types#batch-publish-success-result) or [`BatchPublishFailureResult`](/docs/api/realtime-sdk/types#batch-publish-failure-result) for a channel batch publish request) | `Object[]` | - -### BatchPublishSuccessResult - -A `BatchPublishSuccessResult` contains information about the result of successful publishes to a channel requested by a single [`BatchPublishSpec`](/docs/api/realtime-sdk/types#batch-publish-spec). - -#### Properties - -| Parameter | Description | Type | -|-----------|-------------|------| -| channel | The name of the channel the message(s) was published to | `String` | -| messageId | A unique ID prefixed to the `Message.id` of each published message | `String` | - -### BatchPublishFailureResult - -A `BatchPublishFailureResult` contains information about the result of unsuccessful publishes to a channel requested by a single [`BatchPublishSpec`](/docs/api/realtime-sdk/types#batch-publish-spec). - -#### Properties - -| Parameter | Description | Type | -|-----------|-------------|------| -| channel | The name of the channel the message(s) failed to be published to | `String` | -| error | Describes the reason for which the message(s) failed to publish to the channel as an [`ErrorInfo`](/docs/api/realtime-sdk/types#error-info) object | [`ErrorInfo`](/docs/api/realtime-sdk/types#error-info) | - -### BatchPresenceSuccessResult - -A `BatchPresenceSuccessResult` contains information about the result of a successful batch presence request for a single channel. - -#### Properties - -| Parameter | Description | Type | -|-----------|-------------|------| -| channel | The channel name the presence state was retrieved for | `String` | -| presence | An array of [`PresenceMessage`](/docs/api/realtime-sdk/types#presence-message) describing members present on the channel | [`PresenceMessage[]`](/docs/api/realtime-sdk/types#presence-message) | - -### BatchPresenceFailureResult - -A BatchPresenceFailureResult contains information about the result of an unsuccessful batch presence request for a single channel. - -#### Properties - -| Parameter | Description | Type | -|-----------|-------------|------| -| channel | The channel name the presence state failed to be retrieved for | `String` | -| error | Describes the reason for which presence state could not be retrieved for the channel as an [`ErrorInfo`](/docs/api/realtime-sdk/types#error-info) object | [`ErrorInfo`](/docs/api/realtime-sdk/types#error-info) | - -### TokenRevocationSuccessResult - -A `TokenRevocationSuccessResult` contains information about the result of a successful token revocation request for a single target specifier. - -#### Properties - -| Parameter | Description | Type | -|-----------|-------------|------| -| target | The target specifier | `String` | -| appliesAt | The time at which the token revocation will take effect, as a Unix timestamp in milliseconds | `Number` | -| issuedBefore | A Unix timestamp in milliseconds. Only tokens issued earlier than this time will be revoked | `Number` | - -### TokenRevocationFailureResult - -A `TokenRevocationFailureResult` contains information about the result of an unsuccessful token revocation request for a single target specifier. - -#### Properties - -| Parameter | Description | Type | -|-----------|-------------|------| -| target | The target specifier | `String` | -| error | Describes the reason for which token revocation failed for the given `target` as an [`ErrorInfo`](/docs/api/realtime-sdk/types#error-info) object | [`ErrorInfo`](/docs/api/realtime-sdk/types#error-info) | - - - ## REST Other types -### AuthOptions ObjectARTAuthOptionsAuthOptions HashAuthOptions Arrayio.ably.lib.rest.Auth.AuthOptionsIO.Ably.AuthOptions +### AuthOptions ObjectARTAuthOptionsAuthOptions HashAuthOptions Arrayio.ably.lib.rest.Auth.AuthOptionsIO.Ably.AuthOptions - - -`AuthOptions` is a plain JavaScript object and is used when making [authentication](/docs/auth) requests. If passed in, an `authOptions` object will be used instead of (as opposed to supplementing or being merged with) the default values given when the library was instantiated. The following attributes are supported: - - `AuthOptions` is a Hash object and is used when making [authentication](/docs/auth) requests. These options will supplement or override the corresponding options given when the library was instantiated. The following key symbol values can be added to the Hash: @@ -1800,28 +1482,22 @@ A `TokenRevocationFailureResult` contains information about the result of an uns -#### PropertiesMembersAttributes +#### PropertiesMembersAttributes | Parameter | Description | Type | |-----------|-------------|------| -| authCallbackAuthCallbackauth_callback:auth_callback | A functionfunction with the form `function(tokenParams, callback(err, tokenOrTokenRequest))``TokenCallback` instancecallable (eg a lambda)proc / lambda (called synchronously in REST and Realtime but does not block EventMachine in the latter) which is called when a new token is required. The role of the callback is to obtain a fresh token, one of: an Ably Token string (in plain text format); a signed [`TokenRequest`](/docs/api/realtime-sdk/types#token-request); a [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) (in JSON format); an [Ably JWT](/docs/api/realtime-sdk/authentication#ably-jwt). See [our authentication documentation](/docs/auth) for details of the Ably TokenRequest format and associated API calls. | `Callable``TokenCallback``Proc``Func>``Callable` | -| authUrlAuthUrl:auth_urlauth_url | A URL that the library may use to obtain a fresh token, one of: an Ably Token string (in plain text format); a signed [`TokenRequest`](/docs/api/realtime-sdk/types#token-request); a [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) (in JSON format); an [Ably JWT](/docs/api/realtime-sdk/authentication#ably-jwt). For example, this can be used by a client to obtain signed Ably TokenRequests from an application server. | `String``Uri``NSURL` | -| authMethodAuthMethodauth_method:auth_method | The HTTP verb to use for the request, either `GET``:get` or `POST``:post`. The default is `GET``:get`. | `String``Symbol``HttpMethod` | -| authHeadersAuthHeadersauth_headers:auth_headers | A set of key value pair headers to be added to any request made to the `authUrl``AuthUrl`. Useful when an application requires these to be added to validate the request or implement the response. If the `authHeaders` object contains an `authorization` key, then `withCredentials` will be set on the xhr request. | `Object``Dict``Hash`Associative Array`Param []``Dictionary``Map``Object` | -| authParamsAuthParams:auth_paramsauth_params | A set of key value pair params to be added to any request made to the `authUrl``AuthUrl`. When the `authMethod``AuthMethod` is `GET`, query params are added to the URL, whereas when `authMethod``AuthMethod` is `POST`, the params are sent as URL encoded form data. Useful when an application require these to be added to validate the request or implement the response. | `Object``Hash`Associative Array`Param[]``Dictionary``NSArray``[NSURLQueryItem]/Array``Map``Object``Object` | -| tokenDetailsTokenDetailstoken_details:token_details | An authenticated [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) object (most commonly obtained from an Ably Token Request response). This option is mostly useful for testing: since tokens are short-lived, in production you almost always want to use an authentication method that allows the client library to renew the token automatically when the previous one expires, such as `authUrl``AuthUrl``:auth_url``auth_url` or `authCallback``AuthCallback``auth_callback``:auth_callback`. Use this option if you wish to use Token authentication. Read more about [Token authentication](/docs/auth/token) | `TokenDetails` | -| keyKey:keykey | Optionally the [API key](/docs/auth#api-keys) to use can be specified as a full key string; if not, the API key passed into [`ClientOptions`](#client-options) when instancing the Realtime or REST library is used | `String` | -| queryTimeQueryTime:query_timequery_time | If true, the library will query the Ably servers for the current time when [issuing TokenRequests](/docs/auth/token) instead of relying on a locally-available time of day. Knowing the time accurately is needed to create valid signed Ably [TokenRequests](/docs/auth/token), so this option is useful for library instances on auth servers where for some reason the server clock cannot be kept synchronized through normal means, such as an [NTP daemon](https://en.wikipedia.org/wiki/Ntpd). The server is queried for the current time once per client library instance (which stores the offset from the local clock), so if using this option you should avoid instancing a new version of the library for each request. The default is false. | `Boolean` | -| tokenToken:tokentoken | An authenticated token. This can either be a [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) object, a [`TokenRequest`](/docs/api/realtime-sdk/types#token-request) object, or token string (obtained from the `token``Token` property of a [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) component of an Ably TokenRequest response, or a [JSON Web Token](https://tools.ietf.org/html/rfc7519) satisfying [the Ably requirements for JWTs](/docs/auth/token/jwt)). This option is mostly useful for testing: since tokens are short-lived, in production you almost always want to use an authentication method that allows the client library to renew the token automatically when the previous one expires, such as `authUrl``AuthUrl``:auth_url``auth_url` or `authCallback``AuthCallback``auth_callback``:auth_callback`. Read more about [Token authentication](/docs/auth/token) | `String`, `TokenDetails` or `TokenRequest` | +| authCallbackAuthCallbackauth_callback:auth_callback | A function`TokenCallback` instancecallable (eg a lambda)proc / lambda (called synchronously in REST and Realtime but does not block EventMachine in the latter) which is called when a new token is required. The role of the callback is to obtain a fresh token, one of: an Ably Token string (in plain text format); a signed [`TokenRequest`](/docs/api/realtime-sdk/types#token-request); a [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) (in JSON format); an [Ably JWT](/docs/api/realtime-sdk/authentication#ably-jwt). See [our authentication documentation](/docs/auth) for details of the Ably TokenRequest format and associated API calls. | `Callable``TokenCallback``Proc``Func>``Callable` | +| authUrlAuthUrl:auth_urlauth_url | A URL that the library may use to obtain a fresh token, one of: an Ably Token string (in plain text format); a signed [`TokenRequest`](/docs/api/realtime-sdk/types#token-request); a [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) (in JSON format); an [Ably JWT](/docs/api/realtime-sdk/authentication#ably-jwt). For example, this can be used by a client to obtain signed Ably TokenRequests from an application server. | `String``Uri``NSURL` | +| authMethodAuthMethodauth_method:auth_method | The HTTP verb to use for the request, either `GET``:get` or `POST``:post`. The default is `GET``:get`. | `String``Symbol``HttpMethod` | +| authHeadersAuthHeadersauth_headers:auth_headers | A set of key value pair headers to be added to any request made to the `authUrl``AuthUrl`. Useful when an application requires these to be added to validate the request or implement the response. | `Object``Dict``Hash`Associative Array`Param []``Dictionary``Map``Object` | +| authParamsAuthParams:auth_paramsauth_params | A set of key value pair params to be added to any request made to the `authUrl``AuthUrl`. When the `authMethod``AuthMethod` is `GET`, query params are added to the URL, whereas when `authMethod``AuthMethod` is `POST`, the params are sent as URL encoded form data. Useful when an application require these to be added to validate the request or implement the response. | `Hash`Associative Array`Param[]``Dictionary``NSArray``[NSURLQueryItem]/Array``Map``Object``Object` | +| tokenDetailsTokenDetailstoken_details:token_details | An authenticated [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) object (most commonly obtained from an Ably Token Request response). This option is mostly useful for testing: since tokens are short-lived, in production you almost always want to use an authentication method that allows the client library to renew the token automatically when the previous one expires, such as `authUrl``AuthUrl``:auth_url``auth_url` or `authCallback``AuthCallback``auth_callback``:auth_callback`. Use this option if you wish to use Token authentication. Read more about [Token authentication](/docs/auth/token) | `TokenDetails` | +| keyKey:keykey | Optionally the [API key](/docs/auth#api-keys) to use can be specified as a full key string; if not, the API key passed into [`ClientOptions`](#client-options) when instancing the Realtime or REST library is used | `String` | +| queryTimeQueryTime:query_timequery_time | If true, the library will query the Ably servers for the current time when [issuing TokenRequests](/docs/auth/token) instead of relying on a locally-available time of day. Knowing the time accurately is needed to create valid signed Ably [TokenRequests](/docs/auth/token), so this option is useful for library instances on auth servers where for some reason the server clock cannot be kept synchronized through normal means, such as an [NTP daemon](https://en.wikipedia.org/wiki/Ntpd). The server is queried for the current time once per client library instance (which stores the offset from the local clock), so if using this option you should avoid instancing a new version of the library for each request. The default is false. | `Boolean` | +| tokenToken:tokentoken | An authenticated token. This can either be a [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) object, a [`TokenRequest`](/docs/api/realtime-sdk/types#token-request) object, or token string (obtained from the `token``Token` property of a [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) component of an Ably TokenRequest response, or a [JSON Web Token](https://tools.ietf.org/html/rfc7519) satisfying [the Ably requirements for JWTs](/docs/auth/token/jwt)). This option is mostly useful for testing: since tokens are short-lived, in production you almost always want to use an authentication method that allows the client library to renew the token automatically when the previous one expires, such as `authUrl``AuthUrl``:auth_url``auth_url` or `authCallback``AuthCallback``auth_callback``:auth_callback`. Read more about [Token authentication](/docs/auth/token) | `String`, `TokenDetails` or `TokenRequest` | + +### ClientOptions ObjectARTClientOptionsClientOptions HashClientOptions Arrayio.ably.types.ClientOptionsIO.Ably.ClientOptions - -### ClientOptions ObjectARTClientOptionsClientOptions HashClientOptions Arrayio.ably.types.ClientOptionsIO.Ably.ClientOptions - - - -`ClientOptions` is a plain JavaScript object and is used in the `Ably.Rest` constructor's `options` argument. The following attributes can be defined on the object: - - `ClientOptions` is a Hash object and is used in the `Ably::Rest` constructor's `options` argument. The following key symbol values can be added to the Hash: @@ -1843,37 +1519,8 @@ A `TokenRevocationFailureResult` contains information about the result of an uns -#### PropertiesMembersAttributesKeywords arguments - - - -| Parameter | Description | Type | -|-----------|-------------|------| -| key | The full key string, as obtained from the [application dashboard](https://ably.com/dashboard). Use this option if you wish to use Basic authentication, or wish to be able to issue Ably Tokens without needing to defer to a separate entity to sign Ably TokenRequests. Read more about [Basic authentication](/docs/auth/basic) | `String` | -| token | An authenticated token. This can either be a [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) object, a [`TokenRequest`](/docs/api/realtime-sdk/types#token-request) object, or token string (obtained from the `token` property of a [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) component of an Ably TokenRequest response, or a [JSON Web Token](https://tools.ietf.org/html/rfc7519) satisfying [the Ably requirements for JWTs](/docs/auth/token/jwt)). This option is mostly useful for testing: since tokens are short-lived, in production you almost always want to use an authentication method that allows the client library to renew the token automatically when the previous one expires, such as `authUrl` or `authCallback`. Read more about [Token authentication](/docs/auth/token) | `String`, `TokenDetails` or `TokenRequest` | -| authCallback | A functionfunction with the form `function(tokenParams, callback(err, tokenOrTokenRequest))` which is called when a new token is required. The role of the callback is to obtain a fresh token, one of: an Ably Token string (in plain text format); a signed [`TokenRequest`](/docs/api/realtime-sdk/types#token-request); a [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) (in JSON format); an [Ably JWT](/docs/api/realtime-sdk/authentication#ably-jwt). See [our authentication documentation](/docs/auth) for details of the Ably TokenRequest format and associated API calls. | `Callable` | -| authUrl | A URL that the library may use to obtain a fresh token, one of: an Ably Token string (in plain text format); a signed [`TokenRequest`](/docs/api/realtime-sdk/types#token-request); a [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) (in JSON format); an [Ably JWT](/docs/api/realtime-sdk/authentication#ably-jwt). For example, this can be used by a client to obtain signed Ably TokenRequests from an application server. | `String` | -| authMethod | The HTTP verb to use for the request, either `GET` or `POST`. The default is `GET`. | `String` | -| authHeaders | A set of key value pair headers to be added to any request made to the `authUrl`. Useful when an application requires these to be added to validate the request or implement the response. If the `authHeaders` object contains an `authorization` key, then `withCredentials` will be set on the xhr request. | `Object` | -| authParams | A set of key value pair params to be added to any request made to the `authUrl`. When the `authMethod` is `GET`, query params are added to the URL, whereas when `authMethod` is `POST`, the params are sent as URL encoded form data. Useful when an application require these to be added to validate the request or implement the response. | `Object` | -| tokenDetails | An authenticated [`TokenDetails`](/docs/api/realtime-sdk/types#token-details) object (most commonly obtained from an Ably Token Request response). This option is mostly useful for testing: since tokens are short-lived, in production you almost always want to use an authentication method that allows the client library to renew the token automatically when the previous one expires, such as `authUrl` or `authCallback`. Use this option if you wish to use Token authentication. Read more about [Token authentication](/docs/auth/token) | `TokenDetails` | -| tls | A boolean value, indicating whether or not a TLS ("SSL") secure connection should be used. An insecure connection cannot be used with Basic authentication as it would lead to a possible compromise of the private API key while in transit. [Find out more about TLS](https://faqs.ably.com/are-messages-sent-to-and-received-from-ably-securely-using-tls). The default is true. | `Boolean` | -| clientId | A client ID, used for identifying this client when publishing messages or for presence purposes. The `clientId` can be any non-empty string. This option is primarily intended to be used in situations where the library is instantiated with a key; note that a `clientId` may also be implicit in a token used to instantiate the library; an error will be raised if a `clientId` specified here conflicts with the `clientId` implicit in the token. [Find out more about client identities](/docs/auth/identified-clients) | `String` | -| useTokenAuth | When true, forces [Token authentication](/docs/auth/token) to be used by the library. Please note that if a `clientId` is not specified in the [`ClientOptions`](/docs/api/realtime-sdk/types#client-options) or [`TokenParams`](/docs/api/realtime-sdk/types#token-params), then the Ably Token issued will be [anonymous](https://faqs.ably.com/authenticated-and-identified-clients). The default is false. | `Boolean` | -| endpoint | Enables [enterprise customers](https://ably.com/pricing) to use their own custom endpoints, which support dedicated, isolated clusters and regional message routing and storage constraints. See our [platform customization guide](/docs/platform/account/enterprise-customization) for more details. The default is null. | `String` | -| environment | Deprecated, use `endpoint`. Enables [enterprise customers](https://ably.com/pricing) to use their own custom environments, which support dedicated, isolated clusters and regional message routing and storage constraints. See our [platform customization guide](/docs/platform/account/enterprise-customization) for more details. The default is null. | `String` | -| idempotentRestPublishing | When true, enables idempotent publishing by assigning a unique message ID client-side, allowing the Ably servers to discard automatic publish retries following a failure such as a network fault. Enabled by default in all current Ably SDKs. The default is true. | `Boolean` | -| fallbackHosts | An array of fallback hosts to be used in the case of an error necessitating the use of an alternative host. When a custom environment is specified, the [fallback host functionality](https://faqs.ably.com/routing-around-network-and-dns-issues) is disabled. If your customer success manager has provided you with a set of custom fallback hosts, please specify them here. The default is `[a.ably-realtime.com, b.ably-realtime.com, c.ably-realtime.com, d.ably-realtime.com, e.ably-realtime.com]`. | `String []` | -| transportParams | Optional. Can be used to pass in arbitrary connection parameters, such as [`heartbeatInterval`](/docs/connect#heartbeats) and [`remainPresentFor`](/docs/presence-occupancy/presence#unstable-connections) | `Object` | -| logLevel | A number controlling the verbosity of the log output of the library. Valid values are: 0 (no logs), 1 (errors only), 2 (errors plus connection and channel state changes), 3 (high-level debug output), and 4 (full debug output). | `Integer` | -| logHandler | A function to handle each line of the library's log output. If `logHandler` is not specified, `console.log` is used. | `Callable` | -| transports | An optional array of transports to use, in descending order of preference. In the browser environment the available transports are: `web_socket`, `xhr_polling`.The transports available in the Node.js client library are: `web_socket`, `xhr_polling`, `comet`. | `String []` | -| useBinaryProtocol | If set to true, will enable the binary protocol (MessagePack) if it is supported. It's disabled by default on browsers for performance considerations (browsers are optimized for decoding JSON). The default is false.If set to false, will forcibly disable the binary protocol (MessagePack). The binary protocol is used by default unless it is not supported. The default is true. Find out more about the [benefits of binary encoding](https://faqs.ably.com/do-you-binary-encode-your-messages-for-greater-efficiency) | `Boolean` | -| queryTime | If true, the library will query the Ably servers for the current time when [issuing TokenRequests](/docs/auth/token) instead of relying on a locally-available time of day. Knowing the time accurately is needed to create valid signed Ably [TokenRequests](/docs/api/rest-sdk/authentication#token-request), so this option is useful for library instances on auth servers where for some reason the server clock cannot be kept synchronized through normal means, such as an [NTP daemon](https://en.wikipedia.org/wiki/Ntpd). The server is queried for the current time once per client library instance (which stores the offset from the local clock), so if using this option you should avoid instancing a new version of the library for each request. The default is false. | `Boolean` | -| defaultTokenParams | When a [TokenParams](/docs/api/rest-sdk/types#token-params) object is provided, it will override the client library defaults when issuing new [Ably Tokens](/docs/api/realtime-sdk/authentication#token-details) or [Ably TokenRequests](/docs/api/rest-sdk/authentication#token-request) | [`TokenParams`](/docs/api/rest-sdk/types#token-params) | - +#### PropertiesMembersAttributesKeywords arguments - | Parameter | Description | Type | @@ -2088,16 +1735,10 @@ A `TokenRevocationFailureResult` contains information about the result of an uns +### ClientOptions ObjectARTChannelOptionsChannelOptions HashChannelOptions Arrayio.ably.lib.types.ChannelOptionsIO.Ably.ChannelOptions -### ClientOptions ObjectARTChannelOptionsChannelOptions HashChannelOptions Arrayio.ably.lib.types.ChannelOptionsIO.Ably.ChannelOptions - -Channel options are used for setting [channel parameters](/docs/channels/options) and [configuring encryption](/docs/channels/options/encryption). +Channel options are used for setting [channel parameters](/docs/channels/options) and [configuring encryption](/docs/channels/options/encryption). - - -`ChannelOptions`, a plain JavaScript object, may optionally be specified when instancing a [`Channel`](/docs/channels), and this may be used to specify channel-specific options. The following attributes can be defined on the object: - - `ChannelOptions`, a Hash object, may optionally be specified when instancing a [`Channel`](/docs/channels), and this may be used to specify channel-specific options. The following key symbol values can be added to the Hash: @@ -2119,7 +1760,7 @@ Channel options are used for -#### PropertiesMembersAttributes +#### PropertiesMembersAttributes @@ -2128,12 +1769,12 @@ Channel options are used for :cipherCipherParams | Requests encryption for this channel when not null, and specifies encryption-related parameters (such as algorithm, chaining mode, key length and key). See [an example](/docs/channels/options/encryption) | [`CipherParams`](/docs/api/realtime-sdk/encryption#cipher-params) or an options hash containing at a minimum a `key`[`CipherParams`](/docs/api/realtime-sdk/encryption#cipher-params) | - + | Parameter | Description | Type | |-----------|-------------|------| -| paramsParams | Optional [parameters](/docs/channels/options) which specify behaviour of the channel. | `Map`JSON Object | -| cipherCipherParams | Requests encryption for this channel when not null, and specifies encryption-related parameters (such as algorithm, chaining mode, key length and key). See [an example](/docs/api/realtime-sdk/encryption#getting-started) | [`CipherParams`](/docs/api/realtime-sdk/encryption#cipher-params) or an options object containing at a minimum a `key`[`CipherParams`](/docs/api/realtime-sdk/encryption#cipher-params) or a `Param[]` list containing at a minimum a `key`[`CipherParams`](/docs/api/realtime-sdk/encryption#cipher-params) or an Associative Array containing at a minimum a `key`[`CipherParams`](/docs/api/realtime-sdk/encryption#cipher-params) | +| paramsParams | Optional [parameters](/docs/channels/options) which specify behaviour of the channel. | `Map`JSON Object | +| cipherCipherParams | Requests encryption for this channel when not null, and specifies encryption-related parameters (such as algorithm, chaining mode, key length and key). See [an example](/docs/api/realtime-sdk/encryption#getting-started) | [`CipherParams`](/docs/api/realtime-sdk/encryption#cipher-params) or a `Param[]` list containing at a minimum a `key`[`CipherParams`](/docs/api/realtime-sdk/encryption#cipher-params) or an Associative Array containing at a minimum a `key`[`CipherParams`](/docs/api/realtime-sdk/encryption#cipher-params) | @@ -2158,40 +1799,40 @@ On success, the method returns a complete `ChannelOptions` object. Failure will -### CipherParamsARTCipherParamsCipherParams HashCipherParams Arrayio.ably.lib.util.Crypto.CipherParamsIO.Ably.CipherParams +### CipherParamsARTCipherParamsCipherParams HashCipherParams Arrayio.ably.lib.util.Crypto.CipherParamsIO.Ably.CipherParams A `CipherParams` contains configuration options for a channel cipher, including algorithm, mode, key length and key. Ably client libraries currently support AES with CBC, PKCS#7 with a default key length of 256 bits. All implementations also support AES128. -Individual client libraries may support either instancing a `CipherParams` directly, using [`Crypto.getDefaultParams()`](/docs/api/realtime-sdk/encryption#get-default-params)[`Crypto.GetDefaultParams()`](/docs/api/realtime-sdk/encryption#get-default-params)[`Crypto.get_default_params()`](/docs/api/realtime-sdk/encryption#get-default-params), or generating one automatically when initializing a channel, as in [this example](/docs/channels/options/encryption). +Individual client libraries may support either instancing a `CipherParams` directly, using [`Crypto.getDefaultParams()`](/docs/api/realtime-sdk/encryption#get-default-params)[`Crypto.GetDefaultParams()`](/docs/api/realtime-sdk/encryption#get-default-params)[`Crypto.get_default_params()`](/docs/api/realtime-sdk/encryption#get-default-params), or generating one automatically when initializing a channel, as in [this example](/docs/channels/options/encryption). -#### PropertiesMembersAttributes +#### PropertiesMembersAttributes - + | Parameter | Description | Type | |-----------|-------------|------| -| keyKey:key | A binary (`byte[]``ArrayBuffer` or `Uint8Array``Buffer`byte array`NSData`) or base64-encoded `NS``String` containing the secret key used for encryption and decryption | | -| algorithm:algorithmAlgorithm | The name of the algorithm in the default system provider, or the lower-cased version of it; eg "aes" or "AES". The default is AES. | `String` | -| key_length:key_lengthkeyLengthKeyLength | The key length in bits of the cipher, either 128 or 256. The default is 256. | `Integer` | -| mode:modeMode | The cipher mode. The default is CBC. | `String``CipherMode` | +| keyKey:key | A binary (`byte[]`byte array`NSData`) or base64-encoded `NS``String` containing the secret key used for encryption and decryption | | +| algorithm:algorithmAlgorithm | The name of the algorithm in the default system provider, or the lower-cased version of it; eg "aes" or "AES". The default is AES. | `String` | +| key_length:key_lengthkeyLengthKeyLength | The key length in bits of the cipher, either 128 or 256. The default is 256. | `Integer` | +| mode:modeMode | The cipher mode. The default is CBC. | `String``CipherMode` | | Parameter | Description | Type | |-----------|-------------|------| -| algorithm:algorithmAlgorithm | The name of the algorithm in the default system provider, or the lower-cased version of it; eg "aes" or "AES". The default is AES. | `String` | -| key_length:key_lengthkeyLengthKeyLength | The key length in bits of the cipher, either 128 or 256. The default is 256. | `Integer` | -| mode:modeMode | The cipher mode. The default is CBC. | `String``CipherMode` | +| algorithm:algorithmAlgorithm | The name of the algorithm in the default system provider, or the lower-cased version of it; eg "aes" or "AES". The default is AES. | `String` | +| key_length:key_lengthkeyLengthKeyLength | The key length in bits of the cipher, either 128 or 256. The default is 256. | `Integer` | +| mode:modeMode | The cipher mode. The default is CBC. | `String``CipherMode` | | Parameter | Description | Type | |-----------|-------------|------| -| algorithm:algorithmAlgorithm | The name of the algorithm in the default system provider, or the lower-cased version of it; eg "aes" or "AES". The default is AES. | `String` | -| key_length:key_lengthkeyLengthKeyLength | The key length in bits of the cipher, either 128 or 256. The default is 256. | `Integer` | -| mode:modeMode | The cipher mode. The default is CBC. | `String``CipherMode` | +| algorithm:algorithmAlgorithm | The name of the algorithm in the default system provider, or the lower-cased version of it; eg "aes" or "AES". The default is AES. | `String` | +| key_length:key_lengthkeyLengthKeyLength | The key length in bits of the cipher, either 128 or 256. The default is 256. | `Integer` | +| mode:modeMode | The cipher mode. The default is CBC. | `String``CipherMode` | | keySpec | A `KeySpec` for the cipher key | `SecretKeySpec` | @@ -2215,13 +1856,8 @@ Individual client libraries may support either instancing a `CipherParams` direc -### TokenParams ObjectARTTokenParamsTokenParams HashTokenParams Arrayio.ably.lib.rest.Auth.TokenParamsIO.Ably.TokenParams - - +### TokenParams ObjectARTTokenParamsTokenParams HashTokenParams Arrayio.ably.lib.rest.Auth.TokenParamsIO.Ably.TokenParams -`TokenParams` is a plain JavaScript object and is used in the parameters of [token authentication](/docs/auth/token) requests, corresponding to the desired attributes of the [Ably Token](/docs/api/realtime-sdk/authentication#token-details). The following attributes can be defined on the object: - - `TokenParams` is a Hash object and is used in the parameters of [token authentication](/docs/auth/token) requests, corresponding to the desired attributes of the [Ably Token](/docs/api/realtime-sdk/authentication#token-details). The following key symbol values can be added to the Hash: @@ -2248,38 +1884,13 @@ Individual client libraries may support either instancing a `CipherParams` direc -#### PropertiesMembersAttributes +#### PropertiesMembersAttributes | Parameter | Description | Type | |-----------|-------------|------| -| capabilityCapability:capability | JSON stringified capability of the [Ably Token](/docs/api/realtime-sdk/authentication#token-details). If the [Ably Token](/docs/api/realtime-sdk/authentication#token-details) request is successful, the capability of the returned [Ably Token](/docs/api/realtime-sdk/authentication#token-details) will be the intersection of this capability with the capability of the issuing key. [Find our more about how to use capabilities to manage access privileges for clients](/docs/auth/capabilities). | `String``Capability` | -| clientIdClientIdclient_id:client_id | A client ID, used for identifying this client when publishing messages or for presence purposes. The `clientId``client_id``ClientId` can be any non-empty string. This option is primarily intended to be used in situations where the library is instantiated with a key; note that a `clientId``client_id``ClientId` may also be implicit in a token used to instantiate the library; an error will be raised if a `clientId``client_id``ClientId` specified here conflicts with the `clientId``client_id``ClientId` implicit in the token. [Find out more about client identities](/docs/auth/identified-clients) | `String` | -| nonceNonce:nonce | An optional opaque nonce string of at least 16 characters to ensure uniqueness of this request. Any subsequent request using the same nonce will be rejected. | `String` | -| timestampTimestamp:timestamp | The timestamp (in milliseconds since the epoch)The timestamp of this request. `timestamp`, in conjunction with the `nonce`, is used to prevent requests for [Ably Token](/docs/api/realtime-sdk/authentication#token-details) from being replayed. | `Integer``Long Integer``Time``NSDate``DateTimeOffset``DateTime` | -| ttlTtl:ttl | Requested time to live for the [Ably Token](/docs/api/realtime-sdk/authentication#token-details) being created in millisecondsin secondsas a `NSTimeInterval`as a `TimeSpan`. When omitted, the Ably REST API default of 60 minutes is applied by Ably. The default is 1 hour. | `Integer` (milliseconds)`Integer` (seconds)`NSTimeInterval``Long Integer``TimeSpan` | - - +| capabilityCapability:capability | JSON stringified capability of the [Ably Token](/docs/api/realtime-sdk/authentication#token-details). If the [Ably Token](/docs/api/realtime-sdk/authentication#token-details) request is successful, the capability of the returned [Ably Token](/docs/api/realtime-sdk/authentication#token-details) will be the intersection of this capability with the capability of the issuing key. [Find our more about how to use capabilities to manage access privileges for clients](/docs/auth/capabilities). | `String``Capability` | +| clientIdClientIdclient_id:client_id | A client ID, used for identifying this client when publishing messages or for presence purposes. The `clientId``client_id``ClientId` can be any non-empty string. This option is primarily intended to be used in situations where the library is instantiated with a key; note that a `clientId``client_id``ClientId` may also be implicit in a token used to instantiate the library; an error will be raised if a `clientId``client_id``ClientId` specified here conflicts with the `clientId``client_id``ClientId` implicit in the token. [Find out more about client identities](/docs/auth/identified-clients) | `String` | +| nonceNonce:nonce | An optional opaque nonce string of at least 16 characters to ensure uniqueness of this request. Any subsequent request using the same nonce will be rejected. | `String` | +| timestampTimestamp:timestamp | The timestamp (in milliseconds since the epoch)The timestamp of this request. `timestamp`, in conjunction with the `nonce`, is used to prevent requests for [Ably Token](/docs/api/realtime-sdk/authentication#token-details) from being replayed. | `Integer``Long Integer``Time``NSDate``DateTimeOffset``DateTime` | +| ttlTtl:ttl | Requested time to live for the [Ably Token](/docs/api/realtime-sdk/authentication#token-details) being created in millisecondsin secondsas a `NSTimeInterval`as a `TimeSpan`. When omitted, the Ably REST API default of 60 minutes is applied by Ably. The default is 1 hour. | `Integer` (milliseconds)`Integer` (seconds)`NSTimeInterval``Long Integer``TimeSpan` | -### TokenRevocationTargetSpecifier - -A `TokenRevocationTargetSpecifier` describes which tokens should be affected by a token revocation request. - -#### Properties - -| Parameter | Description | Type | -|-----------|-------------|------| -| type | The type of token revocation target specifier. Valid values include `clientId`, `revocationKey` and `channel` | `String` | -| value | The value of the token revocation target specifier | `String` | - -### TokenRevocationOptions - -A `TokenRevocationOptions` describes the additional options accepted by revoke tokens request. - -#### Properties - -| Parameter | Description | Type | -|-----------|-------------|------| -| issuedBefore | An optional Unix timestamp in milliseconds where only tokens issued before this time are revoked. The default is the current time. Requests with an `issuedBefore` in the future, or more than an hour in the past, will be rejected | `Number` | -| allowReauthMargin | If true, permits a token renewal cycle to take place without needing established connections to be dropped, by postponing enforcement to 30 seconds in the future, and sending any existing connections a hint to obtain (and upgrade the connection to use) a new token. The default is `false`, meaning that the effect is near-immediate. | `Boolean` | - - From 07cce8f996ba17afd215f1b4b559534ec9f23a5e Mon Sep 17 00:00:00 2001 From: Mark Hulbert <39801222+m-hulbert@users.noreply.github.com> Date: Mon, 27 Jul 2026 17:29:02 +0100 Subject: [PATCH 7/7] Fix dead anchors in links to the new JavaScript API reference Co-Authored-By: Claude Fable 5 --- .../docs/ai-transport/api/react/core/use-ably-messages.mdx | 2 +- src/pages/docs/api/rest-api.mdx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/src/pages/docs/ai-transport/api/react/core/use-ably-messages.mdx b/src/pages/docs/ai-transport/api/react/core/use-ably-messages.mdx index b757a587f3..f382c6ad5f 100644 --- a/src/pages/docs/ai-transport/api/react/core/use-ably-messages.mdx +++ b/src/pages/docs/ai-transport/api/react/core/use-ably-messages.mdx @@ -46,7 +46,7 @@ This hook must be used within a [`ClientSessionProvider`](/docs/ai-transport/api The accumulated raw Ably messages in chronological order. Resets to an empty array when the resolved session changes. -Each `InboundMessage` carries the wire fields you would see from `channel.subscribe`: `name`, `data`, `serial`, `clientId`, `extras`, `timestamp`, and so on. The [Ably SDK reference](/docs/pub-sub/api/javascript/realtime/messages#message) documents the full type. +Each `InboundMessage` carries the wire fields you would see from `channel.subscribe`: `name`, `data`, `serial`, `clientId`, `extras`, `timestamp`, and so on. The [Ably SDK reference](/docs/pub-sub/api/javascript/realtime/message) documents the full type. ## Example diff --git a/src/pages/docs/api/rest-api.mdx b/src/pages/docs/api/rest-api.mdx index 265aff801a..19f710444d 100644 --- a/src/pages/docs/api/rest-api.mdx +++ b/src/pages/docs/api/rest-api.mdx @@ -343,7 +343,7 @@ curl https://main.realtime.ably.net/channels/rest-example/messages \ ### Token Authentication -**Token Authentication** uses an Ably-compatible token to authenticate with Ably without sharing a private API key. This can be an [Ably Token](/docs/pub-sub/api/javascript/rest/auth#tokens) obtained via the REST API [`requestToken`](#request-token) endpoint, an [Ably JWT](/docs/auth/token/jwt) signed by your API key, or an [External JWT](https://jwt.io) object [with an embedded Ably-compatible token](/docs/auth/token#embedded). Tokens are authentication credentials that are short-lived, and therefore they may more readily be distributed to clients where there is a risk of compromise. Tokens may also be issued with a particular scope - such as a limited set of [access rights or capabilities](/docs/auth/capabilities) or being limited to use by a specific [`clientId` identity](#identified-clients) - and therefore token-based authentication provides the flexibility to implement access and identity control policies in the application. See the [Token Authentication documentation](/docs/auth/token) for more details. +**Token Authentication** uses an Ably-compatible token to authenticate with Ably without sharing a private API key. This can be an [Ably Token](/docs/auth/token/ably-tokens) obtained via the REST API [`requestToken`](#request-token) endpoint, an [Ably JWT](/docs/auth/token/jwt) signed by your API key, or an [External JWT](https://jwt.io) object [with an embedded Ably-compatible token](/docs/auth/token#embedded). Tokens are authentication credentials that are short-lived, and therefore they may more readily be distributed to clients where there is a risk of compromise. Tokens may also be issued with a particular scope - such as a limited set of [access rights or capabilities](/docs/auth/capabilities) or being limited to use by a specific [`clientId` identity](#identified-clients) - and therefore token-based authentication provides the flexibility to implement access and identity control policies in the application. See the [Token Authentication documentation](/docs/auth/token) for more details. The construction of an Ably [`TokenRequest`](/docs/api/token-request-spec) is described in the [Authentication Ably TokenRequest spec documentation](/docs/api/token-request-spec). The resulting `token response` object contains the token properties as defined in [Ably TokenRequest spec](/docs/api/token-request-spec).