React Native SDK Integration (Shoppable Ads)

This guide covers how to integrate Shoppable Ads into your React Native app using SDK+. Shoppable Ads enable post-purchase upsell offers with in-app catalog browsing and instant checkout (via Apple Pay or Stripe) — all within the Rokt placement.

For the general Rokt React Native SDK reference, see the React Native SDK Integration Guide.

注記

If you are using the Direct Rokt SDK (@rokt/react-native-sdk), see the React Native SDK Integration (Legacy) guide instead.

注記

Shoppable Ads in React Native are currently supported on iOS only. Android support is planned for a future release.

Prerequisites

• iOS 15.0+ deployment target
• react-native-mparticle 3.x (SDK+)
• Rokt SDK+ for iOS — RoktSDKPlus '~> 9.2' in ios/Podfile (rokt-sdk-plus-ios); requires 9.1+ for Afterpay and 9.2+ for built-in PayPal and card forwarding on iOS
• A Rokt account with Shoppable Ads enabled — contact your Rokt account manager

Step 1: Install dependencies

React Native

npm install react-native-mparticle --save

iOS native (Podfile)

Add the following pods to your ios/Podfile:

ios/Podfile

pod 'RoktSDKPlus', '~> 9.2'

Because the Rokt iOS SDK contains Swift code, you need to ensure it is built as a dynamic framework. Add the following pre_install block to your Podfile:

ios/Podfile

pre_install do |installer|
  installer.pod_targets.each do |pod|
    if pod.name == 'RoktSDKPlus' || pod.name == 'mParticle-Apple-SDK' || pod.name == 'mParticle-Rokt' || pod.name == 'Rokt-Widget'
      def pod.build_type;
        Pod::BuildType.new(:linkage => :dynamic, :packaging => :framework)
      end
    end
  end
end

Then install the pods:

cd ios && bundle exec pod install

Step 2: Initialize the SDK

SDK initialization is the same as for standard placements. See the React Native SDK Integration Guide — Step 1.

Step 3: Configure Apple Pay (if using Apple Pay)

If you plan to offer Apple Pay in Shoppable Ads, create an Apple Pay merchant ID, configure your Xcode project, and generate a Payment Processing Certificate.

Follow the steps in Apple Pay — iOS setup, then return here.

Step 4: Register a payment extension (native iOS)

Register a RoktPaymentExtension in your native iOS code (AppDelegate). This is required for all Shoppable Ads placements on iOS.

ios/YourApp/AppDelegate.swift

import mParticle_Apple_SDK
import RoktPaymentExtension

// In application(_:didFinishLaunchingWithOptions:), after MParticle.sharedInstance().start(with: options)
if let paymentExt = RoktPaymentExtension(
    applePayMerchantId: "merchant.com.yourapp.rokt", // omit if not offering Apple Pay
    urlScheme: "myapp" // omit if not offering Afterpay / Clearpay
) {
    MParticle.sharedInstance().rokt.registerPaymentExtension(paymentExt)
}

At least one of applePayMerchantId or urlScheme must be provided. For Afterpay / Clearpay, register the URL scheme in Info.plist and pass the matching urlScheme. See the iOS SDK Integration guide for details.

注記

Configure stripePublishableKey in your mParticle Rokt kit settings (mParticle dashboard). The kit forwards it to Rokt as stripeKey at registration time — you do not pass it in code.

注意

You must call registerPaymentExtension after SDK initialization (Step 2) and before calling selectShoppableAds (Step 6) from your React Native code. If no payment extension is registered, selectShoppableAds will fire a PlacementFailure event.

Step 5: Forward redirect URLs (native iOS)

Afterpay, Clearpay, and PayPal redirect back to your app after authentication. Add URL handling in your native iOS SceneDelegate or AppDelegate:

ios/YourApp/SceneDelegate.swift

func scene(_ scene: UIScene, openURLContexts URLContexts: Set<UIOpenURLContext>) {
    for urlContext in URLContexts {
        if MParticle.sharedInstance().rokt.handleURLCallback(with: urlContext.url) {
            return
        }
        MParticle.sharedInstance().handleURLContext(urlContext)
    }
}

See the iOS SDK Integration guide — Forward redirect URLs for AppDelegate and SwiftUI examples.

