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

$3

Install the Bitespeed SDK via npm:

``bash
npm install @bitespeed/react-native-sdk
`

$3

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

👉 React Native Firebase Setup Guide

$3

Set up FCM for push notifications:

👉 FCM Installation Guide

$3

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

`javascript
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

$3

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

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

const sdk = BitespeedSDK.getInstance('.myshopify.com', 'YOUR_API_KEY')
`

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

---

$3

Identify users with their contact details and FCM token:

`javascript
await sdk.identify(
{
email: 'user@example.com',
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 when a user views a product:

`javascript
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()) |

---

$3

Track when a user adds products to their cart:

`javascript
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.

---

$3

Track notification delivery and click events:

#### Track Notification Delivery

`javascript
const mobilePushReportId = remoteMessage?.data?.mobilePushReportId

await sdk.trackNotification('delivered', mobilePushReportId)
`

#### Track Notification Click

`javascript
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

$3

| 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 |

$3

| 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

$3

- ✓ 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

$3

- ✓ 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: support@bitespeed.com, sobhan@bitespeed.co

---

License

© Bitespeed - All rights reserved