The Swift and Objective-C SDK for Ably Pub/Sub: publish and subscribe to channels, and use message history, presence, push notifications and LiveObjects, from iOS, macOS and tvOS apps.
This SDK provides the device package only, for end-user apps. There is no server package; for backends, use a server SDK such as JavaScript, Java, Go, .NET, Python, PHP or Ruby.
| Package | Use it for | Entry point |
|---|---|---|
AblyPubSubDevice |
Applications on end-user devices | PubSubDevice.createClient |
iOS 15 or later, macOS 12 or later, or tvOS 15 or later (building needs Xcode 26 or later, with Swift 6.2).
Install the SDK with Swift Package Manager. Version 2.0 is not published to CocoaPods or Carthage.
In Xcode:
- Choose File > Add Package Dependencies… and enter
https://github.com/ably/ably-pubsub-cocoa. - Add the
AblyPubSubDeviceproduct to your target.
In a Package.swift manifest, add the same package URL from version 2.0.0 and depend on its
AblyPubSubDevice product.
In Objective-C, import the SDK with @import AblyPubSubDevice;. Swift drops the ART prefix from
type names: ARTClientOptions is ClientOptions.
Authenticate a device with tokens issued by your own server, through authUrl or authCallback.
Never embed an API key in an app that runs on an end-user device.
import AblyPubSubDeviceSwift
let options = ClientOptions()
options.authUrl = URL(string: "https://your-server.example.com/ably-auth")
options.clientId = "me"
let client = PubSubDevice.createClient(options: options)
// The client connects automatically. Subscribing attaches the channel.
let channel = client.channels.get("test-channel")
channel.subscribe { message in
print("Received: \(message.data ?? "")")
}
channel.publish("test-event", data: "hello world") { error in
if let error {
print("Publish failed: \(error.message)")
}
}To get tokens from your own code instead of a URL, set authCallback. Pass its callback a token
string, a TokenDetails or a TokenRequest.
In Swift, you can await channel, presence and connection operations instead of passing callbacks,
for example try await channel.publish("test-event", data: "hello world"). They throw an
ErrorInfo.
Important
The async functions in AblyPubSubDeviceSwift are experimental. Their names, signatures and
the set of operations they cover may change in a minor release.
Version 2.0 installs through Swift Package Manager only and creates clients with PubSubDevice.
| 1.x | 2.0 | |
|---|---|---|
| Package | Ably product of ably-cocoa |
AblyPubSubDevice product of ably-pubsub-cocoa |
| Import | import Ably / @import Ably; |
import AblyPubSubDeviceSwift / @import AblyPubSubDevice; |
| Realtime client | ARTRealtime(options: options) |
PubSubDevice.createClient(options: options) |
| REST client | ARTRest(options: options) |
Removed |
See the migration guide for all other changes.
Set options on a ClientOptions object and pass it to PubSubDevice.createClient(options:).
endpoint selects the Ably host for HTTP requests and the realtime connection. It replaces the
1.x environment, restHost and realtimeHost options.
let options = ClientOptions()
options.authUrl = URL(string: "https://your-server.example.com/ably-auth")
options.clientId = "me"
options.endpoint = "nonprod:sandbox"
let client = PubSubDevice.createClient(options: options)- Never put a port in
endpoint:localhost:8080is not a hostname and does not resolve. - Set the port with
tlsPort, or withportwhen TLS is off. - With TLS off (
tls = false), use token authentication.
See the migration guide for how the old options map to
endpoint.
Set logLevel to a LogLevel value: .verbose, .debug, .info, .warn or .error. The
default is .warn. The SDK writes log lines with NSLog.
options.logLevel = .debugTo send log lines elsewhere, set logHandler to a subclass of Log that overrides log(_:with:).
LiveObjects adds realtime data structures, such as maps and counters, that stay in sync across clients.
The plugin ships as the AblyLiveObjects product of this package. It has no separate package or
version, and installs through Swift Package Manager only.
In Xcode, add the package as described in Installation. 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"),
]
),
]Register the plugin, then get a channel with the object 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 client = PubSubDevice.createClient(options: options)
let channelOptions = RealtimeChannelOptions()
channelOptions.modes = [.objectPublish, .objectSubscribe]
let channel = client.channels.get("test-channel", options: channelOptions)
let root = try await channel.object.get()To learn more, follow the Swift quickstart. The LiveObjects README has more examples and an example app.
On iOS, the SDK can activate a device for push notifications and subscribe it to channels. See Push notifications for setup, and Examples/AblyPush for an example app.
The SDK's privacy manifest declares the Device ID data type, which is not used for tracking. The SDK sends the device ID to Ably only when your app uses push notifications. If your app doesn't, you can leave Device ID off your App Store privacy label.
- Getting started with Pub/Sub using Swift
- Ably Pub/Sub documentation and examples
- Token authentication
- Migration guide: migrating from 1.x
- CHANGELOG.md: release notes; all Ably releases are listed on changelog.ably.com
Read CONTRIBUTING.md before contributing; it also describes the release process.
For help, visit Ably's support page. Report bugs and compatibility problems on GitHub Issues.
Licensed under the Apache License, Version 2.0. See LICENSE.