Bitespeed React Native SDK

© Bitespeed

The Bitespeed React Native SDK enables seamless tracking of user events, product interactions, and push notifications in your React Native applications. It provides accurate user identification and easy integration with the Bitespeed API.

Features

• User Identification - Identify users with contact details (email/phone)
• Push Notification Tracking - Track notification delivery and click events
• Product Event Tracking - Track product views and cart events
• Firebase Cloud Messaging Integration - Full FCM support for push notifications

Installation

Step 1: Install the SDK

Install the Bitespeed SDK via npm:

npm install @bitespeed/react-native-sdk

Step 2: Set Up Firebase for React Native

Follow the official React Native Firebase setup guide for both Android and iOS:

👉 React Native Firebase Setup Guide

Step 3: Configure Firebase Cloud Messaging (FCM)

Set up FCM for push notifications:

👉 FCM Installation Guide

Step 4: Add FCM Message Handlers

Add the following code to your App.js (or index.js) to handle incoming FCM messages:

import messaging from '@react-native-firebase/messaging'

// Foreground message handler
messaging().onMessage(async (remoteMessage) => {
  // Track notification delivery
  const mobilePushReportId = remoteMessage?.data?.mobilePushReportId
  await sdk.trackNotification('delivered', mobilePushReportId)
})

// Background/Quit state message handler
messaging().setBackgroundMessageHandler(async (remoteMessage) => {
  // Track notification delivery
  const mobilePushReportId = remoteMessage?.data?.mobilePushReportId
  await sdk.trackNotification('delivered', mobilePushReportId)
})

📚 Learn more: Receiving Messages Documentation

⚠️ Important Setup Notes

1. Add Firebase Configuration Files:

   • Android: Add google-services.json to your Android project (android/app/)
   • iOS: Add GoogleService-Info.plist to your iOS project

2. Platform-Specific Setup:

   • Both Android and iOS require additional FCM configuration
   • Refer to the official Firebase documentation for platform-specific steps

3. Request Push Notification Permissions:

   • Always request user permission before sending push notifications
   • Use messaging().requestPermission() for iOS

4. Track Notifications:

   • Call trackNotification() in both onMessage and setBackgroundMessageHandler handlers

Usage

1. Initialize the SDK

Initialize the SDK with your Bitespeed API key and Shopify store URL:

import BitespeedSDK from '@bitespeed/react-native-sdk'

const sdk = BitespeedSDK.getInstance('<SHOP_URL>.myshopify.com', 'YOUR_API_KEY')

💡 Tip: Initialize the SDK as early as possible in your app lifecycle (e.g., in App.js).

2. Identify User

Identify users with their contact details and FCM token:

await sdk.identify(
  {
    email: '[email protected]',
    phone: '1234567890',
    firstName: 'John',
    lastName: 'Doe',
  },
  '91', // Country code (e.g., '91' for India, '1' for USA)
  'fcm-token', // FCM device token
  'ios_mobile_app' || 'ios_mobile_app', // source type - depending on platform
)

Parameters:

| Parameter | Type | Required | Description | | ------------- | ------ | -------- | ------------------------------ | | email | string | Optional | User's email address | | phone | string | Optional | User's phone number | | firstName | string | Optional | User's first name | | lastName | string | Optional | User's last name | | countryCode | string | Required | Country code (e.g., '91', '1') | | fcmToken | string | Required | Firebase Cloud Messaging token |

⚠️ Important: You must call identify() before tracking any events.

3. Track Product View Events

Track when a user views a product:

import { v4 as uuidv4 } from 'uuid'

const ssid = uuidv4()
const ref = uuidv4()

await sdk.trackProductEvent(
  'productView',
  {
    event: {
      id: '12345', // Product ID
      name: 'Sample Product Variant', // Product name
      price: 4999, // Price
      handle: 'sample-product-variant', // Product handle/slug
      variantId: '54321', // Variant ID
      variants: [
        {
          id: '54321',
          name: 'Sample Product Variant',
          price: 4999,
          handle: 'sample-product-variant',
          // Add any additional variant properties here
        },
      ],
      metadata: {
        // Any additional metadata
        category: 'Electronics',
        brand: 'Sample Brand',
      },
    },
    ssid: ssid, // Session ID
    ref: ref, // Reference ID
  },
  'android',
  'mobile_app',
)

Event Parameters:

