SDK setup

Use these instructions to setup an Ably SDK. How to use Ably outlines the differences between the realtime and REST interfaces in Ably SDKs and the other possible ways to use Ably.

Get an API key

Copied!

An API key is required to instantiate a client and authenticate with Ably. API keys are used either to authenticate directly, or to generate Tokens for untrusted clients. Sign up to Ably to create an API key in the dashboard or use the Control API to create an API programmatically.

Install and instantiate a client

Copied!

Ably SDKs provide a consistent and idiomatic API across a variety of supported platforms. They contain a realtime and a REST interface, each of which can be used to satisfy different use cases. Choose which SDK you’d like to start using by selecting the language from the dropdown menu above.

The JavaScript SDK is available via CDN. To get started with your project, reference the SDK within the <head> of an HTML page. The SDK is also available as an NPM module.

When including the SDK from CDN, Ably recommends that you lock into major version 1 of the library. This means that you will automatically receive minor updates and patches, but you will never receive breaking changes. For example, if you lock into major version 1 using https://cdn.ably.com/lib/ably.min-1.js you will receive all minor updates and patch fixes automatically. Additionally, the .min suffix can be dropped if you want the non-minified version for debugging.


<script lang="text/javascript" src="https://cdn.ably.com/lib/ably.min-1.js"></script>

Copy
Copied!

Run the following to instantiate a client:


JavaScript v1.2

// Using promises
const realtime = new Ably.Realtime.Promise({ key: apiKey });


// Using callbacks
const realtime = new Ably.Realtime({ key: apiKey });

Copy
Copied!

Client options

Copied!

ClientOptions enable the client connection to be configured when instantiating the client.

Properties that can be set include those used to:

authenticate the client, such as key if using basic authentication, or an authUrl or authCallback if using token authentication.
customize client behavior, such as using echoMessages to set whether messages published by the client are received by them, or idempotentRestPublishing to enable idempotent publishing.
set retry and timeout durations.
set environment names and fallbacks if using a custom environment.

See the API references for a full list of properties available to the realtime and REST interfaces.