2.0.0

The 2.0.0 release makes ably-cocoa a device-side SDK, for apps that run on an end user's device. A client is created through PubSubDevice.createClient, and every client it creates tells Ably that it runs on a device. That declaration determines how its traffic is counted: on an account billed by monthly active users, device traffic counts toward the total, the connection must carry a clientId, and that clientId is subject to a concurrency limit.

The repository is renamed to ably-pubsub-cocoa, and the package is distributed through Swift Package Manager only. In Swift, a new AblyPubSubDeviceSwift module adds async versions of channel and presence operations.

2.0 also brings the public API in line with the Ably client library specification: it renames types, removes the APIs deprecated in 1.x, and corrects types and nullability.

Below is an overview of the major changes in this release.

Please refer to the v2 migration guide for the full details, including a list of all breaking changes and instructions on how to address them.

Repository, package and distribution

• Add the package from https://github.com/ably/ably-pubsub-cocoa. The old URL, https://github.com/ably/ably-cocoa, serves the 1.x line, which receives security and critical fixes only.
• Swift Package Manager is the only distribution channel. 2.0 ships no CocoaPods pod and no Carthage framework, and both stay on the 1.x line.
• The SDK is the AblyPubSubDevice product, which replaces Ably. The package also vends AblyLiveObjects, released at the same version.
• In Swift, import AblyPubSubDeviceSwift. In Objective-C, import AblyPubSubDevice.

Creating clients

• Create a client with PubSubDevice.createClient(options:), createClient(key:) or createClient(token:).
• The client class's initializers are no longer public, and the createWithOptions:, createWithKey: and createWithToken: class factories are removed.
• The SDK identifies itself to Ably as ably-pubsub-cocoa, where 1.x sent ably-cocoa. A client from PubSubDevice.createClient also sends a versionless ably-pubsub-device entry.

Swift API

• Swift sees the SDK's types without the ART prefix: ARTClientOptions is ClientOptions, ARTErrorInfo is ErrorInfo, and so on. Objective-C keeps the prefix.
• AblyPubSubDeviceSwift adds async versions of operations such as attach, publish and presence enter, which throw an ErrorInfo.

Client API naming

• ARTRealtime is renamed ARTPubSubClient, and ARTRealtimeProtocol is renamed ARTPubSubProtocol.
• ARTRest is renamed ARTHttpClient, along with ARTHttpChannel, ARTHttpChannels, ARTHttpPresence and ARTHttpAnnotations. These classes are now internal. An application reaches Ably through the realtime client.

Client options

• endpoint replaces the environment, restHost and realtimeHost options, which are removed. A client that sets none of them connects to main.realtime.ably.net, with fallbacks at main.[a-e].fallback.ably-realtime.com.
• realtimeRequestTimeout and maxMessageSize move from ARTDefault to ARTClientOptions, so each client can set its own. maxFrameSize is a new option.
• With an empty fallbackHosts array, an unreachable host no longer fails the connection. The connection moves to DISCONNECTED and retries.

Types and nullability

• ARTStats has no typed properties. Every statistic is in entries, keyed by its name.
• extras is a dictionary on messages, presence messages and annotations.
• ARTCrypto.getDefaultParams: takes an ARTCipherParamOptions, and a dictionary can no longer be passed as a channel's cipher.
• ARTDevicePushDetails.state is an ARTDevicePushState enum.
• ARTMessageVersion and ARTMessageAnnotations are immutable and Sendable.
• Message.version, Message.annotations, Annotation.timestamp and the listener that subscribe returns are no longer optional. Message.connectionId is now optional.
• When a system error stops an operation, the ErrorInfo has an Ably error code, and the system error is its underlying error.

Behaviour changes

• channels.release() throws unless the channel is initialized, detached or failed. Detach a channel before releasing it.
• Invalid arguments to history, stats, request and push listSubscriptions raise NSInvalidArgumentException, and those methods no longer return an error.
• Subscribing on a channel in the FAILED state registers the listener.
• The client falls back to another host after a DISCONNECTED with a 5xx error, or after a CloudFront error response.

Removed APIs

