# Gravix Cloud: integration guide for AI coding assistants

> Add real-time voice, video and live streaming to a Flutter or web app. The app joins a room with a short-lived access token. The developer's own server signs that token with the App ID and App Certificate from the Gravix Cloud dashboard. Checked against gravix_rtc 0.4.13 (pub.dev) and gravix-rtc 0.6.6 (npm) on 8 October 2026.

Use only the packages, classes, options and events in this file. If you need something that is not here, ask the developer instead of guessing.

## 1. Packages

- Flutter (Android and iOS apps): `flutter pub add gravix_rtc`. One import: `import 'package:gravix_rtc/gravix_rtc.dart';`. Needs Flutter 3.38+ and Dart 3.10+. Android 7.0 (API 24)+, iOS 13+.
- Web (any framework, including React): `npm install gravix-rtc` (or `yarn add gravix-rtc`, `pnpm add gravix-rtc`). TypeScript types included. Pages must be served over HTTPS (a local development server on your own machine also works).
- Server, Node 18+, Deno, Bun or edge runtimes: `npm install gravix-rtc-token`, function `createToken(appId, appCertificate, options)`.
- Server, Go 1.21+: `gravix-token-go` (package `gravixtoken`), builder `gravixtoken.New(appID, appCertificate).Room(..).Identity(..).Name(..).CanPublish(..).TTL(..).ToJWT()`.
- Native Kotlin or Swift SDKs do not exist. Android and iOS apps use the Flutter SDK.

## 2. Token flow (do not change it)

