Last updated Jan 29, 2025

Add a placement

The Rokt .NET MAUI SDK can be used by Rokt partners to display overlay and embedded placements, or by Rokt advertisers to record conversions for campaigns.

Before you begin

Ensure that the Rokt .NET MAUI SDK has been integrated into your application.

Overlay placements

Execute the SDK

Execute the SDK at the desired point by adding the appropriate customer attributes. The Rokt placement will then display.

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.

using Rokt.Maui.Sdk;
// Replace RoktExperience with your viewName
Rokt.Maui.Sdk.Rokt.Execute(
    viewName: "RoktExperience", 
    attributes: new Dictionary<string, string>()
    {
        {"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

Configure the RoktEmbeddedViewHandler

You first need to configure the RoktEmbeddedView and its handler in your MauiAppBuilder.

using Rokt.Maui.Sdk;

public static class MauiProgram
{
    public static MauiApp CreateMauiApp()
    {
        var builder = MauiApp.CreateBuilder();
        builder
            .UseMauiApp<App>()
            .ConfigureMauiHandlers(handlers =>
            {
                handlers.AddHandler(typeof(RoktEmbeddedView), typeof(RoktEmbeddedViewHandler));
            });
        return builder.Build();
    }
}

Adding the RoktEmbeddedViewHandler

Add the RoktEmbeddedView to your page's XAML.

<?xml version="1.0" encoding="utf-8" ?>
<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             xmlns:sdk="clr-namespace:Rokt.Maui.Sdk;assembly=Rokt.Maui.Sdk"
             x:Class="SampleApp.MainPage">

    <ScrollView>
        <VerticalStackLayout
            Padding="30,0"
            Spacing="25">
            
            <sdk:RoktEmbeddedView
                x:Name="RoktEmbedded1"/>

        </VerticalStackLayout>
    </ScrollView>

</ContentPage>

Execute the Rokt .NET MAUI SDK

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

using Rokt.Maui.Sdk;
// Replace RoktEmbeddedExperience with your viewName
Rokt.Maui.Sdk.Rokt.Execute(
    viewName: "RoktEmbeddedExperience", 
    attributes: new Dictionary<string, string>()
    {
        {"email", "j.smith@example.com"},
        {"firstname", "Jenny"},
        {"lastname", "Smith"},
        {"mobile", "(555)867-5309"},
        {"postcode", "90210"},
        {"country", "US"}
    },
    placeholders: new Dictionary<string, RoktEmbeddedView>()
    {
        {"RoktEmbedded1", RoktEmbedded1}
    },
    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

The Rokt .NET MAUI SDK exposes an async stream via the IAsyncEnumerable interface for the SDK events. For example, to listen and to react to events you can iterate over RoktEvents() on the page where you call Rokt.

public partial class MainPage : ContentPage
{
    public MainPage()
    {
        InitializeComponent();
        // Start listening when the page loads
        Loaded += OnPageLoaded;
    }

    private async void OnPageLoaded(object? sender, System.EventArgs e)
    {
        await foreach(var roktEvent in Rokt.Maui.Sdk.Rokt.RoktEvents())
        {
            Console.Out.Writeline(roktEvent);
        }
    }
}

Event objects

Event	Description	Other properties
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, PlacementId: string
PositiveEngagement	Triggered when the user positively engages with the offer	ViewName: string, PlacementId: string
PlacementInteractive	Triggered when a placement has been rendered and is interactable	ViewName: string, PlacementId: string
PlacementReady	Triggered when a placement is ready to display but has not rendered content yet	ViewName: string, PlacementId: string
PlacementClosed	Triggered when a placement is closed by the user	ViewName: string, PlacementId: string
PlacementCompleted	Triggered when the offer progression reaches the end and no more offers are available to display	ViewName: string, PlacementId: string
PlacementFailure	Triggered when a placement could not be displayed due to some failure	ViewName: string, PlacementId: string (optional)

Callbacks

The Rokt .NET MAUI 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.

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.

Before you begin​

Overlay placements​

Execute the SDK​

Embedded placements​

Configure the RoktEmbeddedViewHandler​

Adding the RoktEmbeddedViewHandler​

Execute the Rokt .NET MAUI SDK​

Events​

Event objects​

Callbacks​

onLoad​

onShouldShowLoadingIndicator​

onShouldHideLoadingIndicator​

onUnload​