USPs for Pub/Sub

src/components/blocks/dividers/Aside.tsx

@@ -1,4 +1,5 @@
 import Icon from '@ably/ui/core/Icon';
+import * as styles from './dividers.module.css';
 import {
   inlineGridParagraph,
   inlineContentContainer,

src/pages/docs/channels/options/deltas.mdx

@@ -33,6 +33,10 @@ There is no constraint on how many publishers or subscribers there are. If there
 
 If a delta is generated and it results in a difference that is not appreciably smaller than the original message, or is larger than the original message, for example if successive messages are completely different, then the delta will not be sent. Clients will receive the original, unprocessed message.
 
+<Aside data-type='see-evidence'>
+Deltas rely on consistent message ordering. Messages published using Realtime from a single publisher are delivered to all subscribers in the same order, with each message assigned a unique serial number. [See evidence here 🕵️](/docs/platform/architecture/message-ordering#message-ordering-guarantees).
+</Aside>
+
 <If lang="javascript,nodejs">
 ## Install vcdiff decoder <a id="vcdiff"/>
 

src/pages/docs/chat/connect.mdx

@@ -20,6 +20,12 @@ A connection can have any of the following statuses:
 | `closed` | The connection has been explicitly closed by the client. In the closed state, no reconnection attempts are made automatically. No connection state is preserved by the service or the library. |
 | `failed` | This status is entered if the SDK encounters a failure condition that it cannot recover from. This may be a fatal connection error received from the Ably service, such as an attempt to connect with an incorrect API key, or some local terminal error, such as that the token in use has expired and the SDK does not have any way to renew it. |
 
+<Aside data-type="usp">
+Keep users connected through infrastructure issues.
+
+Ably's SDKs automatically resolve edge network failures within 30 seconds, keeping your users connected even during infrastructure issues. [See evidence](/docs/platform/architecture/edge-network)
+</Aside>
+
 <If lang="javascript,swift,kotlin,jetpack">
 Use the <If lang="javascript">[`status`](https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Connection.html#status)</If><If lang="swift">[`status`](https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/connectionstatus)</If><If lang="kotlin,jetpack">[`status`](https://sdk.ably.com/builds/ably/ably-chat-kotlin/main/dokka/chat/com.ably.chat/-connection/status.html)</If> property to check which status a connection is currently in:
 </If>

src/pages/docs/chat/rooms/message-reactions.mdx

@@ -394,6 +394,12 @@ fun RemoveMessageReactionComponent(room: Room, message: Message) {
 ```
 </Code>
 
+<Aside data-type="usp">
+Maintain application state through disruptions.
+
+Applications maintain their state during disruptions. All messages are received in correct order with no message loss. [See evidence](/docs/platform/architecture/connection-recovery#message-identification-with-timeserial)
+</Aside>
+
 ## Messages and reactions <a id="messages-and-reactions"/>
 
 The `Message` object contains a `reactions` property which is an object that looks like this:

src/pages/docs/chat/rooms/messages.mdx

@@ -120,6 +120,12 @@ The following are the properties of a message:
 
 See [below](#global-ordering) for more information on how to apply deterministic global ordering to the chat messages in your application.
 
+<Aside data-type="usp">
+Eliminate race conditions and conflicts.
+
+Messages are delivered to all subscribers in the same order, with each message assigned a unique serial number that enables consistent ordering. [See evidence](/docs/platform/architecture/message-ordering#message-ordering-guarantees)
+</Aside>
+
 ### Unsubscribe from messages <a id="unsubscribe"/>
 
 <If lang="javascript,kotlin">

src/pages/docs/chat/rooms/presence.mdx

@@ -529,6 +529,11 @@ val isPresent = room.presence.isUserPresent("client-id")
 Use the [`presenceData`](https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-react.UsePresenceListener.html#presenceData) property available from the response of the `usePresence` hook to view a list of all member's presence status in the room.
 </If>
 
+<Aside data-type="usp">
+Never lose messages during network disruptions.
+
+Ably automatically recovers connections and prevents message loss or duplication when clients reconnect within two minutes. [See evidence](/docs/platform/architecture/idempotency#connection-recovery-and-exactly-once-delivery)
+</Aside>
 
 ### Presence member structure <a id="member-structure"/>
 

src/pages/docs/chat/rooms/reactions.mdx

@@ -215,3 +215,8 @@ fun SendReactionComponent(room: Room) {
 ```
 </Code>
 
+<Aside data-type="usp">
+Ultra-low latency message delivery.
+
+Ably achieves a global median message delivery latency of 37ms, continuously monitored through over 6 million measurements daily across all regions. [See evidence](/docs/platform/architecture/latency#how-latency-is-measured)
+</Aside>

src/pages/docs/chat/rooms/replies.mdx

@@ -136,6 +136,12 @@ fun SendReplyComponent(room: Room, messageToReplyTo: Message) {
 ```
 </Code>
 
+<Aside data-type="usp">
+Maintain application state through disruptions.
+
+Applications maintain their state during disruptions. All messages are received in correct order with no message loss. [See evidence](/docs/platform/architecture/connection-recovery#message-identification-with-timeserial)
+</Aside>
+
 ## Subscribe to message replies <a id="subscribe"/>
 
 Message replies will be received as normal messages in the room using the [`subscribe()`](/docs/chat/rooms/messages#subscribe) method.

src/pages/docs/chat/rooms/typing.mdx

@@ -107,6 +107,12 @@ The following are the properties of a typing event:
 
 You can use the size of the `currentlyTyping` set to decide whether to display individual user names, or that multiple people are typing in your user interface.
 
+<Aside data-type="usp">
+Ultra-low latency message delivery.
+
+Ably achieves a global median message delivery latency of 37ms, continuously monitored through over 6 million measurements daily across all regions. [See evidence](/docs/platform/architecture/latency#how-latency-is-measured)
+</Aside>
+
 ### Unsubscribe from typing events <a id="unsubscribe"/>
 
 <If lang="javascript,kotlin">

src/pages/docs/chat/setup.mdx

@@ -330,3 +330,4 @@ The `logLevel` sets the verbosity of logs that will be output by the SDK. The fo
 | `error` | A given operation has failed and cannot be automatically recovered. The error may threaten the continuity of operation. |
 | `silent` | No logging will be performed. |
 
+

src/pages/docs/connect/index.mdx

@@ -151,6 +151,10 @@ A connection ID is a unique identifier given to a connection, allowing for ident
 
 An active connection ID is guaranteed to be unique in the Ably system whilst it is active, i.e. no other connection will share that connection ID. However, Ably reserves the right to generate a new connection ID later that may be the same as a previously discarded connection ID (once the connection is closed). Therefore customers are advised to not use the connection ID as a perpetual unique identifier as it is possible that a connection ID may be used many times.
 
+<Aside data-type='see-evidence'>
+Ably automatically recovers connections and prevents message loss or duplication when clients reconnect within two minutes. [See evidence here 🕵️](/docs/platform/architecture/idempotency#connection-recovery-and-exactly-once-delivery)
+</Aside>
+
 ### Connection metachannels <a id="metachannels"/>
 
 [Metachannels](/docs/metadata-stats/metadata/subscribe) are a namespace of channels beginning with the [meta] qualifier, distinguishing them from regular channels. For connections there is a specific `[meta]connection.lifecycle` channel that publishes messages about the lifecycle of realtime connections. The connection lifecycle consists of a number of [connection states](/docs/connect/states#available-connection-states) that can be observed and interacted with using methods available on the connection object.
@@ -222,6 +226,10 @@ By default, the Ably Pub/Sub JavaScript SDK adds a listener for the `beforeunloa
 
 If a connection to Ably is not explicitly closed when there is a page unload event, then the connection state is preserved by Ably for 2 minutes. Preserving connection state for 2 minutes when there is an unexpectedly dropped connection provides the opportunity for the client to reconnect and resume the connection without losing any messages.
 
+<Aside data-type='see-evidence'>
+Ably's SDKs automatically resolve edge network failures within 30 seconds, keeping your users connected even during infrastructure issues. [See evidence here 🕵️](/docs/platform/architecture/edge-network)
+</Aside>
+
 ### Reliability considerations
 The `beforeunload` event can be unreliable and is not guaranteed to fire under certain circumstances:
 * The event may fire but the page is subsequently not disposed of (navigation can be cancelled).

src/pages/docs/connect/states.mdx

@@ -15,6 +15,10 @@ An Ably SDK is responsible for managing a connection. This includes:
 
 When an SDK is instantiated it will establish a connection immediately, and if the connection drops at any time it will attempt to re-establish it by making repeated connection attempts every 15 seconds for up to two minutes.
 
+<Aside data-type='see-evidence'>
+Failed connections automatically try up to 5 alternative endpoints worldwide, maximizing reconnection success. [See evidence here 🕵️](/docs/platform/architecture/edge-network#protocol-level-resilience)
+</Aside>
+
 ## Available connection states <a id="connection-states"/>
 
 The different connection states are:

src/pages/docs/guides/chat/build-livestream.mdx

@@ -25,6 +25,12 @@ Delivering chat messages in realtime is key to an engaging experience. Ably's [s
 
 Despite the challenges of delivering these guarantees, Ably is designed to keep costs predictable. Using features such as server-side batching and efficient connection management, along with Ably's consumption-based pricing model ensures costs are kept as low as possible, no matter the scale.
 
+<Aside data-type="usp">
+Proven scale across global infrastructure.
+
+Ably delivers over 500 billion messages monthly, demonstrating massive throughput capability. [See evidence](/docs/platform/architecture/scalability)
+</Aside>
+
 ## Architecting your chat rooms: UX first, scale always
 
 The most important decision you can make when developing a livestream chat application is the experience you want users to have. This will determine the look and feel of the livestream and ultimately the impression your users leave with.
@@ -69,6 +75,12 @@ Decisions that you need to make around throughput and rates:
   * For a large room chat scenario, we recommend a batching interval of **no more than 1 second**, which keeps the chat responsive but can still [significantly reduce costs](#server-side-batching).
   * For smaller groups and 1:1 chats, you may find that batching does not make a material difference to costs, but does affect the latency of the chat. In the rooms handling those chats, you may choose to not use batching.
 
+<Aside data-type="usp">
+Handle viral moments without breaking.
+
+With 50% capacity headroom built in, Ably instantly absorbs traffic spikes without degradation or pre-provisioning. [See evidence](/docs/platform/architecture/infrastructure-operations#resource-implications)
+</Aside>
+
 ## Authentication
 
 Authentication in livestream chat is a design decision. In some cases, you'll want to tie participants to their identity in your application. In others, anyone can join and participate. Ably Chat supports both of these scenarios - you don't need to go through the hassle of setting up users in Ably and trying to keep them in sync with your application. Every client has a `clientId`. If you want to allow random users, just use a random string. If you want to tie it to your application, then use the UUID of the user or some other well-known identifier.

src/pages/docs/messages/index.mdx

@@ -44,6 +44,10 @@ Ensure a message was successfully published by checking the [history](/docs/stor
 
 Ably does not store per-message delivery logs, nor logs of who is subscribed to a channel at any point in time. This means it is not possible to check which users have received messages retroactively.
 
+<Aside data-type='see-evidence'>
+Applications maintain their state during disruptions. All messages are received in correct order with no message loss. [See evidence here 🕵️](/docs/platform/architecture/connection-recovery#message-identification-with-timeserial)
+</Aside>
+
 ## Message conflation <a id="conflation"/>
 
 Use message conflation to ensure that clients only ever receive the most up-to-date message, by removing redundant and outdated messages. Message conflation will aggregate published messages for a set period of time and evaluate all messages against a [conflation key](#routing). All but the latest message for each conflation key value will be discarded, and the resulting message, or messages, will be delivered to subscribers as a single batch once the period of time elapses.

src/pages/docs/metadata-stats/metadata/subscribe.mdx

@@ -149,6 +149,10 @@ channel.subscribe("channel.closed", new Channel.MessageListener() {
 ```
 </Code>
 
+<Aside data-type='see-evidence'>
+Auto Scaling Groups in each region scale independently according to demand, automatically maintaining sufficient capacity to handle traffic peaks. [See evidence here 🕵️](/docs/platform/architecture/infrastructure-operations#multi-region-deployment)
+</Aside>
+
 ## Log events <a id="log"/>
 
 The `[meta]log` and [`[meta]log:push`](/docs/push#Error) metachannels publish events that aren't otherwise available to clients.

src/pages/docs/metadata-stats/stats.mdx

@@ -23,6 +23,10 @@ Statistics are available as:
 * [Account statistics](#account) covering all applications in your account
 * [App statistics](#app) for each individual application
 
+<Aside data-type='see-evidence'>
+Ably delivers over 500 billion messages monthly, demonstrating large throughput capability. [See evidence here 🕵️](/docs/platform/architecture/platform-scalability#monitoring-and-auto-scaling)
+</Aside>
+
 ## Account statistics <a id="account"/>
 
 Account statistics aggregate metrics from all applications in your account with additional [account-only metrics](#account-only) relating to peak rates monitored and enforced at an account level.

src/pages/docs/presence-occupancy/index.mdx

@@ -14,3 +14,7 @@ Presence is a feature that tracks the membership of a presence set for a channel
 Occupancy provides metrics for a channel. It is a feature that counts how many of a thing are attached to a channel, such as the number of connections. It does not provide any information that can identify individual connections or clients attached to the channel.
 
 Take a chat application containing multiple chat rooms as an example. Occupancy would be a more lightweight method for displaying the popularity of rooms, by displaying the number of connections to each channel. Presence could be utilized in each channel to indicate which users are online, and to notify other members when someone leaves the room.
+
+<Aside data-type='see-evidence'>
+Ably monitors resource headroom and triggers automatic scaling when load approaches capacity, absorbing traffic spikes without degradation. [See evidence here 🕵️](/docs/platform/architecture/platform-scalability#monitoring-and-auto-scaling)
+</Aside>

src/pages/docs/presence-occupancy/occupancy.mdx

@@ -8,6 +8,10 @@ redirect_from:
 
 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.
 
+<Aside data-type='see-evidence'>
+Whether there are many lightly-loaded channels or fewer heavily-loaded ones, scaling and placement strategies ensure capacity is added as required and load is effectively distributed. [See evidence here 🕵️](/docs/platform/architecture/platform-scalability#how-ably-achieves-scalability)
+</Aside>
+
 ## Occupancy metric categories <a id="occupancy-metrics"/>
 
 The following are the metric categories that occupancy reports:

src/pages/docs/presence-occupancy/presence.mdx

@@ -35,6 +35,10 @@ The following presence events are emitted:
 | Update | An already present member has updated their [member data](#member-data). Being notified of member data updates can be useful, for example, it can be used to update the status of a user when they are typing a message |
 | Present | When subscribing to presence events on a channel that already has members present, this event is emitted for every member already present on the channel before the subscribe listener was registered |
 
+<Aside data-type='see-evidence'>
+If clients can't connect to primary endpoints, Ably SDKs automatically attempt alternative fallback endpoints, including a completely segregated secondary domain with a different DNS provider. [See evidence here 🕵️](/docs/platform/architecture/edge-network#fallback-endpoints-and-secondary-domains)
+</Aside>
+
 ### Member data <a id="member-data"/>
 
 In addition to the [`clientId`](/docs/api/realtime-sdk#client-id) for members on a channel, it is also possible to include data when entering a channel. Clients can [update](/docs/api/realtime-sdk/presence#update) their data at any point which will be broadcasted to all presence subscribers as an `update` event.

src/pages/docs/protocols/index.mdx

@@ -19,6 +19,10 @@ Migration times typically range from a few hours (using protocol adapters) to a
 
 A full list of Ably SDKs can be found on the [SDK page](/docs/sdks).
 
+<Aside data-type='see-evidence'>
+Direct site-to-site distribution means that messages are delivered to all subscribers in the minimum time. [See evidence here 🕵️](/docs/platform/architecture/message-ordering#multi-region-message-distribution)
+</Aside>
+
 ## Available Protocol Adapters <a id="available-adapters"/>
 
 Ably supports multiple protocols in addition to the native WebSockets-based one:

src/pages/docs/protocols/mqtt.mdx

@@ -35,6 +35,10 @@ Our MQTT adapter only supports features supported by both the MQTT protocol and
 * Doesn't support any MQTT features that aren't normally supported by Ably, such as `WILL` messages, the `RETAIN` flag or [wildcard channel subscriptions](/docs/channels)
 * Doesn't support Ably features that aren't supported by the MQTT protocol, such as presence, history and push notifications, though you can use the Ably REST API in conjunction with the adapter to access features available over REST
 
+<Aside data-type='see-evidence'>
+Within a single region, all MQTT subscribers will observe messages in the same order, ensuring consistent experiences for users in that region. [See evidence here 🕵️](/docs/platform/architecture/message-ordering#practical-implications-of-dual-ordering)
+</Aside>
+
 ## Configuration <a id="config"/>
 
 To use the Ably MQTT protocol adapter, you'll need to ensure you correctly configure your MQTT client as follows:

src/pages/docs/protocols/pubnub.mdx

@@ -16,6 +16,10 @@ You can use PuBNub and and an Ably SDK side-by-side as they are interoperable, w
 
 For a detailed comparison of Ably and PubNub features, see [Ably vs PubNub](https://ably.com/compare/ably-vs-pubnub).
 
+<Aside data-type='see-evidence'>
+Ably achieves a global median message delivery latency of 37ms, continuously monitored through over 6 million measurements daily across all regions. [See evidence here 🕵️](/docs/platform/architecture/latency#how-latency-is-measured)
+</Aside>
+
 ## Migration process <a id="migration-process"/>
 
 A typical migration from PubNub to Ably follows these steps:

src/pages/docs/protocols/pusher.mdx

@@ -11,6 +11,10 @@ Using an adapter introduces some latency and is slower than using an Ably SDK, h
 
 The Pusher Adapter provides some of the advantages of Ably, such as inter-regional message federation, however others, such as [continuity guarantees](https://ably.com/four-pillars-of-dependability), fallback host support, and [message history](/docs/storage-history/history) are only available when using an Ably SDK. If an [Ably SDK](/docs/sdks) is available in your chosen platform, it is recommended you use that, or plan to transition to it eventually.
 
+<Aside data-type='see-evidence'>
+Ably achieves a global median message delivery latency of 37ms, continuously monitored through over 6 million measurements daily across all regions. [See evidence here 🕵️](/docs/platform/architecture/latency#how-latency-is-measured)
+</Aside>
+
 ## Supported features <a id="features"/>
 
 The following Pusher features are supported using the adapter: