React Native SDK

The Monetai React Native SDK enables you to integrate dynamic pricing and personalized offers directly into your app. This guide walks you through installation, initialization, event tracking, and implementing dynamic pricing with the SDK.

Prerequisites

• React Native 0.73 or higher
• iOS: iOS 13.0 or higher
• Android: API Level 24 or higher
  • Android is supported from SDK version 0.2.9.
  • Android Billing Client v7 is used from SDK version 0.3.0.

---

SDK Setup

📌 This section covers how to install the Monetai SDK and configure it to collect the data needed for dynamic pricing.
Please make sure to follow all three steps to lay the foundation for all promotion features.

1. SDK Installation

First, add the Monetai package to your project using your preferred package manager.

yarn

yarn add @hayanmind/monetai-react-native

npm

npm install @hayanmind/monetai-react-native

iOS Additional Setup
Run the following command in your iOS project to install native modules

cd ios && pod install

App Rebuild
After installation, rebuild your app to apply the changes.

iOS

npx react-native run-ios

Android

npx react-native run-android

---

2. SDK Initialization

Initialize the SDK when your app launches. We recommend doing this in a top-level component like App.js.

import MonetaiSDK from "@hayanmind/monetai-react-native";

// Initialize when app starts
const initializeMonetai = async () => {
  try {
    const result = await MonetaiSDK.initialize({
      sdkKey: "YOUR_SDK_KEY", // SDK key issued from Monetai dashboard
      userId: "USER_ID", // User ID of your app's user
      useStoreKit2: true, // Use StoreKit2 on iOS 15+ devices (recommended)
    });

    console.log("Monetai SDK initialization completed:", result);
  } catch (error) {
    console.error("Monetai SDK initialization failed:", error);
  }
};

// Call in App.js
useEffect(() => {
  initializeMonetai();
}, []);

API Reference: MonetaiSDK.initialize()

Parameters

Parameter	Type	Description
sdkKey	string	SDK key issued from Monetai (Settings > SDK Integration)
userId	string	User ID of your app's user (if not available, use a unique identifier such as email or device ID)
useStoreKit2	boolean?	Whether to use StoreKit2 (iOS only, default: false)

Return Value

Return Value	Type	Description
organizationId	number	Organization ID
platform	'react_native'	Platform info
version	string	SDK version
userId	string	Set user ID

---

3. Logging User Events

This is a critical step. Monetai's AI model relies entirely on the user events you log to analyze behavior and predict purchase intent. Without this data, the prediction feature will not function.

import MonetaiSDK from "@hayanmind/monetai-react-native";

// Basic event logging
await MonetaiSDK.logEvent({
  eventName: "app_in",
});

// Event logging with parameters
await MonetaiSDK.logEvent({
  eventName: "screen_in",
  params: { screen: "home" },
});

Event Logging Tips

• Log all in-app events. Monetai will automatically select events most relevant to non-payer prediction for training.
• If no events are logged, instrument events on key features or buttons, especially those that occur before a purchase.

Event Handling Before Initialization

Events logged before the SDK is initialized are queued and sent automatically once initialization is complete.

Parameter Usage Guidelines

Important: Even with the same event name, different parameters create different events that the AI model recognizes separately. Using too many diverse parameter values can reduce model accuracy.

Best Practices:

• ✅ Good: { screen: "home" }, { button: "upgrade" }, { category: "premium" }
• ❌ Avoid: { timestamp: "2024-01-15T10:30:00Z" }, { userId: "user123" }, { sessionId: "abc123" }

Why? Parameters like timestamps, user IDs, or session IDs create unique events for each occurrence, making it difficult for the model to find patterns. Focus on parameters that represent user behavior categories rather than specific instances.

API Reference: MonetaiSDK.logEvent()

Parameters

Parameter	Type	Description
eventName	string	Event name
params	object?	Event parameters (optional)

---

Implementing Dynamic Pricing

📌 With the essential setup complete, this section covers how to record product impressions and retrieve personalized offers.
The core workflow is: define a placement for each screen and log product views → call getOffer() to retrieve personalized offers.

1. Logging Product Views

This step is required. When a user views a product (pricing screen), call MonetaiSDK.logViewProductItem() to record the impression. This data is essential for Monetai to optimize offer targeting — without it, offer personalization will not work correctly.

Log each product separately

If your pricing screen displays multiple products, you must call logViewProductItem() for each product individually. Every product shown to the user needs its own log call.

All purchase screens

Define a descriptive placement value for each screen where products are displayed (e.g., main_paywall, special_offer, bottom_banner). This data helps Monetai optimize pricing. When you later create a promotion for a screen, use the same placement value as the promotion's placement so that historical data is automatically linked. If you've already created a promotion in the dashboard, you can find its placement value in Dashboard → Promotions → Promotion Settings.

import MonetaiSDK from "@hayanmind/monetai-react-native";

// Log when the user sees the pricing screen — call for each product
await MonetaiSDK.logViewProductItem({
  placement: "main_paywall",
  productId: "premium_monthly",
  price: 9.99,
  regularPrice: 9.99,
  currencyCode: "USD",
});

Pricing optimization screen

For screens where getOffer() is also used to apply Monetai pricing optimization (see next section), use the same placement value for both logViewProductItem() and getOffer().

// Log when the user sees the pricing screen — call for each product
await MonetaiSDK.logViewProductItem({
  placement: "special_offer",
  productId: "premium_monthly",
  price: 4.99,
  regularPrice: 9.99,
  currencyCode: "USD",
});

await MonetaiSDK.logViewProductItem({
  placement: "special_offer",
  productId: "premium_yearly",
  price: 39.99,
  regularPrice: 79.99,
  currencyCode: "USD",
});

API Reference: MonetaiSDK.logViewProductItem()

Parameters (ViewProductItemParams)

Parameter	Type	Required	Description
placement	string	✓	Identifier for the screen or UI component where the product is displayed (e.g., main_paywall, special_offer, bottom_banner). If you've already created a promotion in the dashboard, you can find the placement value in Dashboard → Promotions → Promotion Settings.
productId	string	✓	Product ID (store product ID)
price	number	✓	Displayed price
regularPrice	number	✓	Regular price (before discount)
currencyCode	string	✓	Currency code (e.g., USD, KRW)
month	number | null	-	Subscription period in months

---

2. Getting Offers

Call MonetaiSDK.getOffer(placement) to retrieve a personalized offer for the current user. If the user is eligible for a discount, the SDK returns an Offer object containing the discount details and product information. If not, it returns null.

How to use offers

• If an offer is returned: Apply the optimized discount rate and product info to your existing pricing or promotion screen.
• If null is returned: The user belongs to a group where dynamic pricing optimization is not applied. In this case, use your app's existing default discount price as-is.

Avoid redundant offer calls

Each getOffer() call may return a different optimized result for the same user, as the AI model continuously refines its recommendations. If getOffer() is called multiple times while a promotion is active, the discount shown to the user may change unexpectedly.

Example scenario:

1. User opens the pricing screen → getOffer() returns a 30% discount
2. User navigates away, then returns → getOffer() is called again → returns a 50% discount
3. The user sees a different price for the same promotion, causing confusion

Best practice: Call getOffer() once and cache the result while the promotion is active. Do not re-fetch on every screen visit.

Multiple products in a single offer

If your promotion page displays multiple products (e.g., a monthly plan and a yearly plan) and you have registered both in the agent, products will contain an individually optimized result for each product. For example, if you registered a 1-month and a 12-month product, the response will include optimized pricing for both.

import MonetaiSDK from "@hayanmind/monetai-react-native";

const showPricingScreen = async () => {
  try {
    const offer = await MonetaiSDK.getOffer("special_offer");

    if (offer) {
      // Offer available — apply discount to your existing UI
      // products contains an optimized result per registered product
      console.log("Agent:", offer.agentName);
      console.log("Offer products:", offer.products);

      for (const product of offer.products) {
        console.log(`SKU: ${product.sku}, Discount: ${product.discountRate * 100}%`);
      }

      displayPrice(offer);
    } else {
      // No offer — show your app's existing default discount price
      displayDefaultPrice();
    }
  } catch (error) {
    console.error("Failed to get offer:", error);
    displayDefaultPrice();
  }
};

API Reference: MonetaiSDK.getOffer()

Parameters

Parameter	Type	Description
placement	string	Unique identifier for the screen where pricing optimization is applied. Use the same value defined in logViewProductItem(). If a promotion has already been created in the dashboard, you can find the placement value in Dashboard → Promotions → Promotion Settings.

Return Value: Offer | null

Offer Type

Property	Type	Description
agentId	number	Agent ID
agentName	string	Agent name
products	OfferProduct[]	List of offer products

OfferProduct Type

Property	Type	Description
name	string	Product name
sku	string	Product SKU (store product ID)
discountRate	number	Discount rate (0-1 range, e.g. 0.5 = 50%)

---

Managing User State

SDK Reset

Initialize the SDK when the user logs out.

import MonetaiSDK from "@hayanmind/monetai-react-native";

// When user logs out
const logoutUser = async () => {
  try {
    await MonetaiSDK.reset();
    console.log("User logout completed");
  } catch (error) {
    console.error("User logout failed:", error);
  }
};

Support
If you run into any trouble during the integration, don't hesitate to contact us at support@monetai.io.

---

Next Steps

With the SDK setup complete, you're ready to start a promotion:

• Start a Promotion