> ## Documentation Index
> Fetch the complete documentation index at: https://hellotars.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# React Native integration

> Embed a Tars agent in a React Native app with react-native-webview and the bridge protocol.

The dashboard writes a starting snippet with your real chat URL. Open **Distribute**, then **Mobile App**, turn on **Enable Bridge Events**, and pick the **React Native** tab. The snippet on this page also relays widget messages to the app, which the [WebView bridge](/docs/developer/mobile/webview-bridge) requires.

## Requirements

* The `react-native-webview` package
* **Enable Bridge Events** turned on for the agent

## Snippet

```jsx theme={null}
import { useRef } from 'react';
import { WebView } from 'react-native-webview';

// Forwards every tars: message from the page to onMessage
const RELAY = `
  window.addEventListener('message', function (event) {
    var msg = event.data;
    if (msg && typeof msg.type === 'string' && msg.type.indexOf('tars:') === 0) {
      window.ReactNativeWebView.postMessage(JSON.stringify(msg));
    }
  });
  true;
`;

export function TarsAgentChat({ navigation }) {
  const webViewRef = useRef(null);

  function handleMessage(event) {
    const msg = JSON.parse(event.nativeEvent.data);
    switch (msg.type) {
      case 'tars:ready':
        // The bare ready means the page is listening. Init starts the bridge.
        // The bridge replies with a second ready carrying version+capabilities.
        webViewRef.current?.injectJavaScript(`
          window.postMessage(${JSON.stringify({
            type: 'tars:init',
            platform: 'react-native',
            version: '1.0',
            chrome: { showHeader: false, showCloseButton: true }
          })}, '*'); true;
        `);
        break;
      case 'tars:navigate':
        navigation.navigate(msg.route, msg.params);
        break;
      case 'tars:close':
        navigation.goBack();
        break;
      case 'tars:data':
        // msg.variables holds the captured conversation variables
        break;
    }
  }

  return (
    <WebView
      ref={webViewRef}
      source={{ uri: 'https://YOUR_WIDGET_HOST/widget/YOUR_AGENT_ID?region=YOUR_REGION' }}
      injectedJavaScriptBeforeContentLoaded={RELAY}
      onMessage={handleMessage}
      javaScriptEnabled
      domStorageEnabled
    />
  );
}
```

## Message wiring

| Piece                                    | Role                                                                                                                 |
| ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| `injectedJavaScriptBeforeContentLoaded`  | Installs the relay. The widget posts its messages inside the page, so without the relay `onMessage` receives nothing |
| `onMessage`                              | Receives widget → app messages from the relay. Parse `event.nativeEvent.data` as JSON and branch on `msg.type`       |
| `injectJavaScript`                       | Sends app → widget messages by posting into the page with `window.postMessage`                                       |
| `javaScriptEnabled`, `domStorageEnabled` | Required. The widget needs script execution and local storage                                                        |

The widget posts `tars:ready` twice. The bare one on mount is the cue to send `tars:init`, and the second carries `version` and `capabilities`. This handler answers both, and the widget ignores the repeat init.

Handle at least `tars:navigate`, `tars:data`, and `tars:close`: the three capabilities the bridge declares in its `tars:ready` reply to `tars:init`. Field-level payloads for every message are in the [bridge events reference](/docs/developer/mobile/bridge-events).

## Passing end-user data

Add `userData` and `context` to the `tars:init` payload, or post a `tars:inject` message later in the session. Both shapes are in the [bridge events reference](/docs/developer/mobile/bridge-events).

## Related pages

* [The WebView bridge](/docs/developer/mobile/webview-bridge)
* [Bridge events reference](/docs/developer/mobile/bridge-events)
* [Swift integration](/docs/developer/mobile/swift)
* [Kotlin integration](/docs/developer/mobile/kotlin)