Add a placement (legacy)

The Rokt SDK for Flutter can be used to display overlay and embedded placements within your app's content.

Before you begin

Ensure that the Rokt Flutter SDK has already been integrated into your application.

Select placements

Import the SDK

Import the SDK into your application's dart file:

import 'package:rokt_sdk/rokt_sdk.dart';

Call selectPlacements

Call selectPlacements at the desired point by adding the appropriate customer attributes. The Rokt placement will then display after a short delay that is configurable via the Rokt platform.

You can dictate what customer attributes are included in your Rokt integration. More information on available data fields can be found on the attributes page. If you want to integrate more attributes, you can add additional lines of code for each new attribute to the samples below.

RoktSdk.selectPlacements(
    viewName: "RoktExperience",
    attributes: {
        "email": "j.smith@example.com",
        "firstname": "Jenny",
        "lastname": "Smith",
        "mobile": "(555)867-5309",
        "postcode": "90210",
        "country": "US"
    },
);

note

The viewName ("RoktExperience") can be modified when calling the SDK in multiple locations to display a different experience according to the context of where in the app the SDK is being called. If modifying the viewName, work with the Rokt team to ensure matching adjustments are made within the Rokt system.

Embedded placements

For embedded placements, add a RoktWidget into the build function of your view before calling selectPlacements. The Rokt widget will be injected into this placeholder when selectPlacements is called.

const RoktWidget(placeholderName: "RoktEmbedded1")

RoktWidget has a callback to notify when the widget is created which can be utilized:

RoktWidget(placeholderName: "RoktEmbedded1", onWidgetCreated: () { showWidget() })

Make sure the view is created in the visible area of the screen before calling selectPlacements.

note

If modifying the viewName or placeholderName ("RoktEmbedded1"), please work with the Rokt team to ensure matching adjustments are made within the Rokt system.

Events

The Rokt SDK exposes an EventChannel for SDK events. This is the recommended way to observe placement lifecycle events.

final EventChannel roktEventChannel = EventChannel('RoktEvents');
//...
roktEventChannel.receiveBroadcastStream().listen((dynamic event) {
    debugPrint("Rokt event received $event");
    switch (event["event"]) {
    case "InitComplete":
        debugPrint("Init status: ${event["status"]}");
        break;
    case "ShowLoadingIndicator":
        debugPrint("Event ${event["viewName"]}");
        break;
    case "HideLoadingIndicator":
        debugPrint("Event ${event["viewName"]}");
        break;
    case "OfferEngagement":
        debugPrint("Event ${event["viewName"]}, ${event["identifier"]}");
        break;
    case "PositiveEngagement":
        debugPrint("Event ${event["viewName"]}, ${event["identifier"]}");
        break;
    case "FirstPositiveEngagement":
        debugPrint("Event ${event["viewName"]}, ${event["identifier"]}");
        break;
    case "PlacementInteractive":
        debugPrint("Event ${event["viewName"]}, ${event["identifier"]}");
        break;
    case "PlacementReady":
        debugPrint("Event ${event["viewName"]}, ${event["identifier"]}");
        break;
    case "PlacementClosed":
        debugPrint("Event ${event["viewName"]}, ${event["identifier"]}");
        break;
    case "PlacementCompleted":
        debugPrint("Event ${event["viewName"]}, ${event["identifier"]}");
        break;
    case "PlacementFailure":
        debugPrint("Event ${event["viewName"]}, ${event["identifier"]}");
        break;
    case "EmbeddedSizeChanged":
        debugPrint("Event ${event["identifier"]}, height: ${event["selectedHeight"]}");
        break;
    case "OpenUrl":
        debugPrint("Event ${event["viewName"]}, ${event["identifier"]}, url: ${event["url"]}");
        break;
    case "CartItemInstantPurchaseInitiated":
        debugPrint("Purchase started: ${event["catalogItemId"]}");
        break;
    case "CartItemInstantPurchase":
        debugPrint("Purchase completed: ${event["catalogItemId"]}");
        break;
    case "CartItemInstantPurchaseFailure":
        debugPrint("Purchase failed: ${event["error"]}");
        break;
    case "CartItemDevicePay":
        debugPrint("Device payment triggered: ${event["paymentProvider"]}");
        break;
    case "InstantPurchaseDismissal":
        debugPrint("Purchase dismissed");
        break;
    default:
        break;
    }
});

Event objects

