Skip to main content

Add a placement

For Rokt partners, the Android SDK can be used to display overlay or embedded placements in your android app.

Before you begin​

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

Overlay placements​

Execute the SDK in your desired activity/fragment, adding any appropriate customer attributes and the placement mapping. The example code uses the onCreate method to launch the placement.

The Rokt widget view displays after a short delay, configurable via the Rokt platform. The SDK provides optional callback events for when the view loads and unloads.

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.

import com.rokt.roktsdk.Rokt;

class ConfirmationActivity : Activity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        ...

        Map<String,String> attributes = new HashMap<String, String>();

        attributes.put("email", "j.smith@example.com");
        attributes.put("firstname", "Jenny");
        attributes.put("lastname", "Smith");
        attributes.put("mobile", "(323) 867-5309");
        attributes.put("postcode", "90210");
        attributes.put("country", "US");

        Rokt.INSTANCE.execute("RoktExperience",
            attributes,
            new Rokt.RoktCallback() {
                @Override
                public void onLoad() {
                }
                @Override
                public void onUnload(Rokt.UnloadReasons unloadReasons) {
                }
                @Override
                public void onShouldHideLoadingIndicator() {
                }
                @Override
                public void onShouldShowLoadingIndicator() {
                }
            }
        )
        ...
    }
}

Optional functions​

FunctionPurpose
Rokt.close()Used to auto-close overlay placements.

Embedded placements​

Updating your layout XML file​

<?xml version="1.0" encoding="utf-8"?>
<androidx.constraintlayout.widget.ConstraintLayout xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    xmlns:tools="http://schemas.android.com/tools"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    tools:context=".MainActivity">

    <com.rokt.roktsdk.Widget
        android:id="@+id/roktWidget"
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        app:layout_constraintEnd_toEndOf="parent"
        app:layout_constraintStart_toStartOf="parent"
        app:layout_constraintTop_toTopOf="parent" />

</androidx.constraintlayout.widget.ConstraintLayout>
note

The Rokt embedded placement can also be created in your code and included in the layout dynamically.

Executing the SDK​

Execute the SDK in your desired activity/fragment, adding any appropriate customer attributes and the placement mapping. The example code uses the onCreate method to launch the placement.

The Rokt placement displays after a short delay, configurable via the Rokt platform.

We advise setting the height of the placement to wrap_content so that the placement can set its height dynamically.

The SDK provides optional callback events for when the view loads and unloads.

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

import com.rokt.roktsdk.Widget;
import com.rokt.roktsdk.Rokt;

class ConfirmationActivity : Activity() {

    private Rokt.RoktCallback roktCallback = new Rokt.RoktCallback() {
        @Override
        public void onLoad() {
        }

        @Override
        public void onShouldShowLoadingIndicator() {
        }

        @Override
        public void onShouldHideLoadingIndicator() {
        }

        @Override
        public void onUnload(@NotNull Rokt.UnloadReasons unloadReasons) {
        }
    };

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        ...

        Map<String, String> attributes = new HashMap<String, String>();

        attributes.put("email", "j.smith@example.com");
        attributes.put("firstname", "Jenny");
        attributes.put("lastname", "Smith");
        attributes.put("mobile", "(323) 867-5309");
        attributes.put("postcode", "90210");
        attributes.put("country", "US");

        // Widget placeholder mapping the placeholder view with placement location configuration
        Widget widget = findViewById(R.id.roktWidget);
        Map<String, WeakReference<Widget>> placeHolders = new HashMap<>();
        placeHolders.put("RoktEmbedded1", new WeakReference<>(widget));

        Rokt.INSTANCE.execute("RoktExperience",
                attributes,
                roktCallback,
                placeHolders);
        ...
    }
}
note

If you want to update the view name RoktExperience or placeholder name RoktEmbedded1 with a different value, contact your Rokt account manager to ensure Rokt placements are configured consistently.

Jetpack Compose Component​

Starting from major version 4 of the Rokt Android SDK, you can add a Rokt layout by utilizing the RoktLayout composable. This removes the need to call Rokt.execute and supports a more modern declarative integration using Compose.

Adding the component​

import com.rokt.roktsdk.RoktLayout

@Composable
fun MainScreen(modifier: Modifier = Modifier) {
    Column(
        modifier = modifier
            .background(Color.LightGray)
            .padding(8.dp),
    ) {
        RoktLayout(
            sdkTriggered = true,
            viewName = "RoktExperience",
            attributes = hashMapOf(
                Pair("email", "j.smith@example.com"),
                Pair("firstname", "Jenny"),
                Pair("lastname", "Smith"),
                Pair("mobile", "(323) 867-5309"),
                Pair("postcode", "90210"),
                Pair("country", "US")
            ),
            location = "RoktEmbedded1", // If using an embedded layout
            onLoad = {},
            onUnload = {},
            onShouldShowLoadingIndicator = {},
            onShouldHideLoadingIndicator = {},
        )
    }
}
note

You can use the RoktLayout composable for both embedded and overlay layouts.

Events​

The SDK provides the events on each page as a stream through the Rokt.events API. SDK users can leverage the Kotlin Flow mechanism to consume the events produced by the SDK.

// owner: LifecycleOwner
owner.lifecycleScope.launch {
    owner.lifecycle.repeatOnLifecycle(Lifecycle.State.CREATED) {
        Rokt.events("viewName").collect { roktEvent ->
            Log.d("RoktEvent", "Event received $roktEvent")
        }
    }
}

Event objects​

EventDescriptionParams
ShowLoadingIndicatorTriggered before the SDK calls the Rokt backend
HideLoadingIndicatorTriggered when the SDK receives a success or failure from the Rokt backend
OfferEngagementTriggered when the user engages with the offerplacementId: String
PositiveEngagementTriggered when the user positively engages with the offerplacementId: String
FirstPositiveEngagementTriggered when the user positively engages with the offer for the first timeplacementId: String, fulfillmentAttributes: FulfillmentAttributes
PlacementInteractiveTriggered when a placement has been rendered and is interactableplacementId: String
PlacementReadyTriggered when a placement is ready to display but has not rendered content yetplacementId: String
PlacementClosedTriggered when a placement is closed by the userplacementId: 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		placementId: String
PlacementFailureTriggered when a placement could not be displayed due to some failureplacementId: String (optional)

Callbacks​

The Rokt Android SDK supports the following callbacks which are passed into execute as a Rokt.RoktCallback object:

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 Android 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 recevies a Rokt.UnloadReasons as an argument, but does not return any values. The unload reasons are as follows:

ValueReason
NO_OFFERSThere are no eligible offers to display
FINISHEDA rendered placement or layout has been closed
TIMEOUTTimeout when requesting a response from the backend
NETWORK_ERRORA network error has occured
NO_WIDGETReturned placement or layout is invalid or empty
INIT_FAILEDInit request failed before execute was called
UNKNOWN_PLACEHOLDERPlaceholder string mismatch (available from 4.x.x)
UNKNOWNCatch-all reason
Was this article helpful?