From 1a94aac1df8b40e68037748a17d93657f042c02c Mon Sep 17 00:00:00 2001 From: Mark Hulbert <39801222+m-hulbert@users.noreply.github.com> Date: Fri, 12 Dec 2025 18:08:40 +0100 Subject: [PATCH 1/8] fix: link in platform section was to a redirect --- src/data/nav/platform.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/data/nav/platform.ts b/src/data/nav/platform.ts index 020bb3ed24..be00228b01 100644 --- a/src/data/nav/platform.ts +++ b/src/data/nav/platform.ts @@ -238,7 +238,7 @@ export default { pages: [ { name: 'Overview', - link: '/docs/account', + link: '/docs/platform/account', index: true, }, { From f65132edf75ffa62f69345eb2badd0c41139f95d Mon Sep 17 00:00:00 2001 From: Mark Hulbert <39801222+m-hulbert@users.noreply.github.com> Date: Fri, 12 Dec 2025 18:09:57 +0100 Subject: [PATCH 2/8] Add intro property text to all platform pages using 1st sentence --- src/pages/docs/platform/account/2fa.mdx | 3 +-- src/pages/docs/platform/account/app/api.mdx | 5 +++-- src/pages/docs/platform/account/app/console.mdx | 7 ++++--- src/pages/docs/platform/account/app/index.mdx | 5 +++-- src/pages/docs/platform/account/app/notifications.mdx | 7 +++---- src/pages/docs/platform/account/app/queues.mdx | 11 +++++------ src/pages/docs/platform/account/app/settings.mdx | 3 +-- src/pages/docs/platform/account/app/stats.mdx | 5 ++--- src/pages/docs/platform/account/control-api.mdx | 5 +++-- .../platform/account/enterprise-customization.mdx | 3 ++- src/pages/docs/platform/account/index.mdx | 3 +-- src/pages/docs/platform/account/organizations.mdx | 3 ++- src/pages/docs/platform/account/sso.mdx | 3 +-- src/pages/docs/platform/account/users.mdx | 3 +-- .../platform/architecture/connection-recovery.mdx | 3 +-- src/pages/docs/platform/architecture/edge-network.mdx | 3 +-- .../docs/platform/architecture/fault-tolerance.mdx | 3 +-- src/pages/docs/platform/architecture/idempotency.mdx | 3 +-- src/pages/docs/platform/architecture/index.mdx | 5 +---- .../architecture/infrastructure-operations.mdx | 3 +-- src/pages/docs/platform/architecture/latency.mdx | 5 +---- .../docs/platform/architecture/message-ordering.mdx | 3 +-- src/pages/docs/platform/architecture/performance.mdx | 3 +-- .../platform/architecture/platform-scalability.mdx | 3 +-- src/pages/docs/platform/deprecate/index.mdx | 3 ++- src/pages/docs/platform/deprecate/protocol-v1.mdx | 3 +-- src/pages/docs/platform/deprecate/tls-v1-1.mdx | 3 +-- src/pages/docs/platform/errors/codes.mdx | 7 +------ src/pages/docs/platform/errors/index.mdx | 3 +-- src/pages/docs/platform/index.mdx | 3 +-- .../platform/integrations/inbound/kafka-connector.mdx | 5 +++-- .../docs/platform/integrations/inbound/webhooks.mdx | 3 +-- src/pages/docs/platform/integrations/index.mdx | 3 +-- src/pages/docs/platform/integrations/queues.mdx | 3 ++- .../docs/platform/integrations/skip-integrations.mdx | 3 ++- .../docs/platform/integrations/streaming/amqp.mdx | 3 +-- .../docs/platform/integrations/streaming/datadog.mdx | 5 ++--- .../docs/platform/integrations/streaming/index.mdx | 3 +-- .../docs/platform/integrations/streaming/kafka.mdx | 10 ++++------ .../docs/platform/integrations/streaming/kinesis.mdx | 3 +-- .../docs/platform/integrations/streaming/pulsar.mdx | 5 ++--- .../docs/platform/integrations/streaming/sqs.mdx | 3 +-- .../docs/platform/integrations/webhooks/azure.mdx | 3 +-- .../platform/integrations/webhooks/cloudflare.mdx | 3 +-- .../platform/integrations/webhooks/gcp-function.mdx | 3 +-- .../docs/platform/integrations/webhooks/generic.mdx | 4 ++-- .../docs/platform/integrations/webhooks/ifttt.mdx | 3 +-- .../docs/platform/integrations/webhooks/index.mdx | 3 +-- .../docs/platform/integrations/webhooks/lambda.mdx | 3 +-- .../docs/platform/integrations/webhooks/zapier.mdx | 3 +-- src/pages/docs/platform/pricing/billing.mdx | 3 +-- src/pages/docs/platform/pricing/enterprise.mdx | 3 +-- src/pages/docs/platform/pricing/faqs.mdx | 3 +-- src/pages/docs/platform/pricing/free.mdx | 3 +-- src/pages/docs/platform/pricing/index.mdx | 8 +++----- src/pages/docs/platform/pricing/limits.mdx | 3 +-- src/pages/docs/platform/pricing/pro.mdx | 3 +-- src/pages/docs/platform/pricing/standard.mdx | 3 +-- 58 files changed, 89 insertions(+), 136 deletions(-) diff --git a/src/pages/docs/platform/account/2fa.mdx b/src/pages/docs/platform/account/2fa.mdx index 57ee9560f6..24bbc30d91 100644 --- a/src/pages/docs/platform/account/2fa.mdx +++ b/src/pages/docs/platform/account/2fa.mdx @@ -1,13 +1,12 @@ --- title: Two-factor authentication (2FA) +intro: "Two-factor authentication (2FA) is an authentication process requiring users to utilize two different forms of verification. 2FA for your Ably account requires your password and a security token sent to your mobile phone." meta_description: "Enable two-factor authentication for your Ably account." meta_keywords: "2FA, two-factor, authentication, MFA" redirect_from: - /docs/account/2fa --- -Two-factor authentication (2FA) is an authentication process requiring users to utilize two different forms of verification. 2FA for your Ably account requires your password and a security token sent to your mobile phone. - ## Enable 2FA To enable 2FA for your own user login: diff --git a/src/pages/docs/platform/account/app/api.mdx b/src/pages/docs/platform/account/app/api.mdx index 2421063578..1915f16add 100644 --- a/src/pages/docs/platform/account/app/api.mdx +++ b/src/pages/docs/platform/account/app/api.mdx @@ -1,12 +1,13 @@ --- title: API keys -meta_description: “Manage Ably API keys by creating, updating, setting restrictions, and exploring integration options.” +intro: "The API keys tab lists all API keys associated with your account." +meta_description: "Manage Ably API keys by creating, updating, setting restrictions, and exploring integration options." meta_keywords: "API keys, Ably, create key, update key, key restrictions, integration, webhooks, authentication" redirect_from: - /docs/account/app/api --- -The API keys tab lists all API keys associated with your account and provides information on each key's capabilities and restrictions. You can [create a new API key](#create) and manage an existing one. +View the information on each key's capabilities and restrictions, create new keys, and manage existing ones. -LiveObjects enables you to store shared data as "objects" on a channel, allowing your application data to be synchronized across multiple users and devices in realtime. This document explains the key concepts you need to know when working with objects. - ## Object Types LiveObjects provides specialized object types to model your application state. These object types are designed to be conflict-free and eventually consistent, meaning that all operations on them are commutative and converge to the same state across all clients. diff --git a/src/pages/docs/liveobjects/concepts/operations.mdx b/src/pages/docs/liveobjects/concepts/operations.mdx index c3961c2de8..112add01a1 100644 --- a/src/pages/docs/liveobjects/concepts/operations.mdx +++ b/src/pages/docs/liveobjects/concepts/operations.mdx @@ -1,5 +1,6 @@ --- title: Operations +intro: "LiveObjects operations define how object data is updated and synchronized across multiple clients." meta_description: "Learn how objects are updated by operations in Ably LiveObjects." --- @@ -9,14 +10,10 @@ LiveObjects is currently Experimental. Its features are still in development and **Building with LiveObjects?** Help shape its future by [sharing your use case](https://44qpp.share.hsforms.com/2fZobHQA1ToyRfB9xqZYQmQ). -LiveObjects operations define how object data is updated and synchronized across multiple clients. +## Operation Types When you create or update an object, the change is expressed as an _operation_ that is sent as an [object message](/docs/metadata-stats/stats#messages) on the channel. The operation is then applied to the object instance on all clients that are subscribed to the channel. -This document explains the key concepts you need to know when working with operations. - -## Operation Types - Each object type supports specific operations that modify the object's data. ### LiveMap Operations diff --git a/src/pages/docs/liveobjects/concepts/synchronization.mdx b/src/pages/docs/liveobjects/concepts/synchronization.mdx index ffe50ba02e..cf10f89762 100644 --- a/src/pages/docs/liveobjects/concepts/synchronization.mdx +++ b/src/pages/docs/liveobjects/concepts/synchronization.mdx @@ -1,5 +1,6 @@ --- title: Synchronization +intro: "LiveObjects provides a powerful synchronization mechanism to ensure that all clients see the same data." meta_description: "Learn how data is synchronized between clients." --- @@ -9,8 +10,6 @@ LiveObjects is currently Experimental. Its features are still in development and **Building with LiveObjects?** Help shape its future by [sharing your use case](https://44qpp.share.hsforms.com/2fZobHQA1ToyRfB9xqZYQmQ). -LiveObjects provides a powerful synchronization mechanism to ensure that all clients see the same data. This document explains how synchronization works in LiveObjects. - ## Channel Objects Ably maintains the authoritative state of all objects on each channel across its distributed infrastructure. diff --git a/src/pages/docs/liveobjects/counter.mdx b/src/pages/docs/liveobjects/counter.mdx index 18596161db..6abda5a350 100644 --- a/src/pages/docs/liveobjects/counter.mdx +++ b/src/pages/docs/liveobjects/counter.mdx @@ -1,5 +1,6 @@ --- title: LiveCounter +intro: "LiveCounter is a synchronized numerical counter that supports increment and decrement operations. It ensures that all updates are correctly applied and synchronized across users in realtime, preventing inconsistencies when multiple users modify the counter value simultaneously." meta_description: "Create, update and receive updates for a numerical counter that synchronizes state across clients in realtime." --- @@ -9,8 +10,6 @@ LiveObjects is currently Experimental. Its features are still in development and **Building with LiveObjects?** Help shape its future by [sharing your use case](https://44qpp.share.hsforms.com/2fZobHQA1ToyRfB9xqZYQmQ). -LiveCounter is a synchronized numerical counter that supports increment and decrement operations. It ensures that all updates are correctly applied and synchronized across users in realtime, preventing inconsistencies when multiple users modify the counter value simultaneously. - ## Create LiveCounter A `LiveCounter` instance can be created using the `channel.objects.createCounter()` method. It must be stored inside a `LiveMap` object that is reachable from the [root object](/docs/liveobjects/concepts/objects#root-object). diff --git a/src/pages/docs/liveobjects/inband-objects.mdx b/src/pages/docs/liveobjects/inband-objects.mdx index 586586fac1..1d79e30606 100644 --- a/src/pages/docs/liveobjects/inband-objects.mdx +++ b/src/pages/docs/liveobjects/inband-objects.mdx @@ -1,5 +1,6 @@ --- title: Inband Objects +intro: "Inband objects enables clients to subscribe to LiveObjects updates in realtime, even on platforms that don't yet have a native LiveObjects Realtime client implementation." meta_description: "Subscribe to LiveObjects updates from Pub/Sub SDKs." --- @@ -9,16 +10,6 @@ LiveObjects is currently Experimental. Its features are still in development and **Building with LiveObjects?** Help shape its future by [sharing your use case](https://44qpp.share.hsforms.com/2fZobHQA1ToyRfB9xqZYQmQ). -Inband objects enables clients to subscribe to LiveObjects updates in realtime, even on platforms that don't yet have a native LiveObjects Realtime client implementation. - - - Inband objects works by delivering changes to channel objects as regular channel messages, similar to [inband occupancy](/docs/channels/options#occupancy). ## Enable Inband Objects diff --git a/src/pages/docs/liveobjects/index.mdx b/src/pages/docs/liveobjects/index.mdx index 370460fc96..7ae81386b9 100644 --- a/src/pages/docs/liveobjects/index.mdx +++ b/src/pages/docs/liveobjects/index.mdx @@ -1,5 +1,6 @@ --- title: About LiveObjects +intro: "Ably LiveObjects provides a serverless, durable, and scalable way to create, update, and synchronize shared state across large numbers of connected clients at any scale." meta_description: "Learn about Ably LiveObjects, its features, use cases, and how it simplifies realtime state synchronization." --- @@ -9,18 +10,16 @@ LiveObjects is currently Experimental. Its features are still in development and **Building with LiveObjects?** Help shape its future by [sharing your use case](https://44qpp.share.hsforms.com/2fZobHQA1ToyRfB9xqZYQmQ). -Ably LiveObjects provides a serverless, durable, and scalable way to create, update, and synchronize shared state across large numbers of connected clients at any scale. - LiveObjects provides a global, durable, and conflict-free shared data layer built on Ably's [global platform](/docs/platform/architecture), so your application state stays perfectly synchronized in realtime without the need to build or manage complex infrastructure yourself. - - LiveObjects enables you to store shared data as "objects" on a [channel](/docs/channels). When an object is updated, changes are automatically propagated to all subscribed clients in realtime, ensuring everyone always sees the latest state. LiveObjects provides a simple, purpose-built API that handles realtime synchronization, persistence, and convergence behind the scenes. The result is a single logical view of your data - distributed to the edge, updated in real time, and always in sync - no matter how many users are connected or where they are in the world. + + ## Use cases You can use LiveObjects to build all sorts of powerful functionality in your applications that require realtime updates to shared data. It is useful when your application has data that: diff --git a/src/pages/docs/liveobjects/lifecycle.mdx b/src/pages/docs/liveobjects/lifecycle.mdx index aa635a6374..cac07828d9 100644 --- a/src/pages/docs/liveobjects/lifecycle.mdx +++ b/src/pages/docs/liveobjects/lifecycle.mdx @@ -1,5 +1,6 @@ --- title: Lifecycle events +intro: "Lifecycle events enable you to track synchronization events and object deletions for Objects, LiveMap and LiveCounter." meta_description: "Understand lifecycle events for Objects, LiveMap and LiveCounter to track synchronization events and object deletions." --- diff --git a/src/pages/docs/liveobjects/map.mdx b/src/pages/docs/liveobjects/map.mdx index f05171281f..ebe2613eea 100644 --- a/src/pages/docs/liveobjects/map.mdx +++ b/src/pages/docs/liveobjects/map.mdx @@ -1,5 +1,6 @@ --- title: LiveMap +intro: "LiveMap is a key/value data structure that synchronizes its state across users in realtime." meta_description: "Create, update and receive updates for a key/value data structure that synchronizes state across clients in realtime." --- @@ -9,7 +10,7 @@ LiveObjects is currently Experimental. Its features are still in development and **Building with LiveObjects?** Help shape its future by [sharing your use case](https://44qpp.share.hsforms.com/2fZobHQA1ToyRfB9xqZYQmQ). -LiveMap is a key/value data structure that synchronizes its state across users in realtime. It enables you to store primitive values, such as numbers, strings, booleans, buffers, JSON-serializable objects or arrays and other LiveObjects types, [enabling you to build complex, hierarchical object structure](#composability). +LiveMap enables you to store primitive values, such as numbers, strings, booleans, buffers, JSON-serializable objects or arrays and other LiveObjects types, [enabling you to build complex, hierarchical object structure](#composability). Conflicts in a LiveMap are automatically resolved with last-write-wins (LWW) semantics. The latest received operation on a key will be applied to the LiveMap and broadcast to all clients. diff --git a/src/pages/docs/liveobjects/quickstart/java.mdx b/src/pages/docs/liveobjects/quickstart/java.mdx index 5a3a281de3..e8fa78f17e 100644 --- a/src/pages/docs/liveobjects/quickstart/java.mdx +++ b/src/pages/docs/liveobjects/quickstart/java.mdx @@ -1,16 +1,9 @@ --- title: "Getting started: LiveObjects in Java" +intro: "This guide shows how to integrate Ably LiveObjects into your Java application." meta_description: "A quickstart guide to learn the basics of integrating the Ably LiveObjects product into your Java application." --- - - -This guide shows how to integrate Ably LiveObjects into your Java application. - You will learn how to: * Create an Ably account and get an API key for authentication. diff --git a/src/pages/docs/liveobjects/quickstart/javascript.mdx b/src/pages/docs/liveobjects/quickstart/javascript.mdx index 8136d1c8d8..bd2bc0b606 100644 --- a/src/pages/docs/liveobjects/quickstart/javascript.mdx +++ b/src/pages/docs/liveobjects/quickstart/javascript.mdx @@ -1,18 +1,11 @@ --- title: "Getting started: LiveObjects in JavaScript" +intro: "This guide shows how to integrate Ably LiveObjects into your JavaScript / TypeScript application." meta_description: "A getting started guide to learn the basics of integrating the Ably LiveObjects product into your JavaScript application." redirect_from: - /docs/liveobjects/quickstart --- - - -This guide shows how to integrate Ably LiveObjects into your JavaScript / TypeScript application. - You will learn how to: * Create an Ably account and get an API key for authentication. diff --git a/src/pages/docs/liveobjects/quickstart/swift.mdx b/src/pages/docs/liveobjects/quickstart/swift.mdx index 1c806ea1d8..cbea670997 100644 --- a/src/pages/docs/liveobjects/quickstart/swift.mdx +++ b/src/pages/docs/liveobjects/quickstart/swift.mdx @@ -1,16 +1,9 @@ --- title: "Getting started: LiveObjects in Swift" +intro: "This guide shows how to integrate Ably LiveObjects into your Swift application." meta_description: "A quickstart guide to learn the basics of integrating the Ably LiveObjects product into your Swift application." --- - - -This guide shows how to integrate Ably LiveObjects into your Swift application. - You will learn how to: * Create an Ably account and get an API key for authentication. diff --git a/src/pages/docs/liveobjects/rest-api-usage.mdx b/src/pages/docs/liveobjects/rest-api-usage.mdx index f7d97a78be..8b0684d6e1 100644 --- a/src/pages/docs/liveobjects/rest-api-usage.mdx +++ b/src/pages/docs/liveobjects/rest-api-usage.mdx @@ -1,5 +1,6 @@ --- title: Using the REST API +intro: "LiveObjects provides a comprehensive REST API that enables you to directly work with objects without using a client SDK." meta_description: "Learn how to work with Ably LiveObjects using the REST API" --- @@ -9,8 +10,6 @@ LiveObjects is currently Experimental. Its features are still in development and **Building with LiveObjects?** Help shape its future by [sharing your use case](https://44qpp.share.hsforms.com/2fZobHQA1ToyRfB9xqZYQmQ). -LiveObjects provides a comprehensive REST API that enables you to directly work with objects without using a client SDK. - ## Authentication View the REST API [authentication](/docs/api/rest-api#authentication) documentation for details on how to authenticate your requests. diff --git a/src/pages/docs/liveobjects/storage.mdx b/src/pages/docs/liveobjects/storage.mdx index f45b8097f0..0ecd737492 100644 --- a/src/pages/docs/liveobjects/storage.mdx +++ b/src/pages/docs/liveobjects/storage.mdx @@ -1,5 +1,6 @@ --- title: Object storage +intro: "Ably durably stores all objects on a channel for a retention period that is configured to 90 days by default." meta_description: "Learn about LiveObjects object storage." --- diff --git a/src/pages/docs/liveobjects/typing.mdx b/src/pages/docs/liveobjects/typing.mdx index dbd8716368..6be0c527eb 100644 --- a/src/pages/docs/liveobjects/typing.mdx +++ b/src/pages/docs/liveobjects/typing.mdx @@ -1,5 +1,6 @@ --- title: Typing +intro: "If you are using TypeScript in your project, you can leverage LiveObjects' built-in TypeScript support to ensure type safety and enable autocompletion when working with objects on a channel." meta_description: "Type objects on a channel for type safety and code autocompletion." --- @@ -9,8 +10,6 @@ LiveObjects is currently Experimental. Its features are still in development and **Building with LiveObjects?** Help shape its future by [sharing your use case](https://44qpp.share.hsforms.com/2fZobHQA1ToyRfB9xqZYQmQ). -If you are using TypeScript in your project, you can leverage LiveObjects' built-in TypeScript support to ensure type safety and enable autocompletion when working with objects on a channel. - ## Global AblyObjectsTypes interface You can type objects on all your channels by defining a global `AblyObjectsTypes` interface. If you only want to type the root object for a specific channel, see the [Typing `channel.objects.getRoot()`](#getroot) section below. From 31232ebcf2272626c35d9dcabe28bc7b32329e4b Mon Sep 17 00:00:00 2001 From: Mark Hulbert <39801222+m-hulbert@users.noreply.github.com> Date: Fri, 12 Dec 2025 18:10:59 +0100 Subject: [PATCH 5/8] Add intro text to livesync docs using 1st sentence --- src/pages/docs/livesync/index.mdx | 3 ++- src/pages/docs/livesync/mongodb/index.mdx | 3 ++- src/pages/docs/livesync/postgres/index.mdx | 3 ++- src/pages/docs/livesync/postgres/models.mdx | 3 +-- src/pages/docs/livesync/postgres/quickstart.mdx | 3 +-- 5 files changed, 8 insertions(+), 7 deletions(-) diff --git a/src/pages/docs/livesync/index.mdx b/src/pages/docs/livesync/index.mdx index 8b145df32f..5eeeac461b 100644 --- a/src/pages/docs/livesync/index.mdx +++ b/src/pages/docs/livesync/index.mdx @@ -1,11 +1,12 @@ --- title: About LiveSync +intro: "LiveSync is a powerful realtime data synchronization product designed to facilitate broadcasting realtime updates from backend databases to application clients at scale." meta_description: "LiveSync enables you to synchronize changes in your database to application clients at scale." redirect_from: - /docs/products/livesync --- -LiveSync is a powerful realtime data synchronization product designed to facilitate broadcasting realtime updates from backend databases to application clients at scale. LiveSync ensures that data updates are propagated reliably, and in order, to all connected clients in realtime. +LiveSync ensures that data updates are propagated reliably, and in order, to all connected clients in realtime. LiveSync can be used in applications where your database is the source of truth for the application state, and that state needs to be reflected in realtime to client applications. LiveSync enables this data synchronisation while maintaining data integrity and low latency. diff --git a/src/pages/docs/livesync/mongodb/index.mdx b/src/pages/docs/livesync/mongodb/index.mdx index 2939fb868a..53bc19a092 100644 --- a/src/pages/docs/livesync/mongodb/index.mdx +++ b/src/pages/docs/livesync/mongodb/index.mdx @@ -1,10 +1,11 @@ --- title: MongoDB database connector +intro: "Use the MongoDB database connector to distribute document changes from a MongoDB collection to end users, at scale." meta_description: "The MongoDB database connector connects to your database and publishes document changes in realtime over Ably Pub/Sub channels" meta_keywords: "MongoDB, MongoDB Database Connector, channel" --- -Use the MongoDB database connector to distribute document changes from a MongoDB collection to end users, at scale. It enables you to distribute document state changes to large numbers of subscribing clients, in realtime, as the changes occur. +The MongoDB database connector enables you to distribute document state changes to large numbers of subscribing clients, in realtime, as the changes occur. The MongoDB database connector utilizes the MongoDB [change streams](https://www.mongodb.com/docs/v8.0/changeStreams/) feature to distribute changes from the database to clients over Ably Pub/Sub channels. diff --git a/src/pages/docs/livesync/postgres/index.mdx b/src/pages/docs/livesync/postgres/index.mdx index 5567b410f9..89162295b3 100644 --- a/src/pages/docs/livesync/postgres/index.mdx +++ b/src/pages/docs/livesync/postgres/index.mdx @@ -1,12 +1,13 @@ --- title: Postgres database connector +intro: "Use the Postgres database connector to distribute changes from your Postgres database to end users at scale." meta_description: "The Ably Database Connector connects your database to frontend clients in realtime through Ably channels." redirect_from: - /docs/livesync/connector - /docs/livesync/connector/monitor --- -Use the Postgres database connector to distribute changes from your Postgres database to end users at scale. It enables you to distribute records using the [outbox pattern](https://docs.aws.amazon.com/prescriptive-guidance/latest/cloud-design-patterns/transactional-outbox.html) to large numbers of subscribing clients, in realtime, as the changes occur. +The Postgres database connector enables you to distribute records using the [outbox pattern](https://docs.aws.amazon.com/prescriptive-guidance/latest/cloud-design-patterns/transactional-outbox.html) to large numbers of subscribing clients, in realtime, as the changes occur. ![An image showing how the Database Connector plays in the LiveSync flow](../../../../images/content/diagrams/ably-connector-for-postgres.png) diff --git a/src/pages/docs/livesync/postgres/models.mdx b/src/pages/docs/livesync/postgres/models.mdx index 0801e0391a..e5394dd838 100644 --- a/src/pages/docs/livesync/postgres/models.mdx +++ b/src/pages/docs/livesync/postgres/models.mdx @@ -1,12 +1,11 @@ --- title: Frontend data models +intro: "The Models SDK extends the capability of the LiveSync Postgres database connector with optimistic and confirmed state updates, support for loading the initial model data from the backend, and managing state updates." meta_description: "The frontend data models to keep your frontend applications up to date with your backend database." redirect_from: - /docs/livesync/models/models --- -The Models SDK extends the capability of the LiveSync Postgres database connector with optimistic and confirmed state updates, support for loading the initial model data from the backend, and managing state updates. - ## How it works The Models SDK is a standalone SDK built on [Ably's JavaScript SDK](/docs/getting-started/setup). It sits in your frontend applications and helps manage the state updates based on events streamed by the Postgres database connector via Ably channels. diff --git a/src/pages/docs/livesync/postgres/quickstart.mdx b/src/pages/docs/livesync/postgres/quickstart.mdx index 525dff7fdd..1f3b84eaef 100644 --- a/src/pages/docs/livesync/postgres/quickstart.mdx +++ b/src/pages/docs/livesync/postgres/quickstart.mdx @@ -1,10 +1,9 @@ --- title: Quickstart +intro: "This quickstart will provide you with a set of instructions to get an example running locally on your machine." meta_description: "A quickstart guide to learn the basics of integrating the Ably LiveSync product into your application." --- -This quickstart will provide you with a set of instructions to get an example running locally on your machine. Following this, we'll cover each component of LiveSync found within the code of the example. - ### Clone the repository Clone the [live comments repository](https://github.com/ably-labs/live-comments): From bf964a67dddf501a2dca1cd1baa35063362e9947 Mon Sep 17 00:00:00 2001 From: Mark Hulbert <39801222+m-hulbert@users.noreply.github.com> Date: Fri, 12 Dec 2025 18:11:15 +0100 Subject: [PATCH 6/8] Add intro text to spaces docs using 1st sentence --- src/pages/docs/spaces/avatar.mdx | 3 ++- src/pages/docs/spaces/cursors.mdx | 3 +-- src/pages/docs/spaces/index.mdx | 3 +-- src/pages/docs/spaces/locations.mdx | 3 ++- src/pages/docs/spaces/locking.mdx | 3 ++- src/pages/docs/spaces/react.mdx | 5 ++--- src/pages/docs/spaces/setup.mdx | 3 +-- src/pages/docs/spaces/space.mdx | 3 ++- 8 files changed, 13 insertions(+), 13 deletions(-) diff --git a/src/pages/docs/spaces/avatar.mdx b/src/pages/docs/spaces/avatar.mdx index fd148ec7df..d069870804 100644 --- a/src/pages/docs/spaces/avatar.mdx +++ b/src/pages/docs/spaces/avatar.mdx @@ -1,9 +1,10 @@ --- title: Avatar stack +intro: "Avatar stacks are the most common way of showing the online status of members in an application by displaying an avatar for each member." meta_description: "Avatar stacks display the online status of members in a space." --- -Avatar stacks are the most common way of showing the online status of members in an application by displaying an avatar for each member. Events are emitted whenever a member enters or leaves a space, or updates their profile data. Additional information can also be provided, such as a profile picture and email address. +Avatar stack events are emitted whenever a member enters or leaves a space, or updates their profile data. Additional information can also be provided, such as a profile picture and email address. Subscribe to the `space.members` namespace in order to keep your avatar stack updated in realtime. diff --git a/src/pages/docs/spaces/cursors.mdx b/src/pages/docs/spaces/cursors.mdx index 2b3e30f231..6e33dff7c9 100644 --- a/src/pages/docs/spaces/cursors.mdx +++ b/src/pages/docs/spaces/cursors.mdx @@ -1,10 +1,9 @@ --- title: Live cursors +intro: "The live cursors feature enables you to track the cursors of members within a space in realtime." meta_description: "Track the positions of cursors within a space." --- -The live cursors feature enables you to track the cursors of members within a space in realtime. - Cursor events are emitted whenever a member moves their mouse within a space. In order to optimize the efficiency and frequency of updates, cursor position events are automatically batched. The batching interval may be customized in order to further optimize for increased performance versus the number of events published. Live cursor updates are not available as part of the [space state](/docs/spaces/space#subscribe) and must be subscribed to using [`space.cursors.subscribe()`](#subscribe). diff --git a/src/pages/docs/spaces/index.mdx b/src/pages/docs/spaces/index.mdx index 6c4392dc7d..c4131beb0b 100644 --- a/src/pages/docs/spaces/index.mdx +++ b/src/pages/docs/spaces/index.mdx @@ -1,12 +1,11 @@ --- title: About Spaces +intro: "Spaces enables you to build collaborative environments in your application." meta_description: "Spaces by Ably enables you to build collaborative environments in your application." redirect_from: - /docs/products/spaces --- -Spaces enables you to build collaborative environments in your application. - Building realtime collaborative applications requires managing two different states; participant state and application state. Both states involve different types of data, and that data is handled differently. Participant state is the data related to the members collaborating synchronously in an application, such as their online status, their locations and the positions of their cursors. Application state is the data related to the application itself, such as the data in a cell or field, or the description and status of a task. diff --git a/src/pages/docs/spaces/locations.mdx b/src/pages/docs/spaces/locations.mdx index e55ff8af5a..326ddec724 100644 --- a/src/pages/docs/spaces/locations.mdx +++ b/src/pages/docs/spaces/locations.mdx @@ -1,9 +1,10 @@ --- title: Member location +intro: "The member location feature enables you to track where members are within a space, to see which part of your application they're interacting with." meta_description: "Member location displays where users are within a space." --- -The member location feature enables you to track where members are within a space, to see which part of your application they're interacting with. A location could be the form field they have selected, the cell they're currently editing in a spreadsheet, or the slide they're viewing within a slide deck. Multiple members can be present in the same location. +A location can be the form field a member has selected, the cell they're currently editing in a spreadsheet, or the slide they're viewing within a slide deck. Multiple members can be present in the same location. Member locations are used to visually display which component other members currently have selected, or are currently active on. Events are emitted whenever a member sets their location, such as when they click on a new cell, or slide. Events are received by members subscribed to location events and the UI component can be highlighted with the active member's profile data to visually display their location. diff --git a/src/pages/docs/spaces/locking.mdx b/src/pages/docs/spaces/locking.mdx index 3f88a6c094..bc81f8d9a2 100644 --- a/src/pages/docs/spaces/locking.mdx +++ b/src/pages/docs/spaces/locking.mdx @@ -1,9 +1,10 @@ --- title: Component locking +intro: "The component locking feature enables members to optimistically lock stateful UI components before editing them." meta_description: "Component locking enables members to lock UI components before editing them to reduce the chances of conflicting changes being made." --- -The component locking feature enables members to optimistically lock stateful UI components before editing them. This reduces the chances of conflicting changes being made to the same component by different members. A component could be a cell in a spreadsheet that a member is updating, or an input field on a form they're filling in. +Optimistically locking components reduces the chances of conflicting changes being made to the same component by different members. A component could be a cell in a spreadsheet that a member is updating, or an input field on a form they're filling in. Once a lock has been acquired by a member, the component that it relates to can be updated in the UI to visually indicate to other members that it is locked and which member has the lock. The component can then be updated once the editing member has released the lock to indicate that it is now unlocked. diff --git a/src/pages/docs/spaces/react.mdx b/src/pages/docs/spaces/react.mdx index d6e61821bd..8e9784a4a1 100644 --- a/src/pages/docs/spaces/react.mdx +++ b/src/pages/docs/spaces/react.mdx @@ -1,11 +1,10 @@ --- title: React Hooks +intro: "Incorporate Spaces into your React application with idiomatic and user-friendly React Hooks." meta_description: "Incorporate Spaces into your React application with idiomatic and user-friendly React Hooks." --- -Incorporate Spaces into your React application with idiomatic and user-friendly React Hooks. - -This package enables you to: +The Spaces React package enables you to: * Interact with Ably [Spaces](/docs/spaces) using a React Hook * Subscribe to [events](/docs/spaces/avatar#events) in a space diff --git a/src/pages/docs/spaces/setup.mdx b/src/pages/docs/spaces/setup.mdx index 5fc928839d..df5e850883 100644 --- a/src/pages/docs/spaces/setup.mdx +++ b/src/pages/docs/spaces/setup.mdx @@ -1,10 +1,9 @@ --- title: SDK setup +intro: "Use these instructions to install, authenticate and instantiate the Spaces SDK." meta_description: "Install, authenticate and instantiate the Spaces SDK." --- -Use these instructions to install, authenticate and instantiate the Spaces SDK. - ## Authenticate An [API key](/docs/auth#api-keys) is required to authenticate with Ably. API keys are used either to authenticate directly with Ably using [basic authentication](/docs/auth/basic), or to generate tokens for untrusted clients using [token authentication](/docs/auth/token). diff --git a/src/pages/docs/spaces/space.mdx b/src/pages/docs/spaces/space.mdx index e544e70d21..f72dcfbe28 100644 --- a/src/pages/docs/spaces/space.mdx +++ b/src/pages/docs/spaces/space.mdx @@ -1,9 +1,10 @@ --- title: Space +intro: "A space is a virtual area of your application in which realtime collaboration between users can take place." meta_description: "A space is a virtual area of your application in which realtime collaboration between users can take place." --- -A space is a virtual area of your application in which realtime collaboration between users can take place. You can have any number of virtual spaces within an application, with a single space being anything from a web page, a sheet within a spreadsheet, an individual slide in a slideshow, or the entire slideshow itself. +You can have any number of virtual spaces within an application, with a single space being anything from a web page, a sheet within a spreadsheet, an individual slide in a slideshow, or the entire slideshow itself. The following features can be implemented within a space: From 3885500fa899cf00b54af633eb3fd204fde717b4 Mon Sep 17 00:00:00 2001 From: Mark Hulbert <39801222+m-hulbert@users.noreply.github.com> Date: Fri, 12 Dec 2025 18:58:12 +0100 Subject: [PATCH 7/8] Add intro test to pub/sub docs using 1st sentence --- src/pages/docs/auth/basic.mdx | 11 ++++++----- src/pages/docs/auth/capabilities.mdx | 3 +-- src/pages/docs/auth/identified-clients.mdx | 3 ++- src/pages/docs/auth/index.mdx | 3 +-- src/pages/docs/auth/revocation.mdx | 3 ++- src/pages/docs/auth/token.mdx | 3 ++- src/pages/docs/basics/index.mdx | 3 +-- src/pages/docs/channels/index.mdx | 3 ++- src/pages/docs/channels/options/deltas.mdx | 5 ++--- src/pages/docs/channels/options/encryption.mdx | 5 ++--- src/pages/docs/channels/options/index.mdx | 3 ++- src/pages/docs/channels/options/rewind.mdx | 3 ++- src/pages/docs/channels/states.mdx | 3 +-- src/pages/docs/connect/index.mdx | 3 +-- src/pages/docs/connect/states.mdx | 3 ++- src/pages/docs/getting-started/dotnet.mdx | 3 +-- src/pages/docs/getting-started/flutter.mdx | 3 +-- src/pages/docs/getting-started/go.mdx | 3 +-- src/pages/docs/getting-started/index.mdx | 3 +-- src/pages/docs/getting-started/java.mdx | 3 +-- src/pages/docs/getting-started/javascript.mdx | 3 +-- src/pages/docs/getting-started/kotlin.mdx | 3 +-- src/pages/docs/getting-started/laravel.mdx | 3 +-- src/pages/docs/getting-started/node.mdx | 3 +-- src/pages/docs/getting-started/objective-c.mdx | 3 +-- src/pages/docs/getting-started/php.mdx | 3 +-- src/pages/docs/getting-started/python.mdx | 3 +-- src/pages/docs/getting-started/react-hooks.mdx | 3 ++- src/pages/docs/getting-started/react-native.mdx | 3 +-- src/pages/docs/getting-started/react.mdx | 3 +-- src/pages/docs/getting-started/ruby.mdx | 3 +-- src/pages/docs/getting-started/swift.mdx | 3 +-- src/pages/docs/guides/chat/build-livestream.mdx | 3 ++- src/pages/docs/guides/chat/export-chat.mdx | 3 +-- src/pages/docs/messages/annotations.mdx | 3 ++- src/pages/docs/messages/batch.mdx | 3 +-- src/pages/docs/messages/index.mdx | 3 ++- src/pages/docs/messages/updates-deletes.mdx | 3 ++- src/pages/docs/metadata-stats/metadata/index.mdx | 3 ++- src/pages/docs/metadata-stats/metadata/rest.mdx | 3 ++- src/pages/docs/metadata-stats/metadata/subscribe.mdx | 3 ++- src/pages/docs/metadata-stats/stats.mdx | 9 +++++---- src/pages/docs/presence-occupancy/index.mdx | 3 +-- src/pages/docs/presence-occupancy/occupancy.mdx | 3 ++- src/pages/docs/presence-occupancy/presence.mdx | 3 ++- src/pages/docs/protocols/index.mdx | 3 +-- src/pages/docs/protocols/mqtt.mdx | 3 ++- src/pages/docs/protocols/pubnub.mdx | 3 ++- src/pages/docs/protocols/pusher.mdx | 3 ++- src/pages/docs/protocols/sse.mdx | 3 ++- src/pages/docs/pub-sub/advanced.mdx | 3 +-- src/pages/docs/pub-sub/index.mdx | 3 ++- src/pages/docs/push/configure/device.mdx | 5 ++--- src/pages/docs/push/configure/web.mdx | 5 ++--- src/pages/docs/push/index.mdx | 3 ++- src/pages/docs/push/publish.mdx | 3 ++- src/pages/docs/storage-history/history.mdx | 3 ++- src/pages/docs/storage-history/storage.mdx | 3 ++- 58 files changed, 97 insertions(+), 99 deletions(-) diff --git a/src/pages/docs/auth/basic.mdx b/src/pages/docs/auth/basic.mdx index 285977d8ae..27cba2e2ff 100644 --- a/src/pages/docs/auth/basic.mdx +++ b/src/pages/docs/auth/basic.mdx @@ -1,13 +1,10 @@ --- title: Basic auth +intro: "Basic authentication is the simplest way to authenticate with Ably." meta_description: "Basic authentication allows you to authenticate a secure server using an Ably API key and secret." --- -Basic authentication is the simplest way to authenticate with Ably. It requires passing an [API key](/docs/auth#api-key) when instancing an SDK. - - +Basic authentication requires you to pass an [API key](/docs/auth#api-key) when instancing an SDK. The following is an example of using basic authentication: @@ -111,6 +108,10 @@ $rest = new Ably\AblyRest(['key' => '{{API_KEY}}']); ``` + + ## Basic auth architecture The process used by Ably SDKs to authenticate with Ably using basic authentication is illustrated in the following diagram: diff --git a/src/pages/docs/auth/capabilities.mdx b/src/pages/docs/auth/capabilities.mdx index 34a9d2f663..0ebdfbb24d 100644 --- a/src/pages/docs/auth/capabilities.mdx +++ b/src/pages/docs/auth/capabilities.mdx @@ -1,10 +1,9 @@ --- title: Capabilities +intro: "API keys and Ably-compatible tokens, have a set of capabilities assigned to them that specify which operations (such as subscribe or publish) can be performed on which channels." meta_description: "Capabilities define which operations can be carried out on which channels by a client." --- -API keys and Ably-compatible tokens, have a set of capabilities assigned to them that specify which operations (such as subscribe or publish) can be performed on which channels. - API keys are long-lived, secret and typically not shared with clients. API key capabilities are configured using the [dashboard](https://ably.com/dashboard), or using the [Control API](/docs/platform/account/control-api). Ably-compatible tokens are designed to be shared with untrusted clients, are short-lived, and can be configured and issued programmatically. For restricting client access to channels, tokens provide far more flexibility and security than API key capabilities. See [selecting an authentication mechanism](/docs/auth#selecting-auth) to understand why token authentication is the preferred option in most scenarios. diff --git a/src/pages/docs/auth/identified-clients.mdx b/src/pages/docs/auth/identified-clients.mdx index e4754fa566..26d7d7f16f 100644 --- a/src/pages/docs/auth/identified-clients.mdx +++ b/src/pages/docs/auth/identified-clients.mdx @@ -1,9 +1,10 @@ --- title: Identified clients +intro: "When a client is authenticated and connected to Ably, it is considered to be an authenticated client." meta_description: "Clients can be allocated a client ID to help control their operations and interactions with Ably channels." --- -When a client is authenticated and connected to Ably, it is considered to be an authenticated client. While an authenticated client has a means to authenticate with Ably, they do not necessarily have an identity. +While an authenticated client has a means to authenticate with Ably, they do not necessarily have an identity. When a client is assigned a trusted identity, that is, a `clientId`, then they are considered to be an identified client. For all operations that client performs with the Ably service, their `clientId` field will be automatically populated and can be trusted by other clients. diff --git a/src/pages/docs/auth/index.mdx b/src/pages/docs/auth/index.mdx index 51949e95e5..faa08dbaae 100644 --- a/src/pages/docs/auth/index.mdx +++ b/src/pages/docs/auth/index.mdx @@ -1,5 +1,6 @@ --- title: Authentication overview +intro: "Before a client or server can issue requests to Ably, such as subscribe to channels, or publish messages, it must authenticate with Ably. Authentication requires an Ably API key." meta_description: "Ably supports two main authentication schemes: basic authentication and token authentication. Token authentication can be implemented using JWTs, Ably tokens, and Ably token requests." redirect_from: - /docs/rest/authentication @@ -20,8 +21,6 @@ redirect_from: - /docs/ids-and-keys --- -Before a client or server can issue requests to Ably, such as subscribe to channels, or publish messages, it must authenticate with Ably. Authentication requires an Ably API key. - ## Authentication terminology The following terminology helps explain authentication, authorization, and identification in the context of the Ably service: diff --git a/src/pages/docs/auth/revocation.mdx b/src/pages/docs/auth/revocation.mdx index dad67730ee..6330be6dd0 100644 --- a/src/pages/docs/auth/revocation.mdx +++ b/src/pages/docs/auth/revocation.mdx @@ -1,9 +1,10 @@ --- title: Token revocation +intro: "Token revocation is a mechanism that enables an app to invalidate authentication tokens." meta_description: "Token revocation is a mechanism that enables an app to invalidate authentication tokens." --- -Token revocation is a mechanism that enables an app to invalidate authentication tokens. This invalidation can be used to force specified clients to re-obtain a token, and subsequently enables the app to modify the rights granted to clients, or to decline to re-issue a token. Token revocation can be enforced immediately or postponed by 30 seconds, allowing the client the opportunity to request a new token (see `allowReauthMargin` under [Revoke a token](#revoke)). By default `allowReauthMargin` is set to false, meaning token revocation is near immediate. Setting this value to true would postpone the revocation by 30 seconds. +Authentication token invalidation can be used to force specified clients to re-obtain a token, and subsequently enables the app to modify the rights granted to clients, or to decline to re-issue a token. Token revocation can be enforced immediately or postponed by 30 seconds, allowing the client the opportunity to request a new token (see `allowReauthMargin` under [Revoke a token](#revoke)). By default `allowReauthMargin` is set to false, meaning token revocation is near immediate. Setting this value to true would postpone the revocation by 30 seconds. The main use case of token revocation is as a method to combat malicious clients. In cases where the client behaves safely, you don't need token revocation - your code can instruct the connection to Ably to close, or detach from a channel it shouldn't have access to. But if you want to prevent any chance of a user obtaining the token before it is disconnected, and using it in their own custom client to gain access to Ably, then token revocation can be used. diff --git a/src/pages/docs/auth/token.mdx b/src/pages/docs/auth/token.mdx index 912d469dfe..37d4c967ac 100644 --- a/src/pages/docs/auth/token.mdx +++ b/src/pages/docs/auth/token.mdx @@ -1,9 +1,10 @@ --- title: "Token auth" +intro: "Token authentication uses a trusted device with an API key to issue time-limited tokens to untrusted clients." meta_description: "Token authentication allows clients to authenticate with Ably, without exposing the Ably API key and secret." --- -Token authentication uses a trusted device with an [API key](/docs/auth#api-key) to issue time-limited tokens to untrusted clients. Tokens have a limited set of access rights, known as [capabilities](/docs/auth/capabilities), and can have a specific [identity](/docs/auth/identified-clients) using a `clientId`. +Tokens have a limited set of access rights, known as [capabilities](/docs/auth/capabilities), and can have a specific [identity](/docs/auth/identified-clients) using a `clientId`. Token authentication is the recommended authentication method to use client-side as it provides more fine-grained access control and limits the risk of credentials being exposed. diff --git a/src/pages/docs/basics/index.mdx b/src/pages/docs/basics/index.mdx index 7700fb73cd..3f3f38e546 100644 --- a/src/pages/docs/basics/index.mdx +++ b/src/pages/docs/basics/index.mdx @@ -1,5 +1,6 @@ --- title: About Pub/Sub +intro: "Ably Pub/Sub is Ably's core product. Its flexible APIs are powerful building blocks that you can use to create any realtime experience with." meta_description: "Learn more about what Ably Pub/Sub is and how you can use it to build powerful realtime applications." redirect_from: - /docs/products/channels @@ -15,8 +16,6 @@ redirect_from: - /docs/realtime/versions/v0.8 --- -Ably Pub/Sub is Ably's core product. It's flexible APIs are powerful building blocks that you can use to create any realtime experience with. - ## Features The following features are some of the basics that you need to develop realtime applications: diff --git a/src/pages/docs/channels/index.mdx b/src/pages/docs/channels/index.mdx index 908607717f..a8dc7d666c 100644 --- a/src/pages/docs/channels/index.mdx +++ b/src/pages/docs/channels/index.mdx @@ -1,5 +1,6 @@ --- title: Channel concepts +intro: "Channels are used to separate messages into different topics." meta_description: "Channels are used to organize message traffic within Ably." redirect_from: - /docs/rest/channels @@ -26,7 +27,7 @@ redirect_from: - /docs/general/versions/v0.8/channel-rules-namespaces --- -Channels are used to separate messages into different topics. They are the building block of creating a realtime application using the publish-subscribe pattern. Channels are also the unit of security and scalability. Clients should only ever be provided the [capabilities](/docs/auth/capabilities) for channels that they should have access to. +Channels are the building block of creating a realtime application using the publish-subscribe pattern. Channels are also the unit of security and scalability. Clients should only ever be provided the [capabilities](/docs/auth/capabilities) for channels that they should have access to. [Messages](/docs/channels/messages) contain the data that a client is communicating, such as the contents of an individual chat message, or an event that has occurred, such as updated financial information. diff --git a/src/pages/docs/channels/options/deltas.mdx b/src/pages/docs/channels/options/deltas.mdx index 7e6ef52956..b6bdbdf55d 100644 --- a/src/pages/docs/channels/options/deltas.mdx +++ b/src/pages/docs/channels/options/deltas.mdx @@ -1,13 +1,12 @@ --- title: Deltas +intro: "The delta channel option enables delta compression." meta_description: "The delta channel option enables clients to subscribe to a channel and only receive the difference between the present and previous message." redirect_from: - /docs/realtime/channels/channel-parameters/deltas --- -The `delta` channel option enables delta compression. It is applied on the channel you are subscribing to, enabling delta mode. - -Delta mode is a way for a client to subscribe to a channel so that message payloads sent contain only the difference between the present message and the previous message sent on the channel. +Delta compression is a way for a client to subscribe to a channel so that message payloads sent contain only the difference between the present message and the previous message sent on the channel. As `delta` only applies to channel subscriptions, it is only available when using the realtime interface of an Ably SDK, or when using [SSE](/docs/protocols/sse) or [MQTT](/docs/protocols/mqtt). diff --git a/src/pages/docs/channels/options/encryption.mdx b/src/pages/docs/channels/options/encryption.mdx index 554150a58d..5516629303 100644 --- a/src/pages/docs/channels/options/encryption.mdx +++ b/src/pages/docs/channels/options/encryption.mdx @@ -1,6 +1,7 @@ --- title: Encryption -meta_description: "Encrypt message payloads using the cipher channel option." +intro: "Transport Layer Security (TLS) is enabled by default in Ably SDKs so that data is securely sent to, and received from, Ably." +meta_description: "Encrypt message payloads using the cipher channel option. However, messages are not encrypted within the Ably system. Use the encryption channel option to ensure that message payloads are opaque, that they can't be decrypted by Ably, and can only be decrypted by other clients that share your secret key." redirect_from: - /docs/rest/encryption - /docs/rest/versions/v1.1/encryption @@ -12,8 +13,6 @@ redirect_from: - /docs/realtime/versions/v0.8/encryption --- -[Transport Layer Security (TLS)](https://en.wikipedia.org/wiki/Transport_Layer_Security) is enabled by default in Ably SDKs so that data is securely sent to, and received from, Ably. However, messages are not encrypted within the Ably system. Use the encryption channel option to ensure that message payloads are opaque, that they can't be decrypted by Ably, and can only be decrypted by other clients that share your secret key. - ## TLS transport security All Ably client libraries use TLS by default when communicating with Ably over REST or via realtime transports such as WebSockets. This provides a secure transport for communication with Ably, ensuring that messages in transit cannot be intercepted, inspected, or tampered with. diff --git a/src/pages/docs/channels/options/index.mdx b/src/pages/docs/channels/options/index.mdx index 7f08fe1c02..3356c46570 100644 --- a/src/pages/docs/channels/options/index.mdx +++ b/src/pages/docs/channels/options/index.mdx @@ -1,5 +1,6 @@ --- title: Channel options overview +intro: "Channel options can be used to customize the functionality of channels." meta_description: "Channel options customize the functionality of channels." redirect_from: - /docs/realtime/channels/channel-parameters/overview @@ -7,7 +8,7 @@ redirect_from: - /docs/realtime/versions/v1.1/channel-params --- -Channel options can be used to customize the functionality of channels. This includes enabling features such as [encryption](/docs/channels/options/encryption) and [deltas](/docs/channels/options/deltas), or for a client to retrieve messages published prior to it attaching to a channel using [rewind](/docs/channels/options/rewind). +Channel options enable features such as [encryption](/docs/channels/options/encryption) and [deltas](/docs/channels/options/deltas), or for a client to retrieve messages published prior to it attaching to a channel using [rewind](/docs/channels/options/rewind). Channel options are set under the following properties: diff --git a/src/pages/docs/channels/options/rewind.mdx b/src/pages/docs/channels/options/rewind.mdx index 91f4326318..46b0debc1c 100644 --- a/src/pages/docs/channels/options/rewind.mdx +++ b/src/pages/docs/channels/options/rewind.mdx @@ -1,11 +1,12 @@ --- title: Rewind +intro: "The rewind channel option enables a client to specify where to start an attachment from, when attaching to a channel." meta_description: "The rewind channel option enables clients to attach to a channel and receive messages previously published on it." redirect_from: - /docs/realtime/channels/channel-parameters/rewind --- -The `rewind` channel option enables a client to specify where to start an attachment from, when attaching to a channel. Rewind can provide context to clients attaching to a channel by passing them previously published messages, such as in the example of a joining a chat room. +Rewind can provide context to clients attaching to a channel by passing them previously published messages, such as in the example of a joining a chat room. Clients can rewind to a point in time in the past, or for a given number of messages. diff --git a/src/pages/docs/channels/states.mdx b/src/pages/docs/channels/states.mdx index aa16f0f15e..318abf4ef2 100644 --- a/src/pages/docs/channels/states.mdx +++ b/src/pages/docs/channels/states.mdx @@ -1,10 +1,9 @@ --- title: Channel states +intro: "Channels transition through multiple states throughout their lifecycle. Understanding under which conditions the state of a channel changes, and managing those changes, is important to ensure that your applications behave as expected." meta_description: "Channels transition through multiple states." --- -Channels transition through multiple states throughout their lifecycle. Understanding under which conditions the state of a channel changes, and managing those changes, is important to ensure that your applications behave as expected. - ## States A channel can exist in any of the following states: diff --git a/src/pages/docs/connect/index.mdx b/src/pages/docs/connect/index.mdx index 5e677d29ad..64fcbe43a9 100644 --- a/src/pages/docs/connect/index.mdx +++ b/src/pages/docs/connect/index.mdx @@ -1,5 +1,6 @@ --- title: Connections overview +intro: "Clients establish and maintain a connection to the Ably service using the most efficient transport available, typically WebSockets." meta_description: "Establish and maintain a persistent connection to Ably using the realtime interface of an Ably SDK." redirect_from: - /docs/realtime/connection @@ -8,8 +9,6 @@ redirect_from: - /docs/realtime/versions/v0.8/connection --- -Clients establish and maintain a connection to the Ably service using the most efficient transport available, typically [WebSockets](https://ably.com/topic/websockets). - ## Connection multiplexing Ably SDKs operate and multiplex all [channel](/docs/channels) traffic over a single connection. This means you can publish and subscribe to messages on any number of channels simultaneously using just one transport connection. This approach: diff --git a/src/pages/docs/connect/states.mdx b/src/pages/docs/connect/states.mdx index 6dbac6b249..bef238cef6 100644 --- a/src/pages/docs/connect/states.mdx +++ b/src/pages/docs/connect/states.mdx @@ -1,9 +1,10 @@ --- title: Connection state and recovery +intro: "Connections to Ably will transition through multiple states throughout their lifecycle." meta_description: "Establish and maintain a persistent connection to Ably using the Realtime SDK." --- -Connections to Ably will transition through multiple states throughout their lifecycle. States can be observed and triggered using methods available on the connection object. +Connection states can be observed and triggered using methods available on the connection object. Although connection state is temporary, Ably provides continuity of message delivery between a client and the service provided that a dropped connection is re-established by the client within a limited interval (typically around two minutes). After that time the connection becomes stale and the system will not attempt to recover the connection state. diff --git a/src/pages/docs/getting-started/dotnet.mdx b/src/pages/docs/getting-started/dotnet.mdx index c235dd4ec1..0bc5a3e44f 100644 --- a/src/pages/docs/getting-started/dotnet.mdx +++ b/src/pages/docs/getting-started/dotnet.mdx @@ -1,13 +1,12 @@ --- title: "Getting started: Pub/Sub in C# .NET" +intro: "This guide will get you started with Ably Pub/Sub in C# .NET." meta_description: "A getting started guide for Ably Pub/Sub C# .NET that steps through some of the key features using C# and .NET." meta_keywords: "Pub/Sub C# .NET, C# .NET PubSub, Ably C# .NET SDK, realtime messaging C# .NET, publish subscribe C# .NET, Ably Pub/Sub guide, C# .NET realtime communication, Ably tutorial C# .NET, C# .NET message history, presence API C# .NET, Ably Pub/Sub example, realtime Pub/Sub C# .NET, subscribe to channel C# .NET, publish message C# .NET, Ably CLI Pub/Sub" languages: - csharp --- -This guide will get you started with Ably Pub/Sub in C# .NET. - You'll establish a realtime connection to Ably and learn to publish and subscribe to messages. You'll also implement presence to track other online clients, and learn how to retrieve message history. ## Prerequisites diff --git a/src/pages/docs/getting-started/flutter.mdx b/src/pages/docs/getting-started/flutter.mdx index c3c4a5ccf3..2b8e595114 100644 --- a/src/pages/docs/getting-started/flutter.mdx +++ b/src/pages/docs/getting-started/flutter.mdx @@ -1,13 +1,12 @@ --- title: "Getting started: Pub/Sub with Flutter" +intro: "This guide will get you started with Ably Pub/Sub in a new Flutter application." meta_description: "A getting started guide for Ably Pub/Sub Flutter that steps through some of the key features using Flutter." meta_keywords: "Ably, realtime, quickstart, getting started, basics, Pub/Sub, Flutter, Dart" languages: - flutter --- -This guide will get you started with Ably Pub/Sub in a new Flutter application. - You'll establish a realtime connection to Ably and learn to publish and subscribe to messages. You'll also implement presence to track other online clients, and learn how to retrieve message history. ![Screenshot of the completed Flutter Pub/Sub application showing a web interface with connection status, a message input field, realtime message display, and a presence indicator showing online users. The interface demonstrates the key features you'll build including publishing messages, subscribing to receive messages in realtime, and tracking which clients are currently present in the channel.](../../../images/content/screenshots/getting-started/pub-sub-flutter-getting-started-guide.png) diff --git a/src/pages/docs/getting-started/go.mdx b/src/pages/docs/getting-started/go.mdx index 092eeb208d..cfe60bd53a 100644 --- a/src/pages/docs/getting-started/go.mdx +++ b/src/pages/docs/getting-started/go.mdx @@ -1,11 +1,10 @@ --- title: "Getting started: Pub/Sub in Go" +intro: "This guide will get you started with Ably Pub/Sub in Go." meta_description: "Get started with Pub/Sub in Go using Ably. Learn how to publish, subscribe, track presence, fetch message history, and manage realtime connections." meta_keywords: "Pub/Sub Go, Go PubSub, Ably Go SDK, realtime messaging Go, publish subscribe Go, Ably Pub/Sub guide, Go realtime communication, Ably tutorial Go, Go message history, presence API Go, Ably Pub/Sub example, realtime Pub/Sub Go, subscribe to channel Go, publish message Go, Ably CLI Pub/Sub" --- -This guide will get you started with Ably Pub/Sub in Go. - You'll establish a realtime connection to Ably and learn to publish and subscribe to messages. You'll also implement presence to track other online clients, and learn how to retrieve message history. ## Prerequisites diff --git a/src/pages/docs/getting-started/index.mdx b/src/pages/docs/getting-started/index.mdx index 3bfc41c640..5d9003fe67 100644 --- a/src/pages/docs/getting-started/index.mdx +++ b/src/pages/docs/getting-started/index.mdx @@ -1,5 +1,6 @@ --- title: "Getting started with Pub/Sub" +intro: "Getting started with Ably Pub/Sub by choosing your language or framework." meta_description: "Getting started with Ably Pub/Sub in your language or framework of choice. Learn how to publish, subscribe, track presence, fetch message history, and manage realtime connections." meta_keywords: "Pub/Sub, Ably SDKs, realtime messaging, publish subscribe, getting started guides, realtime communication, Ably tutorial, message history, presence API, Ably CLI Pub/Sub" redirect_from: @@ -9,8 +10,6 @@ redirect_from: - /docs/getting-started/setup --- -Getting started with Ably Pub/Sub by choosing your language or framework. - You'll learn the basics, such as how to connect to Ably, publish and subscribe to messages, and manage the status of clients with presence. You'll also be introduced to the Ably CLI and your Ably dashboard to interact with, and manage your apps. These are your first steps towards building a realtime application that can effortlessly scale to serve millions of users. diff --git a/src/pages/docs/getting-started/java.mdx b/src/pages/docs/getting-started/java.mdx index c5cc497dff..de36f974a8 100644 --- a/src/pages/docs/getting-started/java.mdx +++ b/src/pages/docs/getting-started/java.mdx @@ -1,13 +1,12 @@ --- title: "Getting started: Pub/Sub in Java" +intro: "This guide will get you started with Ably Pub/Sub in Java." meta_description: "A getting started guide for Ably Pub/Sub Java that steps through some of the key features using Java." meta_keywords: "Pub/Sub Java, Java PubSub, Ably Java SDK, realtime messaging Java, publish subscribe Java, Ably Pub/Sub guide, Java realtime communication, Ably tutorial Java, Java message history, presence API Java, Ably Pub/Sub example, realtime Pub/Sub Java, subscribe to channel Java, publish message Java, Ably CLI Pub/Sub" languages: - java --- -This guide will get you started with Ably Pub/Sub in Java. - You'll establish a realtime connection to Ably and learn to publish and subscribe to messages. You'll also implement presence to track other online clients, and learn how to retrieve message history. ## Prerequisites diff --git a/src/pages/docs/getting-started/javascript.mdx b/src/pages/docs/getting-started/javascript.mdx index 4cfeab0d33..b94ca35dad 100644 --- a/src/pages/docs/getting-started/javascript.mdx +++ b/src/pages/docs/getting-started/javascript.mdx @@ -1,11 +1,10 @@ --- title: "Getting started: Pub/Sub in JavaScript" +intro: "This guide will get you started with Ably Pub/Sub in JavaScript." meta_description: "Get started with Pub/Sub in vanilla JavaScript using Ably. Learn how to publish, subscribe, track presence, fetch message history, and manage realtime connections." meta_keywords: "Pub/Sub JavaScript, JavaScript PubSub, Ably JavaScript SDK, realtime messaging JavaScript, publish subscribe JavaScript, Ably Pub/Sub guide, JavaScript realtime communication, Ably tutorial JavaScript, JavaScript message history, presence API JavaScript, Ably Pub/Sub example, realtime Pub/Sub JavaScript, subscribe to channel JavaScript, publish message JavaScript, Ably CLI Pub/Sub" --- -This guide will get you started with Ably Pub/Sub in JavaScript. - You'll establish a realtime connection to Ably and learn to publish and subscribe to messages. You'll also implement presence to track other online clients, and learn how to retrieve message history. ## Prerequisites diff --git a/src/pages/docs/getting-started/kotlin.mdx b/src/pages/docs/getting-started/kotlin.mdx index d9e5df9b0a..bbe078a4f6 100644 --- a/src/pages/docs/getting-started/kotlin.mdx +++ b/src/pages/docs/getting-started/kotlin.mdx @@ -1,11 +1,10 @@ --- title: "Getting started: Pub/Sub in Kotlin" +intro: "This guide will get you started with Ably Pub/Sub in Kotlin." meta_description: "Get started with Pub/Sub in Kotlin using Ably. Learn how to publish, subscribe, track presence, fetch message history, and manage realtime connections." meta_keywords: "Pub/Sub Kotlin, Kotlin PubSub, Ably Kotlin SDK, realtime messaging Kotlin, publish subscribe Kotlin, Ably Pub/Sub guide, Kotlin realtime communication, Ably tutorial Kotlin, Kotlin message history, presence API Kotlin, Ably Pub/Sub example, realtime Pub/Sub Kotlin, subscribe to channel Kotlin, publish message Kotlin, Ably CLI Pub/Sub" --- -This guide will get you started with Ably Pub/Sub in Kotlin. - You'll establish a realtime connection to Ably and learn to publish and subscribe to messages. You'll also implement presence to track other online clients, and learn how to retrieve message history. ## Prerequisites diff --git a/src/pages/docs/getting-started/laravel.mdx b/src/pages/docs/getting-started/laravel.mdx index 42667c2ba3..cb4d34ba70 100644 --- a/src/pages/docs/getting-started/laravel.mdx +++ b/src/pages/docs/getting-started/laravel.mdx @@ -1,11 +1,10 @@ --- title: "Getting started: Pub/Sub in Laravel" +intro: "This guide will get you started with Ably Pub/Sub in Laravel 12." meta_description: "A getting started guide for Ably Pub/Sub Laravel 12 that steps through some of the key features using Laravel." meta_keywords: "Pub/Sub Laravel 12, Laravel PubSub, Ably Laravel SDK, publish Laravel, Ably Pub/Sub guide, Laravel realtime communication, Ably tutorial Laravel, Laravel message history, presence API Laravel, Ably Pub/Sub example, realtime Pub/Sub Laravel, publish message Laravel, Ably CLI Pub/Sub" --- -This guide will get you started with Ably Pub/Sub in Laravel 12. - You'll learn how to create a client and establish a connection to Ably using the [Laravel Broadcaster](https://github.com/ably/laravel-broadcaster) service provider and [Echo](https://github.com/ably-forks/laravel-echo) (a Laravel Echo fork with native Ably integration). You'll also cover creating an event to broadcast messages from the backend and setting up a frontend client to receive and publish messages to a channel. ![Screenshot of the completed Laravel Pub/Sub application showing a web interface with a message input field and realtime message display. The interface demonstrates the key features you'll build including publishing messages and subscribing to receive messages in realtime.](../../../images/content/screenshots/getting-started/pub-sub-laravel-getting-started-guide.png) diff --git a/src/pages/docs/getting-started/node.mdx b/src/pages/docs/getting-started/node.mdx index 3fdcc7b452..8db489c450 100644 --- a/src/pages/docs/getting-started/node.mdx +++ b/src/pages/docs/getting-started/node.mdx @@ -1,11 +1,10 @@ --- title: "Getting started: Pub/Sub in Node.js" +intro: "This guide will get you started with Ably Pub/Sub in Node.js." meta_description: "Get started with Pub/Sub in JavaScript using Ably. Learn how to publish, subscribe, track presence, fetch message history, and manage realtime connections." meta_keywords: "Pub/Sub Node.js, Node.js PubSub, Ably Node.js SDK, realtime messaging Node.js, publish subscribe Node.js, Ably Pub/Sub guide, Node.js realtime communication, Ably tutorial Node.js, Node.js message history, presence API Node.js, Ably Pub/Sub example, realtime Pub/Sub Node.js, subscribe to channel Node.js, publish message Node.js, Ably CLI Pub/Sub" --- -This guide will get you started with Ably Pub/Sub in Node.js. - You'll establish a realtime connection to Ably and learn to publish and subscribe to messages. You'll also implement presence to track other online clients, and learn how to retrieve message history. ## Prerequisites diff --git a/src/pages/docs/getting-started/objective-c.mdx b/src/pages/docs/getting-started/objective-c.mdx index d1d3f41d19..ae663d1d12 100644 --- a/src/pages/docs/getting-started/objective-c.mdx +++ b/src/pages/docs/getting-started/objective-c.mdx @@ -1,5 +1,6 @@ --- title: "Getting started: Pub/Sub in Objective-C" +intro: "This guide will get you started with Ably Pub/Sub in Objective-C." meta_description: "A getting started guide for Ably Pub/Sub Objective-C that steps through some of the key features using Objective-C." meta_keywords: "Pub/Sub Objective-C, Objective-C PubSub, Ably Objective-C SDK, realtime messaging Objective-C, publish subscribe Objective-C, Ably Pub/Sub guide, Objective-C realtime communication, Ably tutorial Objective-C, Objective-C message history, presence API Objective-C, Ably Pub/Sub example, realtime Pub/Sub Objective-C, subscribe to channel Objective-C, publish message Objective-C, Ably CLI Pub/Sub" languages: @@ -10,8 +11,6 @@ languages: Objective-C is not recommended for new projects. This guide is provided for maintaining existing apps. For new apps targeting Apple platforms, use the [Swift getting started guide](/docs/getting-started/swift). -This guide will get you started with Ably Pub/Sub in Objective-C. - You'll establish a realtime connection to Ably and learn to publish and subscribe to messages. You'll also implement presence to track other online clients, and learn how to retrieve message history. ## Prerequisites diff --git a/src/pages/docs/getting-started/php.mdx b/src/pages/docs/getting-started/php.mdx index 8e2a34b92d..3ad9b72092 100644 --- a/src/pages/docs/getting-started/php.mdx +++ b/src/pages/docs/getting-started/php.mdx @@ -1,13 +1,12 @@ --- title: "Getting started: Pub/Sub in PHP" +intro: "This guide will get you started with Ably Pub/Sub in PHP." meta_description: "A getting started guide for Ably Pub/Sub PHP that steps through some of the key features using PHP." meta_keywords: "Pub/Sub PHP, PHP PubSub, Ably PHP SDK, publish PHP, Ably Pub/Sub guide, PHP realtime communication, Ably tutorial PHP, PHP message history, presence API PHP, Ably Pub/Sub example, realtime Pub/Sub PHP, publish message PHP, Ably CLI Pub/Sub" languages: - PHP --- -This guide will get you started with Ably Pub/Sub in PHP. - You'll learn how to connect to Ably using the REST SDK, generate JWTs for client authentication, and publish messages. You'll also implement presence to track other online clients, and learn how to retrieve message history. -Message annotations enable clients to append information to existing messages on a channel. You can use annotations to implement features like: +You can use annotations to implement features like: * **Message reactions** - add emoji reactions (👍, ❤️, 😂) to messages * **Content categorization** - tag messages with categories such as "important" or "urgent" diff --git a/src/pages/docs/messages/batch.mdx b/src/pages/docs/messages/batch.mdx index a7ebf6b153..298faf3356 100644 --- a/src/pages/docs/messages/batch.mdx +++ b/src/pages/docs/messages/batch.mdx @@ -1,10 +1,9 @@ --- title: Message batching +intro: "Ably offers two different types of batching that have distinct use cases; server-side batching and batch publishing." meta_description: "Send messages to multiple channels in a single transaction, or batch messages server-side before sending them to subscribers." --- -Ably offers two different types of batching that have distinct use cases: - Server-side batching groups published messages into batches before sending them to subscribers. It is primarily intended for high-throughput scenarios where a large number of messages are being published to a channel in a short period of time. Each batch received by subscribers counts as a single message in terms of billing which can greatly reduce message costs in high-throughput scenarios. Batch publishing enables clients to publish messages to multiple channels using a single request. It enables the same information to be easily distributed to multiple channels, or different information distributed to many channels, all using a single request. A similar feature is available to retrieve the [presence status of multiple channels](/docs/presence-occupancy/presence#batch) using a single request. diff --git a/src/pages/docs/messages/index.mdx b/src/pages/docs/messages/index.mdx index d3ecbad18a..147fe3ff7e 100644 --- a/src/pages/docs/messages/index.mdx +++ b/src/pages/docs/messages/index.mdx @@ -1,5 +1,6 @@ --- title: Message concepts +intro: "Messages contain the data that a client is communicating, such as the contents of a chat message." meta_description: "Messages contain data and are sent and received through channels." redirect_from: - /docs/rest/messages @@ -13,7 +14,7 @@ redirect_from: - /docs/channels/messages --- -Messages contain the data that a client is communicating, such as the contents of a chat message. Clients publish messages on [channels](/docs/channels), and these messages are received by clients that have [subscribed](/docs/pub-sub#subscribe) to them. This pattern is otherwise known as pub/sub, as publishers and subscribers are completely decoupled. +Clients publish messages on [channels](/docs/channels), and these messages are received by clients that have [subscribed](/docs/pub-sub#subscribe) to them. This pattern is otherwise known as pub/sub, as publishers and subscribers are completely decoupled. -You can update and delete messages that have been published to a channel, for use cases such as: +Use messages updates and deletes for: * **Message editing** - allow users to edit their messages in chat-like applications * **Content moderation** - remove or edit inappropriate content after publication diff --git a/src/pages/docs/metadata-stats/metadata/index.mdx b/src/pages/docs/metadata-stats/metadata/index.mdx index b00aa6977d..eeb8f87b1c 100644 --- a/src/pages/docs/metadata-stats/metadata/index.mdx +++ b/src/pages/docs/metadata-stats/metadata/index.mdx @@ -1,5 +1,6 @@ --- title: Metadata overview +intro: "Metadata provides insight into activity within an app." meta_description: "Metadata retrieves information about app activity, such as connections, channels and API requests." redirect_from: - /docs/realtime/channel-metadata @@ -7,7 +8,7 @@ redirect_from: - /docs/realtime/versions/v1.0/channel-metadata --- -Metadata provides insight into activity within an app. This activity is related to things such as connections, channels and API requests. +The activity exposed by metadata includes resources such as connections, channels and API requests. Metadata can be used to check if there are any subscribers on a channel before publishing to it. By monitoring [channel lifecycle events](/docs/metadata-stats/metadata/subscribe#channel-lifecycle) publishers can know when a channel is opened, becomes active, or is no longer active. This can indicate when the last subscriber has left a channel. diff --git a/src/pages/docs/metadata-stats/metadata/rest.mdx b/src/pages/docs/metadata-stats/metadata/rest.mdx index bb9fda5836..cc8092b308 100644 --- a/src/pages/docs/metadata-stats/metadata/rest.mdx +++ b/src/pages/docs/metadata-stats/metadata/rest.mdx @@ -1,5 +1,6 @@ --- title: Metadata REST requests +intro: "Metadata can be retrieved by REST request for a single channel, or for all active channels in an app." meta_description: "Retrieve metadata about single channels, or enumerate through all active channels via REST requests." redirect_from: - /docs/rest/channel-status @@ -7,7 +8,7 @@ redirect_from: - /docs/rest/versions/v1.0/channel-status --- -Metadata can be retrieved by REST request for a single channel, or for all active channels in an app. The information returned includes the current state of a channel and its [occupancy](/docs/presence-occupancy/occupancy). +The information returned through metadata REST requests includes the current state of a channel and its [occupancy](/docs/presence-occupancy/occupancy). Since the metadata of channels often changes frequently, Ably recommends subscribing to [realtime events](/docs/metadata-stats/metadata/subscribe) rather than polling for status updates via REST. This is because data is likely to become stale shortly after it has been received. diff --git a/src/pages/docs/metadata-stats/metadata/subscribe.mdx b/src/pages/docs/metadata-stats/metadata/subscribe.mdx index ea3184f7c7..dba76ba628 100644 --- a/src/pages/docs/metadata-stats/metadata/subscribe.mdx +++ b/src/pages/docs/metadata-stats/metadata/subscribe.mdx @@ -1,11 +1,12 @@ --- title: Metadata subscriptions +intro: "Realtime metadata updates are provided by subscribing to metachannels using the realtime interface of an Ably SDK." meta_description: "Retrieve metadata updates in realtime by subscribing to metachannels." redirect_from: - /docs/realtime/metachannels --- -Realtime metadata updates are provided by subscribing to metachannels using the realtime interface of an Ably SDK. Metachannels are a namespace of channels beginning with the `[meta]` qualifier and they can be subscribed to in the same manner as regular [channels](/docs/channels). +Metachannels are a namespace of channels beginning with the `[meta]` qualifier and they can be subscribed to in the same manner as regular [channels](/docs/channels). Events are published to metachannels that provide app-level metadata about different resources, such as channels, connections and API requests. diff --git a/src/pages/docs/metadata-stats/stats.mdx b/src/pages/docs/metadata-stats/stats.mdx index 747b18cef0..2014ac57b9 100644 --- a/src/pages/docs/metadata-stats/stats.mdx +++ b/src/pages/docs/metadata-stats/stats.mdx @@ -1,5 +1,6 @@ --- title: Statistics +intro: "Ably provides statistics at one minute intervals, aggregated by minute, hour, day and month." meta_description: "Statistics are available at account-level and app-level to monitor your usage of Ably." redirect_from: - /docs/general/statistics @@ -16,12 +17,12 @@ redirect_from: - /docs/realtime/versions/v0.8/statistics --- -Ably provides statistics at one minute intervals. They are aggregated by minute, hour, day and month. The most recent statistics can be delayed by up to six seconds. - Statistics are available as: -* [Account statistics](#account) covering all applications in your account -* [App statistics](#app) for each individual application +* [Account statistics](#account) covering all applications in your account. +* [App statistics](#app) for each individual application. + +The most recent statistics can be delayed by up to six seconds. ## Account statistics diff --git a/src/pages/docs/presence-occupancy/index.mdx b/src/pages/docs/presence-occupancy/index.mdx index 3cb17665d8..b43cf11d98 100644 --- a/src/pages/docs/presence-occupancy/index.mdx +++ b/src/pages/docs/presence-occupancy/index.mdx @@ -1,10 +1,9 @@ --- title: Presence and occupancy overview +intro: "Presence and occupancy are features that provide information about the clients and connections attached to a channel. Occupancy returns high level metrics about the clients attached to a channel, whereas presence provides details about individual members that have joined a channel's presence set." meta_description: "Presence and occupancy provide information about clients attached to channels. This includes metrics about the attached clients, and details of the individual members attached to the channel." --- -[Presence](/docs/presence-occupancy/presence) and [occupancy](/docs/presence-occupancy/occupancy) are features that provide information about the clients and [connections](/docs/connect) attached to a channel. Occupancy returns high level metrics about the clients attached to a channel, whereas presence provides details about individual members that have joined a channel's presence set. - ## Occupancy versus presence Presence and occupancy can both be used to satisfy some use cases. It is important to understand the differences in order to choose the right feature for each use case. diff --git a/src/pages/docs/presence-occupancy/occupancy.mdx b/src/pages/docs/presence-occupancy/occupancy.mdx index 79e47a836d..6cdb1d7b46 100644 --- a/src/pages/docs/presence-occupancy/occupancy.mdx +++ b/src/pages/docs/presence-occupancy/occupancy.mdx @@ -1,12 +1,13 @@ --- title: Occupancy +intro: "Occupancy provides high level metrics about the clients attached to a channel." meta_description: "Occupancy provides high level metrics about the clients attached to a channel." redirect_from: - /docs/realtime/inband-occupancy - /docs/core-features/occupancy --- -Occupancy provides high level metrics about the clients attached to a channel. This includes the number of [connections](/docs/connect) currently attached to a channel, and the number of connections attached that are permitted to publish and subscribe to the channel. +Occupancy metrics include the number of [connections](/docs/connect) currently attached to a channel, and the number of connections attached that are permitted to publish and subscribe to the channel. ## Occupancy metric categories diff --git a/src/pages/docs/presence-occupancy/presence.mdx b/src/pages/docs/presence-occupancy/presence.mdx index 0821f8d34c..7f1d35afdf 100644 --- a/src/pages/docs/presence-occupancy/presence.mdx +++ b/src/pages/docs/presence-occupancy/presence.mdx @@ -1,5 +1,6 @@ --- title: Presence +intro: "Presence enables clients to be aware of other clients that are currently \"present\" on a channel." meta_description: "Presence enables clients to be aware of the other clients present on a channel." redirect_from: - /docs/rest/presence @@ -14,7 +15,7 @@ redirect_from: - /docs/core-features/versions/v1.1/presence --- -Presence enables clients to be aware of other clients that are currently "present" on a channel. Each member present on a channel has a unique self-assigned client identifier and system-assigned connection identifier, along with an optional payload that can be used to describe the member's status or attributes. Presence enables you to quickly build apps such as chat rooms and multiplayer games by automatically keeping track of who is present in real time across any device. +Each member present on a channel has a unique self-assigned client identifier and system-assigned connection identifier, along with an optional payload that can be used to describe the member's status or attributes. Presence enables you to quickly build apps such as chat rooms and multiplayer games by automatically keeping track of who is present in real time across any device. Other devices and services can subscribe to presence events in real time using the realtime interface or with [integrations](/docs/platform/integrations). You can also request a list of clients or devices on a channel at a particular point in time with the REST interface. diff --git a/src/pages/docs/protocols/index.mdx b/src/pages/docs/protocols/index.mdx index 8f4c6a4a2a..97e995216a 100644 --- a/src/pages/docs/protocols/index.mdx +++ b/src/pages/docs/protocols/index.mdx @@ -1,12 +1,11 @@ --- title: Protocols +intro: "Ably SDKs are the recommended method for connecting to Ably because they offer support for a comprehensive set of Ably features. These features include automatic connection management, authentication token renewal and presence." meta_description: "Clients can use the Ably network protocol adapters. This is especially useful where an Ably SDK is not available for your language of choice, or where platform resource constraints prohibit use of an SDK." redirect_from: - /docs/protocol-adapters --- -Ably SDKs are the recommended method for connecting to Ably because they offer support for a comprehensive set of Ably features, such as automatic [connection management](/docs/connect), [authentication token renewal](/docs/auth/token) and [presence](/docs/presence-occupancy). - Protocol adapters offer an alternative method for connecting to Ably. The advantage to protocol adapters is that they require fewer resources in terms of memory and network overhead such as in smaller footprint devices, or on a platform where an Ably SDK isn't available such as an Arduino-based IoT wearable. The potential drawback to consider when evaluating protocol adapters is that they do not support the full set of Ably features, for example the MQTT protocol adapter does not support presence, and the SSE protocol adapter does not support automatic token renewal. ## Migrate to Ably diff --git a/src/pages/docs/protocols/mqtt.mdx b/src/pages/docs/protocols/mqtt.mdx index 62779c03e9..95c6880319 100644 --- a/src/pages/docs/protocols/mqtt.mdx +++ b/src/pages/docs/protocols/mqtt.mdx @@ -1,5 +1,6 @@ --- title: MQTT +intro: "The Ably MQTT protocol adapter is able to translate back and forth between MQTT and Ably's own protocol, allowing for seamless integration of any systems you may have." meta_description: "Any MQTT-enabled client can communicate with the Ably service through the Ably MQTT protocol adapter. This is especially useful where an Ably SDK is not available for your language of choice." languages: - javascript @@ -8,7 +9,7 @@ redirect_from: - /docs/mqtt --- -The Ably MQTT protocol adapter is able to translate back and forth between [MQTT](https://mqtt.org/) and Ably's own protocol, allowing for seamless integration of any systems you may have. MQTT (MQ Telemetry Transport) is a [publish/subscribe](https://ably.com/topic/pub-sub), lightweight messaging protocol designed for constrained devices and low-bandwidth networks. One of the major uses of MQTT is with IoT (Internet of Things), where these principles are key to having effective communication between various devices. +[MQTT](https://mqtt.org/) (MQ Telemetry Transport) is a [publish/subscribe](https://ably.com/topic/pub-sub), lightweight messaging protocol designed for constrained devices and low-bandwidth networks. One of the major uses of MQTT is with IoT (Internet of Things), where these principles are key to having effective communication between various devices. ## When to use the MQTT adapter diff --git a/src/pages/docs/protocols/pubnub.mdx b/src/pages/docs/protocols/pubnub.mdx index 96e0ccc928..cf84786853 100644 --- a/src/pages/docs/protocols/pubnub.mdx +++ b/src/pages/docs/protocols/pubnub.mdx @@ -1,12 +1,13 @@ --- title: PubNub Adapter +intro: "Ably enables migration from PubNub to Ably using its PubNub Adapter." meta_description: "Use the PubNub Adapter to migrate from PubNub to Ably by only changing your API key." languages: - javascript - ruby --- -Ably enables migration from PubNub to Ably using its PubNub Adapter. The protocol adapter handles all background translation and only requires an API key change. +The protocol adapter handles all background translation and only requires an API key change. Using an adapter introduces some latency and is slower than using an Ably SDK. The PubNub adapter can have more variable latency than other adapters because PubNub's protocol is inherently long-polling based, which creates an impedance mismatch with Ably's WebSocket-based architecture. Some operations are quick with PubNub, but slower or impossible with Ably, and vice versa. diff --git a/src/pages/docs/protocols/pusher.mdx b/src/pages/docs/protocols/pusher.mdx index f4661c728f..6a32d95d03 100644 --- a/src/pages/docs/protocols/pusher.mdx +++ b/src/pages/docs/protocols/pusher.mdx @@ -1,11 +1,12 @@ --- title: Pusher Adapter +intro: "Ably enables migration from Pusher to Ably using its Pusher Adapter." meta_description: "Use the Pusher Adapter to migrate from Pusher to Ably by only changing your API key." languages: - javascript --- -Ably enables migration from Pusher to Ably using its Pusher Adapter. The protocol adapter handles all background translation and only requires an API key change. +The protocol adapter handles all background translation and only requires an API key change. Using an adapter introduces some latency and is slower than using an Ably SDK, however the impact is typically 1-10ms. It will also be slightly slower than using Pusher natively, but only if you are close to whichever Pusher data center used. If you aren't close to the Pusher data center you've chosen, then the extra latency from using the adapter should be more than compensated for by being able to use a data center that is close to you. This is because Ably automatically connects clients to the data center closest to them. diff --git a/src/pages/docs/protocols/sse.mdx b/src/pages/docs/protocols/sse.mdx index 173bda2338..bdc4211f2a 100644 --- a/src/pages/docs/protocols/sse.mdx +++ b/src/pages/docs/protocols/sse.mdx @@ -1,5 +1,6 @@ --- title: SSE +intro: "The Ably SSE (Server-Sent Events) API provides realtime event streams without needing a full SDK or an MQTT library." meta_description: "Ably provides support for Server-Sent Events (SSE). This is useful for where browser clients support SSE, and the use case does not require or support the resources used by an Ably SDK." languages: - javascript @@ -8,7 +9,7 @@ redirect_from: - /docs/sse/versions/v1.1 --- -The Ably SSE (Server-Sent Events) API provides realtime event streams without needing a full SDK or an [MQTT](/docs/protocols/mqtt) library. [SSE](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events) is a lightweight streaming layer over HTTP, primarily accessed through the [EventSource API](https://developer.mozilla.org/en-US/docs/Web/API/EventSource) in modern web browsers — the preferred method to harness SSE. +[SSE](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events) is a lightweight streaming layer over HTTP, primarily accessed through the [EventSource API](https://developer.mozilla.org/en-US/docs/Web/API/EventSource) in modern web browsers — the preferred method to harness SSE. With HTTP streaming, servers can maintain client requests and transmit data without repetitive requests, offering efficiency akin to WebSockets. diff --git a/src/pages/docs/pub-sub/advanced.mdx b/src/pages/docs/pub-sub/advanced.mdx index 54401627a9..6d5000ef19 100644 --- a/src/pages/docs/pub-sub/advanced.mdx +++ b/src/pages/docs/pub-sub/advanced.mdx @@ -1,10 +1,9 @@ --- title: Advanced pub-sub +intro: "After understanding the basics of subscribing to a channel and publishing messages to it, explore the more advanced concepts and features to build more complex and efficient applications." meta_description: "Utilize advanced pub-sub features, such as, subscription filters and idempotent publishing." --- -After understanding the [basics](/docs/pub-sub) of subscribing to a channel and publishing messages to it, explore the more advanced concepts and features to build more complex and efficient applications. - ## Subscribing to channels Explore additional concepts and features after understanding the [basics of subscribing](/docs/pub-sub#subscribe) to channels. diff --git a/src/pages/docs/pub-sub/index.mdx b/src/pages/docs/pub-sub/index.mdx index 84f20a549d..6f54e60424 100644 --- a/src/pages/docs/pub-sub/index.mdx +++ b/src/pages/docs/pub-sub/index.mdx @@ -1,9 +1,10 @@ --- title: Basic pub-sub +intro: "Ably Pub/Sub enables you to implement the publish-subscribe (pub-sub) pattern." meta_description: "Get a channel, subscribe clients to it, and publish messages to the channel." --- -Ably Pub/Sub enables you to implement the publish-subscribe (pub-sub) pattern. Any number of publishers can send messages to a channel, and any number of subscribers can receive those messages. Publishers and subscribers are completely decoupled from one another. +Any number of publishers can send messages to a channel, and any number of subscribers can receive those messages. Publishers and subscribers are completely decoupled from one another. [Channels](/docs/channels) are used to separate messages into different topics. [Messages](/docs/messages) contain the data that a client is communicating, such as the contents of an individual chat message, or an event that has occurred, such as updated financial information. Whilst billions of messages may be delivered by Ably, clients receive only the messages on the channels they subscribe to. diff --git a/src/pages/docs/push/configure/device.mdx b/src/pages/docs/push/configure/device.mdx index 1f21010a46..e53056f902 100644 --- a/src/pages/docs/push/configure/device.mdx +++ b/src/pages/docs/push/configure/device.mdx @@ -1,5 +1,6 @@ --- title: Configure and activate devices +intro: "To send push notifications with Ably, you must first configure the device using its platform-specific notification service (FCM or APNs) and integrate it with Ably's infrastructure." meta_description: "Learn how to set up and manage device activations for push notifications with Ably, including platform installation, device registration, and handling lifecycle events." meta_keywords: "Push, push notifications, Apple push notification service, Google firebase cloud messaging service, activate, subscribe" redirect_from: @@ -9,14 +10,12 @@ redirect_from: - /docs/general/push/activate-subscribe --- -To send push notifications with Ably, you must first configure the device using its platform-specific notification service ([FCM](https://firebase.google.com/docs/cloud-messaging) or [APNs](https://developer.apple.com/notifications/)) and integrate it with Ably's infrastructure. You can then activate the push notifications service, either directly or via a server. +## Configure devices -## Configure devices - Configuration is the first step in setting up push notifications with Ably. This step requires setting up the necessary infrastructure on the device's operating system or platform, as well as on the Ably platform. ![Push Notifications in Ably](../../../../images/content/diagrams/push-process-configure-highlighted.png) diff --git a/src/pages/docs/push/configure/web.mdx b/src/pages/docs/push/configure/web.mdx index 6cd825a669..b7cf34e2b7 100644 --- a/src/pages/docs/push/configure/web.mdx +++ b/src/pages/docs/push/configure/web.mdx @@ -1,17 +1,16 @@ --- title: Configure and activate web browsers +intro: "To send push notifications with Ably, you must first configure browsers using Web Push and integrate it with Ably's infrastructure." meta_description: "Learn how to set up and manage browser activations for push notifications with Ably, including platform installation, browser registration, and handling lifecycle events." meta_keywords: "Push, push notifications, Web Push, activate, subscribe" --- -To send push notifications with Ably, you must first configure browsers using [Web Push](https://www.w3.org/TR/push-api/) and integrate it with Ably's infrastructure. You can then activate the push notifications service, either directly or via a server. +## Configure web browsers -## Configure web browsers - Configuration is the first step in setting up push notifications with Ably. This step requires setting up the necessary infrastructure for your application. ![Push Notifications in Ably](../../../../images/content/diagrams/push-process-configure-highlighted-web-push.png) diff --git a/src/pages/docs/push/index.mdx b/src/pages/docs/push/index.mdx index 637909cff7..d542a47195 100644 --- a/src/pages/docs/push/index.mdx +++ b/src/pages/docs/push/index.mdx @@ -1,5 +1,6 @@ --- title: Push notifications overview +intro: "Push notifications notify user devices or browsers regardless of whether an application is open and running." meta_description: "Ably delivers push notifications to user devices or browsers." meta_keywords: "Push, push notifications, Apple push notification service, Google Firebase cloud messaging service, APNs, FCM, Web Push" redirect_from: @@ -15,7 +16,7 @@ redirect_from: - /docs/general/smart-notifications --- -Push notifications notify user devices or browsers regardless of whether an application is open and running. They deliver information, such as app updates, social media alerts, or promotional offers, directly to the user's screen. Ably sends push notifications to devices using [Firebase Cloud Messaging](https://firebase.google.com/docs/cloud-messaging) or [Apple Push Notification Service](https://developer.apple.com/notifications/), and to browsers using [Web Push](https://developer.mozilla.org/en-US/docs/Web/API/Push_API). Push notifications don't require a device or browser to stay connected to Ably. Instead, a device's or browser's operating system or web browser maintains its own battery-efficient transport to receive notifications. +Push notifications deliver information, such as app updates, social media alerts, or promotional offers, directly to the user's screen. Ably sends push notifications to devices using [Firebase Cloud Messaging](https://firebase.google.com/docs/cloud-messaging) or [Apple Push Notification Service](https://developer.apple.com/notifications/), and to browsers using [Web Push](https://developer.mozilla.org/en-US/docs/Web/API/Push_API). Push notifications don't require a device or browser to stay connected to Ably. Instead, a device's or browser's operating system or web browser maintains its own battery-efficient transport to receive notifications. You can publish push notifications to user devices or browsers [directly](/docs/push/publish/#direct-publishing) or [via channels](#via-channels). diff --git a/src/pages/docs/push/publish.mdx b/src/pages/docs/push/publish.mdx index 2765f08d1b..67daad2370 100644 --- a/src/pages/docs/push/publish.mdx +++ b/src/pages/docs/push/publish.mdx @@ -1,5 +1,6 @@ --- title: Publish and receive push notifications +intro: "Publishing sends push notifications to all specified devices or browsers either directly or via channels." meta_description: "Learn how to publish and manage push notifications with Ably, covering direct and channel-based processes, payload details, and subscription management." meta_keywords: "Push, push notifications, Apple push notification Service, Google Firebase Cloud Messaging Service, publishing, direct publishing, channel-based broadcasting" redirect_from: @@ -12,7 +13,7 @@ redirect_from: - /docs/general/versions/v1.1/push/admin --- -Publishing sends push notifications to all specified devices or browsers either directly or via channels. This process is facilitated by Ably's realtime messaging infrastructure, which ensures that messages and notifications are delivered instantaneously. +The publishing process is facilitated by Ably's realtime messaging infrastructure, which ensures that messages and notifications are delivered instantaneously. ![Push Notifications in Ably](../../../images/content/diagrams/push-process-publish-subscribe-highlighted.png) diff --git a/src/pages/docs/storage-history/history.mdx b/src/pages/docs/storage-history/history.mdx index cfee8a88d7..9c124fa121 100644 --- a/src/pages/docs/storage-history/history.mdx +++ b/src/pages/docs/storage-history/history.mdx @@ -1,5 +1,6 @@ --- title: History +intro: "Ably's message history feature is for short-term catch-up, allowing clients to retrieve messages they missed during a brief disconnection." meta_description: "Learn about accessing message history with the history and rewind features" redirect_from: - /docs/rest/history @@ -14,7 +15,7 @@ redirect_from: - /docs/core-features/versions/v1.1/history --- -Ably's message History feature doesn’t replace a long-term database, it’s for short-term catch-up, allowing clients to retrieve messages they missed during a brief disconnection. Using it as a primary database is an architectural anti-pattern that will lead to problems. +History doesn't replace a long-term database. Using it as your primary database is an architectural anti-pattern that will lead to problems. When a client disconnects, Ably automatically handles the reconnection. If the disconnection lasts less than 2 minutes, Ably's [connection-state recovery](/docs/platform/architecture/connection-recovery) feature streams any missed messages to the client. For longer outages, the client must use the [History API](/docs/api/realtime-sdk/history) to fetch the missed messages. The API works efficiently because it indexes all messages by channel, timestamp, and serial number, allowing retrieval from any point in time. diff --git a/src/pages/docs/storage-history/storage.mdx b/src/pages/docs/storage-history/storage.mdx index d9b3346f01..b598e67cd4 100644 --- a/src/pages/docs/storage-history/storage.mdx +++ b/src/pages/docs/storage-history/storage.mdx @@ -1,9 +1,10 @@ --- title: Message Storage +intro: "Ably stores all messages for two minutes by default." meta_description: "Explore the different ways Ably can handle Message Storage" --- -Ably stores all messages for two minutes by default. This can be increased up to a year, or longer, depending on your account package. It is also possible to persist the last message sent to a channel for a year. Ably [integrations](/docs/platform/integrations) can also be used to send messages outside of Ably for long-term storage. +Messages can be stored up to a year, or longer, depending on your account package. It is also possible to persist the last message sent to a channel for a year. Ably [integrations](/docs/platform/integrations) can also be used to send messages outside of Ably for long-term storage. ## Default message storage - two minutes From c519f9313e5eac7ad4c20cef5c37c492b8857545 Mon Sep 17 00:00:00 2001 From: Mark Hulbert <39801222+m-hulbert@users.noreply.github.com> Date: Mon, 15 Dec 2025 10:47:33 +0100 Subject: [PATCH 8/8] Add intro text to API references and remove unused frontmatter --- src/pages/docs/api/index.mdx | 3 +- src/pages/docs/api/realtime-sdk.mdx | 1 + .../docs/api/realtime-sdk/authentication.mdx | 16 +------ .../api/realtime-sdk/channel-metadata.mdx | 1 + src/pages/docs/api/realtime-sdk/channels.mdx | 1 + .../docs/api/realtime-sdk/connection.mdx | 1 + .../docs/api/realtime-sdk/encryption.mdx | 8 +--- src/pages/docs/api/realtime-sdk/history.mdx | 7 +-- src/pages/docs/api/realtime-sdk/messages.mdx | 3 +- src/pages/docs/api/realtime-sdk/presence.mdx | 17 +------ .../docs/api/realtime-sdk/push-admin.mdx | 8 +--- src/pages/docs/api/realtime-sdk/push.mdx | 7 +-- .../docs/api/realtime-sdk/statistics.mdx | 1 + src/pages/docs/api/realtime-sdk/types.mdx | 5 +-- src/pages/docs/api/rest-api.mdx | 45 +------------------ src/pages/docs/api/rest-sdk.mdx | 1 + .../docs/api/rest-sdk/authentication.mdx | 14 +----- .../docs/api/rest-sdk/channel-status.mdx | 8 +--- src/pages/docs/api/rest-sdk/channels.mdx | 1 + src/pages/docs/api/rest-sdk/encryption.mdx | 8 +--- src/pages/docs/api/rest-sdk/history.mdx | 7 +-- src/pages/docs/api/rest-sdk/messages.mdx | 3 +- src/pages/docs/api/rest-sdk/presence.mdx | 7 +-- src/pages/docs/api/rest-sdk/push-admin.mdx | 9 +--- src/pages/docs/api/rest-sdk/statistics.mdx | 1 + src/pages/docs/api/rest-sdk/types.mdx | 5 +-- src/pages/docs/api/sse.mdx | 5 +-- 27 files changed, 30 insertions(+), 163 deletions(-) diff --git a/src/pages/docs/api/index.mdx b/src/pages/docs/api/index.mdx index 37c6332da9..5a5282e0a1 100644 --- a/src/pages/docs/api/index.mdx +++ b/src/pages/docs/api/index.mdx @@ -1,11 +1,10 @@ --- title: API Reference +intro: "This section of the documentation contains the API references for Ably." meta_description: "API reference section of the Ably developer documentation." meta_keywords: "Ably, Ably realtime, API Reference, Realtime SDK, REST SDK, REST API, SSE API, Control API" --- -This section of the documentation contains the API references for Ably. - The following API references are available: * [Client library Realtime SDK](/docs/api/realtime-sdk) diff --git a/src/pages/docs/api/realtime-sdk.mdx b/src/pages/docs/api/realtime-sdk.mdx index 0c12de70ef..01e5f4dbce 100644 --- a/src/pages/docs/api/realtime-sdk.mdx +++ b/src/pages/docs/api/realtime-sdk.mdx @@ -1,5 +1,6 @@ --- title: Constructor +intro: "The realtime interface of Ably SDKs establishes and maintains a persistent connection the Ably service. You can publish and subscribe to messages on channels over this connection." meta_description: "Realtime Client Library SDK API reference section for the constructor object." meta_keywords: "Ably, Ably realtime, API Reference, Realtime SDK, constructor, instantiate" redirect_from: diff --git a/src/pages/docs/api/realtime-sdk/authentication.mdx b/src/pages/docs/api/realtime-sdk/authentication.mdx index 54764aa625..d6bdd6bcd7 100644 --- a/src/pages/docs/api/realtime-sdk/authentication.mdx +++ b/src/pages/docs/api/realtime-sdk/authentication.mdx @@ -1,28 +1,14 @@ --- title: Authentication +intro: "Authenticate with Ably using API keys, JWTs, or tokens." meta_description: "Realtime Client Library SDK API reference section for authentication." meta_keywords: "Ably, Ably realtime, API Reference, Realtime SDK, auth, authentication, token, JWT, basic auth" -jump_to: - Help with: - - Tokens#tokens - - Auth object#auth-object - Auth API properties: - - clientId#client-id - Auth API methods: - - authorize - - createTokenRequest#create-token-request - - requestToken#request-token - - revokeTokens#revoke-tokens - Types: - - Related Types#related-types redirect_from: - /docs/api/versions/v1.1/realtime-sdk/authentication - /docs/api/versions/v1.0/realtime-sdk/authentication - /docs/api/versions/v0.8/realtime-sdk/authentication --- -This is the Authentication API Reference. - ## Tokens In the documentation, references to Ably-compatible tokens typically refer either to an Ably Token, or an [Ably JWT](#ably-jwt). For Ably Tokens, this can either be referring to the `TokenDetails` object that contain the `token` string or the token string itself. `TokenDetails` objects are obtained when [requesting an Ably Token](#request-token) from the Ably service and contain not only the `token` string in the `token` attribute, but also contain attributes describing the properties of the Ably Token. For [Ably JWT](#ably-jwt), this will be simply referring to a JWT which has been signed by an Ably private API key. diff --git a/src/pages/docs/api/realtime-sdk/channel-metadata.mdx b/src/pages/docs/api/realtime-sdk/channel-metadata.mdx index 21b1c418a9..a9247baf04 100644 --- a/src/pages/docs/api/realtime-sdk/channel-metadata.mdx +++ b/src/pages/docs/api/realtime-sdk/channel-metadata.mdx @@ -1,5 +1,6 @@ --- title: Channel Metadata +intro: "Channel metadata provides information about the state and occupancy of channels." meta_description: "Realtime Client Library SDK API reference section for channel metadata." meta_keywords: "Ably, Ably realtime, API Reference, Realtime SDK, channel, metadata, channel metadata, occupancy" redirect_from: diff --git a/src/pages/docs/api/realtime-sdk/channels.mdx b/src/pages/docs/api/realtime-sdk/channels.mdx index 2160157d91..7f49debb3a 100644 --- a/src/pages/docs/api/realtime-sdk/channels.mdx +++ b/src/pages/docs/api/realtime-sdk/channels.mdx @@ -1,5 +1,6 @@ --- title: Channels +intro: "Use the Channels object and Channel objects to interact with Ably channels." meta_description: "Realtime Client Library SDK API reference section for the channels and channel objects." meta_keywords: "Ably, Ably realtime, API Reference, Realtime SDK, channel, channel, channels, publish, subscribe" redirect_from: diff --git a/src/pages/docs/api/realtime-sdk/connection.mdx b/src/pages/docs/api/realtime-sdk/connection.mdx index 249b58eb45..2ac44af1eb 100644 --- a/src/pages/docs/api/realtime-sdk/connection.mdx +++ b/src/pages/docs/api/realtime-sdk/connection.mdx @@ -1,5 +1,6 @@ --- title: Connection +intro: "Use the Connection object to manage persistent connections to the Ably service." meta_description: "Realtime Client Library SDK API reference section for the connection object." meta_keywords: "Ably, Ably realtime, API Reference, Realtime SDK, connect, connection" redirect_from: diff --git a/src/pages/docs/api/realtime-sdk/encryption.mdx b/src/pages/docs/api/realtime-sdk/encryption.mdx index 5868b60e90..16f5ae5ffd 100644 --- a/src/pages/docs/api/realtime-sdk/encryption.mdx +++ b/src/pages/docs/api/realtime-sdk/encryption.mdx @@ -1,14 +1,8 @@ --- title: Encryption +intro: "Use the Crypto object to encrypt and decrypt messages." meta_description: "Realtime Client Library SDK API reference section for the crypto object." meta_keywords: "Ably, Ably realtime, API Reference, Realtime SDK, encryption, crypto" -jump_to: - API Reference: - - getDefaultParams#get-default-params - - generateRandomKey#generate-random-key - Related types: - - Channel Options - - CipherParams#cipher-params redirect_from: - /docs/api/versions/v1.1/realtime-sdk/encryption - /docs/api/versions/v1.0/realtime-sdk/encryption diff --git a/src/pages/docs/api/realtime-sdk/history.mdx b/src/pages/docs/api/realtime-sdk/history.mdx index c306dc3303..ae7ca5e4ad 100644 --- a/src/pages/docs/api/realtime-sdk/history.mdx +++ b/src/pages/docs/api/realtime-sdk/history.mdx @@ -1,13 +1,8 @@ --- title: History +intro: "Use the history method to retrieve previously sent messages and presence events from a channel." meta_description: "Realtime Client Library SDK API reference section for the history methods." meta_keywords: "Ably, Ably realtime, API Reference, Realtime SDK, history, message, presence" -jump_to: - API reference: - - Message history#channel-history - - Presence history#presence-history - Types: - - Related Types#related-types redirect_from: - /docs/api/versions/v1.1/realtime-sdk/history - /docs/api/versions/v1.0/realtime-sdk/history diff --git a/src/pages/docs/api/realtime-sdk/messages.mdx b/src/pages/docs/api/realtime-sdk/messages.mdx index 7118cd20df..b080e30494 100644 --- a/src/pages/docs/api/realtime-sdk/messages.mdx +++ b/src/pages/docs/api/realtime-sdk/messages.mdx @@ -1,5 +1,6 @@ --- title: Messages +intro: "A Message represents an individual message that is sent to or received from Ably." meta_description: "Realtime Client Library SDK API reference section for the message object." meta_keywords: "Ably, Ably realtime, API Reference, Realtime SDK, message, messages" redirect_from: @@ -10,8 +11,6 @@ redirect_from: ## PropertiesAttributesMembers -A `Message` represents an individual message that is sent to or received from Ably. - ### nameName The event name, if provided.
_Type: `String`_ diff --git a/src/pages/docs/api/realtime-sdk/presence.mdx b/src/pages/docs/api/realtime-sdk/presence.mdx index 5e04e9ac8f..e748da9b2c 100644 --- a/src/pages/docs/api/realtime-sdk/presence.mdx +++ b/src/pages/docs/api/realtime-sdk/presence.mdx @@ -1,23 +1,8 @@ --- title: Presence +intro: "Use the Presence object to manage and interact with presence on Ably channels." meta_description: "Realtime Client Library SDK API reference section for the presence object." meta_keywords: "Ably, Ably realtime, API Reference, Realtime SDK, presence" -jump_to: - Presence API properties: - - syncComplete#sync-complete - Presence API methods: - - enter - - leave - - update - - get - - history - - subscribe - - unsubscribe - - enterClient#enter-client - - leaveClient#leave-client - - updateClient#update-client - Types: - - Related Types#related-types redirect_from: - /docs/api/versions/v1.1/realtime-sdk/presence - /docs/api/versions/v1.0/realtime-sdk/presence diff --git a/src/pages/docs/api/realtime-sdk/push-admin.mdx b/src/pages/docs/api/realtime-sdk/push-admin.mdx index 53b8b171dd..3e863ea29c 100644 --- a/src/pages/docs/api/realtime-sdk/push-admin.mdx +++ b/src/pages/docs/api/realtime-sdk/push-admin.mdx @@ -1,14 +1,8 @@ --- title: Push Notifications - Admin +intro: "Use the Push.Admin object to manage push notifications, including device registrations and channel subscriptions." meta_description: "Realtime Client Library SDK API reference section for push notifications admin." meta_keywords: "Ably, Ably realtime, API Reference, Realtime SDK, push, push notification, notification, push notifications, notifications, admin, push admin" -jump_to: - API reference: - - publish#publish - - DeviceRegistrations#device-registrations-object - - PushChannelSubscriptions#push-channel-subscriptions - Types: - - Related Types#related-types redirect_from: - /docs/api/versions/v1.1/realtime-sdk/push-admin --- diff --git a/src/pages/docs/api/realtime-sdk/push.mdx b/src/pages/docs/api/realtime-sdk/push.mdx index 89196da0e7..2f81ab6b82 100644 --- a/src/pages/docs/api/realtime-sdk/push.mdx +++ b/src/pages/docs/api/realtime-sdk/push.mdx @@ -1,13 +1,8 @@ --- title: Push Notifications - Device Activation and Subscription +intro: "Use the Push object to activate push notification devices and manage push channel subscriptions." meta_description: "Realtime Client Library SDK API reference section for push notification device subscription." meta_keywords: "Ably, Ably realtime, API Reference, Realtime SDK, push, push notification, notification, push notifications, notifications, device subscription, activate device" -jump_to: - API reference: - - activate#activate - - deactivate#deactivate - Types: - - Related Types#related-types redirect_from: - /docs/api/versions/v1.1/realtime-sdk/push --- diff --git a/src/pages/docs/api/realtime-sdk/statistics.mdx b/src/pages/docs/api/realtime-sdk/statistics.mdx index 13767ea322..37e3add120 100644 --- a/src/pages/docs/api/realtime-sdk/statistics.mdx +++ b/src/pages/docs/api/realtime-sdk/statistics.mdx @@ -1,5 +1,6 @@ --- title: Statistics +intro: "Use the stats method to retrieve your application's usage statistics." meta_description: "Realtime Client Library SDK API reference section for the stats object." meta_keywords: "Ably, Ably realtime, API Reference, Realtime SDK, stats, statistics" redirect_from: diff --git a/src/pages/docs/api/realtime-sdk/types.mdx b/src/pages/docs/api/realtime-sdk/types.mdx index d588159d4e..74ca5b67b6 100644 --- a/src/pages/docs/api/realtime-sdk/types.mdx +++ b/src/pages/docs/api/realtime-sdk/types.mdx @@ -1,5 +1,6 @@ --- title: Types +intro: "Ably SDKs define both data types and option types. Data types are used to represent object such as messages. Option types are used in method arguments." meta_description: "Realtime Client Library SDK API reference section for types." meta_keywords: "Ably, Ably realtime, API Reference, Realtime SDK, types, objects, options" redirect_from: @@ -12,9 +13,7 @@ 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. +Where SDKs support both Realtime and REST interfaces, types are shared between both clients. All types are always classes or their respective equivalent for each language implementation. Options on the other hand, may often support both typed option classes or more flexible key value objects such as a Hash or plain JavaScript object. diff --git a/src/pages/docs/api/rest-api.mdx b/src/pages/docs/api/rest-api.mdx index 455091a272..7aa7f8f92c 100644 --- a/src/pages/docs/api/rest-api.mdx +++ b/src/pages/docs/api/rest-api.mdx @@ -1,47 +1,8 @@ --- title: REST API Reference +intro: "The Ably REST API provides a way for a wide range of server and client devices to communicate with the Ably service over REST." meta_description: "Ably provides the raw REST API for situations where an Ably client library SDK is not available on the platform of choice, or due to resource constraints." meta_keywords: "REST API, REST, protocol, resource constraints" -jump_to: - Intro: - - Common API behavior#common - Authentication: - - Authentication - - Basic Authentication - - Token Authentication - Channel API: - - publish - - message history#message-history - - get message#get-message - - update message#update-message - - delete message#delete-message - - message versions#message-versions - - presence - - presence history - Push API: - - register device#post-device-registration - - update a device registration#update-device-registration - - get registered device#get-device-registration - - list registered devices#list-device-registrations - - reset a device's update token#reset-update-token - - unregister device#delete-device-registration - - unregister devices#delete-device-registrations - - subscribe to a channel#post-channel-subscription - - unsubscribe from channels#delete-channel-subscription - - list channel subscriptions#list-channel-subscriptions - - list channels#list-channels - - publish directly to device#push-publish - - publish via batch push API#push-publish-batch - Authentication API: - - requestToken#request-token - - revokeTokens#revoke-tokens - Application API: - - stats - Batch API: - - batch publish#batch-publish - - batch presence#batch-presence - Utilities API: - - time redirect_from: - /docs/api/versions/v1.1/rest-api - /docs/api/versions/v1.0/rest-api @@ -54,9 +15,7 @@ redirect_from: - /docs/rest-api/versions/v1.1/beta --- -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 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 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. diff --git a/src/pages/docs/api/rest-sdk.mdx b/src/pages/docs/api/rest-sdk.mdx index 0967d0235c..550d2a48f1 100644 --- a/src/pages/docs/api/rest-sdk.mdx +++ b/src/pages/docs/api/rest-sdk.mdx @@ -1,5 +1,6 @@ --- title: Constructor +intro: "The REST interface of Ably SDKS provides a simple way to interact with the Ably service over standard HTTP methods. You can publish and retrieve messages, but you cannot subscribe to them." meta_description: "Client Library SDK REST API Reference constructor documentation." meta_keywords: "Ably, Ably REST, API Reference, REST SDK, REST interface, REST API, constructor" redirect_from: diff --git a/src/pages/docs/api/rest-sdk/authentication.mdx b/src/pages/docs/api/rest-sdk/authentication.mdx index 97023b4331..62bbe031b7 100644 --- a/src/pages/docs/api/rest-sdk/authentication.mdx +++ b/src/pages/docs/api/rest-sdk/authentication.mdx @@ -1,20 +1,8 @@ --- title: Authentication +intro: "Authenticate with Ably using API keys, JWTs, or tokens." meta_description: "Client Library SDK REST API Reference Authentication documentation." meta_keywords: "Ably, Ably REST, API Reference, REST SDK, REST interface, REST API, Authentication" -jump_to: - Help with: - - Tokens#tokens - - Auth object#auth-object - Auth API properties: - - clientId#client-id - Auth API methods: - - authorize - - createTokenRequest#create-token-request - - requestToken#request-token - - revokeTokens#revoke-tokens - Types: - - Related Types#related-types redirect_from: - /docs/api/versions/v1.1/rest-sdk/authentication - /docs/api/versions/v1.0/rest-sdk/authentication diff --git a/src/pages/docs/api/rest-sdk/channel-status.mdx b/src/pages/docs/api/rest-sdk/channel-status.mdx index e085e623b7..f91cbb7c29 100644 --- a/src/pages/docs/api/rest-sdk/channel-status.mdx +++ b/src/pages/docs/api/rest-sdk/channel-status.mdx @@ -1,14 +1,8 @@ --- title: Channel Status +intro: "Channel status provides information about the state and occupancy of channels." meta_description: "Client Library SDK REST API Reference Channel Status documentation." meta_keywords: "Ably, Ably REST, API Reference, REST SDK, REST interface, REST API, Channel Status" -section: api -index: 30 -jump_to: - Channel API Types: - - ChannelDetails#channel-details - - ChannelStatus#channel-status - - Occupancy#occupancy redirect_from: - /docs/api/versions/v1.1/rest-sdk/channel-status - /docs/api/versions/v1.0/rest-sdk/channel-status diff --git a/src/pages/docs/api/rest-sdk/channels.mdx b/src/pages/docs/api/rest-sdk/channels.mdx index f57747d395..baa82b4ef5 100644 --- a/src/pages/docs/api/rest-sdk/channels.mdx +++ b/src/pages/docs/api/rest-sdk/channels.mdx @@ -1,5 +1,6 @@ --- title: Channels +intro: "The Channels object and Channel objects are used to interact with Ably channels." meta_description: "Client Library SDK REST API Reference Channels documentation." meta_keywords: "Ably, Ably REST, API Reference, REST SDK, REST interface, REST API, Channels" redirect_from: diff --git a/src/pages/docs/api/rest-sdk/encryption.mdx b/src/pages/docs/api/rest-sdk/encryption.mdx index 98898c9828..b30e6f3ccc 100644 --- a/src/pages/docs/api/rest-sdk/encryption.mdx +++ b/src/pages/docs/api/rest-sdk/encryption.mdx @@ -1,14 +1,8 @@ --- title: Encryption +intro: "Use the Crypto object to encrypt and decrypt messages." meta_description: "Client Library SDK REST API Reference Crypto documentation." meta_keywords: "Ably, Ably REST, API Reference, REST SDK, REST interface, REST API, Encryption, Crypto" -jump_to: - API Reference: - - getDefaultParams#get-default-params - - generateRandomKey#generate-random-key - Related types: - - Channel Options - - CipherParams#cipher-params redirect_from: - /docs/api/versions/v1.1/rest-sdk/encryption - /docs/api/versions/v1.0/rest-sdk/encryption diff --git a/src/pages/docs/api/rest-sdk/history.mdx b/src/pages/docs/api/rest-sdk/history.mdx index 5fc8773130..0b8fcaba9a 100644 --- a/src/pages/docs/api/rest-sdk/history.mdx +++ b/src/pages/docs/api/rest-sdk/history.mdx @@ -1,13 +1,8 @@ --- title: History +intro: "Use the history method to retrieve previously sent messages and presence events from a channel." meta_description: "Client Library SDK REST API Reference History documentation." meta_keywords: "Ably, Ably REST, API Reference, REST SDK, REST interface, REST API, History" -jump_to: - API reference: - - Message history#channel-history - - Presence history#presence-history - Types: - - Related Types#related-types redirect_from: - /docs/api/versions/v1.1/rest-sdk/history - /docs/api/versions/v1.0/rest-sdk/history diff --git a/src/pages/docs/api/rest-sdk/messages.mdx b/src/pages/docs/api/rest-sdk/messages.mdx index 3312386224..e14c7ed46e 100644 --- a/src/pages/docs/api/rest-sdk/messages.mdx +++ b/src/pages/docs/api/rest-sdk/messages.mdx @@ -1,5 +1,6 @@ --- title: Messages +intro: "A Message represents an individual message that is sent to or received from Ably." meta_description: "Client Library SDK REST API Reference Message documentation." meta_keywords: "Ably, Ably REST, API Reference, REST SDK, REST interface, REST API, Message" redirect_from: @@ -8,8 +9,6 @@ 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 The event name, if provided.
_Type: `String`_ diff --git a/src/pages/docs/api/rest-sdk/presence.mdx b/src/pages/docs/api/rest-sdk/presence.mdx index 27114807d3..1ad182c8d4 100644 --- a/src/pages/docs/api/rest-sdk/presence.mdx +++ b/src/pages/docs/api/rest-sdk/presence.mdx @@ -1,13 +1,8 @@ --- title: Presence +intro: "Use the Presence object to retrieve information about the presence set of on Ably channel." meta_description: "Presence events provide clients with information about the status of other clients 'present' on a channel" meta_keywords: "Ably, presence, presence events, channel members, presence history." -jump_to: - Presence API reference: - - get - - history - Types: - - Related Types#related-types redirect_from: - /docs/api/versions/v1.1/rest-sdk/presence - /docs/api/versions/v1.0/rest-sdk/presence diff --git a/src/pages/docs/api/rest-sdk/push-admin.mdx b/src/pages/docs/api/rest-sdk/push-admin.mdx index 097fb57e21..c20bbfa0b1 100644 --- a/src/pages/docs/api/rest-sdk/push-admin.mdx +++ b/src/pages/docs/api/rest-sdk/push-admin.mdx @@ -1,15 +1,8 @@ --- title: Push Notifications - Admin +intro: "Use the Push.Admin object to manage push notifications, including device registrations and channel subscriptions." meta_description: "Client Library SDK REST API Reference Push documentation." meta_keywords: "Ably, Ably REST, API Reference, REST SDK, REST interface, REST API, Push" -jump_to: - Push Admin API properties: - - deviceRegistrations#device-registrations - - channelSubscriptions#channel-subscriptions - Push Admin API methods: - - publish - Types: - - Related Types#related-types redirect_from: - /docs/api/rest-sdk/push - /docs/api/versions/v1.1/rest-sdk/push-admin diff --git a/src/pages/docs/api/rest-sdk/statistics.mdx b/src/pages/docs/api/rest-sdk/statistics.mdx index 31379c5c57..5e0b64582a 100644 --- a/src/pages/docs/api/rest-sdk/statistics.mdx +++ b/src/pages/docs/api/rest-sdk/statistics.mdx @@ -1,5 +1,6 @@ --- title: Statistics +intro: "Use the stats method to retrieve your application's usage statistics." meta_description: "Client Library SDK REST API Reference Statistics documentation." meta_keywords: "Ably, Ably REST, API Reference, REST SDK, REST interface, REST API, Statistics" redirect_from: diff --git a/src/pages/docs/api/rest-sdk/types.mdx b/src/pages/docs/api/rest-sdk/types.mdx index 0f7a7b0e5d..5ba37ea3bf 100644 --- a/src/pages/docs/api/rest-sdk/types.mdx +++ b/src/pages/docs/api/rest-sdk/types.mdx @@ -1,5 +1,6 @@ --- title: Types +intro: "Ably SDKs define both data types and option types. Data types are used to represent object such as messages. Option types are used in method arguments." meta_description: "Client Library SDK REST API Reference Types documentation." meta_keywords: "Ably, Ably REST, API Reference, REST SDK, REST interface, REST API, Types" redirect_from: @@ -9,9 +10,7 @@ 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. +Where SDKs support both Realtime and REST interfaces, types are shared between both clients. All types are always classes or their respective equivalent for each language implementation. Options on the other hand, may often support both typed option classes or more flexible key value objects such as a Hash or plain JavaScript object. diff --git a/src/pages/docs/api/sse.mdx b/src/pages/docs/api/sse.mdx index 7ab31c7bb3..b5ed141f3c 100644 --- a/src/pages/docs/api/sse.mdx +++ b/src/pages/docs/api/sse.mdx @@ -1,11 +1,8 @@ --- title: SSE and Raw HTTP Streaming API +intro: "Use Server-Sent Events (SSE) to stream messages from Ably to browser clients that don't need the support or resources of a full Ably SDK." meta_description: "Ably provides support for Server-Sent Events (SSE). This is useful for where browser clients support SSE, and the use case does not require or support the resources used by the Ably client library SDK." meta_keywords: "Server-Sent Events, SSE, browser clients" -jump_to: - API Routes: - - Server-sent events#sse - - Plain event stream#event-stream redirect_from: - /docs/api/versions/v1.1/sse ---