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.

Prerequisites

• iOS 15.0+ deployment target
• Rokt SDK 5.x (direct) or mParticle Apple SDK 9.x with Rokt Kit 9.x (joint SDK)
• RoktStripePaymentExtension package (required for Apple Pay / Stripe payment processing)
• A Rokt account with Shoppable Ads enabled — contact your Rokt account manager

Step 1: Install dependencies

mParticle Joint SDK

CocoaPods

pod 'Rokt-Widget', '~> 5.0'
pod 'RoktStripePaymentExtension', '~> 1.0'

Swift Package Manager

Add the following packages in Xcode (File > Add Package Dependencies):

Package	URL	Product
Rokt SDK	https://github.com/ROKT/rokt-sdk-ios.git	Rokt-Widget
Stripe Payment Extension	https://github.com/ROKT/rokt-stripe-payment-extension-ios.git	RoktStripePaymentExtension

Direct Rokt SDK

CocoaPods

pod 'mParticle-Apple-SDK', '~> 9.0'
pod 'mParticle-Rokt', '~> 9.0'
pod 'RoktStripePaymentExtension', '~> 1.0'

Swift Package Manager

Add the following packages in Xcode (File > Add Package Dependencies):

Package	URL	Product
mParticle Apple SDK	https://github.com/mParticle/mparticle-apple-sdk	mParticle-Apple-SDK
mParticle Rokt Kit	https://github.com/mparticle-integrations/mp-apple-integration-rokt.git	mParticle-Rokt
Stripe Payment Extension	https://github.com/ROKT/rokt-stripe-payment-extension-ios.git	RoktStripePaymentExtension

Step 2: Initialize the SDK

SDK initialization is the same as for standard placements. See:

• Direct Rokt SDK: Integrating and initializing the iOS SDK
• mParticle Joint SDK: iOS SDK Integration Guide — Initialize the Rokt SDK

Step 3: Register a payment extension

Before displaying Shoppable Ads, register a payment extension. This enables Apple Pay and Stripe payment processing within the placement.

mParticle Joint SDK

import Rokt_Widget
import RoktStripePaymentExtension

// Register after SDK initialization, before selectShoppableAds
let stripeExt = RoktStripePaymentExtension(applePayMerchantId: "merchant.com.yourapp")
Rokt.registerPaymentExtension(stripeExt, config: [
    "stripeKey": "pk_live_your_stripe_publishable_key"
])

注記

For the direct SDK path, you must provide your Stripe publishable key explicitly in the config dictionary.

Direct Rokt SDK

import mParticle_Apple_SDK
import RoktStripePaymentExtension

// Register after mParticle.start(), before selectShoppableAds
let stripeExt = RoktStripePaymentExtension(applePayMerchantId: "merchant.com.yourapp")
MParticle.sharedInstance().rokt.registerPaymentExtension(stripeExt)

注記

For the mParticle path, the Stripe publishable key is automatically provided from the mParticle dashboard configuration. You only need to provide the Apple Pay merchant ID.

注意

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

Step 4: Display Shoppable Ads

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

mParticle Joint SDK

import Rokt_Widget

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"
]

Rokt.selectShoppableAds(
    identifier: "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
        }
    }
)

Direct Rokt SDK

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 5: 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").
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

For detailed setup of individual payment methods, see:

• Apple Pay — Native Apple Pay within the Rokt placement
• Card Forwarding — Reuse the customer's vaulted card from the primary purchase