Flutter SDK+ Integration (Shoppable Ads)

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

注記

If you are using the Legacy Rokt SDK (rokt_sdk), see the Flutter SDK Integration (Legacy) guide instead.

注記

Shoppable Ads in Flutter are currently supported on iOS only.

Prerequisites

• iOS 15.6+ deployment target
• mparticle_flutter_sdk 2.x (SDK+)
• mParticle-Rokt 9.x CocoaPods pod (in ios/Podfile)
• RoktStripePaymentExtension CocoaPods pod (required for Apple Pay / Stripe payment processing)
• A Rokt account with Shoppable Ads enabled — contact your Rokt account manager

Step 1: Install dependencies

Flutter

flutter pub add mparticle_flutter_sdk

After adding the SDK+ Flutter dependency to your application, the following (or similar) lines are added to your package's pubspec.yaml file:

pubspec.yaml

dependencies:
    mparticle_flutter_sdk: ^2.0.0

iOS native (Podfile)

Add the following pods to your ios/Podfile:

ios/Podfile

pod 'mParticle-Rokt', '~> 9.0'
pod 'RoktStripePaymentExtension', '~> 0.1'

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 Flutter SDK+ Integration Guide — Step 1.

Step 3: Configure Apple Pay

Before registering a payment extension, you need to 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 to register the payment extension.

Step 4: Register a payment extension

After configuring Apple Pay, register a payment extension in your native iOS code (AppDelegate). This enables Apple Pay and Stripe payment processing within the placement.

ios/Runner/AppDelegate.swift

import mParticle_Apple_SDK
import RoktStripePaymentExtension

// In application(_:didFinishLaunchingWithOptions:), after MParticle.sharedInstance().start(with: options)
if let stripeExt = RoktStripePaymentExtension(applePayMerchantId: "merchant.com.yourapp.rokt") {
    MParticle.sharedInstance().rokt.registerPaymentExtension(stripeExt)
}

注記

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 (Step 2) and before calling selectShoppableAds (Step 5) from your Flutter code. If no payment extension is registered, selectShoppableAds will fire a PlacementFailure event.

Step 5: Display Shoppable Ads

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

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

import 'package:mparticle_flutter_sdk/mparticle_flutter_sdk.dart';

MparticleFlutterSdk? mpInstance = await MparticleFlutterSdk.getInstance();

final 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",
};

mpInstance?.rokt.selectShoppableAds(
    identifier: "ConfirmationPage",
    attributes: attributes,
);

Step 6: Handle events

Shoppable Ads emit the following events in addition to the standard placement events. Subscribe to events using the MPRoktEvents EventChannel:

import 'package:flutter/services.dart';

final EventChannel roktEventChannel = EventChannel('MPRoktEvents');

roktEventChannel.receiveBroadcastStream().listen((dynamic event) {
  final Map<String, dynamic> payload = Map<String, dynamic>.from(event);
  switch (payload['event']) {
    case 'CartItemInstantPurchaseInitiated':
      debugPrint("Purchase started: ${payload['catalogItemId']}");
      break;
    case 'CartItemInstantPurchase':
      debugPrint("Purchase completed: ${payload['catalogItemId']} — ${payload['totalPrice']} ${payload['currency']}");
      break;
    case 'CartItemInstantPurchaseFailure':
      debugPrint("Purchase failed: ${payload['error']}");
      break;
    case 'CartItemDevicePay':
      debugPrint("Device payment triggered: ${payload['paymentProvider']}");
      break;
    case 'InstantPurchaseDismissal':
      debugPrint("User dismissed purchase");
      break;
    case 'PlacementClosed':
      debugPrint("Shoppable Ads placement closed");
      break;
    default:
      break;
  }
});

Shoppable Ads events

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

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