iOS SDK Integration (Shoppable Ads)

This guide covers how to integrate Shoppable Ads into your native iOS app. 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 iOS SDK reference, see the iOS SDK Integration Guide.

注記

If you are using the Direct Rokt SDK (legacy), see the iOS SDK Integration (Legacy) guide instead.

Prerequisites

• iOS 15.0+ deployment target
• Rokt SDK+ for iOS (RoktSDKPlus 9.2+ via SPM or CocoaPods) — umbrella package that includes mParticle-Rokt, Rokt-Widget, RoktPaymentExtension, and RoktContracts
• A Rokt account with Shoppable Ads enabled — contact your Rokt account manager

Step 1: Install dependencies

Swift Package Manager

In Xcode, select File → Add Package Dependencies, enter https://github.com/ROKT/rokt-sdk-plus-ios.git, set the dependency rule to Up to Next Major Version, and add the RoktSDKPlus product to your app target.

Package	URL	Product
Rokt SDK+ for iOS	https://github.com/ROKT/rokt-sdk-plus-ios.git	RoktSDKPlus

CocoaPods

pod 'RoktSDKPlus', '~> 9.2'

Minimum versions

RoktSDKPlus resolves the Rokt stack as a single dependency. Use 9.2+ for the latest Shoppable Ads payment methods.

Capability	Minimum versions
Shoppable Ads (base)	RoktSDKPlus 9.0+ / Rokt-Widget 5.0+
Afterpay / Clearpay	RoktSDKPlus 9.1+ / Rokt-Widget 5.1+ / RoktPaymentExtension 1.0+ / RoktContracts 2.0+
PayPal, card forwarding (iOS built-in)	RoktSDKPlus 9.2+ / Rokt-Widget 5.2+ / RoktPaymentExtension 2.0+

If your Podfile pins RoktContracts or Rokt-Widget directly, use RoktContracts '~> 2.0' and Rokt-Widget '~> 5.2' so CocoaPods can resolve Shoppable Ads dependencies.

Step 2: Initialize the SDK

SDK initialization is the same as for standard placements. See the iOS SDK Integration Guide — Initialize the Rokt SDK.

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 before registering the payment extension.

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

注記

Apple Pay is optional. Shoppable Ads also supports built-in PayPal and card forwarding on iOS without Apple Pay configuration. However, registerPaymentExtension is still required to launch a Shoppable Ads placement — see Step 4.

Step 4: Register a payment extension

Register a RoktPaymentExtension after SDK initialization. This is required for all Shoppable Ads placements on iOS. The extension enables Stripe-backed methods (Apple Pay, card via Stripe, Afterpay / Clearpay).

import mParticle_Apple_SDK
import RoktPaymentExtension

// Register after mParticle.start(), before selectShoppableAds
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. The initializer returns nil if both are omitted.

注記

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. In your app, provide only the Apple Pay merchant ID and/or urlScheme when creating RoktPaymentExtension.

注意

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

Afterpay / Clearpay (optional)

Afterpay and Clearpay are redirect-based payment methods. To enable them:

1. Register a URL scheme in your app's Info.plist under CFBundleURLTypes (for example, myapp).
2. Pass the matching urlScheme when creating RoktPaymentExtension (for example, "myapp"). The SDK builds the return URL internally.
3. Forward redirect URLs to Rokt — see Step 5.

You can initialize the extension for Afterpay only (no Apple Pay merchant ID):

if let paymentExt = RoktPaymentExtension(urlScheme: "myapp") {
    MParticle.sharedInstance().rokt.registerPaymentExtension(paymentExt)
}

Step 5: Forward redirect URLs

Afterpay, Clearpay, and PayPal send customers to a web view and redirect back to your app via a registered URL scheme. Forward incoming URLs to Rokt so the payment flow can complete.

Call handleURLCallback from your URL handler in addition to any existing mParticle URL handling (for example handleURLContext).

SceneDelegate (recommended):

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)
    }
}

AppDelegate:

func application(
    _ app: UIApplication,
    open url: URL,
    options: [UIApplication.OpenURLOptionsKey: Any] = [:]
) -> Bool {
    if MParticle.sharedInstance().rokt.handleURLCallback(with: url) {
        return true
    }
    return false
}

SwiftUI:

WindowGroup {
    ContentView()
        .onOpenURL { url in
            _ = MParticle.sharedInstance().rokt.handleURLCallback(with: url)
        }
}

Step 6: Display Shoppable Ads

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

import mParticle_Apple_SDK

let attributes: [String: String] = [
    "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.sharedInstance().rokt.selectShoppableAds(
    "ConfirmationPage",
    attributes: attributes,
    config: nil,
    onEvent: { event in
        switch event {
        case let e as RoktEvent.CartItemInstantPurchase:
            print("Purchase completed: \(e.catalogItemId) — \(e.totalPrice ?? 0) \(e.currency)")
        case let e as RoktEvent.CartItemInstantPurchaseFailure:
            print("Purchase failed: \(e.error ?? "unknown")")
        case is RoktEvent.InstantPurchaseDismissal:
            print("User dismissed purchase")
        case is RoktEvent.PlacementClosed:
            print("Shoppable Ads placement closed")
        default:
            break
        }
    }
)

Step 7: Handle events

Shoppable Ads emit the following events in addition to the standard placement events. All event types are defined in the RoktContracts package.

Event (Swift)	Event (ObjC)	Description	Properties
RoktEvent.CartItemInstantPurchaseInitiated	RoktCartItemInstantPurchaseInitiated	Purchase flow started — user tapped "Buy"	identifier, catalogItemId, cartItemId
RoktEvent.CartItemInstantPurchase	RoktCartItemInstantPurchase	Purchase completed successfully	identifier, name, cartItemId, catalogItemId, currency, description, linkedProductId, providerData, quantity, totalPrice, unitPrice
RoktEvent.CartItemInstantPurchaseFailure	RoktCartItemInstantPurchaseFailure	Purchase failed	identifier, catalogItemId, cartItemId, error
RoktEvent.CartItemDevicePay	RoktCartItemDevicePay	Apple Pay / device payment triggered	identifier, catalogItemId, cartItemId, paymentProvider
RoktEvent.InstantPurchaseDismissal	RoktInstantPurchaseDismissal	User dismissed the purchase overlay	identifier

Recommended attributes

The iOS SDK uses the same attributes as the Web SDK. 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").

| partnerpaymentreference | string | Required for card forwarding | Non-guessable identifier for the customer's vaulted payment method. | | last4digits | string | Required for card forwarding | Last 4 digits of the card used for the primary transaction. |

For the full list of supported attributes, see the recommended attributes table and the iOS SDK+ Integration Guide.

注記

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	Apple Pay merchant ID + RoktPaymentExtension (Step 3–4)
PayPal	Built into the Rokt SDK — no extra extension config. Requires Step 5 (handleURLCallback) for redirect return URLs.
Afterpay / Clearpay	Custom URL scheme in Info.plist + urlScheme on RoktPaymentExtension + Step 5 (handleURLCallback)
Card Forwarding	Partner Payment Sharing API + partnerpaymentreference / last4digits attributes. registerPaymentExtension is still required to launch Shoppable Ads.