From 5af23cf72255cc0dfd374aeaf3fdef696075d9eb Mon Sep 17 00:00:00 2001 From: Lawrence Forooghian Date: Thu, 14 Aug 2025 10:52:12 +0100 Subject: [PATCH 1/3] Introduce per-language quickstarts for LiveObjects I'll be adding Swift documentation for LiveObjects shortly, thus giving us our second language. Mark indicated that we wish to have a per-language quickstart guide, consistent with the other getting started guides e.g. chat. --- src/components/SDKsPage/data.ts | 2 +- src/data/nav/liveobjects.ts | 7 ++++++- src/pages/docs/channels/options/index.mdx | 2 +- src/pages/docs/liveobjects/counter.mdx | 2 +- src/pages/docs/liveobjects/inband-objects.mdx | 2 +- .../{quickstart.mdx => quickstart/javascript.mdx} | 4 ++-- 6 files changed, 12 insertions(+), 7 deletions(-) rename src/pages/docs/liveobjects/{quickstart.mdx => quickstart/javascript.mdx} (97%) diff --git a/src/components/SDKsPage/data.ts b/src/components/SDKsPage/data.ts index 111caf90c2..50145eca4f 100644 --- a/src/components/SDKsPage/data.ts +++ b/src/components/SDKsPage/data.ts @@ -245,7 +245,7 @@ export const data = { text: 'LiveObjects plugin for JavaScript.', image: { src: js, isWide: false }, githubRepoURL: 'https://github.com/ably/ably-js', - setupLink: 'liveobjects/quickstart', + setupLink: 'liveobjects/quickstart/javascript', }, ], }, diff --git a/src/data/nav/liveobjects.ts b/src/data/nav/liveobjects.ts index a0484d6cbd..9fa9145753 100644 --- a/src/data/nav/liveobjects.ts +++ b/src/data/nav/liveobjects.ts @@ -18,7 +18,12 @@ export default { }, { name: 'Getting started', - link: '/docs/liveobjects/quickstart', + pages: [ + { + name: 'JavaScript', + link: '/docs/liveobjects/quickstart/javascript', + }, + ], }, ], }, diff --git a/src/pages/docs/channels/options/index.mdx b/src/pages/docs/channels/options/index.mdx index 22969433b4..e3f35afb17 100644 --- a/src/pages/docs/channels/options/index.mdx +++ b/src/pages/docs/channels/options/index.mdx @@ -413,7 +413,7 @@ Occupancy events have a payload in the `data` property with a value of `occupanc When using inband objects, the client receives messages with the special name `[meta]objects` that describe the current set of objects on a channel. For more information see the [inband objects](/docs/liveobjects/inband-objects) documentation. diff --git a/src/pages/docs/liveobjects/counter.mdx b/src/pages/docs/liveobjects/counter.mdx index aabe8ce149..99be7f4e76 100644 --- a/src/pages/docs/liveobjects/counter.mdx +++ b/src/pages/docs/liveobjects/counter.mdx @@ -18,7 +18,7 @@ A `LiveCounter` instance can be created using the `channel.objects.createCounter `channel.objects.createCounter()` is asynchronous, as the client sends the create operation to the Ably system and waits for an acknowledgment of the successful counter creation. diff --git a/src/pages/docs/liveobjects/inband-objects.mdx b/src/pages/docs/liveobjects/inband-objects.mdx index 2372f5e6e0..f9a77c885a 100644 --- a/src/pages/docs/liveobjects/inband-objects.mdx +++ b/src/pages/docs/liveobjects/inband-objects.mdx @@ -12,7 +12,7 @@ LiveObjects is currently Experimental. Its features are still in development and 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). diff --git a/src/pages/docs/liveobjects/quickstart.mdx b/src/pages/docs/liveobjects/quickstart/javascript.mdx similarity index 97% rename from src/pages/docs/liveobjects/quickstart.mdx rename to src/pages/docs/liveobjects/quickstart/javascript.mdx index f434f74e4a..24a1c044dd 100644 --- a/src/pages/docs/liveobjects/quickstart.mdx +++ b/src/pages/docs/liveobjects/quickstart/javascript.mdx @@ -1,6 +1,6 @@ --- title: "Getting started: LiveObjects in JavaScript" -meta_description: "A getting started guide to learn the basics of integrating the Ably LiveObjects product into your application." +meta_description: "A getting started guide to learn the basics of integrating the Ably LiveObjects product into your JavaScript application." --- -This guide shows how to integrate Ably LiveObjects into your application. +This guide shows how to integrate Ably LiveObjects into your JavaScript / TypeScript application. You will learn how to: From 3c7b77debfcfc684be0cc5419c13e6b74dd11c2f Mon Sep 17 00:00:00 2001 From: Lawrence Forooghian Date: Fri, 15 Aug 2025 16:45:04 +0100 Subject: [PATCH 2/3] Make some LiveObjects concepts code language-agnostic --- src/pages/docs/liveobjects/concepts/objects.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/pages/docs/liveobjects/concepts/objects.mdx b/src/pages/docs/liveobjects/concepts/objects.mdx index 7c3d52d033..135062b34a 100644 --- a/src/pages/docs/liveobjects/concepts/objects.mdx +++ b/src/pages/docs/liveobjects/concepts/objects.mdx @@ -215,7 +215,7 @@ Every object has a unique identifier that distinguishes it from all other object Object IDs follow a specific format: -```javascript +```text type:hash@timestamp ``` @@ -223,7 +223,7 @@ type:hash@timestamp For example: -```javascript +```text counter:J7x6mAF8X5Ha60VBZb6GtXSgnKJQagNLgadUlgICjkk@1734628392000 ``` From 47e4dfdb38fe192a5f1431f0a467a3d49165341b Mon Sep 17 00:00:00 2001 From: Lawrence Forooghian Date: Thu, 14 Aug 2025 10:25:03 +0100 Subject: [PATCH 3/3] Add Swift documentation for LiveObjects Based on Swift plugin at commit 714988d and ably-cocoa's integration/liveobjects branch at commit 5096ca3. Some notes: - I haven't added Swift code to the batch API page because it's not yet implemented in Swift and the stub public API that we do have is incorrect and will be removed pre-v0.1 launch. - I haven't bothered adding Swift to the inband-objects page given that on the same page we're telling people to use the Swift SDK. The quickstart content is a copy and paste of the JS quickstart. --- src/components/SDKsPage/data.ts | 7 + src/data/languages/languageData.ts | 1 + src/data/nav/liveobjects.ts | 9 + src/pages/docs/channels/options/index.mdx | 5 +- .../docs/liveobjects/concepts/objects.mdx | 127 ++++++++++- .../docs/liveobjects/concepts/operations.mdx | 68 ++++++ src/pages/docs/liveobjects/counter.mdx | 87 +++++++- src/pages/docs/liveobjects/inband-objects.mdx | 5 +- src/pages/docs/liveobjects/lifecycle.mdx | 20 ++ src/pages/docs/liveobjects/map.mdx | 146 ++++++++++++- .../docs/liveobjects/quickstart/swift.mdx | 201 ++++++++++++++++++ 11 files changed, 666 insertions(+), 10 deletions(-) create mode 100644 src/pages/docs/liveobjects/quickstart/swift.mdx diff --git a/src/components/SDKsPage/data.ts b/src/components/SDKsPage/data.ts index 50145eca4f..f295b87c61 100644 --- a/src/components/SDKsPage/data.ts +++ b/src/components/SDKsPage/data.ts @@ -247,6 +247,13 @@ export const data = { githubRepoURL: 'https://github.com/ably/ably-js', setupLink: 'liveobjects/quickstart/javascript', }, + { + title: 'Swift', + text: 'LiveObjects plugin for Swift.', + image: { src: swift, isWide: false }, + githubRepoURL: 'https://github.com/ably/ably-liveobjects-swift-plugin', + setupLink: 'liveobjects/quickstart/swift', + }, ], }, livesync: { diff --git a/src/data/languages/languageData.ts b/src/data/languages/languageData.ts index 8d8f62d6e4..ab570b7f70 100644 --- a/src/data/languages/languageData.ts +++ b/src/data/languages/languageData.ts @@ -33,6 +33,7 @@ export default { }, liveObjects: { javascript: '2.11', + swift: '0.1', }, liveSync: { javascript: '0.4', diff --git a/src/data/nav/liveobjects.ts b/src/data/nav/liveobjects.ts index 9fa9145753..a4d31c61ac 100644 --- a/src/data/nav/liveobjects.ts +++ b/src/data/nav/liveobjects.ts @@ -23,6 +23,10 @@ export default { name: 'JavaScript', link: '/docs/liveobjects/quickstart/javascript', }, + { + name: 'Swift', + link: '/docs/liveobjects/quickstart/swift', + }, ], }, ], @@ -97,6 +101,11 @@ export default { name: 'JavaScript SDK', external: true, }, + { + link: 'https://sdk.ably.com/builds/ably/ably-liveobjects-swift-plugin/main/AblyLiveObjects/documentation/ablyliveobjects/', + name: 'Swift plugin', + external: true, + }, { link: '/docs/api/liveobjects-rest', name: 'REST API', diff --git a/src/pages/docs/channels/options/index.mdx b/src/pages/docs/channels/options/index.mdx index e3f35afb17..c0227ac29e 100644 --- a/src/pages/docs/channels/options/index.mdx +++ b/src/pages/docs/channels/options/index.mdx @@ -413,7 +413,10 @@ Occupancy events have a payload in the `data` property with a value of `occupanc When using inband objects, the client receives messages with the special name `[meta]objects` that describe the current set of objects on a channel. For more information see the [inband objects](/docs/liveobjects/inband-objects) documentation. diff --git a/src/pages/docs/liveobjects/concepts/objects.mdx b/src/pages/docs/liveobjects/concepts/objects.mdx index 135062b34a..a329bac457 100644 --- a/src/pages/docs/liveobjects/concepts/objects.mdx +++ b/src/pages/docs/liveobjects/concepts/objects.mdx @@ -17,7 +17,7 @@ LiveObjects provides specialized object types to model your application state. T ### LiveMap Object -[LiveMap](/docs/liveobjects/map) is a key/value data structure similar to a dictionary or JavaScript [Map](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map): +[LiveMap](/docs/liveobjects/map) is a key/value data structure similar to a dictionary or JavaScript [Map](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map)`Dictionary`: * Keys must be strings * Values can be primitive types, JSON-serializable objects or arrays, or [references](#composability) to other objects @@ -33,12 +33,22 @@ const userSettings = await channel.objects.createMap(); await userSettings.set('theme', 'dark'); await userSettings.set('notifications', true); ``` + +```swift +// Create a LiveMap +let userSettings = try await channel.objects.createMap() + +// Set primitive values +try await userSettings.set(key: "theme", value: "dark") +try await userSettings.set(key: "notifications", value: true) +``` #### Primitive Types [LiveMap](/docs/liveobjects/map) supports the following primitive types as values: + * `string` * `number` * `boolean` @@ -47,6 +57,15 @@ await userSettings.set('notifications', true); + + + +* `String` +* `Double` +* `Bool` +* `Data` +* JSON arrays or objects + ### LiveCounter Object @@ -63,6 +82,14 @@ const visitsCounter = await channel.objects.createCounter(); // Increment the counter await visitsCounter.increment(1); ``` + +```swift +// Create a LiveCounter +let visitsCounter = try await channel.objects.createCounter(); + +// Increment the counter +try await visitsCounter.increment(amount: 1); +``` ### Root Object @@ -84,6 +111,14 @@ const root = await channel.objects.getRoot(); // Use it like any other LiveMap await root.set('app-version', '1.0.0'); ``` + +```swift +// Get the Root Object +let root = try await channel.objects.getRoot() + +// Use it like any other LiveMap +try await root.set(key: "app-version", value: "1.0.0") +``` ## Reachability @@ -109,6 +144,21 @@ counterOld.on('deleted', () => { const counterNew = await channel.objects.createCounter(); await root.set('myCounter', counterNew); ``` + +```swift +// Create a counter and reference it from the root +let counterOld = try await channel.objects.createCounter() +try await root.set(key: "myCounter", value: .liveCounter(counterOld)) + +// counterOld will eventually be deleted +counterOld.on(event: .deleted) { _ in + print("counterOld has been deleted and can no longer be used") +} + +// Create a new counter and replace the old one referenced from the root +let counterNew = try await channel.objects.createCounter() +try await root.set(key: "myCounter", value: .liveCounter(counterNew)) +```