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

# Open Wearables React Native Example App

> Explore the React Native SDK with a working example app. Syncs Apple Health and Android health data in minutes. Use it as a reference implementation.

## Overview

The SDK repository includes a fully functional example app that demonstrates how to use SDK to sync Apple Health and Android health data with Open Wearables. It's also a great way for individuals to sync their personal health data and get it into Open Wearables in minutes! Use it to test the SDK, explore the code, and see how everything works together.

<Card title="Example App Source" icon="github" href="https://github.com/the-momentum/open-wearables-react-native-sdk/tree/main/example">
  View the example app source code on GitHub.
</Card>

<Info>
  Don't want to build the app yourself? Join our [Discord](https://discord.gg/qrcfFnNE6H) and ask for a **TestFlight** beta invitation. The app will also be available in the App Store soon!
</Info>

## What You'll See

The example app demonstrates the complete integration flow:

1. **Invitation Code** - Connect via invitation code (host + code → redeem → sign in)
2. **SDK Configuration** - Initialize the SDK with proper host settings
3. **Authentication** - Sign in with credentials from the dashboard
4. **Provider Selection** - On Android, choose between Samsung Health and Health Connect
5. **Permission Request** - Request health data permissions from the user
6. **Background Sync** - Enable automatic health data synchronization
7. **Sync Status** - Monitor sync progress and handle interruptions
8. **Log Viewer** - Browse SDK logs with search

<Card title="See the full flow in action" icon="play" href="/app/introduction#see-it-in-action">
  Watch how data flows from device setup through syncing to the dashboard and API.
</Card>

## Running the Example App

<Steps>
  <Step title="Clone the repository">
    ```bash theme={null}
    git clone https://github.com/the-momentum/open-wearables-react-native-sdk.git
    cd open-wearables-react-native-sdk
    ```
  </Step>

  <Step title="Install SDK dependencies">
    From the repository root:

    ```bash theme={null}
    npm install
    ```
  </Step>

  <Step title="Install example app dependencies">
    ```bash theme={null}
    cd example
    npm install
    ```
  </Step>

  <Step title="Get credentials from Open Wearables Dashboard">
    1. Go to your Open Wearables dashboard
    2. Create a new user or select an existing one
    3. Generate an invitation code for the user
    4. Copy the invitation code and host URL
  </Step>

  <Step title="Run on iOS">
    From the `example` directory:

    ```bash theme={null}
    npx expo run:ios
    ```

    <Note>
      Run on a **physical iOS device** for health data sync — HealthKit is not available in the iOS Simulator.
    </Note>

    If you encounter a signing error, update the bundle identifier to a unique value in `example/app.json` → `expo` → `ios` → `bundleIdentifier`, then regenerate the native project:

    ```bash theme={null}
    npx expo prebuild --clean
    ```
  </Step>

  <Step title="Run on Android">
    The Android SDK is distributed via Maven Local. First, generate the native project:

    ```bash theme={null}
    npx expo prebuild
    ```

    Then clone and publish the Android SDK to Maven Local:

    ```bash theme={null}
    git clone https://github.com/the-momentum/open_wearables_android_sdk
    cd open_wearables_android_sdk
    git checkout v0.6.0
    ./gradlew publishToMavenLocal
    ```

    Add `mavenLocal()` as the first entry under `allprojects` → `repositories` in `example/android/build.gradle`:

    ```gradle theme={null}
    allprojects {
      repositories {
        mavenLocal()
        // ...
      }
    }
    ```

    Run the app from the `example` directory:

    ```bash theme={null}
    npx expo run:android
    ```
  </Step>

  <Step title="Connect and sync">
    1. Enter the host URL and invitation code
    2. Tap **Connect** to redeem the code and sign in
    3. Grant health permissions when prompted
    4. Tap **Start Sync** to begin background synchronization
    5. Check the dashboard to see your health data appear!
  </Step>
</Steps>

## Example App Code Structure

The example app demonstrates best practices for SDK integration:

