Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
43 changes: 41 additions & 2 deletions src/pages/docs/protocols/pusher.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -63,13 +63,14 @@ const pusher = new Pusher('appId.keyId', {
httpHost: 'main.pusher.ably.net',
disableStats: true,
forceTls: true,
cluster: 'eu'
cluster: 'eu',
authEndpoint: '...',
});
```
</Code>

<Aside data-type='note'>
You should only use your [Ably API key name](/docs/auth#format), not the full API key. This includes everything before the colon `:` in your API key.
You should only use your [Ably API key name](/docs/auth#format), not the full API key. This is the part before the colon `:`.
</Aside>

| Option | Description |
Expand All @@ -79,9 +80,40 @@ You should only use your [Ably API key name](/docs/auth#format), not the full AP
| 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](#configure-rest), if you are using one. |

You can also add any other Pusher options that you normally use.

### Configure a Pusher server library <a id="configure-rest"/>

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:

<Code>
```ruby
Pusher::Client.new(
app_id: 'appId',
key: 'appId.keyId',
secret: 'keySecret',
host: 'main.pusher.ably.net',
use_tls: true
)
```
</Code>

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](/docs/auth#format). 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. |

<Aside data-type='note'>
The adapter uses the standard Ably service behind the scenes, so you can use Pusher and Ably SDKs side-by-side against the same channels. For example, you can publish and subscribe using Pusher libraries, but use the [Ably REST API](/docs/api/rest-api) to retrieve [message history](/docs/storage-history/history), which isn't available through the Pusher libraries. Bear in mind [channel name mapping](#mapping) when mixing libraries.
</Aside>

## Channel mapping <a id="mapping"/>

Ably and Pusher have different naming restrictions for channel names, and use namespaces differently.
Expand All @@ -105,3 +137,10 @@ The following are some example channel name mappings:
| foo;bar | public:foo:bar |
| private-ablyroot-foo | foo |
| private-ablyroot-foo;bar | foo:bar |

## User and subscriber count <a id="counts"/>

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.