@yesplz-ai/analytics-react-native 0.1.0

package/README.md

@@ -0,0 +1,183 @@
+# @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`.
+
+```sh
+npm install @yesplz-ai/analytics-react-native @react-native-async-storage/async-storage
+```
+
+Or with Yarn:
+
+```sh
+yarn add @yesplz-ai/analytics-react-native @react-native-async-storage/async-storage
+```
+
+Or with pnpm:
+
+```sh
+pnpm add @yesplz-ai/analytics-react-native @react-native-async-storage/async-storage
+```
+
+For Expo projects, install the AsyncStorage peer dependency with Expo:
+
+```sh
+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.
+
+```sh
+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.
+
+```ts
+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:
+
+```ts
+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
+
+```ts
+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:
+
+```ts
+await analytics.setUser('customer_123', {
+  email_hash: 'hash-value',
+  loyalty_tier: 'gold',
+});
+```
+
+Clear the customer when they sign out:
+
+```ts
+await analytics.setUser(null);
+```
+
+## Flush on App Background
+
+For critical flows, flush when the app moves to the background:
+
+```ts
+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
+
+```ts
+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.