```
example/
├── App.tsx                    # Main app entry, SDK init & session state
├── components/
│   ├── SessionGroup.tsx       # Connect form (host URL + invitation code)
│   ├── ActionsGroup.tsx       # Sync controls (start/stop/sync now)
│   ├── ProvidersGroup.tsx     # Android provider selection
│   └── StatusBanner.tsx       # Sync status display
├── screens/
│   └── LogsScreen.tsx         # SDK log viewer
├── hooks/
│   └── useLogs.ts             # Subscribes to onLog / onAuthError events
├── app.json                   # Expo config (bundle ID, permissions plugin)
└── package.json               # Dependencies
```

### Key Code Sections

**SDK Initialization:**

```ts theme={null}
import OpenWearablesHealthSDK from "open-wearables";

OpenWearablesHealthSDK.configure("https://your-api-host.com");
```

**Sign In (via invitation code):**

```ts theme={null}
// Redeem invitation code to get credentials
const response = await fetch(
  `${host}/api/v1/invitation-code/redeem`,
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ code: invitationCode }),
  }
);
const data = await response.json();

// Sign in with returned credentials
await OpenWearablesHealthSDK.signIn(
  data.user_id,
  data.access_token,
  data.refresh_token,
  null
);
```

**Request Permissions:**

```ts theme={null}
import OpenWearablesHealthSDK, { HealthDataType } from "open-wearables";

const granted = await OpenWearablesHealthSDK.requestAuthorization(
  Object.values(HealthDataType)
);
```

**Start / Stop Background Sync:**

```ts theme={null}
// Start
await OpenWearablesHealthSDK.startBackgroundSync();

// Stop
await OpenWearablesHealthSDK.stopBackgroundSync();
```

**Sync Now:**

```ts theme={null}
await OpenWearablesHealthSDK.syncNow();
```

**Listen for SDK Events:**

```ts theme={null}
import { useEvent } from "expo";

// In a React component
const onLogPayload = useEvent(OpenWearablesHealthSDK, "onLog");
const onAuthErrorPayload = useEvent(OpenWearablesHealthSDK, "onAuthError");
```

Or outside React with the standard `addListener` API:

```ts theme={null}
const subscription = OpenWearablesHealthSDK.addListener(
  "onLog",
  ({ message }) => console.log("SDK log:", message)
);

// Clean up
subscription.remove();
```

## Testing the Full Flow

<Steps>
  <Step title="Set up Open Wearables locally (optional)">
    If you want to test with a local instance:

    ```bash theme={null}
    git clone https://github.com/the-momentum/open-wearables.git
    cd open-wearables
    docker compose up -d
    ```

    Then use your local URL as the host when connecting in the app.
  </Step>

  <Step title="Create test data">
    **iOS:** Add some health data to Apple Health on your device:

    * Open the Health app
    * Browse → Steps → Add Data
    * Add a few data points

    **Android:** Add data via Health Connect or Samsung Health.
  </Step>

  <Step title="Trigger sync and verify">
    1. In the example app, tap **Sync Now**
    2. Check the Open Wearables dashboard
    3. Your health data should appear under the user's timeseries!
  </Step>
</Steps>

## Troubleshooting the Example App

<AccordionGroup>
  <Accordion title="App crashes on launch (iOS)">
    Make sure you're running on a **physical device**, not the simulator. HealthKit is not available in the iOS Simulator.
  </Accordion>

  <Accordion title="Sign-in fails">
    * Verify your invitation code is correct and hasn't been used already
    * Check that the host URL is the API URL (not the dashboard URL)
    * Check that your Open Wearables instance is running
    * Ensure network connectivity
  </Accordion>

  <Accordion title="No data syncing">
    * Confirm health permissions were granted (check iOS Settings → Privacy → Health, or Android Settings → Health Connect)
    * Make sure there's actual health data in Apple Health / Health Connect
    * Try tapping **Sync Now** to trigger an immediate sync
    * Check the Logs page in the app for errors
  </Accordion>

  <Accordion title="Xcode signing errors (iOS)">
    * Select your development team in Xcode
    * Update the bundle identifier to something unique
    * Ensure your Apple Developer account has HealthKit capability
  </Accordion>

  <Accordion title="Provider not available (Android)">
    * For Health Connect: ensure it's installed from Play Store (pre-installed on Android 14+)
    * For Samsung Health: only available on Samsung devices with Samsung Health installed
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Integration Guide" icon="book" href="/sdk/react-native/integration">
    Integrate the SDK into your own app.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/sdk/react-native/troubleshooting">
    Common issues and solutions.
  </Card>
</CardGroup>