@triplewhale/react-native-triple-pixel

React Native bridge for the Triple Whale mobile tracking SDK. The package bundles the pre-built native binaries (Android + iOS) and exposes a single JavaScript API.

Installation

npm install @triplewhale/react-native-triple-pixel

iOS only:

cd ios && pod install

The package ships pre-built native binaries — no Gradle / Xcode edits required. Autolinking handles the wiring.

Requirements

| | | |---|---| | React Native | 0.71+ | | Android minSdk | 24 | | iOS deployment target | 14.0 | | Node | 18+ |

Quickstart

import { TriplePixel } from '@triplewhale/react-native-triple-pixel';

// Once at app startup.
// The first argument is your Triple Whale shop ID — the identifier shown for
// your store in Triple Whale — NOT your storefront domain or shop name.
TriplePixel.init('your-tw-shop-id', 'US', 'USD');

// Screen view
TriplePixel.pageView('/home');

// Product page
TriplePixel.pageViewWithProduct('/products/42', '42', 'T-Shirt', '29.99');

// Add to cart
TriplePixel.addToCart('42', /* variant */ '', /* price */ 29.99, /* qty */ 1);

// Contact capture
TriplePixel.contact('[email protected]');

// Checkout funnel
const order = {
  email: '[email protected]',
  lineItems: [{ id: '42', quantity: 1, variant: '', price: 29.99 }],
  orderId: '1001',
  token: 'abc123',
};

TriplePixel.checkoutStarted(order);
TriplePixel.paymentSubmitted(order);
TriplePixel.purchase(order);

API reference

Lifecycle

| Method | Description | |---|---| | init(shopId, msCountry, curr) | Required once at app startup. The first argument is your Triple Whale shop ID — the identifier shown for your store in Triple Whale. Do not pass your storefront domain or shop name; Triple Whale resolves the platform from the registered shop ID. |

Tracking

| Method | Description | |---|---| | pageView(url) | Screen view. | | pageViewWithProduct(url, productId, productName, productPrice) | Screen view with product context. | | addToCart(productId, variant, price, quantity) | Item added to cart. | | contact(email, phone?) | Capture user contact info. |

Checkout funnel

All accept the same CheckoutOptions object:

type CheckoutOptions = {
  email: string;            // required (email or phone)
  phone?: string;
  firstName?: string;
  lastName?: string;
  orderId?: string;         // required for purchase()
  token?: string;
  checkoutUrl?: string;
  lineItems: LineItem[];    // required, must not be empty
  discountTotal?: number;
  discountCodes?: string[];
};

type LineItem = {
  id: string;
  quantity: number;
  variant?: string;
  price?: number;           // per-unit
};

| Method | Funnel step | |---|---| | checkoutStarted(options) | User entered checkout | | paymentSubmitted(options) | Payment info submitted | | purchase(options) | Order confirmed (requires orderId) | | addressSubmitted(options) | Shipping address submitted | | contactSubmitted(options) | Contact info submitted | | shippingSubmitted(options) | Shipping method submitted |

Consent

Opt-out model: tracking is on by default; DENIED short-circuits everything.

| Method | Description | |---|---| | setConsentGranted() | Mark consent as granted. | | setConsentDenied() | Mark as denied. Clears persisted user ID + session state, cancels in-flight sends, blocks all subsequent track calls. Persists across app restarts. | | getConsentStatus(): Promise<'UNKNOWN' \| 'GRANTED' \| 'DENIED' \| undefined> | Read current state. Resolves to undefined if the native module isn't reachable; never rejects. |

Behavior under consent

| State | pageView / addToCart | contact / checkout* | |---|---|---| | UNKNOWN (default) | sent | sent | | GRANTED | sent | sent | | DENIED | blocked | blocked |

Apps targeting GDPR-style opt-in jurisdictions should call setConsentDenied() at startup and only setConsentGranted() after explicit user consent.

Error handling

Every bridge call is wrapped in try/catch on both the JS and native sides. Malformed payloads are silently dropped with a console.warn — they will never crash your app. Tracking is best-effort.

Reporting security issues

If you believe you have found a security vulnerability in this SDK, please report it privately — do not open a public issue or post it in any public forum.

Email [email protected] with:

• A description of the vulnerability and its potential impact.
• Steps to reproduce, ideally with a minimal proof-of-concept.
• The SDK version (@triplewhale/react-native-triple-pixel@<version>), platform (Android / iOS / React Native), and runtime versions.
• Whether the issue is currently being exploited in the wild, to the best of your knowledge.

We aim to acknowledge reports within two business days and to share a remediation plan within seven. Please give us a reasonable window to investigate and ship a fix before any public disclosure.

License

MIT — see the LICENSE file shipped with this package.