> For the complete documentation index, see [llms.txt](https://docs.chartbeat.com/cbp/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.chartbeat.com/cbp/tracking/mobile-app-sdks/react-native-sdk.md).

# React Native SDK

### Overview

`react-native-chartbeat` is a React Native wrapper around the native Chartbeat iOS and Android SDKs. It exposes a single JavaScript/TypeScript surface (`Chartbeat`) that routes calls to the appropriate native module at runtime.

* **Package name:** `react-native-chartbeat`
* **Source layout:**
  * `src/index.ts` — TypeScript API surface
  * `ios/RNChartbeat.{h,m}` — iOS native bridge
  * `android/src/**` — Android native bridge
  * `react-native-chartbeat.podspec` — iOS pod spec
  * `android/build.gradle` — Android module build

***

**Native dependencies (resolved automatically):**

* iOS: `Chartbeat` CocoaPod — pinned to **1.5.13**
* Android: `com.github.chartbeat:android_sdk` via JitPack — pinned to **1.8.0**

***

### Installation

#### 1. Install the package

```typescript
npm install react-native-chartbeat
# or
yarn add react-native-chartbeat
```

#### 2. iOS — install the pod

```typescript
cd ios && pod install
```

No manual linking required; autolinking picks up the module. The Chartbeat CocoaPod is declared in the podspec, so pod install pulls it automatically.

#### 3. Android — JitPack repository

The SDK's own `android/build.gradle` already declares `maven { url '<https://jitpack.io'> }`, so autolinking should work. If your app-level Gradle overrides repositories and your build fails with "could not find com.github.chartbeat:android\_sdk", add JitPack to your **root** `android/build.gradle` (or `settings.gradle` in newer RN projects):

```typescript
allprojects {
    repositories {
        google()
        mavenCentral()
        maven { url 'https://jitpack.io' }
    }
}
```

#### 4. Expo

Custom native modules do **not** run in **Expo Go**. All Chartbeat calls will silently no-op (with a single console.warn on first call). Instead, use:

* **Expo development build:** `npx expo run:ios` / `npx expo run:android`
* **Bare React Native:** `npx react-native run-ios` / `run-android`
* **EAS Build:** `eas build` to produce a custom dev client or production build

***

### Quick Start

```typescript
import Chartbeat from 'react-native-chartbeat';

// 1. Initialize once at app startup with your account ID and dashboard ID
Chartbeat.setupTracker('12345', 'yoursite.com');

// 2. On each screen/article view, send viewID and title
Chartbeat.trackView('/articles/hello-world', 'Hello World');

// 3. Signal user engagement
Chartbeat.userInteracted();  // tap, scroll, etc.
Chartbeat.userTyped();        // text input

// 4. Stop the tracker when you're done (e.g. app teardown)
Chartbeat.stopTracker();
```

***

### Usage Guide

#### Initializing the tracker

Call `setupTracker` exactly once, before any other API call. Your account ID is passed as a string on both platforms.

```typescript
Chartbeat.setupTracker('12345', 'yoursite.com');
```

Replace the placeholder accountID `12345` with your organization’s specific Account ID and the placeholder dashboard ID `yoursite.com` with the dashboard ID of your site.

#### Tracking views

Call `trackView` each time the user navigates to a new screen or article.

```typescript
Chartbeat.trackView('/articles/hello-world', 'Hello World');
```

Include the `viewId` (e.g. `'/articles/hello-world'`) every time you call `trackView` .

To identify your pages and views in your dashboard, you should also include your view’s `title` (e.g. 'Hello World').

To accurately match pages and views across platforms, the `viewId` in your app **must** be set to the same string path (`p` key) that’s reported from your website. You can find more details about path settings by reviewing the documentation for [Canonical Links](http://support.chartbeat.com/docs/#canonical) and [Custom Path Variable](http://support.chartbeat.com/docs/#path).

#### Metadata

Set article metadata after `setupTracker` and before `trackView` (or between views, as the article changes).

```typescript
Chartbeat.setAuthors(['Jane Doe', 'John Smith']);
Chartbeat.setSections(['Technology', 'News']);
Chartbeat.setPushReferrer('push-campaign-42');
```

#### User Subscriber State

Set the [user's subscriber state](https://docs.chartbeat.com/cbp/tracking/standard-websites/subscriber-engagement) as Guest, Registered, or Subscriber.

```typescript
Chartbeat.setUserAnonymous(); // for Guest
Chartbeat.setUserLoggedIn(); // for Registered
Chartbeat.setUserPaid(); // for Subscriber
```

#### ID Sync

For iOS only, send ID Sync values if your organization is using [Datastream](https://docs.chartbeat.com/datastream/implement-tracking/id-sync).

```typescript
Chartbeat.setIdSync({ partnerA: 'abc', partnerB: 'def' }); 
```

#### Engagement Signals

| `userInteracted()`     | <p>iOS: <code>userEngaged(writing: false)</code></p><p>Android: <code>userInteracted()</code></p> |
| ---------------------- | ------------------------------------------------------------------------------------------------- |
| `userTyped()`          | <p>iOS: <code>userEngaged(writing: true)</code></p><p>Android: <code>userTyped()</code></p>       |
| `userLeftView(viewId)` | **Android only**; no-op on iOS                                                                    |

***

### Dependencies

* iOS: `Chartbeat` CocoaPod v1.5.13
* Android: `com.github.chartbeat:android_sdk` v1.8.0 via JitPack