ably/ably-cocoa

Build any realtime experience using Ably's Pub/Sub Cocoa SDK. Supported on all popular platforms and frameworks, including Swift and Objective-C.

Getting started

Everything you need to get started with Ably:

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.

The following platforms are supported:

| Platform | Support | |----------|---------| | iOS| >= 10 | | macOS| >= 10.12 | | tvOS | >= 10 |

[!IMPORTANT] Ably Cocoa SDK versions below 1.2.23 will be deprecated from November 1, 2025.

Installation

You can install Ably for iOS and macOS through Swift package manager, CocoaPods, Carthage or install manually.

To use the Ably LiveObjects plugin, see its installation notes below — it is available via Swift Package Manager only.

Swift Package Manager

The Ably Pub/Sub SDK includes installation support for Swift Package Manager.

<details> <summary>Swift Package Manager installation details.</summary>

To install the ably-cocoa package in your Xcode project:

Paste https://github.com/ably/ably-cocoa in the Swift Packages search box. ( Xcode project → Swift Packages.. . → + button)
Select the Ably SDK for your target.

To install the ably-cocoa package in another Swift package, add the following to your Package.Swift:

 .package(url: "https://github.com/ably/ably-cocoa", from: "1.4.0"),

See Apple's adding package dependencies to your app guide for more detail. </details>

CocoaPods

The Ably Pub/Sub SDK includes installation support for CocoaPods.

<details> <summary>CocoaPods installation details.</summary>

If you intend to use Swift, using use_frameworks! in your Podfile is recommended (this will create a Framework that can be used in Swift natively).

Add this line to your application's Podfile:

# For Xcode 7.3 and newer
pod 'Ably', '>= 1.2'

And then install the dependency:

$ pod install

</details>

Carthage

The Ably Pub/Sub SDK includes installation support for Carthage.

<details> <summary>Carthage installation details.</summary>

Add the following line to your application's Cartfile:

# For Xcode 7.3 and newer
github "ably/ably-cocoa" >= 1.2

And then run one of the following commands required for your platform:

| Platform | Command | |----------|---------| | iOS | carthage update --use-xcframeworks --platform iOS --no-use-binaries | | macOS | carthage update --use-xcframeworks --platform macOS --no-use-binaries| | tvOS | carthage update --use-xcframeworks --platform tvOS --no-use-binaries |

After building the framework (located in [PROJECT_ROOT]/Carthage/Build), drag the following files into the Frameworks, Libraries, and Embedded content section of your Xcode target's General tab:

Ably.xcframework
AblyDeltaCodec.xcframework
msgpack.xcframework
For applications, select Embed & Sign
For other targets, select Do Not Embed

If you encounter an error similar to the following, you've likely missed adding one or more required dependencies:

dyld: Library not loaded: @rpath/AblyDeltaCodec.framework/AblyDeltaCodec

For further information review the Carthage adding frameworks to an application guide.

</details>

Manual install

The Ably Pub/Sub SDK includes manual installation support.

<details> <summary>Manual installation details.</summary>

Download the Ably Pub/Sub Cocoa SDK.
Drag the ably-cocoa/ably-cocoa directory into your Xcode project as a group.

Ably depends on our MessagePack Fork 0.2.0; get it from the releases page and link it into your project.

</details>

Usage

// Initialize Ably Realtime client
let clientOptions = ARTClientOptions(key: "your-ably-api-key")
clientOptions.clientId = "me"
let realtime = ARTRealtime(options: clientOptions)

// Wait for connection to be established
realtime.connection.on { stateChange in
    if stateChange.current == .connected {
        print("Connected to Ably")
        
        // Get a reference to the 'test-channel' channel
        let channel = realtime.channels.get("test-channel")
        
        // Subscribe to all messages published to this channel
        channel.subscribe { message in
            print("Received message: \(message.data ?? "")")
        }
        
        // Publish a test message to the channel
        channel.publish("test-event", data: "hello world!") { error in
            guard error == nil else {
                print("Error publishing message: \(error!.message)")
                return
            }
            print("Message successfully published")
        }
    }
}

LiveObjects

Ably LiveObjects provides realtime, collaborative data structures that automatically synchronize state across all connected clients. This repository contains the Ably LiveObjects plugin, which enables LiveObjects on top of the core Pub/Sub SDK.

Install LiveObjects

The plugin is available via Swift Package Manager only (there is no CocoaPods or Carthage distribution). There is no separate package or version to install: the plugin ships as a product of this package and is versioned and released as part of ably-cocoa.

To install it in your Xcode project, add the ably-cocoa package as above and additionally select the AblyLiveObjects product for your target.

To install it in another Swift package, add the product to your target's dependencies:

.target(
    name: "MyTarget",
    dependencies: [
        .product(name: "Ably", package: "ably-cocoa"),
        .product(name: "AblyLiveObjects", package: "ably-cocoa"),
    ]
)

For usage, platform requirements, the example app and the migration guide for users of the standalone plugin package, see the LiveObjects README. For a comprehensive guide, check the LiveObjects documentation, starting with the Swift quickstart.

Contribute

Read the CONTRIBUTING.md guidelines to contribute to Ably.

Releases

The CHANGELOG.md contains details of the latest releases for this SDK. You can also view all Ably releases on changelog.ably.com.

Support, feedback, and troubleshooting

For help or technical support, visit Ably's support page or GitHub Issues for community-reported bugs and discussions.

Package Metadata

Repository: ably/ably-cocoa

Default branch: main

README: README.md