react-native-converted-in-sdk

A React Native SDK for ConvertedIn, providing easy integration of ConvertedIn's tracking and analytics features into your React Native application.

📹 Demo

| iOS | Android | | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | | | |

🛠️ Requirements

• iOS 13.0 or higher
• Android 5.0 (API level 21) or higher

📦 Installation

Install the package using npm:

npm install react-native-converted-in-sdk

Or with yarn:

yarn add react-native-converted-in-sdk

Follow these steps to complete the installation:

iOS

• Add ConvertedinMobileSDK to your Podfile:

  pod 'react-native-converted-in-sdk', :path => '../node_modules/react-native-converted-in-sdk'

• Run pod install inside the ios directory.

Android

• Add the following line to the android/settings.gradle file:

  include ':react-native-converted-in-sdk'
  project(':react-native-converted-in-sdk').projectDir = new File(rootProject.projectDir, '../node_modules/react-native-converted-in-sdk/android')

• Add the following line to the android/app/build.gradle file:

  implementation project(':react-native-converted-in-sdk')

• Sync your project with Gradle files by running:

  ./gradlew sync

🚀 Usage

Manual Module Usage

1. Import the module and initialize it in the root of your app:

   import { initializeSDK } from 'react-native-converted-in-sdk';
   
   initializeSDK({
     pixelId: 'your_pixel_id',
     storeUrl: 'your_store_url',
   });

2. Use the SDK methods in your components:

   import { identifyUser } from 'react-native-converted-in-sdk';
   
   const Component = () => {
     React.useEffect(() => {
       // Example usage of SDK functions
       identifyUser("[email protected]", "+91", "9876543210");
     }, []);
   
     // Your component logic here
   };

Usage with Hook

1. Wrap your app with RNConvertInSDKProvider:

   export default function App() {
     return (
       <RNConvertInSDKProvider
         pixelId="your_pixel_id"
         storeUrl="your_store_url"
       >
         <AppContent />
       </RNConvertInSDKProvider>
     );
   }

2. Use the useConvertedInSdk hook in your components:

   import { useConvertedInSdk } from 'react-native-converted-in-sdk';
   
   const Component = () => {
     const { identifyUser } = useConvertedInSdk();
   
     React.useEffect(() => {
       // Example usage of SDK functions
       identifyUser("[email protected]", "+91", "9876543210");
     }, []);
   
     // Your component logic here
   };

📚 API Reference

RNConvertInSDKProvider

| Prop | Type | Required | Description | | ---------- | ------ | -------- | ------------------------- | | pixelId | string | Yes | Your ConvertedIn pixel ID | | storeUrl | string | Yes | Your store URL |

useConvertedInSdk

Returns an object with the following methods:

| Method | Parameters | Return Type | Description | | ----------------------- | ------------------------------------------------------------------------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | isInitialized | None | boolean | Returns whether the SDK has been initialized. | | initializeSDK | config: { pixelId: string, storeUrl: string } | Promise<void> | Initializes the SDK with the provided configuration. Call this as early as possible in your app's lifecycle. | | identifyUser | email: string, countryCode: string, phoneNumber: string | void | Identifies a user with their email, country code, and phone number. This helps in tracking user-specific events and improving personalization. | | addEvent | eventName: string, currency: string, total: number, products: Product[] | void | Adds a custom event with the specified name, currency, total, and products. This allows tracking specific actions or milestones in your app. | | viewContentEvent | currency: string, total: number, products: Product[] | void | Tracks a view content event when a user views a product or content page. Includes details like currency, total value, and viewed products. | | addToCartEvent | currency: string, total: number, products: Product[] | void | Tracks an add-to-cart event when a user adds items to their shopping cart. Includes details about the added products, total value, and currency. | | initiateCheckoutEvent | currency: string, total: number, products: Product[] | void | Tracks the initiation of the checkout process. This event should be called when a user starts the purchasing process. | | purchaseEvent | currency: string, total: number, products: Product[] | void | Tracks a completed purchase event. This should be called when a user successfully completes a transaction, including details of purchased products. | | registerEvent | None | void | Tracks a user registration event. This should be called when a new user creates an account in your app. |

Product Interface

| Property | Type | Description | | ---------- | ------ | ------------------------------------- | | id | number | The unique identifier of the product. | | quantity | number | The quantity of the product. | | name | string | The name of the product. |

🧪 Sample App

Check the example folder for a complete implementation example.

[!NOTE] If you encounter an error while installing pods in example/ios, please refer to this solution: https://stackoverflow.com/a/78874710/12355129

🛠️ Development

To develop the SDK locally:

1. Clone the repository.

2. Ensure you have the following environment set up:

   • Node.js version 18 or higher.
   • Yarn version 3 or higher (project version: 3.6.1).
   • Java 17 or higher.
   • For iOS development: Xcode 12.0 or higher. iOS deployment target 13.0 or higher.
   • For Android development: Android Studio 4.0 or higher.

3. Install dependencies:

   yarn install

4. Run the example app:

   • iOS:

     cd example/ios && pod install && cd ../..
     yarn example ios

   • Android:

     yarn example android

🧪 Testing

Run tests with:

yarn test

🚨 Error Handling

If any SDK method is called before initialization, an error will be thrown with the message:

SDK must be initialized before calling this method.

Make sure to initialize the SDK using the initializeSDK method before invoking any other SDK methods.

🤝 Contributing

See the contributing guide to learn how to contribute to the repository and the development workflow.

📚 Official Documentation

For detailed information and advanced usage, refer to the official ConvertedIn SDK documentation:

• Android Getting Started Guide
• iOS Getting Started Guide

📜 License

MIT