• The members deprecated in 1.x: fallbackHostsUseDefault, ARTConnection.recoveryKey and ARTStats.intervalGranularity.
• The publish overloads that take clientId or extras alongside name and data. Set them on a Message instead.
• didAblyPushRegistrationFail:. Implement didUpdateAblyPush: instead.
• ARTDataQueryError, ARTRealtimeHistoryError and ARTCustomRequestError.

Supported platforms changes

• Support for macOS earlier than 12, iOS earlier than 15 and tvOS earlier than 15 has been dropped.
• Building the SDK requires Xcode 26 or later (Swift 6.2).

Full Changelog

1.4.1

What's Changed

• Fix crash when a connection attempt fails synchronously by @maratal in https://github.com/ably/ably-cocoa/pull/2322
• Deprecate releasing a channel that isn't detached (RTS4b) by @SimonWoolf in https://github.com/ably/ably-cocoa/pull/2314
• Don't mark the device ID as used for tracking in the privacy manifest by @maratal in https://github.com/ably/ably-cocoa/pull/2338
• LiveObjects: preserve exact Double values for numbers read over the JSON protocol by @maratal in https://github.com/ably/ably-cocoa/pull/2261

CocoaPods and Carthage consumers receive only the Ably product, which gets the first three changes; the LiveObjects fix (#2261) is in the AblyLiveObjects product, available via Swift Package Manager only.

Privacy manifest changes

The SDK's privacy manifest (PrivacyInfo.xcprivacy) no longer marks the Device ID data type as used for tracking: NSPrivacyCollectedDataTypeTracking is now false (#2338). The device ID is a random UUID that the SDK generates and sends to Ably only to register the device for push notifications and to subscribe it to push channels. That is app functionality, not tracking as Apple defines it. Device ID is still declared as collected, linked to the user, for app functionality.

What this means for your app:

• Xcode's privacy report no longer lists Device ID as used for tracking, so the SDK no longer requires you to declare it under "Data Used to Track You" on your App Store privacy label.
• If your app doesn't use push notifications, the SDK never sends the device ID off the device, and you can leave Device ID off your App Store privacy label.

Full Changelog: ably/ably-cocoa@1.4.0...1.4.1

1.4.0

What's Changed

• Read the channel's data encoder live when encoding annotations by @SimonWoolf in https://github.com/ably/ably-cocoa/pull/2231
• Render JSONValue as compact JSON text by @maratal in https://github.com/ably/ably-cocoa/pull/2257
• Add per-case value accessors to the primitive path object and instance by @maratal in https://github.com/ably/ably-cocoa/pull/2260
• Expand the LiveObjects README usage section and point to the web docs by @sacOO7 in https://github.com/ably/ably-cocoa/pull/2258

CocoaPods and Carthage consumers receive only the Ably product, for which the sole change in this release is the annotations fix (#2231); everything else is in the AblyLiveObjects product, available via Swift Package Manager only.

Breaking LiveObjects API changes

The AblyLiveObjects public API changed in this release:

• PrimitivePathObject gains six per-case value accessors (stringValue() … jsonObjectValue()), and PrimitiveInstance gains the same six as throwing properties, for reading a primitive whose type is known at the call site.
• The per-case getters on Primitive (stringValue, numberValue, boolValue, dataValue, jsonArrayValue, jsonObjectValue) and the same six on LiveMapValue are no longer public. Read one expected primitive type through the new accessors on PrimitivePathObject (try node.asPrimitive().stringValue()) or PrimitiveInstance (try instance.stringValue), or switch over Primitive's cases. LiveMapValue keeps primitiveValue, liveMapValue, liveCounterValue and its ExpressibleBy*Literal conformances.

Full Changelog: ably/ably-cocoa@1.3.0...1.4.0

1.3.0

What's Changed

• The Ably LiveObjects plugin now lives in this repository and has a new path-based API. It is available as the AblyLiveObjects product of this package, and LiveObjects data is now accessed through channel.object, which returns a RealtimeObject exposing PathObjects — stable references to locations within the channel object that resolve to values dynamically at runtime, instead of explicit LiveMap/LiveCounter instances. See the PathObject documentation for details, and the breaking changes below if you are migrating from the standalone ably-liveobjects-swift-plugin package. LiveObjects remains experimental: breaking changes to the AblyLiveObjects API may be made in minor or patch releases, and ably-cocoa's semantic versioning guarantees apply only to the Ably product. This work was integrated by @sacOO7 in https://github.com/ably/ably-cocoa/pull/2230 and delivered through the following PRs:
  • Merge LiveObjects plugin and plugin-support into ably-cocoa by @lawrence-forooghian in https://github.com/ably/ably-cocoa/pull/2222
  • Add path-based LiveObjects public API by @sacOO7 in https://github.com/ably/ably-cocoa/pull/2227
  • Move _AblyPluginSupportPrivate out of Sources/ to the repo root by @maratal in https://github.com/ably/ably-cocoa/pull/2228
  • Implement path-based public API end-to-end with UTS tests by @sacOO7 in https://github.com/ably/ably-cocoa/pull/2234
  • Enable UTS integration test suites for the objects tier by @sacOO7 in https://github.com/ably/ably-cocoa/pull/2235
  • Restructure LiveObjects test-support and native test suites by role and tier by @sacOO7 in https://github.com/ably/ably-cocoa/pull/2239
  • Align UTS objects test helpers with the spec's standard_test_pool by @sacOO7 in https://github.com/ably/ably-cocoa/pull/2240
• Universal Test Suite (UTS) integration and proxy test infrastructure by @sacOO7 in https://github.com/ably/ably-cocoa/pull/2223
• First spec-derived UTS integration and proxy tests via the rewritten uts-to-swift skill by @sacOO7 in https://github.com/ably/ably-cocoa/pull/2224
• Swift Package Manager consumers of this package now require Xcode 16.3 or later (the package manifest's swift-tools-version is now 6.1). CocoaPods and Carthage consumers are unaffected.
• The AblyLiveObjects product is available via Swift Package Manager only. CocoaPods and Carthage consumers receive the core Ably product alone; for them this release contains no functional changes.

Breaking changes

This release replaces the previous experimental instance-based LiveObjects API (as last published in the standalone plugin's 0.4.1 release) with the new path-based API. The module name (AblyLiveObjects) and plugin registration (clientOptions.plugins = [.liveObjects: AblyLiveObjects.Plugin.self]) are unchanged, but:

• The channel.objects property (returning RealtimeObjects, with getRoot()) has been replaced by the channel.object property (returning RealtimeObject, with get())
• Instead of obtaining and operating on explicit LiveMap/LiveCounter instances, data is accessed and mutated through PathObject references

Full Changelog: ably/ably-cocoa@1.2.62...1.3.0

1.2.62

What's Changed

• Add API for registering Live Activity push-to-start token by @ttypic in https://github.com/ably/ably-cocoa/pull/2219

1.2.61

What's Changed

• Remove logExceptionReportingUrl client option by @lawrence-forooghian in https://github.com/ably/ably-cocoa/pull/2215
• Store all persisted data atomically in a single file with None protection by @maratal in https://github.com/ably/ably-cocoa/pull/2207

Full Changelog: ably/ably-cocoa@1.2.60...1.2.61

1.2.60

What's Changed

Adds missing onAttach callback variants to ARTRealtimeAnnotations subscribe (#2199).

Full Changelog: ably/ably-cocoa@1.2.59...1.2.60

1.2.59

What's Changed

Adds support for the upcoming version 0.4.0 of the LiveObjects plugin and removes support for earlier versions of the plugin.

Full Changelog: ably/ably-cocoa@1.2.58...1.2.59

1.2.58

What's Changed

• Decode and encode extras on presence messages (TP3i) by @AndyTWF in https://github.com/ably/ably-cocoa/pull/2186

Full Changelog: ably/ably-cocoa@1.2.57...1.2.58

1.2.57

What's Changed

This release introduces new overloads of publish() that return the serial of the published message(s). This simplifies the scenario in which a client wishes to perform an update to a message that it previously published.

These new overloads are differentiated from the existing ones by:

• a different argument label for the callback (resultCallback instead of callback)
• a different number of arguments for the callback (two instead of one)

If you have any existing calls to publish(), they should be unaffected by the introduction of these new overloads.

To call these new overloads in Swift, you can simply pass a trailing closure which accepts two arguments:

channel.publish("foo", data: nil) { publishResult, error in
  // publishResult.serials contains the serial of the published message
  // …
}

For more information, see the documentation on updating and deleting messages.

Full Changelog: ably/ably-cocoa@1.2.56...1.2.57