Step 6: Display Shoppable Ads

Shoppable Ads always display as an overlay — no embedded views or placeholders are needed.

Call selectShoppableAds from your React Native code once all required attributes are available:

import MParticle from 'react-native-mparticle';

const attributes = {
  email: 'j.smith@example.com',
  firstname: 'Jane',
  lastname: 'Smith',
  confirmationref: 'ORD-8829-XK2',
  amount: '52.25',
  currency: 'USD',
  paymenttype: 'visa',
  shippingaddress1: '123 Main St',
  shippingcity: 'Brooklyn',
  shippingstate: 'NY',
  shippingzipcode: '11201',
  shippingcountry: 'US',
};

MParticle.Rokt.selectShoppableAds('ConfirmationPage', attributes);

Step 7: Handle events

Shoppable Ads emit the following events in addition to the standard placement events. Subscribe to events using the NativeEventEmitter mechanism:

import { NativeEventEmitter } from 'react-native';
import MParticle from 'react-native-mparticle';

const emitter = new NativeEventEmitter(MParticle.RoktEventManager);

emitter.addListener('RoktEvents', (data) => {
  switch (data.event) {
    case 'CartItemInstantPurchaseInitiated':
      console.log(`Purchase started: ${data.catalogItemId}`);
      break;
    case 'CartItemInstantPurchase':
      console.log(`Purchase completed: ${data.catalogItemId} — ${data.totalPrice} ${data.currency}`);
      break;
    case 'CartItemInstantPurchaseFailure':
      console.log(`Purchase failed: ${data.error}`);
      break;
    case 'CartItemDevicePay':
      console.log(`Device payment triggered: ${data.paymentProvider}`);
      break;
    case 'InstantPurchaseDismissal':
      console.log('User dismissed purchase');
      break;
    case 'PlacementClosed':
      console.log('Shoppable Ads placement closed');
      break;
    default:
      break;
  }
});

Shoppable Ads events

Event	Description	Properties
CartItemInstantPurchaseInitiated	Purchase flow started — user tapped "Buy"	placementId, catalogItemId, cartItemId
CartItemInstantPurchase	Purchase completed successfully	placementId, name, cartItemId, catalogItemId, currency, description, linkedProductId, providerData, quantity, totalPrice, unitPrice
CartItemInstantPurchaseFailure	Purchase failed	placementId, catalogItemId, cartItemId, error
CartItemDevicePay	Apple Pay / device payment triggered	placementId, catalogItemId, cartItemId, paymentProvider
InstantPurchaseDismissal	User dismissed the purchase overlay	placementId

Recommended attributes

The following attributes are particularly important for Shoppable Ads:

Attribute	Type	Required	Description
email	string	Yes	Customer email (unhashed). Used for order confirmation.
confirmationref	string	Yes	Order or transaction reference number.
amount	string	Recommended	Decimal transaction amount (e.g., "52.25").
currency	string	Recommended	ISO 4217 currency code (e.g., "USD").
firstname	string	Recommended	Customer first name.
lastname	string	Recommended	Customer last name.
paymenttype	string	Recommended	Payment method used for the primary purchase (e.g., "visa", "apple_pay"). Used for payment method prioritization.
shippingaddress1	string	Recommended	Shipping street address.
shippingcity	string	Recommended	Shipping city.
shippingstate	string	Recommended	Shipping state or province.
shippingzipcode	string	Recommended	Shipping postal code.
shippingcountry	string	Recommended	ISO Alpha-2 country code (e.g., "US").

For the full list of supported attributes, see the recommended attributes table.

注記

If your platform does not have shipping address details (e.g., ticket or digital goods purchases), pass billing address details instead. Rokt will provide a UI for the customer to confirm or edit their shipping address before completing the purchase.

Payment methods

Method	iOS setup
Apple Pay	Native iOS setup — see iOS SDK Integration Steps 3–4
PayPal	Built into the Rokt SDK — requires native handleURLCallback (Step 5)
Afterpay / Clearpay	URL scheme + RoktPaymentExtension + native handleURLCallback — see iOS SDK Integration
Card Forwarding	Partner Payment Sharing API + partnerpaymentreference / last4digits attributes