Skip to main content

Add a placement

The Rokt SDK for Flutter can be used to display the overlay placement on top of your app's content.

Before you begin​

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

Overlay placements​

Import the SDK​

Import the SDK into your application's dart file:

import 'package:rokt_sdk/rokt_sdk.dart';

Execute the SDK​

Execute the SDK 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.

void executeRokt() {
    // Replace RoktExperience with your viewName
    RoktSdk.execute(
                    viewName: "RoktExperience",
                    attributes: {"email": "j.smith@example.com",
                        "firstname": "Jenny",
                        "lastname": "Smith",
                        "mobile": "(555)867-5309",
                        "postcode": "90210",
                        "country": "US"},
                    onLoad: () {
                        // Optional callback for when the Rokt placement loads
                    },
                    onUnLoad: () {
                        // Optional callback for when the Rokt placement unloads
                    },
                    onShouldShowLoadingIndicator: () {
                        // Optional callback to show a loading indicator
                    },
                    onShouldHideLoadingIndicator: () {
                        // Optional callback to hide a loading indicator
                    });
}
note

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

Embedded placements​

Import the SDK​

Import the Rokt SDK into the JavaScript file:

import 'package:rokt_sdk/rokt_sdk.dart';

Add RoktWidget to your view​

Add RoktWidget into build function of your view. The Rokt widget will be injected into this placeholder when the execute method is called:

const RoktWidget(placeholderName: "RoktEmbedded1")

Please make sure that the view is created on the visible area of the screen and then call showWidget. RoktWidget has a callback to notify when widget is created which could be utilized.

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

Execute the Rokt Flutter SDK​

Execute the SDK at the desired point by sending the appropriate customer attributes. The Rokt placement 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.

void executeRokt() {
    // Replace RoktExperience with your viewName
    RoktSdk.execute(
                    viewName: "RoktEmbeddedExperience",
                    attributes: {"email": "j.smith@example.com",
                        "firstname": "Jenny",
                        "lastname": "Smith",
                        "mobile": "(555)867-5309",
                        "postcode": "90210",
                        "country": "US"},
                    onLoad: () {
                        // Optional callback for when the Rokt placement loads
                    },
                    onUnLoad: () {
                        // Optional callback for when the Rokt placement unloads
                    },
                    onShouldShowLoadingIndicator: () {
                        // Optional callback to show a loading indicator
                    },
                    onShouldHideLoadingIndicator: () {
                        // Optional callback to hide a loading indicator
                    });
}
note

The ViewName (“RoktEmbeddedExperience”) can be modified when executing the SDK in multiple locations. This configuration allows you to display a different experience according to the context of where in the app the SDK is being executed. If modifying the ViewName or placeholderName ("RoktEmbedded1"), please work with the Rokt team to ensure matching adjustments are made within the Rokt system.

Events​

From version 4.3.0 Rokt SDK exposes an EventChannel for the SDK events

final EventChannel roktEventChannel = EventChannel('RoktEvents');
//...
roktEventChannel.receiveBroadcastStream().listen((dynamic event) {
    debugPrint("Rokt event received $event");
    switch (event["event"]) {
    case "ShowLoadingIndicator":
        debugPrint("Event ${event["viewName"]}");
        break;
    case "HideLoadingIndicator":
        debugPrint("Event ${event["viewName"]}");
        break;
    case "OfferEngagement":
        debugPrint("Event ${event["viewName"]}, ${event["placementId"]}");
        break;
    case "PositiveEngagement":
        debugPrint("Event ${event["viewName"]}, ${event["placementId"]}");
        break;
    case "FirstPositiveEngagement":
        debugPrint("Event ${event["viewName"]}, ${event["placementId"]}");
        break;
    case "PlacementInteractive":
        debugPrint("Event ${event["viewName"]}, ${event["placementId"]}");
        break;
    case "PlacementReady":
        debugPrint("Event ${event["viewName"]}, ${event["placementId"]}");
        break;
    case "PlacementClosed":
        debugPrint("Event ${event["viewName"]}, ${event["placementId"]}");
        break;
    case "PlacementCompleted":
        debugPrint("Event ${event["viewName"]}, ${event["placementId"]}");
        break;
    case "PlacementFailure":
        debugPrint("Event ${event["viewName"]}, ${event["placementId"]}");
        break;
    default:
        break;
    }
});

Event objects​

EventDescriptionOther properties
ShowLoadingIndicatorTriggered before the SDK calls the Rokt backendviewName: String
HideLoadingIndicatorTriggered when the SDK receives a success or failure from the Rokt backendviewName: String
OfferEngagementTriggered when the user engages with the offerviewName: String, placementId: String
PositiveEngagementTriggered when the user positively engages with the offerviewName: String, placementId: String
FirstPositiveEngagementTriggered when the user positively engages with the offer for the first timeviewName: String, placementId: String
PlacementInteractiveTriggered when a placement has been rendered and is interactableviewName: String, placementId: String
PlacementReadyTriggered when a placement is ready to display but has not rendered content yetviewName: String, placementId: String
PlacementClosedTriggered when a placement is closed by the userviewName: String, placementId: String
PlacementCompletedTriggered 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, placementId: String
PlacementFailureTriggered when a placement could not be displayed due to some failureviewName: String, placementId: String (optional)

Callbacks​

The Rokt Flutter SDK supports the following callbacks which are passed into execute:

onLoad​

The onLoad callback will be called when the placement becomes loaded and interactive. This callback provides no arguments and does not return any values.

onShouldShowLoadingIndicator​

The onShouldShowLoadingIndicator will be called upon a successful execute call, just before the SDK triggers a call to the Rokt backend. It can be used to display progress views of loading indicators while waiting for the placement to load. It does not require any arguments and does not return any values.

note

The behaviour of this callback has changed between major version 3 and major version 4 of the Rokt Flutter SDK. There is no longer a 1 second delay before the callback is executed. If you make use of these callbacks in major version 3 and are upgrading to major version 4, test the behavior to ensure the user experience is not impacted. You can create delay behavior that suits your applications needs if necessary.

onShouldHideLoadingIndicator​

The onShouldHideLoadingIndicator callback will be called when the SDK obtains a success or failure response from the Rokt backend. It can be used to cancel progress views or loading indicators. It does not require any arguments and does not return any values.

onUnload​

The onUnload callback will be called when the SDK closes the placement. It will also be triggered if the execute call fails. It does not require any arguments and does not return any values.

Was this article helpful?