# Live Connection

Create and join a Live co-viewing session from supported frontend frameworks.

Canonical: https://developer.realsee.ai/docs/live/get-started/live-connect
Source: https://developer.realsee.ai/docs/live/get-started/live-connect.md
Language: en

> **tip**

This guide does not cover Live voice capabilities for now.

**Choose the example that matches your actual development framework.**

## Framework-free Example

**This guide assumes you are building your application with native `js` | `ts`.**

### 1. Create a Live instance

```js
import { createLive, LiveState } from "@realsee/live";

const live = createLive({
  __debug__: true, // In this mode, logs are printed to the terminal to make debugging easier. We recommend enabling it during development.
});
```

**Two parameters are configured when creating the live instance:**

- **url**: The URL for connecting to the WebSocket service. Supply it either when creating the Live instance or later through `live.connect({ url })`.
- **getTicket()**: An async callback whose return value is the Live ticket. Supply it with the URL and obtain the ticket through your backend.


> **info**

For more parameter options of the `createLive()` function, refer to the [`@realsee/live@0.7.6` LiveOptions API](https://unpkg.com/@realsee/live@0.7.6/docs/interfaces/LiveOptions.html).

### 2. Connect to Live

After obtaining the `live` instance, call the `connect()` method at an appropriate time to establish the Live connection.

```js
live.on("stateChange", (state) => {
  if (state === LiveState.OPEN) {
    console.log("Successfully joined the Live session");
  }
});

const result = await live.connect({
  url: "wss://ws-access.realsee.com/***/?=xxx",
  getTicket: async () => requestTicket(),
});
if (result instanceof Error) throw result;
```

### 3. Confirming a successful connection


> **tip**

`LiveState.OPEN` is the connection-ready signal. To restore or apply synchronized state, listen for the public `keyframes` event. The older `readyKeyframeSync` event is deprecated in `@realsee/live@0.7.6`.

```js
live.on("keyframes", (keyframes) => {
  if (keyframes.FiveState) {
    setDefaultFiveState(keyframes.FiveState);
  }
});
```


> **tip**

You can also quickly check whether the Live session connected successfully from the console.

![Chrome DevTools showing successful room, user, and RTC WebSocket messages after Live connects](https://developer.realsee.ai/assets/docs/live/live-connect-success.png)

As shown above, if the code and message of all four commands — `ROOM_INFO`, `SELF_USER_INFO`, `USER_LIST`, and `RTC_INFO` — are `SUCCESS`, the Live channel has connected successfully.

## React Example

**This guide assumes you are building your application with the `React` framework.**

### 1. Create a Live instance


> **info**

Create a new file `LiveReact.js` | `LiveReact.ts` and create your own LiveReact instance.


**JavaScript**


```jsx title='LiveReact.js'
import { createLiveReact } from "@realsee/live";

const LiveReact = createLiveReact({
  __debug__: true,
});

export default LiveReact;

/** If you dislike the `LiveReact.LiveProvider` coding style, you can "expose" the functions you need */
// export const LiveProvider = liveReactInstance.LiveProvider
// export const useConnect = liveReactInstance.useConnect
// export const useKeyframe = liveReactInstance.useKeyframe
// export ..
```


**TypeScript**


```tsx title='LiveReact.ts'
import { createLiveReact } from "@realsee/live";
import { Mode } from "@realsee/five";

/** Define the structure of the frame data snapshot */
interface Snapshot {
  /** Using the Five state snapshot as an example */
  FiveState: {
    panoIndex: number;
    fov: number;
    mode: Mode;
    latitude: number;
    longitude: number;
  };
}

/** Create an instance via the `createLiveReact()` function */
const LiveReact = createLiveReact<Snapshot>({
  __debug__: true,
});

export default LiveReact;

/** If you dislike the `LiveReact.LiveProvider` coding style, you can "expose" the functions you need */
// export const LiveProvider = LiveReact.LiveProvider
// export const useConnect = LiveReact.useConnect
// export const useKeyframe = LiveReact.useKeyframe
// export ..
```


### 2. Integrate the context


> **info**

Use `LiveProvider` to integrate the `live` instance into the `React` `Context`.


**JavaScript**


```jsx
ReactDOM.render(
  <LiveProvider>
    <App />
  </LiveProvider>,
  document.getElementById("root") // Change this to your container
);
```


**TypeScript**


```tsx
ReactDOM.render(
  <LiveProvider>
    <App />
  </LiveProvider>,
  document.getElementById("root") // Change this to your container
);
```


### 3. Connect to Live


> **info**

Use the `useConnect` hook to establish the Live connection.


**JavaScript**


```jsx
import { useConnect } from "./LiveReact";

function ConnectBtn() {
  // highlight-start
  const connect = useConnect();
  //  highlight-end

  const handleConnect = async () => {
    // highlight-start
    const result = await connect({
      force: true,
      url: wsUrl, // The ws connection is obtained from your backend
      getTicket: async () => {
        // Live ticket callback
        return requestTicket({ roomCode, userId, userRole });
      },
    });
    if (result instanceof Error) throw result;
    //  highlight-end
  };

  return <button onClick={() => handleConnect()}>Live connection example button</button>;
}

const requestTicket = async ({ roomCode, userId, userRole }) => {
  // Call your backend API and return the ticket
  return ""; //  string
};
```


**TypeScript**


```tsx
import { useConnect } from "./LiveReact";

function ConnectBtn() {
  // highlight-start
  const connect = useConnect();
  //  highlight-end

  const handleConnect = async () => {
    // highlight-start
    const result = await connect({
      force: true,
      url: wsUrl, // The ws connection is obtained from your backend
      getTicket: async () => {
        // Live ticket callback
        return requestTicket({ roomCode, userId, userRole });
      },
    });
    if (result instanceof Error) throw result;
    //  highlight-end
  };

  return <button onClick={() => handleConnect()}>Live connection example button</button>;
}

const requestTicket = async ({
  roomCode,
  userId,
  userRole,
}: {
  roomCode: string;
  userId: string;
  userRole: string;
}) => {
  // Call your backend API and return the ticket
  return ""; //  string
};
```


### 4. Confirming a successful connection


> **info**

Use `useLiveState` to confirm the connection is open, and `useLiveEventCallback("keyframes", ...)` to restore synchronized state. The older `readyKeyframeSync` event is deprecated in `@realsee/live@0.7.6`.

```jsx
import { useEffect } from "react";
import { LiveState } from "@realsee/live";
import LiveReact from "./LiveReact";

const { useLiveEventCallback, useLiveState } = LiveReact;

function LiveConnectionStatus() {
  const liveState = useLiveState();

  useEffect(() => {
    if (liveState === LiveState.OPEN) {
      console.log("Successfully joined the Live session");
    }
  }, [liveState]);

  useLiveEventCallback("keyframes", (keyframes) => {
    if (keyframes.FiveState) {
      setDefaultFiveState(keyframes.FiveState);
    }
  });

  return null;
}
```


> **tip**

You can also quickly check whether the Live session connected successfully from the console.

![Chrome DevTools showing successful room, user, and RTC WebSocket messages after Live connects](https://developer.realsee.ai/assets/docs/live/live-connect-success.png)

As shown above, if the code and message of all four commands — `ROOM_INFO`, `SELF_USER_INFO`, `USER_LIST`, and `RTC_INFO` — are `SUCCESS`, the Live channel has connected successfully.