react-native-comscore-sdk

📖 Documentation: wellbrito29.github.io/react-native-comscore-sdk

A React Native Turbo Module that wraps the native Comscore SDK for audience measurement on iOS and Android.

• ✅ New Architecture — Built for TurboModules + Fabric (React Native 0.83+)
• ✅ TypeScript — Fully typed API with strict mode
• ✅ Consent & Privacy — Built-in support for GDPR consent (cs_ucfr) and child-directed mode (COPPA)
• ✅ Validation Mode — Debug-only implementation validation for Comscore certification

Requirements

| Platform | Minimum Version | Notes | |---|---|---| | React Native | 0.83.0 | New Architecture (TurboModules) required | | iOS | 15.1 | | | Android | minSdk 24 | | | Comscore SDK (iOS) | ~> 6.0 | Installed via CocoaPods | | Comscore SDK (Android) | 6.11.0 | Installed via Maven Central |

Installation

npm install react-native-comscore-sdk
# or
yarn add react-native-comscore-sdk

iOS Setup

cd ios && pod install

The library depends on the ComScore CocoaPod (~> 6.0), which will be installed automatically.

Android Setup

The library automatically pulls the Comscore Android SDK from Maven Central via Gradle. No additional setup is required.

Note for Validation Mode: If you plan to inspect Comscore network traffic with Charles Proxy on Android 7.0+, the library includes a default network_security_config.xml that whitelists scorecardresearch.com for debug builds. See VALIDATION.md for details.

Usage

Initialization

Initialize the SDK as early as possible (e.g., in your root component or app entry point). The module guards against double-initialization.

import Comscore from 'react-native-comscore-sdk';

useEffect(() => {
  Comscore.initialize({
    publisherId: 'YOUR_PUBLISHER_ID',
    applicationName: 'My App Name',
    initialConsent: '1', // "1" opted-in, "0" opted-out, "" unknown
    usagePropertiesAutoUpdateMode: 'foregroundOnly',
    autoUpdateIntervalSeconds: 60,
    childDirected: false,
    validationMode: __DEV__, // NEVER enable in production
  });
}, []);

ComscoreConfig

| Property | Type | Required | Default | Description | |---|---|---|---|---| | publisherId | string | ✅ | — | Your Comscore publisher ID | | applicationName | string | | '' | Application name reported to Comscore | | usagePropertiesAutoUpdateMode | 'foregroundOnly' \| 'foregroundAndBackground' \| 'disabled' | | '' | When usage properties are auto-updated | | autoUpdateIntervalSeconds | number | | -1 | Interval in seconds (minimum: 60) | | childDirected | boolean | | false | Enables COPPA/child-directed mode. Disables advertising identifiers | | validationMode | boolean | | false | Debug only. Enables Comscore implementation validation | | startOnlyWhenUIIsVisible | boolean | | false | Delays analytics start until UI is visible | | initialConsent | '0' \| '1' \| '' | | '' | Initial GDPR consent state | | debugLogs | boolean | | false | Enables SDK debug logging |

Tracking Sections

Notify Comscore when the user navigates to a new screen or section.

// Track a named section
Comscore.trackSection('Home');

// Track with no specific section (e.g., splash screen)
Comscore.trackSection('');

Updating Consent

If the user changes their consent preference after initialization, update it dynamically. The module automatically fires a hidden event so Comscore picks up the change immediately.

// User opted in
Comscore.updateConsent('1');

// User opted out
Comscore.updateConsent('0');

// Unknown / no action
Comscore.updateConsent('');

Accepted values: "1" (opted in), "0" (opted out), "" (unknown).

Background User Experience

If your app provides a background experience (e.g., audio playback), notify Comscore when the UX becomes active or inactive.

// When background playback starts
Comscore.notifyUxActive();

// When background playback stops
Comscore.notifyUxInactive();

Child-Directed Mode (COPPA)

You can toggle child-directed mode after initialization. When enabled, the SDK stops collecting advertising identifiers.

Comscore.setChildDirected(true);

Validation Mode

Enable validation mode to output debug request URLs. This is blocked in release builds on both platforms.

Comscore.setValidationMode(true);

SDK Version

const version = await Comscore.getVersion();
console.log(version); // e.g., "6.15.0+2509100829"

API Reference

interface ComscoreModule {
  initialize(config: ComscoreConfig): Promise<void>;
  notifyUxActive(): Promise<void>;
  notifyUxInactive(): Promise<void>;
  trackSection(sectionName?: string | null): Promise<void>;
  updateConsent(value: '0' | '1' | ''): Promise<void>;
  setChildDirected(enabled: boolean): Promise<void>;
  setValidationMode(enabled: boolean): Promise<void>;
  getVersion(): Promise<string>;
}

Validation

For detailed instructions on validating your Comscore implementation using Charles Proxy and the SDK's Validation Mode, see VALIDATION.md.

Contributing

See CONTRIBUTING.md for development setup, build commands, and commit conventions.

License

MIT © Wellington Nascimento