diff --git a/docs/getting-data/eventsub/listener-setup.md b/docs/getting-data/eventsub/listener-setup.md index 17cf09a6d..0307d29c0 100644 --- a/docs/getting-data/eventsub/listener-setup.md +++ b/docs/getting-data/eventsub/listener-setup.md @@ -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. @@ -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: @@ -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'; @@ -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}}: diff --git a/docs/getting-data/index.md b/docs/getting-data/index.md index 64155035d..590a07ad8 100644 --- a/docs/getting-data/index.md +++ b/docs/getting-data/index.md @@ -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) |