Skip to content

Latest commit

 

History

History

LiveObjects

README.md

Ably LiveObjects Swift Header SPM Swift Compatibility License


Ably LiveObjects Swift plugin

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.


Getting started

Everything you need to get started with Ably LiveObjects:


Supported platforms

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.


Installation

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"),
        ]
    ),
]

Usage

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()

Create and update objects

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 values

// 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 updates

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()

Migrating from the standalone plugin package

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.

Step 1: Swap the package dependency

  1. Remove the ably-liveobjects-swift-plugin package dependency from your project.
  2. Replace the ably-cocoa package with the ably-pubsub-cocoa package at version 2.0.0 or later, and select its AblyPubSubDevice and AblyLiveObjects products 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.

Step 2: Adopt the path-based API

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.


Example app

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:

  1. Open the AblyLiveObjects.xcworkspace workspace in Xcode.
  2. Follow the instructions inside the Secrets.example.swift file to add your Ably API key to the example app.
  3. Run the AblyLiveObjectsExample target. If you wish to run it on an iOS or tvOS device, you'll need to set up code signing.

Releases

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.


Contribute

Read the CONTRIBUTING.md guidelines to contribute to Ably or share feedback or request a new feature.

Support, feedback and troubleshooting

For help or technical support, visit Ably's support page. You can also view the community-reported GitHub issues or raise one yourself.