From 9a4f257d9976b4773edf18b28ce0a53a8fcbdfe7 Mon Sep 17 00:00:00 2001 From: Oliver Lazoroski Date: Thu, 7 Sep 2023 13:28:36 +0200 Subject: [PATCH] docs: accommodate various docs feedback (#1063) Accommodates some of the received feedback about our docs. --- .../javascript/01-basics/03-quickstart.mdx | 23 +++++--- .../02-guides/04-camera-and-microphone.mdx | 20 +++---- .../javascript/02-tutorials/02-audio-room.mdx | 6 --- .../docs/javascript/10-advanced/06-events.mdx | 51 ++++++++++++++---- .../javascript/10-advanced/08-recording.mdx | 24 ++++++++- .../docs/React/01-basics/03-quickstart.mdx | 2 +- .../docs/React/02-guides/01-client-auth.mdx | 33 +++++------- .../docs/React/10-advanced/06-events.mdx | 52 +++++++++++++++---- 8 files changed, 144 insertions(+), 67 deletions(-) delete mode 100644 packages/client/docusaurus/docs/javascript/02-tutorials/02-audio-room.mdx diff --git a/packages/client/docusaurus/docs/javascript/01-basics/03-quickstart.mdx b/packages/client/docusaurus/docs/javascript/01-basics/03-quickstart.mdx index 11bd060862..952f7626b4 100644 --- a/packages/client/docusaurus/docs/javascript/01-basics/03-quickstart.mdx +++ b/packages/client/docusaurus/docs/javascript/01-basics/03-quickstart.mdx @@ -6,7 +6,6 @@ description: How to Build a Web Video Calling App import { TokenSnippet } from '../../../shared/_tokenSnippet.jsx'; This tutorial gives you a quick overview of how Stream's video JavaScript client works. - The code snippets use TypeScript, but you can use the library with JavaScript as well. ## Client setup & Calls @@ -21,9 +20,7 @@ const token = 'authentication-token'; const user: User = { id: 'user-id' }; const client = new StreamVideoClient({ apiKey, token, user }); - const call = client.call('default', 'call-id'); - call.join({ create: true }); ``` @@ -40,12 +37,24 @@ For an easy setup, you can copy the following credentials to use for the tutoria Once we join a call, we can start publishing audio and video: ```typescript -call.join({ create: true }).then(async () => { - call.camera.enable(); - call.microphone.enable(); -}); +await call.join({ create: true }); + +await call.camera.enable(); +await call.microphone.enable(); ``` +Or, if you wish to join a call with both, audio and video muted: + +```typescript +await call.microphone.disable(); +await call.camera.disable(); + +await call.join({ create: true }); +``` + +Please note that if the integrator omits enabling or disabling the camera and microphone, +our SDK will respect the [Call Type Settings](../../guides/configuring-call-types/) as defined in the dashboard. + More information about this topic can be found in the [Camera & Microphone guide](../../guides/camera-and-microphone). ## Render video diff --git a/packages/client/docusaurus/docs/javascript/02-guides/04-camera-and-microphone.mdx b/packages/client/docusaurus/docs/javascript/02-guides/04-camera-and-microphone.mdx index fb00815831..96d4d90d12 100644 --- a/packages/client/docusaurus/docs/javascript/02-guides/04-camera-and-microphone.mdx +++ b/packages/client/docusaurus/docs/javascript/02-guides/04-camera-and-microphone.mdx @@ -83,11 +83,11 @@ If you're building a lobby screen, this is how you can apply the backend setting await call.get(); // fallback in case no backend setting let defaultDirection: CameraDirection = 'front'; -const backendSetting = this.state.settings?.video.camera_facing; +const backendSetting = call.state.settings?.video.camera_facing; if (backendSetting) { defaultDirection = backendSetting === 'front' ? 'front' : 'back'; } -this.camera.selectDirection(defaultDirection); +call.camera.selectDirection(defaultDirection); ``` ### Render video @@ -122,13 +122,11 @@ if (videoEl.srcObject !== call.camera.state.mediaStream) { ### Start-stop microphone ```typescript -const toggleMicrophone = () => { - call.microphone.toggle(); +call.microphone.toggle(); - // or - call.microphone.enable(); - call.microphone.disable(); -}; +// or +call.microphone.enable(); +call.microphone.disable(); ``` This is how you can access the microphone status: @@ -145,7 +143,11 @@ If you're building a lobby screen, this is how you can apply the backend setting ```typescript await call.get(); const defaultMicStatus = call.state.settings?.audio.mic_default_on; -defaultMicStatus ? call.microphone.enable() : call.microphone.disable(); +if (defaultMicStatus) { + call.microphone.enable(); +} else { + call.microphone.disable(); +} ``` ### List and select devices diff --git a/packages/client/docusaurus/docs/javascript/02-tutorials/02-audio-room.mdx b/packages/client/docusaurus/docs/javascript/02-tutorials/02-audio-room.mdx deleted file mode 100644 index 7c5d786ee0..0000000000 --- a/packages/client/docusaurus/docs/javascript/02-tutorials/02-audio-room.mdx +++ /dev/null @@ -1,6 +0,0 @@ ---- -title: Audio Room Tutorial -description: How to build an audio room using Stream's JavaScript Client ---- - -This tutorial is coming soon diff --git a/packages/client/docusaurus/docs/javascript/10-advanced/06-events.mdx b/packages/client/docusaurus/docs/javascript/10-advanced/06-events.mdx index b29551a67d..fdf65fbfc8 100644 --- a/packages/client/docusaurus/docs/javascript/10-advanced/06-events.mdx +++ b/packages/client/docusaurus/docs/javascript/10-advanced/06-events.mdx @@ -103,7 +103,7 @@ The `on` method returns a method that can be called to unsubscribe from WebSocke Subscribing to all events: ```typescript -import { StreamVideoClient } from '@stream-io/video-client'; +import { StreamVideoClient, StreamVideoEvent } from '@stream-io/video-client'; let client: StreamVideoClient; @@ -119,7 +119,7 @@ unsubscribe(); Subscribing to `call.created` events: ```typescript -import { StreamVideoClient } from '@stream-io/video-client'; +import { StreamVideoClient, StreamVideoEvent } from '@stream-io/video-client'; let client: StreamVideoClient; @@ -136,18 +136,17 @@ unsubscribe(); ## Listening to call events -You can use the `on` method of the `Call` instance to subscribe to WebSocket events belonging to a specific call. - -The `on` method takes the type of the event you want to subscribe to. +You can use the `on` method of the `call` instance to subscribe to WebSocket events belonging to a specific call. -The event handler will receive an object with type [`StreamCallEvent`](https://github.com/GetStream/stream-video-js/blob/main/packages/client/src/coordinator/connection/types.ts) that has a `type` attribute that tells the type of the event. The available event types are described by the [`CallEventTypes`](https://github.com/GetStream/stream-video-js/blob/main/packages/client/src/coordinator/connection/types.ts) type. - -The `on` method returns a method that can be called to unsubscribe from WebSocket events. +The `call.on` method takes the type of the event you want to subscribe to. +The event handler will receive an object with type [`StreamCallEvent`](https://github.com/GetStream/stream-video-js/blob/main/packages/client/src/coordinator/connection/types.ts) that has a `type` attribute that tells the type of the event. +The available event types are described by the [`CallEventTypes`](https://github.com/GetStream/stream-video-js/blob/main/packages/client/src/coordinator/connection/types.ts) type. +The `call.on` method returns a method that can be called to unsubscribe from WebSocket events. -Subscribing to `call.reaction_new` event. +**Example:** Subscribing to `call.reaction_new` event: ```typescript -import { Call } from '@stream-io/video-client'; +import { Call, StreamVideoEvent } from '@stream-io/video-client'; let call: Call; @@ -161,3 +160,35 @@ const unsubscribe = call.on('call.reaction_new', (event: StreamVideoEvent) => { // Unsubscribe unsubscribe(); ``` + +## Custom events + +You can send custom events between the call participants using the `sendCustomEvent` method of the `call` instance. +Note that the payload for these events is limited to 5KB in size. + +```typescript +import { + Call, + CustomVideoEvent, + StreamVideoEvent, +} from '@stream-io/video-client'; + +let call: Call; + +// sending a custom event +await call.sendCustomEvent({ + type: 'my-event-type', + payload: { + foo: 'bar', + }, +}); + +// receiving a custom event +call.on('custom', (event: StreamVideoEvent) => { + const customEvent = event as CustomVideoEvent; + const payload = customEvent.custom; + if (payload.type === 'my-event-type') { + console.log(payload.foo); + } +}); +``` diff --git a/packages/client/docusaurus/docs/javascript/10-advanced/08-recording.mdx b/packages/client/docusaurus/docs/javascript/10-advanced/08-recording.mdx index 952d871853..8c63a34baa 100644 --- a/packages/client/docusaurus/docs/javascript/10-advanced/08-recording.mdx +++ b/packages/client/docusaurus/docs/javascript/10-advanced/08-recording.mdx @@ -14,7 +14,13 @@ The `Call` objects exposes the call recording API. To start recording, we simply To determine, whether a call recording is in progress, we use `call.state.recording$` Observable. This may serve us well, when we want to provide visual clues about the recording state. We have to be aware, that it can take few moments until a call recording starts. We recommend to keep own state signalling that the call recording is starting, but has not begun yet. ```typescript -TODO: example; +import { Call } from '@stream-io/video-client'; + +let call: Call; +await call.startRecording(); + +// to stop the recording +await call.stopRecording(); ``` ### Permissions @@ -22,7 +28,21 @@ TODO: example; To start and stop recording, the user has to have corresponding permissions. ```typescript -TODO: example; +import { Call, OwnCapability } from '@stream-io/video-client'; +let call: Call; + +if (call.permissionsContext.hasPermission(OwnCapability.START_RECORD_CALL)) { + await call.startRecording(); +} else { + // handle lack of permissions +} + +// to stop the recording +if (call.permissionsContext.hasPermission(OwnCapability.STOP_RECORD_CALL)) { + await call.stopRecording(); +} else { + // handle lack of permissions +} ``` To learn more about permissions, take a look at our [permissions guide](../../guides/permissions-and-moderation). diff --git a/packages/react-sdk/docusaurus/docs/React/01-basics/03-quickstart.mdx b/packages/react-sdk/docusaurus/docs/React/01-basics/03-quickstart.mdx index d6062d5249..f53eba0dea 100644 --- a/packages/react-sdk/docusaurus/docs/React/01-basics/03-quickstart.mdx +++ b/packages/react-sdk/docusaurus/docs/React/01-basics/03-quickstart.mdx @@ -27,7 +27,7 @@ const user: User = { id: userId }; const client = new StreamVideoClient({ apiKey, user, token }); const call = client.call('default', 'my-first-call'); -myCall.join({ create: true }); +call.join({ create: true }); export const App = () => { return ( diff --git a/packages/react-sdk/docusaurus/docs/React/02-guides/01-client-auth.mdx b/packages/react-sdk/docusaurus/docs/React/02-guides/01-client-auth.mdx index 23b3211f77..203034bdd4 100644 --- a/packages/react-sdk/docusaurus/docs/React/02-guides/01-client-auth.mdx +++ b/packages/react-sdk/docusaurus/docs/React/02-guides/01-client-auth.mdx @@ -12,14 +12,10 @@ Before joining a call, it is necessary to set up the video client. Here's a basi import { StreamVideoClient, User } from '@stream-io/video-react-sdk'; const user: User = { - id: 'sara'; + id: 'sara', }; -const client = new StreamVideoClient({ - apiKey, - token, - user, -}); +const client = new StreamVideoClient({ apiKey, token, user }); ``` - The API Key can be found in your dashboard. @@ -52,10 +48,7 @@ const user: User = { type: 'guest', }; -const client = new StreamVideoClient({ - apiKey, - user, -}); +const client = new StreamVideoClient({ apiKey, user }); ``` And here's an example for an anonymous user @@ -67,10 +60,7 @@ const user: User = { type: 'anonymous', }; -const client = new StreamVideoClient({ - apiKey, - user, -}); +const client = new StreamVideoClient({ apiKey, user }); ``` ## Client options @@ -83,14 +73,16 @@ To authenticate users you can either provide a string `token` or a `tokenProvide You can configure the log level and the logger method used by the SDK. -The default log level is `warn`, other options are: `debug`, `info`, and `error`. +The default log level is `warn`, other options are: `trace`, `debug`, `info`, and `error`. -The default logger method will log to the browser `console`. +The default logger method will log to the browser's `console`. ```ts import { StreamVideoClient, Logger } from '@stream-io/video-react-sdk'; -const myLogger: Logger; +const myLogger: Logger = (logLevel, message, ...args) => { + // Do something with the log message +}; const client = new StreamVideoClient({ apiKey, @@ -118,18 +110,17 @@ logLevelMapping.set('error', 'error'); export const customSentryLogger: Logger = ( logLevel: LogLevel, message: string, - extraData?: any, - tags?: string[], + ...args: unknown[] ) => { if (logLevel === 'warn' || logLevel === 'error') { Sentry.captureEvent({ level: logLevelMapping.get(logLevel), - extra: extraData, + extra: args, }); } // Call the SDK's default log method - logToConsole(logLevel, message, extraData, tags); + logToConsole(logLevel, message, { data: 'some data' }); }; ``` diff --git a/packages/react-sdk/docusaurus/docs/React/10-advanced/06-events.mdx b/packages/react-sdk/docusaurus/docs/React/10-advanced/06-events.mdx index b51459918b..ef9b94eaf0 100644 --- a/packages/react-sdk/docusaurus/docs/React/10-advanced/06-events.mdx +++ b/packages/react-sdk/docusaurus/docs/React/10-advanced/06-events.mdx @@ -32,8 +32,8 @@ import { StreamVideoClient } from '@stream-io/video-react-sdk'; let client: StreamVideoClient; await client.queryCalls({ - ... - watch: true + // ... + watch: true, }); ``` @@ -44,8 +44,7 @@ import { StreamVideoClient } from '@stream-io/video-react-sdk'; let client: StreamVideoClient; -const call = client.call('default', 'test-call'); -await call.join(); +await client.call('default', 'test-call').join(); ``` 3. Watch a call: @@ -143,15 +142,14 @@ unsubscribe(); ## Listening to call events -You can use the `on` method of the `Call` instance to subscribe to WebSocket events belonging to a specific call. +You can use the `on` method of the `call` instance to subscribe to WebSocket events belonging to a specific call. -The `on` method takes the type of the event you want to subscribe to. +The `call.on` method takes the type of the event you want to subscribe to. +The event handler will receive an object with type [`StreamCallEvent`](https://github.com/GetStream/stream-video-js/blob/main/packages/client/src/coordinator/connection/types.ts) that has a `type` attribute that tells the type of the event. +The available event types are described by the [`CallEventTypes`](https://github.com/GetStream/stream-video-js/blob/main/packages/client/src/coordinator/connection/types.ts) type. +The `call.on` method returns a method that can be called to unsubscribe from WebSocket events. -The event handler will receive an object with type [`StreamCallEvent`](https://github.com/GetStream/stream-video-js/blob/main/packages/client/src/coordinator/connection/types.ts) that has a `type` attribute that tells the type of the event. The available event types are described by the [`CallEventTypes`](https://github.com/GetStream/stream-video-js/blob/main/packages/client/src/coordinator/connection/types.ts) type. - -The `on` method returns a method that can be called to unsubscribe from WebSocket events. - -Subscribing to `call.reaction_new` event. +**Example:** Subscribing to `call.reaction_new` event: ```typescript import { Call, StreamVideoEvent } from '@stream-io/video-react-sdk'; @@ -168,3 +166,35 @@ const unsubscribe = call.on('call.reaction_new', (event: StreamVideoEvent) => { // Unsubscribe unsubscribe(); ``` + +## Custom events + +You can send custom events between the call participants using the `sendCustomEvent` method of the `call` instance. +Note that the payload for these events is limited to 5KB in size. + +```typescript +import { + Call, + CustomVideoEvent, + StreamVideoEvent, +} from '@stream-io/video-react-sdk'; + +let call: Call; + +// sending a custom event +await call.sendCustomEvent({ + type: 'my-event-type', + payload: { + foo: 'bar', + }, +}); + +// receiving a custom event +call.on('custom', (event: StreamVideoEvent) => { + const customEvent = event as CustomVideoEvent; + const payload = customEvent.custom; + if (payload.type === 'my-event-type') { + console.log(payload.foo); + } +}); +```