Event	Description	Properties
InitComplete	Triggered when SDK initialization completes	status: String
ShowLoadingIndicator	Triggered before the SDK calls the Rokt backend	viewName: String
HideLoadingIndicator	Triggered when the SDK receives a success or failure from the Rokt backend	viewName: String
OfferEngagement	Triggered when the user engages with the offer	viewName: String, identifier: String
PositiveEngagement	Triggered when the user positively engages with the offer	viewName: String, identifier: String
FirstPositiveEngagement	Triggered when the user positively engages with the offer for the first time	viewName: String, identifier: String
PlacementInteractive	Triggered when a placement has been rendered and is interactable	viewName: String, identifier: String
PlacementReady	Triggered when a placement is ready to display but has not rendered content yet	viewName: String, identifier: String
PlacementClosed	Triggered when a placement is closed by the user	viewName: String, identifier: String
PlacementCompleted	Triggered when the offer progression reaches the end and no more offers are available to display. Also triggered when cache is hit but the retrieved placement will not be displayed as it has previously been dismissed	viewName: String, identifier: String
PlacementFailure	Triggered when a placement could not be displayed due to some failure or when no placements are available to show	viewName: String, identifier: String (optional)
EmbeddedSizeChanged	Triggered when an embedded placement's height changes	identifier: String, selectedHeight: Double
OpenUrl	Triggered when the user presses a URL that is configured to be sent to the partner app	viewName: String, identifier: String, url: String
CartItemInstantPurchaseInitiated	Purchase flow started — user tapped "Buy" (Shoppable Ads, iOS only)	identifier: String, catalogItemId: String, cartItemId: String
CartItemInstantPurchase	Purchase completed successfully (Shoppable Ads, iOS only)	identifier: String, catalogItemId: String, cartItemId: String, totalPrice: String, currency: String
CartItemInstantPurchaseFailure	Purchase failed (Shoppable Ads, iOS only)	identifier: String, catalogItemId: String, cartItemId: String, error: String
CartItemDevicePay	Apple Pay / device payment triggered (Shoppable Ads, iOS only)	identifier: String, catalogItemId: String, cartItemId: String, paymentProvider: String
InstantPurchaseDismissal	User dismissed the purchase overlay (Shoppable Ads, iOS only)	identifier: String

Shoppable Ads (iOS only)

Shoppable Ads allow users to make instant purchases directly from ad placements. This feature is currently available on iOS only.

For the full integration guide, see the Flutter Shoppable Ads Integration (Legacy) guide.

Prerequisites

• iOS 15.0+ deployment target
• rokt_sdk 5.x
• RoktStripePaymentExtension CocoaPods pod

iOS native setup

1. Add the payment extension to your iOS Podfile:

ios/Podfile

pod 'RoktStripePaymentExtension', '~> 0.1'

2. Set the payment extension factory in your AppDelegate.swift:

ios/Runner/AppDelegate.swift

import RoktStripePaymentExtension
import rokt_sdk

// In application(_:didFinishLaunchingWithOptions:), after GeneratedPluginRegistrant.register:
SwiftRoktSdkPlugin.paymentExtensionFactory = { type, config in
    switch type {
    case "stripe":
        guard let merchantId = config["applePayMerchantId"] else { return nil }
        return RoktStripePaymentExtension(
            applePayMerchantId: merchantId,
            countryCode: config["countryCode"] ?? "US"
        )
    default:
        return nil
    }
}

Register the payment extension

Register from Dart after initialize and before selectShoppableAds:

RoktSdk.registerPaymentExtension(
  extensionType: 'stripe',
  config: {
    'stripeKey': 'YOUR_STRIPE_PUBLISHABLE_KEY',
    'applePayMerchantId': 'merchant.com.yourapp.rokt',
  },
);

Display Shoppable Ads

RoktSdk.selectShoppableAds(
  viewName: "ConfirmationPage",
  attributes: {
    "email": "j.smith@example.com",
    "firstname": "Jenny",
    "lastname": "Smith",
    "confirmationref": "ORD-12345",
    "amount": "52.25",
    "currency": "USD",
    "paymenttype": "visa",
    "shippingaddress1": "123 Main St",
    "shippingcity": "New York",
    "shippingstate": "NY",
    "shippingzipcode": "10001",
    "shippingcountry": "US",
  },
);

Shoppable Ads events are delivered via the RoktEvents EventChannel — see the Events section above.