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:

final client = StreamVideo(
  'REPLACE_WITH_API_KEY',
  user: User.regular(
    userId: 'REPLACE_WITH_USER_ID',
    name: 'John Doe',
  ),
  userToken: 'REPLACE_WITH_TOKEN',
);

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.

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"
  ]
}

Quickstart

Joining and Creating Calls