React Native Quin SDK

Overview

Quin AI is a real-time digital customer analytics tool that helps e-commerce applications predict visitors' behavior after only 3-clicks, and engage them in real-time.

The React Native Quin SDK enables you to integrate Quin's powerful analytics and personalization capabilities into your React Native mobile applications.

Features

• Real-time user behavior tracking
• Event-based analytics
• Personalized user engagement
• E-commerce specific tracking events
• Custom event support

Installation

# Using npm
npm install react-native-quin-sdk @react-native-async-storage/async-storage

# Using yarn
yarn add react-native-quin-sdk @react-native-async-storage/async-storage

Important: This SDK requires @react-native-async-storage/async-storage as a peer dependency to store session and user data.

iOS Setup

After installation, install the CocoaPods dependencies:

cd ios && pod install && cd ..
# or
npx pod-install

Android Setup

No additional steps required for Android setup.

Basic Integration

Initialize the SDK

Add the following code to your application's entry point (typically App.js or index.js):

import React, { useEffect } from 'react';
import { Quin } from 'react-native-quin-sdk';

function App() {
  useEffect(() => {
    const initQuin = async () => {
      try {
        // Initialize with your API key and domain
        await Quin.getInstance().setConfig(
          'YOUR_API_KEY',
          'YOUR_DOMAIN',
          __DEV__ // Enable logging in development mode
        );

        // Set user identifier
        await Quin.getInstance().setUser('GoogleClientId');

        console.log('Quin SDK initialized successfully');
      } catch (error) {
        console.error('Failed to initialize Quin SDK:', error);
      }
    };

    initQuin();
  }, []);

  // Rest of your App component
  return (
    // Your app content
  );
}

export default App;

Tracking User Behavior

Tracking Page Views

import { Quin } from 'react-native-quin-sdk';

function HomeScreen() {
  useEffect(() => {
    // Track when user visits the home screen
    Quin.getInstance().eCommerce.sendPageViewHomeEvent('ios | android', (action) => {
      // Added platform parameter
      if (action) {
        // Handle action (show promotions, personalized content, etc.)
        console.log('Received action:', action);
      }
    });
  }, []);

  // Your component JSX
}

Tracking Product Interactions

import { Quin } from 'react-native-quin-sdk';

function ProductScreen({ product }) {
  const viewProduct = () => {
    const item = {
      id: product.id,
      name: product.name,
      category: product.category,
      categoryId: product.categoryId,
      price: product.price,
      currency: 'USD',
      customAttributes: product.attributes,
    };

    // Track product view
    Quin.getInstance().eCommerce.sendPageViewDetailEvent(item, 'ios | android', (action) => {
      // Added platform parameter
      // Handle any returned actions
    });
  };

  const addToCart = () => {
    const item = {
      /*...same as above*/
    };

    // Track add to cart
    Quin.getInstance().eCommerce.sendAddToCartDetailEvent(item, 1, 'ios | android', (action) => {
      // Added platform parameter
      // Handle any returned actions
    });
  };

  useEffect(() => {
    viewProduct();
  }, [product]);

  // Your component JSX with add to cart button that calls addToCart()
}

Tracking Purchases

import { Quin } from 'react-native-quin-sdk';

function CheckoutComplete({ orderTotal, items }) {
  useEffect(() => {
    // Track completed purchase
    Quin.getInstance().eCommerce.sendPurchaseCompletedEvent(orderTotal, 'ios | android', (action) => {
      // Added platform parameter
      // Maybe show a thank you promotion based on the action
    });
  }, []);

  // Your order confirmation UI
}

Data Structures

Item

The core data structure for products:

interface Item {
  id: string;
  name: string;
  category: string;
  categoryId: string;
  price: number;
  currency: string;
  customAttributes?: Record<string, any>;
}

Action

Actions are returned from tracking functions and can be used to drive personalized experiences:

interface Action {
  actionId?: string;
  actionType?: string;
  category?: string;
  categoryId?: string;
  promotionCode?: string;
  custom?: boolean;
  display?: Display;
  html?: string;
}

Display

Controls how an action should be displayed in your UI:

interface Display {
  paddle?: boolean;
  position?: string;
  fields?: Record<string, DisplayField>;
  properties?: Record<string, DisplayProperty>;
}

Custom Events

For tracking specialized behaviors:

import { Quin, createEvent } from 'react-native-quin-sdk';

// Create a custom event
const customEvent = createEvent(
  'user_engagement', // category
  'tutorial_complete', // action
  'onboarding', // label
  'tutorial_screen', // page
  null, // no item for this event
);

// Add custom attributes
const eventWithAttributes = {
  ...customEvent,
  customAttributes: {
    completionTime: '45s',
    tutorialVersion: '2.1',
  },
};

// Track the event
Quin.getInstance().track(eventWithAttributes, undefined, (action) => {
  // Handle any actions
});

Testing the Integration

To verify your integration, use the test method:

import { Quin, createEvent } from 'react-native-quin-sdk';

// Create a test event
const testEvent = createEvent('test', 'verification', 'test_label', 'test_screen');

// Send test event
Quin.getInstance().test(testEvent, (action) => {
  console.log('Test successful, received action:', action);
  // This action is a mock response to help you implement UI components
});

Available E-Commerce Events

The SDK provides these pre-defined e-commerce events:

• sendPageViewHomeEvent(platform: string) - Home page view
• sendPageViewListingEvent(platform: string, label: string) - Product listing view
• sendAddToCartListingEvent(platform: string, item: Item, quantity: number) - Add to cart from listing
• sendPageViewDetailEvent(platform: string, item: Item) - Product detail view
• sendAddToCartDetailEvent(platform: string, item: Item, quantity: number) - Add to cart from detail
• sendAddToFavouritesEvent(platform: string, item: Item) - Add to favorites/wishlist
• sendGoToCartEvent(platform: string) - Cart page view
• sendCheckoutEvent(platform: string) - Checkout initiation
• sendPurchaseCompletedEvent(platform: string, totalBasketSize: number) - Completed purchase

And many more. See the SDK reference for the complete list.

Troubleshooting

Common Issues

• SDK not initializing: Verify your API key and domain, and ensure you have network connectivity.

• Events not tracking: Make sure SDK initialization completes before sending events.

• AsyncStorage issues: If you see AsyncStorage errors, ensure the library is properly installed:

  npm install @react-native-async-storage/async-storage
  cd ios && pod install

• iOS build failures: Try clearing the build folder and reinstalling pods:

  cd ios
  rm -rf build
  pod install

• No actions returning: Verify your Quin account configuration in the dashboard.

Support

For additional help, contact us at [email protected] or visit our documentation at docs.quinengine.com.

License

MIT