chartbeat-react-native-bridge-sdk

React Native wrapper for the Chartbeat iOS and Android SDKs.

Installation

npm install chartbeat-react-native-bridge-sdk
cd ios && pod install

That's it. Native dependencies (Chartbeat iOS pod and Android SDK) are resolved automatically.

Usage

All methods shown below work on both iOS and Android. For platform-specific extras, see the API Reference tables.

import Chartbeat from 'chartbeat-react-native-bridge-sdk';

// Initialize (call once at app start)
Chartbeat.setupTracker('12345', 'yoursite.com');

// Track a screen/article view
Chartbeat.trackView('/articles/hello-world', 'Hello World');

// Set metadata
Chartbeat.setAuthors(['Jane Doe', 'John Smith']);
Chartbeat.setSections(['Technology', 'News']);
Chartbeat.setZones(['homepage']);
Chartbeat.setDomain('yoursite.com');
Chartbeat.setSubDomain('mobile.yoursite.com');
Chartbeat.setAppReferrer('com.example.referrer');
Chartbeat.setPushReferrer('push-campaign-42');

// Signal user interaction
Chartbeat.userInteracted();
Chartbeat.userTyped();

// User state
Chartbeat.setUserLoggedIn();
Chartbeat.setUserPaid();
Chartbeat.setUserAnonymous();

// Video tracking
Chartbeat.trackVideo({
  viewId: '/video/123',
  title: 'My Video',
  duration: 300,
  playState: 'playing',
});
Chartbeat.updateVideoPlayState('s2', 300, 12, 45, 45);

// Conversion tracking
import { PaywallType } from 'chartbeat-react-native-bridge-sdk';

Chartbeat.trackConversionPaywall(PaywallType.Shown);
Chartbeat.trackConversionPaywall(PaywallType.Complete, {
  eventLabel: 'monthly-sub',
  eventValue: '9.99',
});
Chartbeat.trackConversionCustomEvent('share_clicked', {
  eventLabel: 'facebook',
});

// Debug mode & properties
Chartbeat.setDebugMode(true);
Chartbeat.setUsePong(true);
const usingPong = Chartbeat.getUsePong();

// Stop tracker when done
Chartbeat.stopTracker();

API Reference

Core

| Method | iOS | Android | Description | |--------|-----|---------|-------------| | setupTracker(accountId, domain) | Yes | Yes | Initialize the tracker | | stopTracker() | Yes | Yes | Stop and release the tracker | | trackView(viewId, title) | Yes | Yes | Track a page/screen view | | trackViewWithPosition(viewId, title, position) | No | Yes | Track view with scroll data | | userInteracted() | Yes | Yes | Signal user interaction | | userTyped() | Yes | Yes | Signal user is typing | | userLeftView(viewId) | No | Yes | Signal user left a view |

Metadata

| Method | iOS | Android | Description | |--------|-----|---------|-------------| | setAuthors(authors) | Yes | Yes | Set article authors | | setSections(sections) | Yes | Yes | Set article sections | | setZones(zones) | Yes | Yes | Set article zones | | setDomain(domain) | Yes | Yes | Update domain | | setSubDomain(subDomain) | Yes | Yes | Set subdomain | | setAppReferrer(appReferrer) | Yes | Yes | Set app referrer | | setPushReferrer(pushReferrer) | Yes | Yes | Set push notification referrer | | setViewLoadTime(loadTime) | No | Yes | Set view load time in seconds | | setPosition(position) | No | Yes | Set scroll position data |

User State

| Method | iOS | Android | Description | |--------|-----|---------|-------------| | setUserPaid() | Yes | Yes | Mark user as paid subscriber | | setUserLoggedIn() | Yes | Yes | Mark user as logged in | | setUserAnonymous() | Yes | Yes | Mark user as anonymous | | setIdSync(idSync) | Yes | Yes | Set ID sync dictionary |

Video Tracking

| Method | iOS | Android | Description | |--------|-----|---------|-------------| | trackVideo(params) | Yes | Yes | Start tracking a video | | updateVideoPlayState(playState, duration, engagedTime, contentTime, playerTime) | Yes | Yes | Update video state |

Conversion Tracking

| Method | iOS | Android | Description | |--------|-----|---------|-------------| | trackConversionPaywall(type, options?) | Yes | Yes | Paywall conversion | | trackConversionRegistration(type, options?) | Yes | Yes | Registration conversion | | trackConversionNewsletter(type, options?) | Yes | Yes | Newsletter conversion | | trackConversionUnsubscribe(type, options?) | Yes | Yes | Unsubscribe conversion | | trackConversionOffer(type, options?) | Yes | Yes | Offer conversion | | trackConversionSurvey(type, options?) | Yes | Yes | Survey conversion | | trackConversionAccountCreation(type, options?) | Yes | Yes | Account-creation conversion | | trackConversionDownload(type, options?) | Yes | Yes | Download conversion | | trackConversionDonation(type, options?) | Yes | Yes | Donation conversion | | trackConversionPayment(type, options?) | Yes | Yes | Payment conversion | | trackConversionSearch(type, options?) | Yes | Yes | Search conversion | | trackConversionSave(type, options?) | Yes | Yes | Save conversion | | trackConversionCustomEvent(name, options?) | Yes | Yes | Custom conversion event |

Properties

| Method | iOS | Android | Description | |--------|-----|---------|-------------| | setDebugMode(enabled) | Yes | Yes | Enable/disable debug logging | | setUsePong(enabled) | Yes | Yes | Use Pong server endpoint instead of Ping | | getUsePong() | Yes | Yes | Whether the Pong endpoint is active. | | setLogLevel(level) | Yes | No | Set log verbosity (LogLevel enum) | | getTrackerStatus() | Yes | No | Get tracker status (TrackerStatus enum). Returns a Promise. |

Expo Go vs Development Builds

Expo Go does not support custom native modules. If you run your app with Expo Go, every Chartbeat call (setupTracker, trackView, userInteracted, etc.) will silently no-op — nothing will be tracked. The SDK logs a single warning to the console when this happens.

To get real tracking you must use one of the following:

• Expo development build — run npx expo run:ios or npx expo run:android so that native code is compiled into your app.
• Bare React Native project (npx react-native run-ios / run-android).
• EAS Build — use eas build to produce a custom dev client or production build that includes native modules.

Debugging

Enable verbose logging from the native SDKs by calling setDebugMode(true) once at startup (ideally right after setupTracker):

Chartbeat.setDebugMode(true);

To view the native SDK logs:

• iOS — Open Console.app, filter by the iOS Simulator process, and search for Chartbeat-related messages. Or stream them from the terminal:

  xcrun simctl spawn booted log stream --level debug --style compact \
    --predicate 'eventMessage CONTAINS "[CB]:Pinging"'

• Android — Open Logcat in Android Studio and filter by Chartbeat-related tags. Or stream them from the terminal:

  adb logcat -T 1 | grep -i pingclient

Platform Notes

• Most methods are synchronous (fire-and-forget). The exception is getTrackerStatus(), which returns a Promise.
• getTrackerStatus() resolves to -1 on Android (not supported).
• Methods marked "iOS only" are safe to call on Android — they execute as no-ops.
• Methods marked "Android only" are safe to call on iOS — they execute as no-ops.
• accountId is passed as a string on both platforms (converted to int internally on iOS).

Dependencies

• iOS: Chartbeat CocoaPod
• Android: Chartbeat Android SDK via JitPack