Client and Authentication

Client Overview

StreamVideo is the main class used for creating class, performing authentication and listening to core events dispatched by Stream’s servers.

Before users are able to join or create a call, the client must first be configured with an apiKey obtained from the Stream Dashboard for the given project.

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 automatically by default. You can set autoConnect to false in StreamVideoOptions to change this behaviour.

To connect later, you can use the connect() method:

    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.

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 can be used by simply passing in a User object and the userToken as a String.

Dynamic tokens

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

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.
  },
);

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.

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;

note

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 user the generated ID across your app.