From 273421c745fe81ecd9fbf03c9676b2d266e0711b Mon Sep 17 00:00:00 2001 From: Zita Szupera Date: Wed, 25 Oct 2023 11:33:49 +0200 Subject: [PATCH] basic explanations for the Basics sections --- .../docs/api/basics/authentication.mdx | 114 +++++++++++++++--- .../docusaurus/docs/api/basics/calls.mdx | 37 +++++- .../docs/api/basics/get_started.mdx | 48 +++++++- 3 files changed, 174 insertions(+), 25 deletions(-) diff --git a/docusaurus/video/docusaurus/docs/api/basics/authentication.mdx b/docusaurus/video/docusaurus/docs/api/basics/authentication.mdx index 4afbfe42..09cccdfa 100644 --- a/docusaurus/video/docusaurus/docs/api/basics/authentication.mdx +++ b/docusaurus/video/docusaurus/docs/api/basics/authentication.mdx @@ -10,18 +10,24 @@ import TabItem from '@theme/TabItem'; ## Creating users +Stream Users require only an id to be created. Users can be created with role of user or admin. The role will be set to user if a value is not provided in the request. There are additional properties you can provide to further describe your users. + +The `name` and `image` fields are special fields that are supported by client-side SDKs. + +You can provide additional data for the user object using the `custom` field. + ```js const newUser: UserObjectRequest = { id: 'userid', - role: "user", + role: 'user', custom: { - color: 'red' + color: 'red', }, name: 'This is a test user', - image: 'link/to/profile/image' + image: 'link/to/profile/image', }; await client.upsertUsers({ users: { @@ -35,18 +41,23 @@ await client.upsertUsers({ ## Updating users +There are two ways to update user objects: + +- Updating will replace the existing user object +- Partial update will let you choose which fields you want to chage/unset + ```js const user: UserObjectRequest = { id: 'userid', - role: "user", + role: 'user', custom: { - color: 'red' + color: 'red', }, name: 'This is a test user', - image: 'link/to/profile/image' + image: 'link/to/profile/image', }; client.upsertUsers({ users: { @@ -55,22 +66,71 @@ client.upsertUsers({ }); // or -client.updateUsersPartial({users: [ - { - id: user.id, - set: { - color: 'blue' - }, - unset: ['name'], - } -]}); +client.updateUsersPartial({ + users: [ + { + id: user.id, + set: { + color: 'blue', + }, + unset: ['name'], + }, + ], +}); ``` +## Anonymous users + +Anonymous users are users that are not authenticated. It's common to use this for watching a livestream or similar where you aren't authenticated. Anonymous users can be connected using client-side SDKs. + +## Guest users + +Guest users are temporary user accounts. You can use it to temporarily give someone a name and image when joining a call. Guest users can aslso be created cliend-side. + + + + +```js +const guest: UserObjectRequest = { + id: '', + name: '', + custom: { + color: 'red', + }, +}; + +const guest = (await client.createGuest({ user: guest })).user; +``` + + + + +## Deactivating and deleting users + +While it is usually safer for data retention to deactivate a user, some use cases require completely deleting a user and their data. + +Once a user has been deleted, it cannot be un-deleted and the user_id cannot be used again. + +```js +client.deactivateUser({ + user_id: '', +}); + +client.deleteUser({ userId: '' }); +``` + ## User tokens +Stream uses JWT (JSON Web Tokens) to authenticate chat users, enabling them to login. Knowing whether a user is authorized to perform certain actions is managed separately via a role based permissions system. Tokens need to be generated server-side. + +You can optionally provide + +- expiration time +- issued at date which is necessary if you manually wan to revoke tokens + @@ -130,6 +190,8 @@ func main() { ## Call tokens +Call tokens contain a list of call IDs. If a user is authenticated with a call token, they can only access the specified calls. + @@ -142,7 +204,12 @@ const iat = Math.round(new Date().getTime() / 1000); const call_cids = ['default:call1', 'livestream:call2']; -client.createToken(user_id=user_id, exp=exp, iat=iat, call_cids=call_cids); +client.createToken( + (user_id = user_id), + (exp = exp), + (iat = iat), + (call_cids = call_cids), +); ``` @@ -192,5 +259,16 @@ func main() { ## Token expiration and token providers -TODO: explain that tokens should have an expiration -TODO: mention that in a production environment you have an endpoint to send fresh tokens to users +At a high level, the Token Provider is an endpoint on your server that can perform the following sequence of tasks: + +1. Receive information about a user from the front end. + +2. Validate that user information against your system. + +3. Provide a User-ID corresponding to that user to the server client's token creation method. + +4. Return that token to the front end. + +Tokens can only be safely generated from a server. This means you will need to implement a Token Provider prior to deploying your application to production. To conduct development before implementing a Token Provider, you will need to disable token authentication. + +Tokens also should have an expiration date to ensure adequate security. Once a token is expired, cliend-side SDKs can automatically call an endpoint to refresh the token, this endpoint should also be part of the Token Provider implementation. diff --git a/docusaurus/video/docusaurus/docs/api/basics/calls.mdx b/docusaurus/video/docusaurus/docs/api/basics/calls.mdx index 495f4f0f..5d3859e7 100644 --- a/docusaurus/video/docusaurus/docs/api/basics/calls.mdx +++ b/docusaurus/video/docusaurus/docs/api/basics/calls.mdx @@ -10,6 +10,13 @@ import TabItem from '@theme/TabItem'; ## Creating calls +You can create a call by providing the call type and an ID: + +- The [call type](call_types/builtin) controls which features are enabled, and sets up permissions. +- Calls IDs can be reused, which means they can be joined multiple times, so it's possible to set up recurring calls. + +You can optionally restrict call access by providing a list of users. + @@ -47,9 +54,9 @@ call.get_or_create_call( created_by_id='john', members=[ MemberRequest( - user_id: 'john', + user_id: 'john', role: 'admin' - ), + ), MemberRequest( user_id: 'jack' ) @@ -113,11 +120,19 @@ curl -X POST "https://video.stream-io-api.com/video/call/default/${CALL_ID}?api_ ## Updating calls +- Most of the call type settings can be overriden on a call level. + +- Custom data can also be stored for calls. + ```js -call.update({ settings_override: { audio: { mic_default_on: true, default_device: "speaker" } } }); +call.update({ + settings_override: { + audio: { mic_default_on: true, default_device: 'speaker' }, + }, +}); // or to update custom data call.update({ custom: { color: 'red' } }); @@ -212,6 +227,8 @@ curl -X PUT "https://video.stream-io-api.com/video/call/default/${CALL_ID}?api_k ## Manage call members +Call members can be added and removed as necessary. Their role's can also be changed. + @@ -235,7 +252,7 @@ call.updateCallMembers({ call.update_call( members=[ - MemberRequest(user_id: 'sara'), + MemberRequest(user_id: 'sara'), MemberRequest(user_id: 'jack', role: 'admin') ] ) @@ -312,6 +329,14 @@ curl -X PUT "https://video.stream-io-api.com/video/call/default/${CALL_ID}/membe ## Query calls +For many video calling, live stream, or audio rooms apps, you'll want to show: + +- Upcoming calls +- Calls that are currently live +- Popular live streams / audio rooms with a link to the recording + +Below you can find a few examples of different quieries: + @@ -368,6 +393,8 @@ call.query_calls( +Filter expressions support multiple match criteria and it's also possible to combine filters. For more information visit the [filter operators](https://getstream.io/chat/docs/node/query_syntax_operators/?language=javascript) guide. + ## Query call members @@ -425,3 +452,5 @@ call.query_members( + +Filter expressions support multiple match criteria and it's also possible to combine filters. For more information visit the [filter operators](https://getstream.io/chat/docs/node/query_syntax_operators/?language=javascript) guide. diff --git a/docusaurus/video/docusaurus/docs/api/basics/get_started.mdx b/docusaurus/video/docusaurus/docs/api/basics/get_started.mdx index 8bdcf4de..ac6ae0c2 100644 --- a/docusaurus/video/docusaurus/docs/api/basics/get_started.mdx +++ b/docusaurus/video/docusaurus/docs/api/basics/get_started.mdx @@ -7,7 +7,13 @@ title: Get started import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; -import RTMP from '../_common_/rtmp.mdx' +import RTMP from '../_common_/rtmp.mdx'; + +For the average Stream integration, the development work focuses on code that executes in the client. However, some tasks must be executed from the server for safety (for example token generation). + +Stream provides server-side SDKs to help executing these tasks. + +You can reference our [development roadmap](https://github.com/GetStream/protocol/discussions/177) to know which languages and features are supported. ## Installation @@ -39,6 +45,8 @@ go get github.com/GetStream/video-go-sdk ## Creating client +To create a server-side client you'll need your **API key** and **secret**, both of them can be found in your [Stream Dashboard](https://dashboard.getstream.io/). + @@ -75,6 +83,8 @@ TODO ## Creating user tokens +Tokens need to be generated server-side. Typically you integrate this into the part of your codebase where you login or register users. The tokens provide a way to authenticate a user or give access to a specific set of video/audio calls. + @@ -130,6 +140,13 @@ func main() { ## Creating a call +You can create a call by providing the call type and an ID: + +- The [call type](call_types/builtin) controls which features are enabled, and sets up permissions. +- Calls IDs can be reused, which means they can be joined multiple times, so it's possible to set up recurring calls. + +You can optionally restrict call access by providing a list of users. + @@ -299,11 +316,19 @@ curl -X PUT "https://video.stream-io-api.com/video/call/default/${CALL_ID}/membe ## Updating a call +- Most of the call type settings can be overriden on a call level. + +- Custom data can also be stored for calls. + ```js -call.update({ settings_override: { audio: { mic_default_on: true, default_device: "speaker" } } }); +call.update({ + settings_override: { + audio: { mic_default_on: true, default_device: 'speaker' }, + }, +}); // or to update custom data call.update({ custom: { color: 'red' } }); @@ -396,6 +421,17 @@ curl -X PUT "https://video.stream-io-api.com/video/call/default/${CALL_ID}?api_k ## Start HLS broadcasting +Broadcasting serves are a means of transmitting live or pre-recorded content to a wide audience. + +We can choose from two approaches to broadcasting the media: + +- [HLS](https://en.wikipedia.org/wiki/HTTP_Live_Streaming) - slight delay, better buffering +- [WebRTC](https://webrtc.org/) - lower latency, less reliability + +It is up to the integrators to decide, what approach will be used in their apps for the audience to consume the streams. + +For more information see the [Streaming section](streaming/overview/). + @@ -473,10 +509,16 @@ curl -X POST "https://video.stream-io-api.com/video/call/default/${CALL_ID}/star ## Set up a call for RTMP - +Almost all livestream software and hardware supports RTMPS. Our API supports using a third-party software for streaming using RTMPS. For more information reference the [Streaming section](streaming/overview/). + + ## Start call recording +Calls can be recorded for later use. Calls recording can be started/stopped via API calls or configured to start automatically when the first user joins the call. + +For more information see the [Recordings section](recording/calls/). +