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 and Custom Path Variable.

Metadata

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

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

User Subscriber State

Set the user's subscriber state as Guest, Registered, or Subscriber.

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.

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

Engagement Signals

userInteracted()	iOS: userEngaged(writing: false) Android: userInteracted()
userTyped()	iOS: userEngaged(writing: true) Android: userTyped()
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