Skip to content

Commit

Permalink
mention eventsub-ws in docs, remove HTTP specific concerns from overv…
Browse files Browse the repository at this point in the history 
…iew table
  • Loading branch information
@d-fischer
d-fischer committed Nov 17, 2022
1 parent e7bb61d commit 99853ba
Show file tree
Hide file tree
Showing 2 changed files with 68 additions and 29 deletions.
58 changes: 49 additions & 9 deletions docs/getting-data/eventsub/listener-setup.md
View file
Original file line number Diff line number Diff line change
@@ -1,13 +1,12 @@
:::warning{title="Authentication"}

This section assumes that you have prepared [authentication](/docs/auth/) with an **app token**,
for example using the {@link ClientCredentialsAuthProvider}.
This section assumes that you have prepared [authentication](/docs/auth/).

:::

## Setting up an EventSub listener
## Setting up an HTTP EventSub listener

A prerequisite of EventSub is a working {@link ApiClient} instance.
A prerequisite of EventSub over HTTP is a working {@link ApiClient} instance using an app token.
With that, you can create an {@link EventSubHttpListener} instance,
which (in a basic setup without a reverse proxy) requires a trusted SSL certificate for the host name you provide.

Expand Down Expand Up @@ -48,6 +47,36 @@ If you are testing locally, you may need to forward the port to your development
A very helpful tool for that is [ngrok](/docs/getting-data/eventsub/ngrok) -
this even spares you from creating your own certificate in development!

## Setting up a WebSocket EventSub listener

You can also use EventSub over WebSockets. This is easier to set up especially in development,
and the only way to use EventSub on the client side (at the time of writing), but doesn't scale as well for many users,
as authenticated topics are limited to one user. Instead of an app token, you have to use a user token
(for example using the {@link RefreshingAuthProvider}).

The setup is similar to HTTP, except you don't need an adapter nor a secret,
and you create a {@link EventSubWsListener} instead.

For ease of demonstration, the following example uses a static token, but you should investigate
[the other auth providers](/docs/auth/).

```ts twoslash
// @module: esnext
// @target: ES2017
import { StaticAuthProvider } from '@twurple/auth';
import { ApiClient } from '@twurple/api';
import { EventSubWsListener } from '@twurple/eventsub-ws';

const clientId = 'YOUR_CLIENT_ID';
const accessToken = 'YOUR_ACCESS_TOKEN';

const authProvider = new StaticAuthProvider(clientId, accessToken);
const apiClient = new ApiClient({ authProvider });

const listener = new EventSubWsListener({ apiClient });
await listener.start();
```

## Subscribing to (and unsubscribing from) events

When your listener is set up, you can subscribe to all supported events using this listener:
Expand All @@ -56,8 +85,8 @@ When your listener is set up, you can subscribe to all supported events using th
// @module: esnext
// @target: ES2017
// @lib: es2015,dom
import { EventSubHttpListener } from '@twurple/eventsub-http';
declare const listener: EventSubHttpListener;
import { EventSubListener } from '@twurple/eventsub-base';
declare const listener: EventSubListener;
// ---cut---
const userId = 'YOUR_USER_ID';

Expand All @@ -70,18 +99,29 @@ const offlineSubscription = await listener.subscribeToStreamOfflineEvents(userId
});
```

The subscription will then automatically start.

When you don't want to listen to a particular event anymore, you just stop its subscription:

```typescript
```ts
await onlineSubscription.stop();
```

To start it back up after stopping, you can use:

```ts
await onlineSubscription.start();
```

Note that you don't need to call `.start()` after creating the subscription.
It's only used for subscriptions that you previously stopped manually.

## Testing events

You can use the Twitch CLI to test your subscriptions,
If using the HTTP listener, you can use the Twitch CLI to test your subscriptions,
but you need to take care about some implementation details of this library:
- At the end of each callback, each event has a unique identifier that is generally built by joining the event name and the other parameters (like the user ID) of the event.
- This user ID is also prepended to the secret you passed to generate an unique secret for each callback. After this, if the resulting string is longer than 100 characters, the last 100 characters will be taken as the secret.
- This user ID is also prepended to the secret you passed to generate a unique secret for each callback. After this, if the resulting string is longer than 100 characters, the last 100 characters will be taken as the secret.

The easiest way to get the proper test command is by using the method {@link EventSubSubscription#getCliTestCommand}}:

Expand Down
39 changes: 19 additions & 20 deletions docs/getting-data/index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -51,23 +51,22 @@ should use for which use case.

## Events

| Event type | `@twurple/chat` | `@twurple/pubsub` | `@twurple/eventsub-*` |
|-----------------------------------|------------------------------|---------------------------|--------------------------------------|
| Chat messages | Yes | Sub & cheer messages only | Sub & cheer messages only |
| Chat mode (e.g. sub only) changes | Yes | No | No |
| Whispers | Yes | Yes | No |
| Cheers | Yes | Yes | Yes |
| Channel points | Redemptions w/ messages only | Redemptions only | Yes |
| Subscriptions | Published only | Published only | Yes |
| AutoMod | No | Yes | No |
| Live / offline / stream changes | No | No | Yes |
| Follows | No | No | Yes |
| Raids | Yes | No | Yes |
| Bans | Yes | Yes | Yes |
| Mod add/remove | No | Yes | Yes |
| Polls & predictions | No | No | Yes |
| Extension transactions | No | No | Yes |
| Hype Trains | No | No | Yes |
| Authorization grant/revoke | No | No | Yes |
| Drops | No | No | No (supported by Twitch) |
| Additional concerns | - | - | As of now, must have a public server |
| Event type | `@twurple/chat` | `@twurple/pubsub` | `@twurple/eventsub-*` |
|-----------------------------------|------------------------------|---------------------------|---------------------------|
| Chat messages | Yes | Sub & cheer messages only | Sub & cheer messages only |
| Chat mode (e.g. sub only) changes | Yes | No | No |
| Whispers | Yes | Yes | No |
| Cheers | Yes | Yes | Yes |
| Channel points | Redemptions w/ messages only | Redemptions only | Yes |
| Subscriptions | Published only | Published only | Yes |
| AutoMod | No | Yes | No |
| Live / offline / stream changes | No | No | Yes |
| Follows | No | No | Yes |
| Raids | Yes | No | Yes |
| Bans | Yes | Yes | Yes |
| Mod add/remove | No | Yes | Yes |
| Polls & predictions | No | No | Yes |
| Extension transactions | No | No | Yes |
| Hype Trains | No | No | Yes |
| Authorization grant/revoke | No | No | Yes |
| Drops | No | No | No (supported by Twitch) |

0 comments on commit 99853ba

Please sign in to comment.