1. The developer gets an App ID, an App Certificate and a region URL (wss://...) from the dashboard.
2. The backend exposes one endpoint, for example POST /rtc/token, behind the app's existing login.
3. The SDK POSTs JSON `{ "room": "...", "identity": "...", "name": "...", "can_publish": true|false }` to it.
4. The endpoint takes the identity from its own session (not from the body), decides whether the user may publish, signs a token and answers `{ "token": "<jwt>", "url": "<region url>" }`.
5. The app joins with that token. No Gravix Cloud service is called to make a token.

Rules:

- The App Certificate is a secret. Keep it in the server environment (GRAVIX_APP_CERTIFICATE). Never put it in app code, a mobile build, a web bundle, a .env file that ships to the browser, or a git repository.
- Tokens are short-lived: 6 hours by default, 24 hours at most (`ttlSeconds` in Node, `TTL` in Go).
- `canPublish: false` makes a listener or viewer. Decide it on the server.
- Pass the plain room name. The token library adds the App ID prefix itself.
- The identity in the token is the identity the user has in the room. Use the app's own user ID.

## 3. Server: token endpoint (Node)

```ts
// server.ts (your backend, Node 18+). This file never ships inside an app.
import express from 'express';
import { createToken } from 'gravix-rtc-token';

const APP_ID = process.env.GRAVIX_APP_ID!;                   // from your dashboard
const APP_CERTIFICATE = process.env.GRAVIX_APP_CERTIFICATE!; // server only, never in an app
const REGION_URL = process.env.GRAVIX_URL!;                   // wss://YOUR-REGION-URL

const app = express();
app.use(express.json());

// requireUser is your own login check: the identity comes from YOUR session,
// never from the request body.
app.post('/rtc/token', requireUser, async (req, res) => {
  const room = req.body?.room;
  if (typeof room !== 'string' || !/^[\w.-]{1,64}$/.test(room)) {
    return res.status(400).json({ error: 'invalid room' });
  }
  const token = await createToken(APP_ID, APP_CERTIFICATE, {
    room,                       // the library adds your App ID prefix
    identity: req.user.id,
    name: req.user.name,
    canPublish: true,           // false = listen only; decide it here, not in the app
    ttlSeconds: 60 * 60,        // short-lived: 1 hour
  });
  res.json({ token, url: REGION_URL });
});

app.listen(3000);
```

## 4. Server: token endpoint (Go)

```go
// token.go (your backend, Go 1.21+). gravixtoken is the gravix-token-go package.
func tokenHandler(w http.ResponseWriter, r *http.Request) {
	user, ok := currentUser(r) // your own login check
	if !ok {
		http.Error(w, "sign in first", http.StatusUnauthorized)
		return
	}
	var body struct {
		Room string `json:"room"`
	}
	if err := json.NewDecoder(r.Body).Decode(&body); err != nil || body.Room == "" {
		http.Error(w, "invalid room", http.StatusBadRequest)
		return
	}

	// The App Certificate stays in the server's environment.
	jwt, err := gravixtoken.New(os.Getenv("GRAVIX_APP_ID"), os.Getenv("GRAVIX_APP_CERTIFICATE")).
		Room(body.Room).
		Identity(user.ID).
		Name(user.Name).
		CanPublish(true). // false = listen only
		TTL(time.Hour).   // short-lived
		ToJWT()
	if err != nil {
		http.Error(w, "could not sign", http.StatusInternalServerError)
		return
	}
	w.Header().Set("Content-Type", "application/json")
	json.NewEncoder(w).Encode(map[string]string{
		"token": jwt,
		"url":   os.Getenv("GRAVIX_URL"), // wss://YOUR-REGION-URL
	})
}
```

## 5. Flutter client: join a room

```dart
import 'package:gravix_rtc/gravix_rtc.dart';

// One provider per signed-in user. It caches each token until it is about to expire.
final tokens = GravixTokenProvider.endpoint(
  Uri.parse('https://YOUR-BACKEND/rtc/token'),
  headers: {'Authorization': 'Bearer $sessionJwt'}, // your app's own login session
);

final room = GravixRoomService();

Future<void> join(String roomId, String userId, String name) async {
  room.onRemoteVideoTrack = (uid, track) {
    // show it with VideoTrackRenderer(track)
  };

  final ok = await room.connectWithTokenProvider(
    tokenProvider: tokens,
    request: GravixTokenRequest(
      room: roomId,
      identity: userId,
      name: name,
      canPublish: true,
    ),
    publishMic: true,
    enableVideo: true,
  );
  if (!ok) {
    // room.lastTokenError is set when your token endpoint failed
  }
}

Future<void> leave() => room.disconnect();
```

- `connectWithTokenProvider` returns false instead of throwing. `room.lastTokenError?.message` says why when the token endpoint failed.
- Observable state is `ValueNotifier`s: `isConnected`, `isMicMuted`, `isCameraEnabled`, `activeSpeakers`.
- Controls: `setMicEnabled(bool)`, `setCameraEnabled(bool)`, `switchCamera()`, `disconnect()`, then `dispose()` when the screen is gone.
- Video: `room.onRemoteVideoTrack = (uid, track) {...}`, `room.onRemoteVideoTrackRemoved = (uid) {...}`, own camera from `room.localVideoTrack`. Show a track with `VideoTrackRenderer(track, fit: VideoViewFit.cover)`.

## 6. Flutter platform setup

Android, android/app/src/main/AndroidManifest.xml:

```xml
<!-- android/app/src/main/AndroidManifest.xml -->
<manifest xmlns:android="http://schemas.android.com/apk/res/android">
  <uses-permission android:name="android.permission.INTERNET" />
  <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
  <uses-permission android:name="android.permission.RECORD_AUDIO" />
  <uses-permission android:name="android.permission.CAMERA" />
  <uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" />
  <!-- Bluetooth headsets: Android 12+ needs BLUETOOTH_CONNECT -->
  <uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
  <uses-permission android:name="android.permission.BLUETOOTH" android:maxSdkVersion="30" />
  <!-- ... your <application> ... -->
</manifest>
```

iOS, ios/Runner/Info.plist:

```xml
<!-- ios/Runner/Info.plist -->
<key>NSMicrophoneUsageDescription</key>
<string>Talk in calls</string>
<key>NSCameraUsageDescription</key>
<string>Video in calls</string>
<!-- Keep call audio playing with the screen locked or the app in the background -->
<key>UIBackgroundModes</key>
<array>
  <string>audio</string>
</array>
```

- Ask for microphone (and camera) access at runtime before the user joins with them on. On Android 12+ also request BLUETOOTH_CONNECT so Bluetooth headsets are found.
- Android background audio: the SDK has a foreground service, off by default. Turn it on once before the first join with `GravixForegroundService.defaults = const GravixForegroundServiceOptions(enabled: true, notificationTitle: '...', notificationText: '...', showLeaveAction: true);` and listen to `GravixForegroundService.leaveRequests`.

## 7. Web client: join a room

```ts
import { Room, RoomEvent, GravixTokenProvider, connectWithTokenProvider } from 'gravix-rtc';

// Calls YOUR backend with the user's session cookie. Tokens are cached until they expire.
const tokens = GravixTokenProvider.endpoint('https://YOUR-BACKEND/rtc/token', {
  credentials: 'include',
});

const room = new Room();
const stage = document.getElementById('stage')!;

room
  .on(RoomEvent.TrackSubscribed, (track) => {
    stage.appendChild(track.attach()); // a <video> or <audio> element
  })
  .on(RoomEvent.TrackUnsubscribed, (track) => {
    track.detach().forEach((el) => el.remove());
  });

export async function join(roomId: string, userId: string, name: string) {
  await connectWithTokenProvider(room, {
    tokenProvider: tokens,
    request: { room: roomId, identity: userId, name },
  });
  await room.localParticipant.setMicrophoneEnabled(true);
  await room.localParticipant.setCameraEnabled(true);
}

export const leave = () => room.disconnect();
```

- `connectWithTokenProvider` throws when the token cannot be fetched. Catch it.
- Remote tracks: `RoomEvent.TrackSubscribed` gives a track; `track.attach()` returns a ready <video> or <audio> element. `RoomEvent.TrackUnsubscribed`: `track.detach()` and remove the elements.
- Autoplay: if `room.canPlaybackAudio` is false (watch `RoomEvent.AudioPlaybackStatusChanged`), show a button that calls `room.startAudio()`.
- `room.disconnect()` leaves and stops the local camera and microphone.

## 8. React

Use the core client inside a component: create the Room in `useEffect` and call `room.disconnect()` in the cleanup. The package also has an optional `gravix-rtc/react` entry with hooks for large rooms; a simple call or stream does not need it.

```tsx
import { useEffect, useRef, useState } from 'react';
import { Room, RoomEvent, GravixTokenProvider, connectWithTokenProvider } from 'gravix-rtc';

// One provider for the whole app. It sends the user's session cookie to YOUR backend
// and caches each token until shortly before it expires.
const tokens = GravixTokenProvider.endpoint('https://YOUR-BACKEND/rtc/token', {
  credentials: 'include',
});

type Props = { streamId: string; userId: string; userName: string; isHost: boolean };
type Status = 'joining' | 'live' | 'ended' | 'error';

export function LiveStream({ streamId, userId, userName, isHost }: Props) {
  const stageRef = useRef<HTMLDivElement>(null);
  const roomRef = useRef<Room | null>(null);
  const [status, setStatus] = useState<Status>('joining');
  const [audioBlocked, setAudioBlocked] = useState(false);

  useEffect(() => {
    const stage = stageRef.current!;
    const room = new Room();
    roomRef.current = room;
    let cancelled = false;

    room
      // Audience: the host's camera and mic arrive as subscribed tracks.
      .on(RoomEvent.TrackSubscribed, (track) => {
        stage.appendChild(track.attach()); // a <video> or <audio> element
      })
      .on(RoomEvent.TrackUnsubscribed, (track) => {
        track.detach().forEach((el) => el.remove());
      })
      // Browsers can block sound until the user clicks something.
      .on(RoomEvent.AudioPlaybackStatusChanged, () => {
        setAudioBlocked(!room.canPlaybackAudio);
      })
      .on(RoomEvent.Disconnected, () => {
        if (!cancelled) setStatus('ended');
      });

    (async () => {
      try {
        await connectWithTokenProvider(room, {
          tokenProvider: tokens,
          request: { room: streamId, identity: userId, name: userName, canPublish: isHost },
        });
        if (cancelled) return;
        if (isHost) {
          // Host: publish camera and mic, and show your own preview.
          const camera = await room.localParticipant.setCameraEnabled(true);
          await room.localParticipant.setMicrophoneEnabled(true);
          const preview = camera?.videoTrack?.attach();
          if (preview) stage.appendChild(preview);
        }
        if (!cancelled) setStatus('live');
      } catch {
        if (!cancelled) setStatus('error');
      }
    })();

    return () => {
      cancelled = true;
      roomRef.current = null;
      void room.disconnect(); // also stops the host's camera and mic
      stage.replaceChildren();
    };
  }, [streamId, userId, userName, isHost]);

  const label = {
    joining: 'Joining…',
    live: isHost ? 'You are live' : 'Watching',
    ended: 'The stream has ended',
    error: 'Could not join the stream',
  }[status];

  return (
    <section>
      <p role="status">{label}</p>
      {audioBlocked && (
        <button type="button" onClick={() => roomRef.current?.startAudio()}>
          Tap to hear the stream
        </button>
      )}
      <div ref={stageRef} className="stage" />
    </section>
  );
}
```

## 9. Flutter live stream screen (host and audience)

```dart
import 'package:flutter/material.dart';
import 'package:gravix_rtc/gravix_rtc.dart';

/// One screen for both roles. isHost comes from your app;
/// the token from your server decides whether this user may really publish.
class LivePage extends StatefulWidget {
  const LivePage({
    super.key,
    required this.tokens,
    required this.streamId,
    required this.userId,
    required this.userName,
    required this.isHost,
  });

  final GravixTokenProvider tokens;
  final String streamId;
  final String userId;
  final String userName;
  final bool isHost;

  @override
  State<LivePage> createState() => _LivePageState();
}

class _LivePageState extends State<LivePage> {
  final room = GravixRoomService();
  VideoTrack? hostVideo; // what the audience watches
  String? error;

  @override
  void initState() {
    super.initState();
    room.onRemoteVideoTrack = (uid, track) {
      if (mounted) setState(() => hostVideo = track);
    };
    room.onRemoteVideoTrackRemoved = (uid) {
      if (mounted) setState(() => hostVideo = null);
    };
    _join();
  }

  Future<void> _join() async {
    final ok = await room.connectWithTokenProvider(
      tokenProvider: widget.tokens,
      request: GravixTokenRequest(
        room: widget.streamId,
        identity: widget.userId,
        name: widget.userName,
        canPublish: widget.isHost,
      ),
      publishMic: widget.isHost,
      enableVideo: widget.isHost,
    );
    if (!ok && mounted) {
      setState(() => error = room.lastTokenError?.message ?? 'Could not join the stream');
    }
  }

  @override
  void dispose() {
    room.disconnect().whenComplete(room.dispose);
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    if (error != null) return Center(child: Text(error!));
    return Stack(
      children: [
        Positioned.fill(child: widget.isHost ? _preview() : _hostVideo()),
        if (widget.isHost)
          Positioned(left: 0, right: 0, bottom: 32, child: _hostControls()),
      ],
    );
  }

  // Host: your own camera.
  Widget _preview() => ValueListenableBuilder<bool>(
        valueListenable: room.isCameraEnabled,
        builder: (context, on, _) {
          final track = room.localVideoTrack;
          if (!on || track == null) return const Center(child: Text('Starting camera…'));
          return VideoTrackRenderer(track, fit: VideoViewFit.cover);
        },
      );

  // Audience: the host's camera. The host's audio plays on its own.
  Widget _hostVideo() {
    final track = hostVideo;
    if (track == null) return const Center(child: Text('Waiting for the host…'));
    return VideoTrackRenderer(track, fit: VideoViewFit.cover);
  }

  Widget _hostControls() => Row(
        mainAxisAlignment: MainAxisAlignment.center,
        children: [
          ValueListenableBuilder<bool>(
            valueListenable: room.isMicMuted,
            builder: (context, muted, _) => IconButton.filled(
              tooltip: muted ? 'Unmute' : 'Mute',
              icon: Icon(muted ? Icons.mic_off : Icons.mic),
              onPressed: () => room.setMicEnabled(muted),
            ),
          ),
          const SizedBox(width: 16),
          IconButton.filled(
            tooltip: 'Flip camera',
            icon: const Icon(Icons.cameraswitch),
            onPressed: room.switchCamera,
          ),
          const SizedBox(width: 16),
          IconButton.filled(
            tooltip: 'End live',
            icon: const Icon(Icons.call_end),
            onPressed: () => Navigator.of(context).pop(),
          ),
        ],
      );
}
```

## 10. Common mistakes

- Signing tokens in the app, or shipping the App Certificate in any client build. Always sign on the server.
- Trusting `identity` or `can_publish` from the request body. Take them from the server session and your own rules.
- Returning only the token. The endpoint must return `{ token, url }`.
- Hard-coding a region URL in the app. It comes back from the endpoint.
- Using a deprecated `GravixCloudBackend` with an API secret on the device. Use `GravixTokenProvider`.
- Forgetting the Info.plist usage strings (the iOS app crashes when it opens the microphone) or the Android permissions.
- Serving the web app over plain HTTP. Browsers allow the microphone and camera only on HTTPS pages and a local development server.
- Never leaving the room. Call `disconnect()` (and `dispose()` on Flutter) when the screen closes.

## 11. Done when

- The backend endpoint signs tokens and the App Certificate exists only in server configuration.
- The app joins a room and two devices hear and see each other.
- Mic and camera permissions are declared and requested on every platform the app ships.
- Leaving the screen leaves the room.

## Links

- [Docs](https://www.gravixcloud.com/docs)
- [SDKs](https://www.gravixcloud.com/docs/sdks)
- [Quick start: live streaming](https://www.gravixcloud.com/docs/live-streaming)
- [Integrate with an AI coding assistant](https://www.gravixcloud.com/docs/ai-agents)
- [Contact](https://www.gravixcloud.com/contact)