| Parameter | Type | Required | Description | | ----------- | ------ | -------- | ----------------------------------------- | | id | string | Required | Unique product identifier | | name | string | Required | Product name | | price | number | Required | Product price (in smallest currency unit) | | handle | string | Required | Product handle/slug | | variantId | string | Required | Product variant ID | | variants | array | Required | Array of product variants | | metadata | object | Optional | Additional product metadata | | ssid | string | Required | Session identifier (use uuidv4()) | | ref | string | Required | Reference identifier (use uuidv4()) |

4. Track Add to Cart Events

Track when a user adds products to their cart:

import { v4 as uuidv4 } from 'uuid'

const ssid = uuidv4()
const ref = uuidv4()

// Map cart items to line items format
const lineItems = listOfProductsAddedToCart.map((item) => ({
  product_id: item?.id,
  variant_id: item?.variantId,
  sku: item?.sku,
  title: item?.title,
}))

await sdk.trackProductEvent(
  'cartCreated',
  {
    event: {
      cartToken: cartToken, // Cart token - REQUIRED for proper cart tracking
      id: '12345', // Product ID
      name: 'Sample Product Variant', // Product name
      price: 4999, // Price in smallest currency unit
      handle: 'sample-product-variant', // Product handle
      variantId: '54321', // Variant ID
      variants: [
        {
          id: '54321',
          name: 'Sample Product Variant',
          price: 4999,
          handle: 'sample-product-variant',
          // Add any additional variant properties here
        },
      ],
      metadata: {
        // Any additional metadata
      },
      quantity: 1, // Quantity added to cart
      lineItems: lineItems, // All items in the cart
    },
    ssid: ssid,
    ref: ref,
  },
  'android',
  'mobile_app',
)

Event Parameters:

| Parameter | Type | Required | Description | | ----------- | ------ | ------------ | ---------------------------------------------- | | cartToken | string | Required | Unique cart identifier (critical for tracking) | | id | string | Required | Product ID | | name | string | Required | Product name | | price | number | Required | Product price | | handle | string | Required | Product handle/slug | | variantId | string | Required | Product variant ID | | variants | array | Required | Array of product variants | | quantity | number | Required | Quantity added to cart | | lineItems | array | Required | Array of all cart items | | metadata | object | Optional | Additional metadata | | ssid | string | Required | Session identifier | | ref | string | Required | Reference identifier |

⚠️ Critical: Always include cartToken in cart events, or cart tracking will not work properly.

💡 Tip: Use the same ssid and ref throughout a user session for better tracking continuity.

5. Track Push Notification Events

Track notification delivery and click events:

Track Notification Delivery

const mobilePushReportId = remoteMessage?.data?.mobilePushReportId

await sdk.trackNotification('delivered', mobilePushReportId)

Track Notification Click

const mobilePushReportId = remoteMessage?.data?.mobilePushReportId

await sdk.trackNotification('clicked', mobilePushReportId)

Parameters:

| Parameter | Type | Required | Description | | -------------------- | ------ | -------- | ---------------------------------------- | | event | string | Required | Event type: 'delivered' or 'clicked' | | mobilePushReportId | string | Required | Unique notification identifier (UUID) |

💡 Tip: The mobilePushReportId is automatically included in the notification payload by Bitespeed.

Supported Events

Product Events

| Event | Description | When to Use | | ------------- | --------------------- | ---------------------------------------- | | productView | Product page viewed | User lands on a product detail page | | cartCreated | Product added to cart | User adds item(s) to their shopping cart |

Notification Events

| Event | Description | When to Use | | ----------- | ---------------------- | ------------------------------------------------------- | | delivered | Notification delivered | Notification received on device (foreground/background) | | clicked | Notification clicked | User taps on the notification |

Best Practices

✅ Initialize Early - Initialize the SDK when your app starts ✅ Identify First - Always call identify() before tracking events ✅ Use UUIDs - Generate unique ssid and ref values for each session ✅ Include Cart Tokens - Always pass cartToken in cart events ✅ Handle Errors - Wrap SDK calls in try-catch blocks ✅ Track All Notification States - Track both delivery and click events

Troubleshooting

Issue: Events not appearing in Bitespeed dashboard

• ✓ Verify API key and shop URL are correct
• ✓ Ensure identify() was called before tracking events
• ✓ Check that cartToken is included in cart events
• ✓ Verify FCM is properly configured

Issue: Push notifications not working

• ✓ Confirm Firebase configuration files are added to both platforms
• ✓ Check that notification permissions are granted
• ✓ Verify FCM token is being passed to identify()
• ✓ Test with Firebase Console to isolate SDK issues

Support

For assistance or questions, contact Bitespeed Support:

📧 Email: [email protected], [email protected]

License

© Bitespeed - All rights reserved