# 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

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

#### 2. iOS — install the pod

```
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):

```
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

```
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.

```
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.

```
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');
Chartbeat.setViewLoadTime(1.23);    // Android only
Chartbeat.setPosition({ ... });      // Android only
```

#### 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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.chartbeat.com/cbp/tracking/mobile-app-sdks/react-native-sdk.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.