Developer guide

Quick start: join an audio room

Mint a token on your own backend, hand it to the kit with tokenProvider, and the user is in the room.

Zurück zu Entwickler

Applies to: utd_audio_room_kit 3.14.1, utd_live_room_kit 3.11.0

Your backend, not the app, tells UTD Stream who the user is. The app asks your backend for a token, your backend asks UTD Stream with your Server Secret, and the answer goes back to the app. The App Key on its own can no longer mint a token that names a user: on a project with default settings it is refused with 403 appkey_identity_mint_disabled.

Older quick starts told you to pass only appId and appKey ("no backend"). That path works only on projects that still carry the per-project exception allow_appkey_identity_mint, and it is not offered to new projects. Use the flow below.

1. Create a project and copy two values

  • Create a project in the dashboard (UTD Stream, then New project) and enable the room type you need: audio rooms or live streaming.
  • Copy the App ID and the Server Secret. The Server Secret stays on your server and never ships in the app.
  • The App Key is the project's public identifier. The kits still take it as a parameter, but it cannot sign a token for a user.

2. One endpoint on your backend

Put it behind your own login. Read the user from your session, never from the body the app sends. Forward the device facts the app sends you and the end user's own IP: your server cannot see either on its own (see Minting tokens from your backend for what each field changes).

backend/rooms.js (Node 18+, Express)
import express from "express";

const app = express();
app.use(express.json());
app.set("trust proxy", 1); // only if you run behind ONE trusted proxy; then req.ip is the user's address

app.post("/rooms/:roomId/token", requireLogin, async (req, res) => {
  const upstream = await fetch("https://udt-stream.com/api/v1/token", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-App-Id": process.env.UTD_APP_ID,
      "X-App-Secret": process.env.UTD_SERVER_SECRET, // never ship this in the app
    },
    body: JSON.stringify({
      user_id: String(req.user.id),          // from YOUR session
      display_name: req.user.name,
      room_id: req.params.roomId,
      type: "audio_room",                    // or "live_stream"
      client_ip: req.ip,                     // the user's address, not your server's
      device_id: req.body.device_id,         // forwarded from the app
      device_model: req.body.device_model,
      os: req.body.os,
      os_version: req.body.os_version,
      app_version: req.body.app_version,
    }),
  });
  // Pass the answer through unchanged: { token, url, user_token, user_token_expires_in, ws_url, roomName, room_id, user_id, seats }
  res.status(upstream.status).json(await upstream.json());
});

Check it before you touch the app. A 200 with token, url and user_token means the project, the secret and the room type are right:

terminal
curl -X POST https://udt-stream.com/api/v1/token \
  -H "Content-Type: application/json" \
  -H "X-App-Id: $UTD_APP_ID" -H "X-App-Secret: $UTD_SERVER_SECRET" \
  -d '{"user_id":"u1","room_id":"lobby","type":"audio_room"}'

3. The app: pass tokenProvider

terminal
flutter pub add utd_audio_room_kit http
lib/room_page.dart
import 'dart:convert';
import 'package:flutter/material.dart';
import 'package:http/http.dart' as http;
import 'package:utd_audio_room_kit/utd_audio_room_kit.dart';

class RoomPage extends StatelessWidget {
  const RoomPage({super.key, required this.roomId, required this.ownerId});
  final String roomId;
  final String ownerId;

  @override
  Widget build(BuildContext context) {
    return UTDAudioRoom(
      appId: '<utd-app-id>',
      appKey: '<utd-app-key>', // identifies the project; cannot mint a user token by itself
      userId: me.id,
      userName: me.name,
      roomId: roomId,
      roomOwnerId: ownerId,
      tokenProvider: () async {
        final res = await http.post(
          Uri.parse('https://api.example.com/rooms/$roomId/token'),
          headers: {
            'Authorization': 'Bearer $yourSessionToken', // YOUR login, not UTD's
            'Content-Type': 'application/json',
          },
          body: jsonEncode({
            'device_id': await stableDeviceId(), // persisted, survives app restarts
            'device_model': deviceModel,
            'os': Platform.isAndroid ? 'android' : 'ios',
            'os_version': osVersion,
            'app_version': appVersion,
          }),
        );
        if (res.statusCode != 200) throw Exception('token ${res.statusCode}');
        return UTDTokenResponse.fromJson(jsonDecode(res.body) as Map<String, dynamic>);
      },
    );
  }
}

me, stableDeviceId(), deviceModel, osVersion, appVersion and yourSessionToken are yours. The kit calls tokenProvider on the first join and again on every automatic redial, so it must return a fresh token each time (see Reconnection).

Android build setup

The kits' dependencies (connectivity_plus, device_info_plus, flutter_webrtc, androidx.core 1.18) require compiling against Android API 36. On a fresh Flutter project the build fails with "requires libraries and applications that depend on it to compile against version 36 or later of the Android APIs" until you raise compileSdk to 36.

android/app/build.gradle.kts
android {
    compileSdk = 36
    // ...
}
android/build.gradle.kts (before evaluationDependsOn)
subprojects {
    afterEvaluate {
        extensions.findByType(com.android.build.gradle.BaseExtension::class.java)?.compileSdkVersion(36)
    }
}

The UTDAudioRoom and UTDLiveRoom widgets talk to UTD Stream's own engine and have no baseUrl parameter. After a 403 the controller stops dialing until the app starts a new join, so create a new controller for the next attempt. The 403 from the App Key arrives as UTDServiceNotAvailableException carrying appkey_identity_mint_disabled.

If tokenProvider throws or returns null, the widget falls back to minting with the App Key. On a project without the exception that fallback is refused with 403 appkey_identity_mint_disabled, so a failing provider shows up as exactly that error. UTDLiveRoom takes the same tokenProvider parameter, with type: "live_stream" on the backend.

What to read next

  • Minting tokens from your backend: every request field, the refusal codes and the auth modes.
  • Limits: how many people a room holds and how often you may call.
  • Errors: every code, what it means and what to do.
  • Reconnection: what the kit does when the network drops.

Bereit, mit UTD zu entwickeln?

Erstellen Sie Ihr Konto, laden Sie Ihre Master-Wallet auf und aktivieren Sie die Dienste, die Sie brauchen.