The Ably LiveObjects plugin enables real-time collaborative data synchronization for the ably-pubsub-cocoa SDK. LiveObjects provides a simple way to build collaborative applications with synchronized state across multiple clients in real-time. Built on Ably's core service, it abstracts complex details to enable efficient collaborative architectures.
Note
The plugin is the AblyLiveObjects product of the ably-pubsub-cocoa package, and is released with it at the same version. See Installation. It was previously the standalone ably-liveobjects-swift-plugin package. If you are coming from that package, see the migration guide.
Everything you need to get started with Ably LiveObjects:
- Learn about Ably LiveObjects.
- Getting started with LiveObjects in Swift.
- Explore the example app to see LiveObjects in action.
Ably aims to support a wide range of platforms. If you experience any compatibility issues, open an issue in the repository or contact Ably support.
This plugin supports the following platforms:
| Platform | Support |
|---|---|
| iOS | >= 15.0 |
| macOS | >= 12.0 |
| tvOS | >= 15.0 |
Note
Xcode 26 or later is required.
The plugin ships as the AblyLiveObjects product of the ably-pubsub-cocoa package. It has no separate package or version, and installs through Swift Package Manager only.
In Xcode, choose File > Add Package Dependencies… and enter https://github.com/ably/ably-pubsub-cocoa. Then select both the AblyPubSubDevice and AblyLiveObjects products for your target.
In a Package.swift manifest, add the package and both products:
dependencies: [
.package(url: "https://github.com/ably/ably-pubsub-cocoa", from: "2.0.0"),
],
targets: [
.target(
name: "MyTarget",
dependencies: [
.product(name: "AblyPubSubDevice", package: "ably-pubsub-cocoa"),
.product(name: "AblyLiveObjects", package: "ably-pubsub-cocoa"),
]
),
]The examples below are a quick tour of the API. Check the LiveObjects documentation for a comprehensive guide — starting with the Swift quickstart, it covers maps, counters, path objects, subscriptions, lifecycle events and more.
Devices authenticate with tokens from your own server: the samples set authUrl to its /ably-auth endpoint.
After installing the plugin, pass it to the client via
ClientOptions, and fetch channels with the LiveObjects channel modes:
import AblyPubSubDeviceSwift
import AblyLiveObjects
let options = ClientOptions()
options.authUrl = URL(string: "https://your-server.example.com/ably-auth")
options.clientId = "me"
options.plugins = [.liveObjects: AblyLiveObjects.Plugin.self]
let realtime = PubSubDevice.createClient(options: options)
// Fetch a channel, specifying the LiveObjects channel modes
let channelOptions = RealtimeChannelOptions()
channelOptions.modes = [.objectPublish, .objectSubscribe]
let channel = realtime.channels.get("my-channel", options: channelOptions)channel.object is the entry point into the LiveObjects API. Fetch the channel's root map — this implicitly attaches the channel and waits for the channel's objects to be synchronized:
let rootObject = try await channel.object.get()LiveObjects provides two synchronized data structures — LiveMap, a key/value map, and LiveCounter, a numeric counter — which you create and assign to keys on the root object:
// Create a counter and a map, and assign them to keys on the root object
try await rootObject.set(key: "visits", value: .liveCounter(LiveCounter.create(initialCount: 0)))
try await rootObject.set(key: "reactions", value: .liveMap(LiveMap.create(entries: [
"likes": 0,
"hearts": 0,
])))Navigate the object graph with path objects — stable references to locations within the channel's objects that resolve to values at the time each method is called — and send operations to update the objects. Updates are synchronized to all clients subscribed to the channel:
let visits = rootObject.get(key: "visits").asLiveCounter()
try await visits.increment(amount: 5)
let reactions = rootObject.get(key: "reactions").asLiveMap()
try await reactions.set(key: "likes", value: 10)
try await reactions.remove(key: "hearts")// Read individual values
let visitCount = try visits.value() // 5.0
let likes = try reactions.get(key: "likes").asPrimitive().numberValue() // 10.0
// Or take a JSON-serializable snapshot of an entire object
let snapshot = try rootObject.compactJson() // {"reactions":{"likes":10},"visits":5}Subscribe to a path object to be notified whenever the object at that path is updated, by any client:
let subscription = try visits.subscribe { event in
guard let value = try? event.object.asLiveCounter().value() else { return }
print("Visits updated: \(value)")
}
// Later, stop receiving updates
subscription.unsubscribe()Since ably-cocoa 1.3.0, the plugin is developed and released in this repository as the AblyLiveObjects product. In 2.0, the repository and package are renamed ably-pubsub-cocoa. The standalone ably-liveobjects-swift-plugin package is deprecated: no further releases will be published from it, and its final release is 0.4.1. Migrating takes two steps.
- Remove the
ably-liveobjects-swift-pluginpackage dependency from your project. - Replace the
ably-cocoapackage with theably-pubsub-cocoapackage at version 2.0.0 or later, and select itsAblyPubSubDeviceandAblyLiveObjectsproducts for your target. See Installation.
The AblyLiveObjects import and the plugin registration are unchanged. In 2.0, import Ably becomes import AblyPubSubDeviceSwift, and ARTClientOptions is ClientOptions in Swift:
import AblyPubSubDeviceSwift
import AblyLiveObjects
let options = ClientOptions()
options.authUrl = URL(string: "https://your-server.example.com/ably-auth")
options.clientId = "me"
options.plugins = [.liveObjects: AblyLiveObjects.Plugin.self]For the other changes from ably-cocoa 1.x, such as creating the client with PubSubDevice.createClient, see the v2 migration guide.
Important
If the standalone package is still in your dependency graph, package resolution fails with declare targets with a conflicting name errors for the AblyLiveObjects and _AblyPluginSupportPrivate targets.
The fix is to remove the standalone package dependency, as described above.
ably-cocoa 1.3.0 replaced the instance-based API of the standalone plugin (last published in its 0.4.1 release) with the path-based API, which ably-pubsub-cocoa 2.0 keeps: instead of obtaining and operating on explicit LiveMap/LiveCounter instances, data is accessed and mutated through PathObjects — stable references to locations within the channel object that resolve to values dynamically at runtime. See the PathObject documentation.
The headline API changes:
| Standalone plugin (≤ 0.4.1) | ably-pubsub-cocoa 2.0 |
|---|---|
channel.objects, returning RealtimeObjects |
channel.object, returning RealtimeObject |
try await channel.objects.getRoot(), returning any LiveMap |
try await channel.object.get(), returning any LiveMapPathObject |
Operate on explicit LiveMap/LiveCounter instances |
Navigate with PathObjects: rootObject.get(key:), then cast with asLiveMap() / asLiveCounter() / asPrimitive() |
For example:
// Standalone plugin (≤ 0.4.1) — instance-based
let rootObject = try await channel.objects.getRoot()
try await rootObject.set(key: "myKey", value: "myValue")
let value = try rootObject.get(key: "myKey")?.stringValue
// ably-pubsub-cocoa 2.0 — path-based
let rootObject = try await channel.object.get()
try await rootObject.set(key: "myKey", value: "myValue")
let value = try rootObject.get(key: "myKey").asPrimitive().stringValue()A PathObject is purely navigational: it can be created before the data at its path exists, and it survives the object at its path being replaced — there is no need to re-fetch anything when the underlying object changes. The example app demonstrates the path-based API.
This repository contains an example app, written using SwiftUI, which demonstrates how to use the plugin. The code for this app is in the Example directory.
In order to allow the app to use modern SwiftUI features, it supports the following OS versions:
- macOS 14 and above
- iOS 17 and above
- tvOS 17 and above
To run the app:
- Open the
AblyLiveObjects.xcworkspaceworkspace in Xcode. - Follow the instructions inside the
Secrets.example.swiftfile to add your Ably API key to the example app. - Run the
AblyLiveObjectsExampletarget. If you wish to run it on an iOS or tvOS device, you'll need to set up code signing.
The plugin is released as part of ably-pubsub-cocoa. See the ably-pubsub-cocoa CHANGELOG for its releases, and CHANGELOG.md for the historical releases of the standalone plugin package. You can also view all Ably releases on changelog.ably.com.
Read the CONTRIBUTING.md guidelines to contribute to Ably or share feedback or request a new feature.
For help or technical support, visit Ably's support page. You can also view the community-reported GitHub issues or raise one yourself.
