Pusher Adapter
Ably enables migration from Pusher to Ably using its Pusher Adapter. The protocol adapter handles all background translation and only requires an API key change.
Using an adapter introduces some latency and is slower than using an Ably SDK, however the impact is typically 1-10ms. It will also be slightly slower than using Pusher natively, but only if you are close to whichever Pusher data center used. If you aren't close to the Pusher data center you've chosen, then the extra latency from using the adapter should be more than compensated for by being able to use a data center that is close to you. This is because Ably automatically connects clients to the data center closest to them.
The Pusher Adapter provides some of the advantages of Ably, such as inter-regional message federation, however others, such as continuity guarantees, fallback host support, and message history are only available when using an Ably SDK. If an Ably SDK is available in your chosen platform, it is recommended you use that, or plan to transition to it eventually.
Supported features
The following Pusher features are supported using the adapter:
- Realtime subscribe
- Realtime presence
- Realtime publish
- REST publish
- REST get occupied channels
- REST get presence set
- REST get user count
Enable the Pusher Adapter
The Pusher protocol is not supported by default in Ably apps. This is due to security reasons associated with the use of public channels.
To enable the Pusher Adapter in an app:
- Log into your Ably dashboard and create or select the app you're using.
- Click the Settings tab.
- Check the box for Pusher protocol support under Protocol Adapter Settings.
- Click Save settings.
Once you save the settings, you will be offered the choice for Ably to create a set of namespaces for you. These are required to provide interoperability with Pusher client libraries:
- Pusher public channels will use the
public:namespace. - Pusher private channels will use the
private:namespace. - Pusher presence channels will use the
presence:namespace.
All namespaces must also have the Require identification rule disabled, as Pusher clients are never identified in the context of Ably. If you are receiving error code 40160 then Require identification is enabled.
Configure a Pusher SDK
Initialize your Pusher SDK to connect to Ably. All of Pusher's SDKs are supported, and need to be configured similar to the following:
1
2
3
4
5
6
7
8
const pusher = new Pusher('appId.keyId', {
wsHost: 'main.pusher.ably.net',
httpHost: 'main.pusher.ably.net',
disableStats: true,
forceTls: true,
cluster: 'eu',
authEndpoint: '...',
});| Option | Description |
|---|---|
| wsHost | Set the Websocket host to point to Ably. |
| httpHost | Set the HTTP requests host to point to Ably. |
| disableStats | Disable the collection of stats in Pusher. |
| forceTls | Force the connection to use TLS. This isn't required but strongly recommended by Ably to avoid sending private keys over a plain text connection. |
| cluster | Set this to any value as it is required by Pusher. It has no impact on the Ably Pusher endpoint as Ably will use the closest data center available to the client. |
| authEndpoint | The address of your auth server, if you are using one. |
You can also add any other Pusher options that you normally use.
Configure a Pusher server library
If doing anything other than subscribing to public channels, such as authorizing a client to access a private or presence channel or publishing from your backend, you will need to configure a Pusher server-side library to point at Ably. Using Ruby as an example:
You're currently viewing the JavaScript docs. There either isn't a JavaScript code sample for this example, or this feature isn't supported in JavaScript. Switch language to view this example in a different language, or check which SDKs support this feature.
All other Pusher server libraries are configured in a similar way.
| Option | Description |
|---|---|
| app_id | Your Ably app ID. This is the part of the API key before the first dot. |
| key | Your Ably API key name. This is everything before the colon : in your API key. |
| secret | The secret portion of your API key. This is everything after the colon : in your API key. |
| host | Set the host to point to Ably: main.pusher.ably.net. |
| use_tls | Use TLS for the connection. This isn't required but is strongly recommended to avoid sending your API key secret over a plain text connection. |
Channel mapping
Ably and Pusher have different naming restrictions for channel names, and use namespaces differently.
Channel names are mapped when using the adapter as follows:
- Pusher public channels will use the
public:namespace. - Pusher private channels will use the
private:namespace. - Pusher presence channels will use the
presence:namespace. - Channels not in any of the above namespaces were receive a
private-ablyroot-prefix.
Colons are not permitted in Pusher channel names, but are used as namespace separators in Ably. Because of this, the adapter maps semicolons to colons in Ably channel names and colons to semicolons in Pusher channel names. This means that you will be unable to access any Ably channels with semicolons in their name.
The following are some example channel name mappings:
| Pusher Adapter channel | Ably channel |
|---|---|
| presence-foo | presence:foo |
| private-foo | private:foo |
| foo | public:foo |
| foo;bar | public:foo:bar |
| private-ablyroot-foo | foo |
| private-ablyroot-foo;bar | foo:bar |
User and subscriber count
Both user count and subscriber count currently only work on presence channels.
- User count returns the size of the presence set once it has been made unique by
clientId. - Subscriber count returns the raw size of the presence set.