@yesplz-ai/analytics-react-native

YesPlz Analytics SDK for React Native and Expo apps. This package provides manual event tracking for product discovery, cart, checkout, purchase, and user identity events.

Installing the Library

After setting up your development environment for React Native, navigate to your app's root directory and install the YesPlz React Native Analytics SDK. The SDK requires React Native 0.74+ and @react-native-async-storage/async-storage.

npm install @yesplz-ai/analytics-react-native @react-native-async-storage/async-storage

Or with Yarn:

yarn add @yesplz-ai/analytics-react-native @react-native-async-storage/async-storage

Or with pnpm:

pnpm add @yesplz-ai/analytics-react-native @react-native-async-storage/async-storage

For Expo projects, install the AsyncStorage peer dependency with Expo:

npx expo install @react-native-async-storage/async-storage

For bare React Native iOS apps, navigate to your application's iOS folder and install native dependencies. You do not need to update your Podfile to add YesPlz.

cd ios
pod install

Basic Setup

After installation, import the singleton analytics instance from the SDK, then initialize it once when your app starts. The value passed to init is your YesPlz app/shop ID.

import { analytics } from '@yesplz-ai/analytics-react-native';

analytics.init('YOUR_APP_ID');

If a customer is already signed in when your app starts, you can identify them during initialization:

analytics.init('YOUR_APP_ID', {
  userId: 'customer_123',
  userProperties: {
    loyalty_tier: 'gold',
  },
});

You can track events immediately after calling init. If your app tracks before initialization completes, the SDK queues the event and sends it when ready.

After initialization, direct tracking calls and event payloads are the same as the web integration. For more details, refer to the YesPlz Analytics documentation: https://docs.yesplz.ai/docs/analytics/#2-api-calls-direct-tracking

Tracking Events

import { analytics, EventType, ItemListId } from '@yesplz-ai/analytics-react-native';

// Product list impression
analytics.track(EventType.ViewItemList, {
  item_list_id: ItemListId.SEARCH_RESULTS,
  search_term: 'linen dress',
  items: [
    { item_id: 'sku_1001', index: 0 },
    { item_id: 'sku_1002', index: 1 },
  ],
});

// Product view
analytics.track(EventType.ViewProduct, {
  id: 'sku_1001',
  item_list_id: ItemListId.SEARCH_RESULTS,
  currency: 'USD',
  value: 128,
});

// Add to cart
analytics.track(EventType.AddToCart, {
  currency: 'USD',
  value: 128,
  items: [{ item_id: 'sku_1001', quantity: 1, price: 128 }],
});

// Begin checkout
analytics.track(EventType.BeginCheckout, {
  currency: 'USD',
  value: 128,
  items: [{ item_id: 'sku_1001', quantity: 1, price: 128 }],
});

// Purchase
analytics.track(EventType.Purchase, {
  transaction_id: 'order_9001',
  currency: 'USD',
  value: 138,
  tax: 10,
  shipping: 0,
  items: [{ item_id: 'sku_1001', quantity: 1, price: 128 }],
});

await analytics.flush();

Call flush() after high-value events such as purchases to send queued events immediately.

User Identity

Associate events with a signed-in customer:

await analytics.setUser('customer_123', {
  email_hash: 'hash-value',
  loyalty_tier: 'gold',
});

Clear the customer when they sign out:

await analytics.setUser(null);

Flush on App Background

For critical flows, flush when the app moves to the background:

import { AppState } from 'react-native';
import { analytics } from '@yesplz-ai/analytics-react-native';

const subscription = AppState.addEventListener('change', (state) => {
  if (state === 'background' || state === 'inactive') {
    void analytics.flush();
  }
});

// Later, during cleanup:
subscription.remove();

TypeScript Payload Example

import {
  analytics,
  EventType,
  ItemListId,
  type TrackProperties,
} from '@yesplz-ai/analytics-react-native';

const purchase: TrackProperties = {
  transaction_id: 'order_9001',
  currency: 'USD',
  value: 138,
  item_list_id: ItemListId.YOU_MAY_ALSO_LIKE,
  items: [
    {
      item_id: 'sku_1001',
      quantity: 1,
      price: 128,
      size: 'M',
      color: 'Black',
    },
  ],
};

analytics.track(EventType.Purchase, purchase);

Notes

• Tracking is manual. Call analytics.track(...) at the points in your app where customer actions occur.
• Use stable product IDs in id and item_id fields so attribution and reporting stay consistent.
• Include currency, value, and items for commerce events whenever available.