Aller au contenu principal

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.

PrerequisitesLien direct vers 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 dependenciesLien direct vers Step 1: Install dependencies

CocoaPodsLien direct vers CocoaPods

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

Swift Package ManagerLien direct vers Swift Package Manager

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

PackageURLProduct
mParticle Apple SDKhttps://github.com/mParticle/mparticle-apple-sdkmParticle-Apple-SDK
mParticle Rokt Kithttps://github.com/mparticle-integrations/mp-apple-integration-rokt.gitmParticle-Rokt
Stripe Payment Extensionhttps://github.com/ROKT/rokt-stripe-payment-extension-ios.gitRoktStripePaymentExtension

Step 2: Initialize the SDKLien direct vers Step 2: Initialize the SDK

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

Step 3: Register a payment extensionLien direct vers 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.

import mParticle_Apple_SDK
import RoktStripePaymentExtension

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

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.

attention

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 AdsLien direct vers Step 4: 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 5: Handle eventsLien direct vers 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)DescriptionProperties
RoktEvent.CartItemInstantPurchaseInitiatedRoktCartItemInstantPurchaseInitiatedPurchase flow started — user tapped "Buy"identifier, catalogItemId, cartItemId
RoktEvent.CartItemInstantPurchaseRoktCartItemInstantPurchasePurchase completed successfullyidentifier, name, cartItemId, catalogItemId, currency, description, linkedProductId, providerData, quantity, totalPrice, unitPrice
RoktEvent.CartItemInstantPurchaseFailureRoktCartItemInstantPurchaseFailurePurchase failedidentifier, catalogItemId, cartItemId, error
RoktEvent.CartItemDevicePayRoktCartItemDevicePayApple Pay / device payment triggeredidentifier, catalogItemId, cartItemId, paymentProvider
RoktEvent.InstantPurchaseDismissalRoktInstantPurchaseDismissalUser dismissed the purchase overlayidentifier

The iOS SDK uses the same attributes as the Web SDK. The following attributes are particularly important for Shoppable Ads:

AttributeTypeRequiredDescription
emailstringYesCustomer email (unhashed). Used for order confirmation.
confirmationrefstringYesOrder or transaction reference number.
amountstringRecommendedDecimal transaction amount (e.g., "52.25").
currencystringRecommendedISO 4217 currency code (e.g., "USD").
paymenttypestringRecommendedPayment method used for the primary purchase (e.g., "visa", "apple_pay"). Used for payment method prioritization.
shippingaddress1stringRecommendedShipping street address.
shippingcitystringRecommendedShipping city.
shippingstatestringRecommendedShipping state or province.
shippingzipcodestringRecommendedShipping postal code.
shippingcountrystringRecommendedISO Alpha-2 country code (e.g., "US").

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

remarque

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 methodsLien direct vers 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
Cet article vous a-t-il été utile ?
Last updated Apr 10, 2026