final client = StreamVideo(
'REPLACE_WITH_API_KEY',
user: User.regular(
userId: 'REPLACE_WITH_USER_ID',
name: 'John Doe',
),
userToken: 'REPLACE_WITH_TOKEN',
);
Client and Authentication
StreamVideo
is the main class used for creating class, performing authentication and listening to core events dispatched by Stream’s servers.
Before joining a call, it is necessary to set up the video client. Here’s a basic example:
- The API Key can be found in your Stream dashboard.
- The User can be either authenticated, anonymous or guest.
- Note: You can store custom data on the user object, if required.
StreamVideo
is the main class used for creating class, performing authentication and listening to core events dispatched by Stream’s servers.
The initialization constructor for StreamVideo
also exposes many customization options which can be overridden based on the project needs such as the logging level, SDP policy, retry policy, etc.
factory StreamVideo(
String apiKey, {
StreamVideoOptions options = StreamVideoOptions(
coordinatorRpcUrl: _defaultCoordinatorRpcUrl,
coordinatorWsUrl: _defaultCoordinatorWsUrl,
latencySettings: const LatencySettings(),
sdpPolicy: const SdpPolicy(),
retryPolicy: const RetryPolicy(),
logPriority: Priority.none,
logHandlerFunction: _defaultLogHandler,
muteVideoWhenInBackground: false,
muteAudioWhenInBackground: false,
autoConnect: true,
includeUserDetailsForAutoConnect: true,
keepConnectionsAliveWhenInBackground: false,
),
required User user,
String? userToken,
TokenLoader? tokenLoader,
OnTokenUpdated? onTokenUpdated,
bool failIfSingletonExists = true,
PNManagerProvider? pushNotificationManagerProvider,
});
The SDK tries to connect to Stream’s backend automatically by default. You can set autoConnect
to false in StreamVideoOptions
to change this behaviour.
If you choose to connect later, you can use the connect()
method to connect to Stream Video:
StreamVideo.instance.connect();
The connection passes the user info by default to the backend.
To change this, you can set the includeUserDetailsForAutoConnect
parameter in StreamVideoOptions
when auto-connecting
or use the includeUserDetails
parameter when using the connect()
method:
StreamVideo.instance.connect(
includeUserDetails: false,
);
Working with Tokens
All tokens must be generated via a backend SDK and cannot be created from a frontend client. This step is typically included whenever a new user is registered on your backend.
Here’s a valid user and token to help you get started on the client side, before integrating with your backend API.
Here are credentials to try out the app with:
Property | Value |
---|---|
API Key | mmhfdzb5evj2 |
Token | eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwczovL3Byb250by5nZXRzdHJlYW0uaW8iLCJzdWIiOiJ1c2VyL0FzYWpqX1ZlbnRyZXNzIiwidXNlcl9pZCI6IkFzYWpqX1ZlbnRyZXNzIiwidmFsaWRpdHlfaW5fc2Vjb25kcyI6NjA0ODAwLCJpYXQiOjE3MzUwNTgyMTUsImV4cCI6MTczNTY2MzAxNX0.PYRk8kBIpw3jki6PBZ45K0OHLzdFGWaA8rJvx1hmkac |
User ID | Asajj_Ventress |
Call ID | aLnnkaUgGn0v |
There are a few ways in which users can connect using our SDK.
We support both long lived tokens and dynamic tokens via two parameters accessible on the StreamVideo
class:
StreamVideo(apiKey, user: User, userToken: String)
StreamVideo(apiKey, user: User, tokenLoader: TokenLoader)
For situations where your backend does not require tokens to be refreshed, the first variant of the two above can be used by simply passing in a User
object and the userToken
as a String
.
Using the second variant, a Token Loader can be used to dynamically load a token from a server. On expiration, the SDK automatically calls the Token Loader to obtain a new token.
As long as your handler returns a String
it will satisfy the contract of TokenLoader
.
Here is an example of how you could write the token loader
Future<String> _tokenLoader(String userId) async {
final token = await backend.loadToken(
apiKey: Env.apiKey,
userId: userId,
);
return token;
}
StreamVideo(
apiKey,
user: user,
tokenLoader: _tokenLoader,
onTokenUpdated: (token) async {
// Callback function with the token.
// Called when the token is updated.
},
);
Guest / Anonymous users
For use-cases like live streaming or guest meeting, you may want to allow users to join a call without creating an account.
Guest Users
For these use-cases, the SDK has a guest endpoint which can be used to create a temporary user
final guest = User.guest(userId: guestId, name: guestName, image: guestImage);
final client = StreamVideo(
apiKey,
user: guest,
);
final result = await client.connect();
// if result wasn't successful, then result will return null
final userToken = result.getDataOrNull();
final userInfo = client.currentUser;
userInfo.id
will be slightly different from what you passed in. This is because the SDK will generate a unique ID for the user.
Please use the generated ID across your app.
Anonymous Users
final anonymous = User.anonymous();
final client = StreamVideo(
apiKey,
user: anonymous,
);
Anonymous users don’t establish an active web socket connection, therefore they won’t receive any events. They are just able to watch a livestream or join a call.
The token for an anonymous user should contain the call_cids
field, which is an array of the call cid
’s that the user is allowed to join.
Here’s an example JWT token payload for an anonymous user:
{
"iss": "@stream-io/dashboard",
"iat": 1726406693,
"exp": 1726493093,
"user_id": "!anon",
"role": "viewer",
"call_cids": [
"livestream:123"
]
}