@reflect-sdk/react-native

Reflect MMP SDK for React Native — mobile attribution, event tracking, deep linking, and SKAdNetwork/AdAttributionKit.

Architecture (v2): a thin JS + native bridge over the shared ReflectCore engine — the exact same Kotlin (reflect-android) and Swift (reflect-ios) native core the Reflect Flutter and Unity SDKs use. All SDK logic (sessions, durable queue, HMAC-signed ingest, batching, response-driven retry, client-side dedup, device signals, deferred deep links, attribution, SKAN, ATT) lives in the core; this package only translates the RN bridge onto core.handle(...). (v1 was a standalone re-implementation that posted unsigned events — v2 is a breaking native rewrite; the public JS API stays backward-compatible and gains new methods.)

Install

npm install @reflect-sdk/react-native
# or: yarn add @reflect-sdk/react-native

Android also needs the JitPack repository in your app's root android/build.gradle — a library cannot add it for you, and on RN 0.73+ a settings.gradle dependencyResolutionManagement block is ignored. See below.

Core versions. v2.0.5 pins the shared native cores at reflect-android 1.1.2 (JitPack) and ReflectCore 1.1.4 (CocoaPods git tag). The 1.1.x line is the privacy floor — 1.0.0 shipped with no privacy engine; never pin a core below 1.1.0.

This is an autolinked native module.

Android — the shared core (com.github.bablu147:reflect-android) is pulled from JitPack. React Native 0.73+ resolves dependencies per-project, so add the repository to an allprojects block in your app's root android/build.gradle. A settings.gradle dependencyResolutionManagement block is ignored on RN 0.73+ and the build fails with Could not resolve com.github.bablu147:reflect-android:

// android/build.gradle — after the buildscript { } block
allprojects {
    repositories {
        maven { url 'https://jitpack.io' }   // com.github.bablu147:reflect-android
    }
}

iOS — one Podfile line is required first; the library cannot supply it. The podspec declares ReflectCore ~> 1.1, but ReflectCore is not published on CocoaPods trunk (trunk.cocoapods.org/api/v1/pods/ReflectCore → 404), and CocoaPods does not follow a dependency to a git source on its own. Without it pod install fails with "None of your spec sources contain a spec satisfying the dependency: ReflectCore (~> 1.1)".

# ios/Podfile — inside your app target
pod 'ReflectCore', :git => 'https://github.com/bablu147/reflect-ios.git', :tag => '1.1.4'

1.1.4 satisfies the ~> 1.1 constraint; do not pin below 1.1.1 (the first tag that does not brand every event flutter on the wire). Then install the pods:

cd ios && pod install && cd ..

Then rebuild the native app — a Metro/JS reload is not enough for a newly-added native module (and Expo Go won't work; use a development build):

npx react-native run-android   # or run-ios

Requires react >= 18.0.0 and react-native >= 0.71.0.

Quick start

Call initialize once, as early as possible in your app's lifecycle (e.g. in your root component or index.js). An app_open event is sent automatically on init.

import { Reflect } from "@reflect-sdk/react-native";

Reflect.initialize({
    appKey: "your-app-key",
    signingSecret: "your-app-hmac-secret", // required for default/shared_hmac apps
    // companyKey: "acme",                // optional, multi-tenant setups
    // baseUrl: "https://api.reflect.cloud", // optional, override endpoint
    // debug: true,                       // optional, console logging
    // requireAdvertisingConsent: true,   // optional, withhold IDFA/GAID until granted
});

New mobile apps default to server policy shared_hmac; for those apps, signingSecret is required and an unsigned fallback is rejected with signature_required. Omit it only for an app deliberately configured as legacy_unsigned during a reviewed compatibility rollout. Inject credentials through ignored local/CI configuration; never commit a real value.

Track named events with optional properties (validated client-side):

Reflect.trackEvent("level_completed", { level: 7, score: 42000 });
Reflect.trackEvent("tutorial_finished");

Revenue and purchases:

Reflect.trackRevenue({ amount: 4.99, currency: "USD", productId: "coins_500" });

Identify API — setEmail / clearEmail

setEmail(email) associates a raw email address with the current install for email-attribution and better Conversions API (CAPI) match quality. The address is attached as email to every subsequent event and hashed server-side — you pass the raw email, never a hash.

// After the user logs in or provides their email:
Reflect.setEmail("[email protected]");

// On logout:
Reflect.clearEmail();

Consent gating is load-bearing. Denial immediately erases wrapper-only email and global-property caches, blocks callbacks and event forwarding, and ignores new PII setters. A later grant starts clean; the host must re-supply any identity fields. During asynchronous initialization or an enable/consent grant, measurement and profile operations wait in a bounded, generation-fenced FIFO. Destructive clears remain immediately available and are also replayed in order, so a queued setter can never resurrect a value that the app cleared later. Calls to setConsent(false) or setEnabled(false) made before initialize are folded into the native initialization arguments. This closes native automatic install/open work from its first instruction even when an older persisted grant exists; pre-init grant/re-enable never clears native fail-closed state.

Reflect.setConsent(false);            // consent_state: "denied"
Reflect.setEmail("[email protected]"); // ignored while denied
Reflect.trackEvent("checkout");       // dropped while denied

Reflect.setConsent(true);              // waits for native confirmation
Reflect.setEmail("[email protected]"); // re-supply after the grant
Reflect.trackEvent("purchase");

Notes:

• The email is sticky — it rides on every event until you clearEmail().
• Per-event properties override it, so passing email in a trackEvent call takes precedence for that event.
• setEnabled(false) is reversible: collection and PII setters are blocked, while existing wrapper email and global properties remain behind the closed gate for a native-confirmed setEnabled(true). Use the explicit clear APIs, consent denial, or deleteUserData() when the state must be destroyed.
• deleteUserData() clears sticky email and global properties for every initialized deletion attempt, including when the native bridge rejects or the remote request is still pending. It resolves true only when the server explicitly accepts the deletion. false means remote acknowledgement was not confirmed; when that value comes from the native core, its local cleanup/suppression is already complete and it keeps the delete queued for retry. If the bridge itself rejects, retry the call after restoring the native connection. Completion cleanup is generation-fenced, so an older delete promise cannot erase profile state supplied after an explicit re-enable.

Deep links (native wiring)

Android — no wiring needed for standard ReactActivity apps: warm deep links (onNewIntent) and cold-launch links (getInitialDeepLink) are captured automatically by the native module. Declare your intent filters in AndroidManifest.xml as usual.

iOS — RN has no automatic app-delegate hook, so forward the URL callbacks into the core from your AppDelegate:

The iOS module is created on the main queue and dispatches every core/UI/ATT command, listener delivery, and AppDelegate URL hook through the main queue. This is required by UIKit and ATT even when React Native assigns a background module queue.

#import "ReflectExample-Swift.h"   // or your app's <ProductModuleName>-Swift.h

// Cold launch — stash the URL so getInitialDeepLink() resolves before JS subscribes
- (BOOL)application:(UIApplication *)application
    didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
  NSURL *url = launchOptions[UIApplicationLaunchOptionsURLKey];
  if (url) { [ReflectModule stashLaunchURL:url]; }
  // ... your existing RN setup ...
}

