react-native-insider 8.1.0 → 9.0.0-nh

package/README.md

@@ -1,710 +1,139 @@
 # Insider ReactNative SDK
 
-Official React Native SDK for [Insider](https://www.insiderone.com) - A single platform for building individualized, cross-channel customer experiences.
-
 [![Coverus](https://github.com/useinsider/coverus-artifacts/raw/main/badges/github/useinsider/react-native-insider/coverage.svg)](http://coverus.internal.dataforce/app/project/github/useinsider/react-native-insider)
 [![npm version](https://img.shields.io/npm/v/react-native-insider.svg)](https://www.npmjs.com/package/react-native-insider)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 
-## Features
-
-- **User Management** - Comprehensive user profile management with custom attributes
-- **Event Tracking** - Track custom events with flexible parameters
-- **E-commerce** - Product tracking, cart management, purchase events, and wishlist
-- **Smart Recommendations** - AI-powered personalized product recommendations
-- **Message Center** - In-app messaging and notification management
-- **Content Optimizer** - A/B testing and dynamic content optimization
-- **Push Notifications** - Rich push notifications with deep linking support
-- **In-App Messages** - Native in-app messaging with callback handlers
-- **Geofencing** - Location-based targeting and triggers
-- **GDPR Compliance** - Built-in consent management and privacy controls
-- **TypeScript Support** - Full TypeScript definitions included
+Official React Native SDK for the [Insider](https://www.insiderone.com) marketing
+and growth platform. Wraps the native Insider SDK on Android and iOS and exposes
+its features — user identification, event tracking, product and purchase events,
+push notifications, smart recommendations, content optimizer, message center,
+App Cards and App Frames — through a single `Insider` module with full TypeScript definitions.
 
 ## Installation
 
-With npm:
-
 ```bash
 npm install react-native-insider
 ```
 
-With yarn:
-
-```bash
-yarn add react-native-insider
-```
-
-### iOS
-
-1. Install CocoaPods dependencies:
+On iOS, install the pods afterwards:
 
 ```bash
-cd ios && pod install && cd ..
-```
-
-2. In your Xcode project, enable the following capabilities under **Signing & Capabilities**:
-   - **Push Notifications** (if you are using **InsiderMobileAdvancedNotification** SDK)
-   - **Location (Always and WhenInUse)** (if you are using **InsiderGeofence** SDK)
-   - **Background Modes**: `Remote notifications` and `Location updates`
-
-3. For rich push notifications, add Notification Service Extension and Notification Content Extension targets to your iOS project. Add the following to your `Podfile`:
-
-```ruby
-target 'YourNotificationService' do
-  use_frameworks!
-  pod "InsiderMobileAdvancedNotification"
-end
-
-target 'YourNotificationContent' do
-  use_frameworks!
-  pod "InsiderMobileAdvancedNotification"
-end
-```
-
-### Android Setup
-
-1. Add the Insider Maven repository to your **project-level** `android/build.gradle`:
-
-```gradle
-allprojects {
-    repositories {
-        maven { url 'https://mobilesdk.useinsider.com/android' }
-    }
-}
+cd ios && pod install
 ```
 
-2. Add Google Services to your **project-level** `android/build.gradle`:
+## Platform requirements
 
-```gradle
-buildscript {
-    dependencies {
-        classpath 'com.google.gms:google-services:4.4.4'
-    }
-}
-```
+| Platform | Minimum |
+|----------|---------|
+| React Native | `>=0.74` (autolinking) |
+| React | `>=18` |
+| Android | `minSdk 24`, `compileSdk 36` |
+| iOS | deployment target `12.0` |
 
-3. In your **app-level** `android/app/build.gradle`, add your partner name:
+App Frames on iOS additionally needs React Native `>=0.77` with the New
+Architecture enabled; the rest of the SDK works on `>=0.74`.
 
-```gradle
-android {
-    defaultConfig {
-        manifestPlaceholders = [partner: 'your_partner_name']
-    }
-}
-```
+The Insider pods are pinned by the podspec, so no version has to be declared
+in your `Podfile`. On Android the SDK pulls in Firebase Messaging, Google Play
+Services location and Huawei HMS push as transitive dependencies.
 
-4. If `android:allowBackup="false"` exists in your `AndroidManifest.xml`, remove it to allow Insider SDK to function properly.
+Gradle and Xcode setup — the Insider Maven repository, the `partner`
+manifest placeholder, App Groups and the notification service extensions — is
+covered in the integration guide and the sample app linked below.
 
-## Quick Start
+## Quick start
 
 ```typescript
-import React, { useEffect } from 'react';
 import Insider from 'react-native-insider';
 import InsiderCallbackType from 'react-native-insider/src/InsiderCallbackType';
 
-function App() {
-  useEffect(() => {
-    // Initialize the SDK
-    Insider.init(
-      'your_partner_name',
-      'group.com.your.app', // iOS App Group ID
-      (type, data) => {
-        // Handle SDK callbacks
-        switch(type) {
-          case InsiderCallbackType.NOTIFICATION_OPEN:
-            console.log('Notification opened:', data);
-            break;
-          case InsiderCallbackType.INAPP_BUTTON_CLICK:
-            console.log('In-app button clicked:', data);
-            break;
-          case InsiderCallbackType.SESSION_STARTED:
-            console.log('Session started');
-            break;
-        }
-      }
-    );
-
-    // iOS-specific configurations
-    Insider.registerWithQuietPermission(false);
-    Insider.setActiveForegroundPushView();
-
-    // Enable data collection
-    Insider.enableIDFACollection(true);
-    Insider.enableLocationCollection(true);
-
-    // Start geofencing
-    Insider.startTrackingGeofence();
-  }, []);
-
-  return <YourApp />;
+function onInsiderCallback(type, data) {
+  switch (type) {
+    case InsiderCallbackType.NOTIFICATION_OPEN:
+      // Handle push tap.
+      break;
+    case InsiderCallbackType.INAPP_BUTTON_CLICK:
+      // Handle in-app button tap.
+      break;
+    case InsiderCallbackType.INAPP_SEEN:
+      // Handle in-app message displayed.
+      break;
+    case InsiderCallbackType.TEMP_STORE_PURCHASE:
+      // Handle temp store purchase.
+      break;
+    case InsiderCallbackType.TEMP_STORE_ADDED_TO_CART:
+      // Handle temp store add-to-cart.
+      break;
+    case InsiderCallbackType.TEMP_STORE_CUSTOM_ACTION:
+      // Handle temp store custom action.
+      break;
+    case InsiderCallbackType.SESSION_STARTED:
+      // Handle session start.
+      break;
+  }
 }
-```
 
-## API Reference
-
-### Initialization
-
-#### `init(partnerName, appGroup, callback)`
-
-Initialize the Insider SDK with your partner name and callback handler.
-
-```typescript
 Insider.init(
-  'your_partner_name',
-  'group.com.your.app', // iOS App Group ID
-  (type, data) => {
-    // Handle callbacks
-  }
+  'YOUR_PARTNER_NAME',
+  'group.com.example.app', // iOS App Group; pass any value on Android.
+  onInsiderCallback,
 );
-```
 
-**Parameters:**
-- `partnerName` (string): Your Insider partner name
-- `appGroup` (string): iOS App Group ID (e.g., 'group.com.your.app')
-- `callback` (function): Callback function to handle SDK events
+// Identify the user.
+Insider.getCurrentUser()
+  .setName('Ada')
+  .setEmail('ada@example.com')
+  .setEmailOptin(true);
 
-#### `initWithCustomEndpoint(partnerName, appGroup, endpoint, callback)`
-
-Initialize with a custom API endpoint for enterprise customers.
-
-```typescript
-Insider.initWithCustomEndpoint(
-  'your_partner_name',
-  'group.com.your.app',
-  'https://your-custom-endpoint.com',
-  (type, data) => {
-    // Handle callbacks
-  }
-);
-```
-
-### User Management
-
-#### Get Current User
-
-```typescript
-const user = Insider.getCurrentUser();
-```
-
-#### User Attributes
-
-```typescript
-import InsiderGender from 'react-native-insider/src/InsiderGender';
-
-user
-  .setName('John')
-  .setSurname('Doe')
-  .setAge(30)
-  .setGender(InsiderGender.Male) // Male: 0, Female: 1, Other: 2
-  .setBirthday(new Date('1990-01-01'))
-  .setEmail('john.doe@example.com')
-  .setPhoneNumber('+1234567890')
-  .setLanguage('en')
-  .setLocale('en_US');
-```
-
-#### Marketing Preferences
-
-```typescript
-user
-  .setEmailOptin(true)
-  .setSMSOptin(true)
-  .setPushOptin(true)
-  .setWhatsappOptin(true)
-  .setLocationOptin(true);
-```
-
-#### Custom Attributes
-
-```typescript
-user
-  .setCustomAttributeWithString('membership_level', 'gold')
-  .setCustomAttributeWithInt('loyalty_points', 1500)
-  .setCustomAttributeWithDouble('account_balance', 99.99)
-  .setCustomAttributeWithBoolean('is_premium', true)
-  .setCustomAttributeWithDate('last_purchase', new Date())
-  .setCustomAttributeWithArray('interests', ['sports', 'technology']);
-
-// Remove a custom attribute
-user.unsetCustomAttribute('membership_level');
-```
-
-#### Login/Logout
-
-```typescript
-import InsiderIdentifier from 'react-native-insider/src/InsiderIdentifier';
-
-// Login with identifiers
-const identifiers = new InsiderIdentifier()
-  .addEmail('user@example.com')
-  .addPhoneNumber('+1234567890')
-  .addUserID('user123')
-  .addCustomIdentifier('custom_key', 'custom_value');
-
-user.login(identifiers);
-
-// Login with callback to get Insider ID
-user.login(identifiers, (insiderID) => {
-  console.log('Insider ID:', insiderID);
-});
-
-// Logout
-user.logout();
-
-// Sign-up confirmation
-Insider.signUpConfirmation();
-```
-
-### Event Tracking
-
-```typescript
-// Simple event
-Insider.tagEvent('app_opened').build();
-
-// Event with parameters
-Insider.tagEvent('product_viewed')
-  .addParameterWithString('product_id', 'SKU123')
-  .addParameterWithString('category', 'Electronics')
-  .addParameterWithDouble('price', 299.99)
-  .addParameterWithInt('quantity', 1)
-  .addParameterWithBoolean('in_stock', true)
-  .addParameterWithDate('viewed_at', new Date())
-  .addParameterWithArray('tags', ['featured', 'sale'])
-  .addParameterWithStringArray('colors', ['red', 'blue'])
-  .addParameterWithNumericArray('ratings', [4.5, 5.0])
+// Tag a custom event with typed parameters.
+Insider.tagEvent('add_to_favorites')
+  .addParameterWithString('product_id', 'sku-123')
+  .addParameterWithDouble('price', 29.99)
   .build();
 ```
 
-### Product & E-commerce
-
-#### Create a Product
-
-```typescript
-const product = Insider.createNewProduct(
-  'product_id',                              // Product ID
-  'Product Name',                            // Product name
-  ['Category', 'Subcategory'],               // Taxonomy (array)
-  'https://example.com/image.jpg',           // Image URL
-  99.99,                                     // Price
-  'USD'                                      // Currency
-);
-
-// Add optional attributes
-product
-  .setColor('Blue')
-  .setSize('M')
-  .setBrand('BrandName')
-  .setSalePrice(79.99)
-  .setStock(100)
-  .setQuantity(1)
-  .setSku('SKU-123')
-  .setVoucherName('SUMMER2024')
-  .setVoucherDiscount(20)
-  .setPromotionName('Summer Sale')
-  .setPromotionDiscount(15)
-  .setShippingCost(5.99)
-  .setGender('Unisex')
-  .setDescription('Product description')
-  .setTags(['featured', 'bestseller'])
-  .setInStock(true);
-```
-
-#### Cart Operations
-
-```typescript
-// Add to cart
-Insider.itemAddedToCart(product);
-
-// Remove from cart
-Insider.itemRemovedFromCart('product_id');
-
-// Clear cart
-Insider.cartCleared();
-```
-
-#### Wishlist Operations
-
-```typescript
-// Add to wishlist
-Insider.itemAddedToWishlist(product);
-
-// Remove from wishlist
-Insider.itemRemovedFromWishlist('product_id');
-
-// Clear wishlist
-Insider.wishlistCleared();
-```
-
-#### Purchase
-
-```typescript
-Insider.itemPurchased('unique_sale_id_12345', product);
-```
-
-### Page Visits
-
-```typescript
-// Home page
-Insider.visitHomePage();
-
-// Listing/Category page
-Insider.visitListingPage(['Category', 'Subcategory']);
-
-// Product detail page
-Insider.visitProductDetailPage(product);
-
-// Cart page with products
-Insider.visitCartPage([product1, product2]);
-
-// Wishlist page
-Insider.visitWishlistPage([product1, product2]);
-```
-
-### Smart Recommendations
-
-```typescript
-// Basic recommendation
-Insider.getSmartRecommendation(
-  12345,           // Recommendation ID
-  'en_US',         // Locale
-  'USD',           // Currency
-  (recommendation) => {
-    console.log('Recommendations:', recommendation);
-  }
-);
-
-// Recommendation with product context
-Insider.getSmartRecommendationWithProduct(
-  product,         // Current product
-  12345,           // Recommendation ID
-  'en_US',         // Locale
-  (recommendation) => {
-    console.log('Related products:', recommendation);
-  }
-);
-
-// Recommendation with product IDs
-Insider.getSmartRecommendationWithProductIDs(
-  ['prod1', 'prod2'],  // Product IDs array
-  12345,               // Recommendation ID
-  'en_US',             // Locale
-  'USD',               // Currency
-  (recommendation) => {
-    console.log('Recommendations:', recommendation);
-  }
-);
-
-// Track recommendation click
-Insider.clickSmartRecommendationProduct(12345, product);
-```
-
-### Message Center
+TypeScript definitions for the full surface ship with the package
+(`index.d.ts` and `src/*.d.ts`).
 
-```typescript
-Insider.getMessageCenterData(
-  20,                      // Limit
-  new Date('2024-01-01'),  // Start date
-  new Date(),              // End date
-  (messages) => {
-    console.log('Messages:', messages);
-  }
-);
-```
+### Multiple apps under one partner
 
-### Content Optimizer
+If your partner account serves several apps, pass the app identifier Insider
+gave you as the optional last argument (`appIdentifier`), so sessions and push targeting are
+attributed to the right app:
 
 ```typescript
-import ContentOptimizerDataType from 'react-native-insider/src/ContentOptimizerDataType';
-
-// Get string content
-Insider.getContentStringWithName(
-  'variable_name',
-  'default_value',
-  ContentOptimizerDataType.Content, // Content: 0, Element: 1
-  (value) => {
-    console.log('Content:', value);
-  }
-);
-
-// Get boolean content
-Insider.getContentBoolWithName(
-  'feature_enabled',
-  false,
-  ContentOptimizerDataType.Element,
-  (value) => {
-    console.log('Feature enabled:', value);
-  }
-);
-
-// Get integer content
-Insider.getContentIntWithName(
-  'max_items',
-  10,
-  ContentOptimizerDataType.Content,
-  (value) => {
-    console.log('Max items:', value);
-  }
-);
+Insider.init('YOUR_PARTNER_NAME', 'group.com.example.app', onInsiderCallback, 'my_app');
 
-// Without cache (always fetch fresh data)
-Insider.getContentStringWithoutCache(
-  'variable_name',
-  'default',
-  ContentOptimizerDataType.Content,
-  (value) => {
-    console.log('Fresh content:', value);
-  }
+Insider.initWithCustomEndpoint(
+  'YOUR_PARTNER_NAME',
+  'group.com.example.app',
+  'https://your.custom.endpoint',
+  onInsiderCallback,
+  'my_app',
 );
 ```
 
-### Push Notifications
-
-#### iOS Configuration
-
-```typescript
-// Enable quiet permission (iOS only)
-Insider.registerWithQuietPermission(true);
-
-// Handle foreground push
-Insider.setForegroundPushCallback((notification) => {
-  console.log('Foreground push:', notification);
-});
-
-// Set active foreground push view
-Insider.setActiveForegroundPushView();
-
-// Enable IDFA collection
-Insider.enableIDFACollection(true);
-
-// Disable in-app message templates (iOS)
-Insider.disableTemplatesForIOS();
-
-// Re-enable templates (iOS)
-Insider.reenableTemplatesForIOS();
-```
-
-#### Android Configuration
-
-```typescript
-// Set hybrid push token (Android only)
-Insider.setHybridPushToken('your_fcm_token');
-
-// Handle universal links (Android only)
-Insider.handleUniversalLink('https://your-link.com/path');
-```
-
-#### General Push Methods
-
-```typescript
-// Handle notification manually
-Insider.handleNotification(notificationData);
-```
-
-### In-App Messages
-
-```typescript
-// Remove current in-app message
-Insider.removeInapp();
-
-// Disable in-app messages
-Insider.disableInAppMessages();
-
-// Enable in-app messages
-Insider.enableInAppMessages();
-```
-
-### Geofencing
-
-```typescript
-// Start tracking geofences
-Insider.startTrackingGeofence();
-
-// Allow background location updates (iOS)
-Insider.setAllowsBackgroundLocationUpdates(true);
-```
-
-### GDPR & Privacy
-
-```typescript
-// Set GDPR consent
-Insider.setGDPRConsent(true);
-
-// Set mobile app access
-Insider.setMobileAppAccess(true);
-
-// Enable/disable data collection
-Insider.enableLocationCollection(true);
-Insider.enableIpCollection(true);
-Insider.enableCarrierCollection(true);
-```
-
-### Insider ID
-
-```typescript
-// Get current Insider ID (returns a Promise)
-const insiderID = await Insider.getInsiderID();
-console.log('Insider ID:', insiderID);
-
-// Listen for Insider ID changes
-Insider.insiderIDListener((insiderID) => {
-  console.log('Insider ID updated:', insiderID);
-});
-```
-
-### Miscellaneous
-
-```typescript
-// Show native app review dialog
-Insider.showNativeAppReview();
-
-// Reinitialize with new partner name
-Insider.reinitWithPartnerName('new_partner_name');
-```
-
-## TypeScript Support
-
-The SDK includes full TypeScript definitions:
-
-```typescript
-import Insider from 'react-native-insider';
-import InsiderGender from 'react-native-insider/src/InsiderGender';
-import InsiderIdentifier from 'react-native-insider/src/InsiderIdentifier';
-import InsiderCallbackType from 'react-native-insider/src/InsiderCallbackType';
-import ContentOptimizerDataType from 'react-native-insider/src/ContentOptimizerDataType';
-```
-
-## Enums
-
-### InsiderGender
-
-```typescript
-InsiderGender.Male    // 0
-InsiderGender.Female  // 1
-InsiderGender.Other   // 2
-```
-
-### InsiderCallbackType
-
-```typescript
-InsiderCallbackType.NOTIFICATION_OPEN        // 0
-InsiderCallbackType.INAPP_BUTTON_CLICK       // 1
-InsiderCallbackType.TEMP_STORE_PURCHASE      // 2
-InsiderCallbackType.TEMP_STORE_ADDED_TO_CART // 3
-InsiderCallbackType.TEMP_STORE_CUSTOM_ACTION // 4
-InsiderCallbackType.INAPP_SEEN               // 5
-InsiderCallbackType.SESSION_STARTED          // 6
-```
-
-### ContentOptimizerDataType
-
-```typescript
-ContentOptimizerDataType.Content  // 0
-ContentOptimizerDataType.Element  // 1
-```
-
-## Complete Example
-
-```typescript
-import React, { useEffect } from 'react';
-import { Platform, Linking } from 'react-native';
-import Insider from 'react-native-insider';
-import InsiderGender from 'react-native-insider/src/InsiderGender';
-import InsiderIdentifier from 'react-native-insider/src/InsiderIdentifier';
-import InsiderCallbackType from 'react-native-insider/src/InsiderCallbackType';
-
-function App() {
-  useEffect(() => {
-    // Initialize SDK
-    Insider.init('your_partner_name', 'group.com.your.app', (type, data) => {
-      switch(type) {
-        case InsiderCallbackType.NOTIFICATION_OPEN:
-          console.log('Notification clicked:', data);
-          break;
-        case InsiderCallbackType.INAPP_BUTTON_CLICK:
-          console.log('In-app button clicked:', data);
-          break;
-        case InsiderCallbackType.SESSION_STARTED:
-          console.log('Session started');
-          break;
-      }
-    });
-
-    // Configure SDK
-    Insider.registerWithQuietPermission(false);
-    Insider.setActiveForegroundPushView();
-    Insider.startTrackingGeofence();
-    Insider.enableIDFACollection(true);
-    Insider.enableLocationCollection(true);
-
-    // Handle deep links (Android)
-    if (Platform.OS === 'android') {
-      Linking.getInitialURL().then((url) => {
-        if (url) {
-          Insider.handleUniversalLink(url);
-        }
-      });
-
-      const urlListener = Linking.addEventListener('url', (event) => {
-        Insider.handleUniversalLink(event.url);
-      });
-
-      return () => urlListener.remove();
-    }
-
-    // Set up user
-    const user = Insider.getCurrentUser();
-    user
-      .setName('Jane')
-      .setEmail('jane@example.com')
-      .setAge(25)
-      .setGender(InsiderGender.Female);
-
-    // Login user
-    const identifiers = new InsiderIdentifier()
-      .addEmail('jane@example.com')
-      .addUserID('user_123');
-    user.login(identifiers);
-
-    // Track page visit
-    Insider.visitHomePage();
-
-    // Track custom event
-    Insider.tagEvent('app_opened')
-      .addParameterWithString('source', 'direct')
-      .addParameterWithDate('timestamp', new Date())
-      .build();
-
-    // Create and track product
-    const product = Insider.createNewProduct(
-      'SKU001',
-      'Premium T-Shirt',
-      ['Clothing', 'T-Shirts'],
-      'https://example.com/tshirt.jpg',
-      29.99,
-      'USD'
-    );
-
-    product.setColor('Blue').setSize('M');
-    Insider.visitProductDetailPage(product);
-  }, []);
-
-  return <YourApp />;
-}
-```
-
-## Requirements
+- The identifier must match `^[a-z0-9][a-z0-9_]{0,49}$`. The native SDK
+  validates it: an invalid value is logged and ignored, and initialization
+  still completes.
+- Omit it (or pass an empty string) to initialize without one; nothing about
+  your integration changes. A non-string value logs a warning and is ignored.
+- `reinitWithPartnerName` clears the app identifier on both platforms when it
+  switches to a different partner name; the native SDK skips a reinit with the
+  same name, so the identifier is kept.
 
-- React Native >= 0.60
-- iOS >= 11.0
-- Android >= API 21 (Android 5.0)
+## Documentation
 
-## Support
+- Integration guide: <https://academy.insiderone.com/docs/react-native-basic-sdk-setup>
+- Changelog: <https://academy.insiderone.com/docs/react-native-changelogs>
+- Sample app: <https://github.com/useinsider/ReactNativeDemo>
+- Insider website: <https://insiderone.com/>
+- Issue tracker: <https://github.com/useinsider/ReactNativeDemo/issues>
 
-- **Documentation**: [Insider Developer Hub](https://academy.insiderone.com/docs/react-native-integration)
-- **GitHub**: [useinsider/react-native-insider](https://github.com/useinsider/react-native-insider)
-- **Issues**: [Report issues](https://github.com/useinsider/react-native-insider/issues)
-- **Email**: Contact your Insider representative
+For panel-side setup — partner name, campaign and placement configuration —
+contact your Insider account manager.
 
 ## License
 
-This SDK is provided by Insider. Please refer to your commercial agreement with Insider for licensing terms.
+react-native-insider is released under the MIT License. See [LICENSE](LICENSE).