From 7221fe9a90b25c0d26beacf151d1053dfc996643 Mon Sep 17 00:00:00 2001 From: umair Date: Wed, 7 Jan 2026 12:00:03 +0000 Subject: [PATCH] Adds a Product guidance page which details which products and/or interfaces we'd expect our users to use for their usecase --- src/data/nav/platform.ts | 5 + src/pages/docs/platform/index.mdx | 4 + src/pages/docs/platform/products/index.mdx | 307 +++++++++++++++++++++ 3 files changed, 316 insertions(+) create mode 100644 src/pages/docs/platform/products/index.mdx diff --git a/src/data/nav/platform.ts b/src/data/nav/platform.ts index 2630e7b854..466a2c751e 100644 --- a/src/data/nav/platform.ts +++ b/src/data/nav/platform.ts @@ -62,6 +62,11 @@ export default { { name: 'Products and SDKs', pages: [ + { + name: 'Product guidance', + link: '/docs/platform/products', + index: true, + }, { name: 'SDKs', link: '/docs/sdks', diff --git a/src/pages/docs/platform/index.mdx b/src/pages/docs/platform/index.mdx index 4bd9a44f96..bc7ab24408 100644 --- a/src/pages/docs/platform/index.mdx +++ b/src/pages/docs/platform/index.mdx @@ -114,3 +114,7 @@ LiveObjects is effective for use cases such as realtime voting and polling syste Use Ably [LiveSync](/docs/livesync) to synchronize changes between your database and frontend clients. It provides support for PostgreSQL and MongoDB and uses the Ably platform to synchronize your application's data. LiveSync automatically streams changes you make in your database to clients to keep them in sync with the source of truth in your database. + +## Next steps + +* For guidance on choosing between Ably's interfaces and products, see [Product guidance](/docs/platform/products). diff --git a/src/pages/docs/platform/products/index.mdx b/src/pages/docs/platform/products/index.mdx new file mode 100644 index 0000000000..f76fed590c --- /dev/null +++ b/src/pages/docs/platform/products/index.mdx @@ -0,0 +1,307 @@ +--- +title: Product guidance +meta_description: "Choose the right Ably interface and SDK for your use case. Compare REST vs Realtime, purpose-built SDKs, and protocol adapters." +meta_keywords: "Ably SDK, REST API, Realtime, Chat SDK, Spaces SDK, LiveObjects, LiveSync, Pub/Sub, protocol adapters" +--- + +Ably provides multiple interfaces and SDKs to suit different use cases, platforms, and requirements. This guide helps you choose the right approach for your application. + +## Overview + +When building with Ably, you need to make several decisions: + +1. **Which product**: Pub/Sub, Chat SDK, Spaces SDK, or LiveSync +2. **Which features**: LiveObjects for synchronized state, channel rules for per-namespace configuration +3. **Which interface**: REST, Realtime, or protocol adapters + +The right choice depends on your application's requirements for latency, connection persistence, and the complexity of the features you're building. These choices also have [pricing implications](/docs/platform/pricing), as different interfaces and connection patterns affect how your usage is metered. + +## Purpose-built SDKs vs Pub/Sub + +Ably provides purpose-built SDKs that abstract away the complexity of building common realtime features. These SDKs are built on top of Pub/Sub and benefit from all the same platform guarantees. + +### Pub/Sub + +[Pub/Sub](/docs/basics) is Ably's core product. It provides flexible, low-level APIs for publishing and subscribing to messages on channels. Use Pub/Sub when you need full control over your message architecture or are building custom realtime features. + +Use Pub/Sub when: + +* You need maximum flexibility in message structure and channel design +* You're building custom realtime features not covered by purpose-built SDKs +* You need to integrate with existing backend systems + +With Pub/Sub, you can use [channel rules](/docs/channels#rules) to configure namespace-specific settings such as message persistence, client identification requirements, and push notification enablement. + +### Chat SDK + +[Ably Chat](/docs/chat) provides purpose-built APIs for building chat functionality. It handles the complexities of architecting chat features so you don't have to. + +Use the Chat SDK when you're building: + +* 1:1 customer support chat +* Group conversations +* Livestream chat with thousands of users +* Any application requiring rooms, messages, typing indicators, reactions, or presence + +The Chat SDK provides: + +| Feature | Description | +| ------- | ----------- | +| [Rooms](/docs/chat/rooms) | Organize users and messages into chat rooms | +| [Messages](/docs/chat/rooms/messages) | Send and receive messages within rooms | +| [Presence](/docs/chat/rooms/presence) | Display who is currently online in a room | +| [Occupancy](/docs/chat/rooms/occupancy) | Track the number of users connected to a room | +| [Typing indicators](/docs/chat/rooms/typing) | Show when users are typing | +| [Message reactions](/docs/chat/rooms/reactions) | Enable reactions to specific messages | +| [Room reactions](/docs/chat/rooms/room-reactions) | Broadcast ephemeral sentiments to a room | +| [Moderation](/docs/chat/moderation) | Detect and manage inappropriate content | + +### Spaces SDK + +[Ably Spaces](/docs/spaces) provides high-level APIs for building collaborative environments where users work together in realtime. + +Use the Spaces SDK when you're building: + +* Interactive whiteboards with live cursors +* Collaborative document editing +* Avatar stacks showing online users +* Applications with component locking to prevent edit conflicts + +The Spaces SDK is optimized for participant state, which is largely ephemeral and doesn't need to be stored. This is distinct from application state, which must be validated and stored in your database. + +The Spaces SDK provides: + +| Feature | Description | +| ------- | ----------- | +| [Space](/docs/spaces/space) | Virtual area for realtime collaboration | +| [Avatar stack](/docs/spaces/avatar) | Show online status of users | +| [Member locations](/docs/spaces/locations) | Track where users are in your application | +| [Live cursors](/docs/spaces/cursors) | Display cursor positions in realtime | +| [Component locking](/docs/spaces/locking) | Optimistically lock UI components before editing | + +### LiveObjects + +[Ably LiveObjects](/docs/liveobjects) provides the ability to associate durable state with a channel. Participants can use and modify that state concurrently, with conflicts resolved automatically, and clients can use that state to hydrate. + +Use LiveObjects to manage state when: + +* The state is more naturally represented as a structured collection of objects and/or primitive values +* Your application needs a way to structure and manage the state explicitly + +LiveObjects provides: + +| Feature | Description | +| ------- | ----------- | +| [LiveCounter](/docs/liveobjects/counter) | Synchronized numerical counters | +| [LiveMap](/docs/liveobjects/map) | Synchronized key-value stores | +| [Batch operations](/docs/liveobjects/batch) | Atomic updates across multiple objects | + +Pub/Sub channels, without LiveObjects, can also be used as a durable store of channel state, and for client hydration, but in this case the state is simply the content of messages sent on the channel. See [history](/docs/storage-history/history) and [rewind](/docs/channels/options/rewind) for further discussion of how this pattern applies. + +### LiveSync + +[Ably LiveSync](/docs/livesync) synchronizes your database state to frontend clients in realtime, whilst having only a single write path. + +Use LiveSync when: + +* Your database is the source of truth for application state +* You need to reflect database changes to clients in realtime +* You want to enable optimistic updates in the UI +* You're using PostgreSQL or MongoDB + +### Why use purpose-built SDKs + +Purpose-built SDKs provide an API optimized for specific use cases: + +* Additional use-case-specific functionality beyond raw Pub/Sub +* A more targeted and opinionated API that's a natural fit for the application +* Non-default channel behavior applied as appropriate for the use case (such as enabling persistence) +* Developer guides tailored to the use case +* Simplified design decisions, reducing friction and helping you succeed as easily as possible + +## REST vs Realtime interface + +Ably SDKs contain both a REST and a Realtime interface. Each serves different use cases. + +### REST interface + +The REST interface communicates with Ably using HTTP and is effectively stateless. It does not maintain a persistent connection to Ably. + +Use the REST interface when you need to: + +* Publish messages from a server without receiving updates +* Issue tokens on behalf of other clients +* Retrieve message history, presence history, or application statistics +* Perform occasional, request-response style operations +* Minimize resource usage in environments where persistent connections are impractical + +The REST interface is more commonly used server-side. It is more efficient if you don't need to establish a persistent connection to Ably, such as when you have a server publishing messages to channels that doesn't need to receive any updates from them. + +### Serverless and cloud functions + +Use the REST interface when publishing from serverless environments such as AWS Lambda, Google Cloud Functions, Azure Functions, or Cloudflare Workers. These environments are designed for short-lived, stateless execution and do not support persistent WebSocket connections. + +The REST interface is also the appropriate choice when handling [inbound webhooks](/docs/platform/integrations/inbound/webhooks) from Ably. Your webhook handler receives event data via HTTP and can publish responses or trigger actions using the REST interface. + +### Realtime interface + +The Realtime interface uses an Ably-defined protocol, primarily over WebSockets, to establish and maintain a persistent connection to Ably. The Realtime interface extends the functionality of the REST interface. + +Use the Realtime interface when you need to: + +* Subscribe to messages in realtime +* Maintain a persistent connection to Ably +* Attach to one or more channels and publish and subscribe to messages +* Register presence on a channel, or listen for others present in realtime +* Publish at very high message rates, or with the lowest possible latencies +* Benefit from automatic reconnection and connection state recovery + +The Realtime interface is most commonly used client-side. Subscribing to messages is only available through the Realtime interface because it requires establishing a persistent connection to Ably in order to receive messages in realtime. + +### Comparison + +| Aspect | REST interface | Realtime interface | +| ------ | -------------- | ------------------ | +| Protocol | HTTP | WebSockets (primarily) | +| Connection | Stateless, no persistent connection | Persistent, maintained connection | +| Subscribing | Not supported | Supported | +| Publishing | Supported | Supported | +| Presence | History retrieval only | Full realtime presence | +| Latency | Higher (request-response) | Lower (persistent connection) | +| Resource usage | Lower | Higher | +| Cost | Lower (per-request) | Higher (connection + channel minutes) | +| Typical use | Server-side | Client-side | +| Connection recovery | Not applicable | Automatic | + +### REST HTTP API vs SDK REST interface + +Ably provides a [REST HTTP API](/docs/api/rest-api) that you can use directly without an SDK. + +Use the REST interface of an Ably SDK when: + +* You want automatic re-routing around network problems via alternative datacenters and other resilience features +* You prefer a language-idiomatic API + +Use the REST HTTP API directly when: + +* No Ably SDK is available for your platform +* You want to avoid having any third-party SDK in your app or SDK + +Ably recommends using SDK REST interfaces where possible. SDKs provide additional features that improve performance and resilience that the REST HTTP API cannot deliver on its own, such as automatic re-routing around network problems by using alternative datacenters. + +## Protocol adapters + +[Ably SDKs](/docs/sdks) are the recommended method for connecting to Ably. They provide comprehensive feature support including automatic connection management, authentication token renewal, and APIs for the full range of Ably functionality. + +[Protocol adapters](/docs/protocols) offer an alternative for specific scenarios where SDKs are impractical. + +### When to use SDKs + +Use an Ably SDK when: + +* An SDK is available for your platform +* You need the full set of Ably features +* You want automatic connection recovery and token renewal +* You're building a production application + +### When to use protocol adapters + +Consider protocol adapters when: + +* There is no Ably SDK available for your platform (such as embedded or IoT devices) +* You are migrating from another messaging service (such as Pusher or PubNub) and want to minimise the cost and risk of transition +* You want to avoid including any third-party SDK in your own application or SDK (such as for footprint reasons), and are able to use a subset of features that's supportable without an Ably SDK + +Available protocol adapters: + +| Protocol | Best for | +| -------- | -------- | +| [MQTT](/docs/protocols/mqtt) | IoT devices, constrained environments | +| [SSE](/docs/protocols/sse) | Subscribe-only clients, browser streaming | +| [Pusher Adapter](/docs/protocols/pusher) | Migration from Pusher | +| [PubNub Adapter](/docs/protocols/pubnub) | Migration from PubNub | + +Protocol adapters do not support the full set of Ably features. For example, the MQTT protocol adapter does not support presence, and the SSE protocol does not support message publishing. + +## Combining SDKs with Pub/Sub + +Purpose-built SDKs like Chat and Spaces are built on top of the Ably Pub/Sub SDK. When using a purpose-built SDK, you can also use Pub/Sub features directly over a shared connection. Do not share the use of specific channels with the purpose-built SDK, but share the connection. + +### Accessing the underlying Realtime client + +The Chat and Spaces SDKs expose the underlying Ably Realtime client that powers them. This client is the same one you would use directly with Pub/Sub, giving you access to all of its functionality. + +There are several benefits to this architecture: + +* [Authentication](/docs/auth) and [connection management](/docs/connect) are handled by the underlying SDK +* You maintain a single connection to Ably rather than multiple connections +* You can extend your application's functionality with custom Pub/Sub features alongside the purpose-built SDK + +### When to combine SDKs + +Combine a purpose-built SDK with Pub/Sub when: + +* The SDK covers most of your requirements but lacks a specific feature +* You need to build custom functionality that integrates with SDK-managed features +* You want to publish or subscribe to custom channels alongside SDK-managed channels + +### Example use cases + +The following are examples where combining the Chat SDK with Pub/Sub is effective: + +| Feature | Approach | +| ------- | -------- | +| File attachments | Use Chat SDK for messages, Pub/Sub for file upload notifications and metadata | +| Custom notifications | Use Chat SDK for conversations, Pub/Sub channels for system-wide alerts | +| Read receipts | Use Chat SDK for messaging, Pub/Sub for custom read receipt events | +| Integrations | Use Chat SDK for user-facing chat, Pub/Sub to publish events to backend services | + +### How it works in practice + +When you initialize a Chat or Spaces client, it creates or accepts an underlying Ably Realtime client. You can use this client directly to: + +* Attach to custom channels outside of SDK-managed rooms or spaces +* Publish messages with custom event types +* Subscribe to channels for features the SDK doesn't provide +* Access presence on channels not managed by the SDK + +This approach lets you start with a purpose-built SDK for rapid development, then extend with Pub/Sub only where needed. You avoid rebuilding features that the SDK already handles well, while retaining the flexibility to customize your application. + +### Best practices + +When combining SDKs with Pub/Sub: + +* **Use consistent authentication**: Let the purpose-built SDK manage authentication and share its Realtime client rather than creating separate clients +* **Avoid duplicating SDK features**: If the Chat SDK provides typing indicators, use them rather than building your own on Pub/Sub +* **Namespace your custom channels**: Use a clear naming convention to distinguish custom Pub/Sub channels from SDK-managed channels +* **Consider message ordering**: Messages on SDK-managed channels and custom Pub/Sub channels are independent; design your application accordingly +* **Handle connection state once**: The underlying Realtime client manages connection state; don't add redundant connection handling for custom features + +## Quick reference + +Use this table to quickly identify the right product or interface for common scenarios: + +| Scenario | Recommended approach | +| -------- | -------------------- | +| Building chat functionality | Chat SDK | +| Collaborative features (cursors, avatars, locking) | Spaces SDK | +| Synchronized shared state (counters, maps) | LiveObjects | +| Database-to-client synchronization | LiveSync | +| Custom realtime features | Pub/Sub with Realtime interface | +| Server publishing events | Pub/Sub with REST interface | +| Receiving live updates | Pub/Sub with Realtime interface | +| Issuing authentication tokens | REST interface | +| Cloud function publishing events | Pub/Sub with REST interface | +| Server handling Ably webhooks | Pub/Sub with REST interface | +| No SDK available for platform | Protocol adapters or REST HTTP API | +| Migrating from Pusher or PubNub | Protocol adapters | + +## Next steps + +* Read about [Pub/Sub](/docs/basics) to understand Ably's core functionality +* Explore the [Chat SDK](/docs/chat) for building chat features +* Learn about [Spaces](/docs/spaces) for collaborative applications +* Discover [LiveObjects](/docs/liveobjects) for synchronized shared state +* Set up [LiveSync](/docs/livesync) for database-to-client synchronization +* Understand [authentication](/docs/auth) before going to production +* Review [connection management](/docs/connect) for the Realtime interface