// Custom-scheme deep links
- (BOOL)application:(UIApplication *)app openURL:(NSURL *)url
    options:(NSDictionary<UIApplicationOpenURLOptionsKey,id> *)options {
  [ReflectModule handleURL:url];
  return [RCTLinkingManager application:app openURL:url options:options];
}

// Universal Links
- (BOOL)application:(UIApplication *)application
    continueUserActivity:(NSUserActivity *)userActivity
      restorationHandler:(void (^)(NSArray<id<UIUserActivityRestoring>> *))restorationHandler {
  if (userActivity.webpageURL) { [ReflectModule handleURL:userActivity.webpageURL]; }
  return [RCTLinkingManager application:application
                  continueUserActivity:userActivity
                    restorationHandler:restorationHandler];
}

Then subscribe in JS:

const unsub = Reflect.onDeepLink((dl) => console.log("deep link:", dl.url, dl.path));
const initial = await Reflect.getInitialDeepLink();   // link that cold-launched the app

What's new in v2

Because the SDK now runs on the shared core, these methods are available in addition to the v1 API: trackAdRevenue, verifyPurchase, setThirdPartySharing, setPartnerSharing, setExternalDeviceId, setPartnerParameter / unsetPartnerParameter / clearPartnerParameters, setOfflineMode, isEnabled, getLastDeepLink, getAttributionWithTimeout, resolveDeepLink, handleDeepLink, requestIosTracking (ATT), setIntegrityToken, setPushToken, getDebugState, and an onAttribution(listener) stream. trackPurchase / trackSubscription now hit the core's real purchase handler (receipt validation + dedup), and every event is HMAC-signed with sdk_version: react-native-2.x. getLastDeepLink accepts both the core's structured JSON form and its native plain URL form, normalizing either into a complete DeepLinkData object.

Upgrading from v1: the install_uuid is preserved automatically (the core reads the same storage key the v1 module used), so upgrades are not counted as reinstalls.

How the native core is distributed

The SDK is a thin wrapper over the shared native engine, published from its own public repos — you never copy the core into this SDK:

• Android → com.github.bablu147:reflect-android via JitPack
• iOS → the ReflectCore pod (source: github.com/bablu147/reflect-ios)

The build is dual-mode: inside the Reflect monorepo it compiles the core from ../../reflect-android source (instant, no publish step); as an installed package it pulls the published version. Nothing to configure for that switch — it's automatic (coreSrcDir.exists()).

Consumer setup

Install the package from npm (see Install):

npm install @reflect-sdk/react-native
# or: yarn add @reflect-sdk/react-native

Android needs the JitPack repo once, in an allprojects block in your app's root android/build.gradle (React Native 0.73+ ignores a settings.gradle dependencyResolutionManagement block — dependencies resolve per-project):

allprojects {
    repositories {
        maven { url 'https://jitpack.io' }   // for com.github.bablu147:reflect-android
    }
}

iOS needs the explicit git-sourced core pod in your app's ios/Podfile (ReflectCore is not on CocoaPods trunk — see iOS):

pod 'ReflectCore', :git => 'https://github.com/bablu147/reflect-ios.git', :tag => '1.1.4'

Use the same core release on both platforms; never pin the pre-privacy-engine ReflectCore 1.0.0 tag.

Releasing a new core version (maintainers)

1. Version, push, and tag matching reflect-android + reflect-ios source commits. JitPack builds the Android AAR on first request.
2. pod trunk push ReflectCore.podspec (once per version) for zero-config iOS.
3. Bump the core version + the reflect-android/ReflectCore version in each SDK's build files. No copying — every SDK (RN, Flutter, Unity) references the version.

License

MIT