MAUI SDK Integration Guide

This page explains how to implement the MAUI SDK for Rokt Ecommerce to deliver more relevant customer experiences at checkout. The SDK allows you to trigger and track these experiences (like displaying offers on confirmation pages) by firing on configured pages and passing user and transaction data back to Rokt for personalization and measurement.

Your dedicated account representative will help configure your account for the MAUI SDK. They will provide you with a key and secret for both Android and iOS, which are required to initialize the SDK and additional resources needed to render the most relevant experiences for your customers.

remarque

These instructions require development resources to complete. If you require additional assistance, please reach out to your Rokt account manager.

1. Add the Rokt SDK to your app

dotnet add package mParticle.MAUI
dotnet add package mParticle.MAUI.Kits.Rokt

2. Initialize the Rokt SDK

To initialize the SDK, insert the following initialization snippet in your AppDelegate file:

attention

• Make sure to replace your-key and your-secret with the key and secret provided by your dedicated Rokt team.

using mParticle.MAUI;

string key = "";
string secret = "";
#if __ANDROID__
    key = "your-key";
    secret = "your-secret";
#elif __IOS__
    key = "your-key";
    secret = "your-secret";
#endif

// Initialize the SDK
var options = new MParticleOptions()
{
    ApiKey = key,
    ApiSecret = secret
};

// Specify the data environment with environment:
// Set it to .development if you are still testing your integration.
// Set it to .production if your integration is ready for production data.
// The default is .autoDetect which attempts to detect the environment automatically
options.Environment = mParticle.MAUI.Environment.Development;

// Identify the current user:
var identifyRequest = new IdentityApiRequest();
// If you're using an un-hashed email address, set it in 'email'.
identifyRequest.UserIdentities = new Dictionary<UserIdentity, string>()
{
    { UserIdentity.Email, "j.smith@example.com" }
};
// If the user is identified with their email address, set additional user attributes.
options.IdentifyRequest = identifyRequest;

OnUserIdentified onIdentifyComplete = newUser =>
{
    if (newUser != null)
    {
        newUser.SetUserAttribute("example attribute key", "example attribute value");
    }
};
options.IdentityStateListener = onIdentifyComplete;

// Register the Rokt kit with mParticle before initialization
RoktKit.Register();

MParticle.Instance.Initialize(options);

remarque

For Android you also need to ensure your activty extends MauiAppCompatActivity

2.1 Identify the User on initialization

When the SDK is initialized, it can identify the current user so that any collected data is correctly attributed to them and to ensure they are shown the most relevant ads based on their behavior.

The SDK initialization script includes an object called identifyRequest:

var identifyRequest = new IdentityApiRequest();
identifyRequest.UserIdentities = new Dictionary<UserIdentity, string>()
{
    { UserIdentity.Email, "j.smith@example.com" }
};
options.IdentifyRequest = identifyRequest;

2.2 Set additional user attributes

The initialization script includes a callback function that allows you to set additional user attributes for the user if they are successfully identified with their email address:

OnUserIdentified onIdentifyComplete = newUser =>
{
    if (newUser != null)
    {
        newUser.SetUserAttribute("example attribute key", "example attribute value");
    }
};
options.IdentityStateListener = onIdentifyComplete;

3. Identify the User as data becomes available

Whenever the user provides their email address after the SDK has initialized (for example, when they log in or make a purchase), you should call the identify method to pass their email to Rokt. This ensures that data is correctly attributed to the current user.

3.1 Create an identifyRequest

To identify the user, first create an identifyRequest object to contain the user’s email address.

If you are providing an un-hashed email address, use:

var identifyRequest = new IdentityApiRequest();
identifyRequest.UserIdentities = new Dictionary<UserIdentity, string>()
{
    { UserIdentity.Email, "j.smith@example.com" }
};

3.2 Call the identify method

Finally, after creating your identifyRequest, to set any additional attributes, call the Identify method, passing in the identifyRequest object you just created:

MParticle.Instance.Identity.Identify(identifyRequest);

For example, to identify a user named Jane Smith with the email address j.smith@example.com (and you don't need to hash their email address) you would use:

var identifyRequest = new IdentityApiRequest();
identifyRequest.UserIdentities = new Dictionary<UserIdentity, string>()
{
    { UserIdentity.Email, "j.smith@example.com" }
};

MParticle.Instance.Identity.Identify(identifyRequest)
    .AddSuccessListener(success => 
    {
        success.User.SetUserAttribute("example attribute key", "example attribute value");
    });

3.3 Set additional user attributes

Next, you have the option of setting additional user attributes with SetUserAttribute.

MParticle.Instance.Identity.SetUserAttribute("example attribute key", "example attribute value");

4. Track User Attributes

You can use the Rokt SDK to collect user attributes separately from events. User attributes are separate from custom attributes when tracking events. The SDK will associate any user attributes collected in a given session with events triggered in the same session.

To collect user attributes, the following code should be run in your app immediately after initializing the Rokt SDK, and before you log an event.

// Retrieve the current user. This will only succeed if you have identified the user during SDK initialization or by calling the identify method.
var currentUser = MParticle.Instance.Identity.CurrentUser;

// Once you have successfully set the current user to `currentUser`, you can set user attributes with:
currentUser.SetUserAttribute("custom-attribute-name", "custom-attribute-value");
// Note: all user attributes (including list attributes and tags) must have distinct names.

// Rokt recommends setting as many of the following user attributes as possible:
currentUser.SetUserAttribute("firstname", "Jane");
currentUser.SetUserAttribute("lastname", "Smith");

// Phone numbers can be formatted either as '1234567890', or '+1 (234) 567-8901'
currentUser.SetUserAttribute("mobile", "3125551515");
currentUser.SetUserAttribute("age", "33");
currentUser.SetUserAttribute("gender", "M");
currentUser.SetUserAttribute("city", "Brooklyn");
currentUser.SetUserAttribute("state", "NY");
currentUser.SetUserAttribute("zip", "123456");
currentUser.SetUserAttribute("dob", "yyyymmdd");
currentUser.SetUserAttribute("title", "Mr");
currentUser.SetUserAttribute("language", "en");
currentUser.SetUserAttribute("value", "52.25");
currentUser.SetUserAttribute("predictedltv", "136.23");

// You can create a user attribute to contain a list of values
currentUser.SetUserAttribute("favorite-genres", string.Join(", ", new string[] { "documentary", "comedy", "romance", "drama" }));

5. Capture Funnel Events

The Rokt SDK allows you to implement event tracking to collect data describing your users' journeys through your app. You can then use this data to optimize your users' experience.

There are three primary event types you can record with the SDK:

• Screen View Events: These are events you can trigger when a page of your app is loaded.
• Custom Events: These are freeform events you create to track information specific to your app.
• Commerce Events: These are events specific to ecommerce that can describe the different stages of the shopping experience, including adding items to a cart and making a final purchase.

When first integrating with the Rokt SDK, start by implementing screen view tracking.

Track screen views

One of the most basic event types you can track is the screen view. To log a screen view, call the .logScreen method, passing in the name of the screen as a string. The name you pass in should be one of a limited set of pages, like 'homepage' or 'product detail page'. You can also include additional custom attributes in the eventInfo array.

MParticle.Instance.LogScreen("homepage", new Dictionary<string, string>() { { "custom-attribute", "custom-value" } });

6. Show a Placement

The main value of the Rokt SDK is unlocked through the selectPlacements method, which serves a placement (or layout) that is hyper-relevant to your customers based on attributes you provide.

Once the Rokt integration has been initialized, you can call the selectPlacements method from the page where your layout will be rendered. It should be called as early as possible, and once all required attributes are available, to ensure the best experience for your users.

When calling selectPlacements you should provide at least the email, firstname, lastname, billingzipcode and confirmationref attributes to provide your users with the most relevent placement.

Overlay placements

using mParticle.MAUI

var attributes = new Dictionary<string, string>
{
    ["email"] = "j.smith@example.com",
    ["firstname"] = "Jenny",
    ["lastname"] = "Smith",
    ["billingzipcode"] = "07762",
    ["confirmationref"] = "54321",
    ["country"] = "US"
};

MParticle.Instance.Rokt.SelectPlacements(
    identifier: "RoktExperience",
    attributes: attributes
);

remarque

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

Optional functions

Embedded placements

Embedded placements share all of the same recommendations and requirements as overlay placements above but allow you to embed the placement views in your UI.

Firstly in your app class you'll need to configure MAUI handlers for the RoktEmbeddedView.

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();
    }
}

You then need to add RoktEmbeddedView in your relevant XML.

<?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:mParticle.MAUI;assembly=mParticle.Maui.Sdk"
        x:Class="SampleApp.MainPage">

    <VerticalStackLayout>
        <sdk:RoktEmbeddedView
            x:Name="Location1"/>
    </VerticalStackLayout>
</ContentPage>

The RoktEventCallback class, which is passed to Rokt through the callbacks parameter, allow you to respond to various events that occur when generating and displaying a placement.

using mParticle.MAUI;

var attributes = new Dictionary<string, string>
{
    ["email"] = "test@gmail.com",
    ["firstname"] = "Jenny",
    ["lastname"] = "Smith",
    ["billingzipcode"] = "07762",
    ["confirmationref"] = "54321",
    ["country"] = "US"
};

var callbacks = new RoktEventCallback
{
    OnLoad = () => Console.WriteLine("Rokt placement loaded"),
    OnUnLoad = (reason) => Console.WriteLine($"Rokt placement unloaded with reason: {reason}"),
    OnShouldShowLoadingIndicator = () => Console.WriteLine("Should show loading indicator"),
    OnShouldHideLoadingIndicator = () => Console.WriteLine("Should hide loading indicator"),
    OnEmbeddedSizeChange = (identifier, size) => Console.WriteLine($"Embedded view '{identifier}' size changed to {size}")
};

MParticle.Instance.Rokt.SelectPlacements(
    identifier: "MSDKEmbeddedLayout",
    attributes: attributes,
    embeddedViews: new Dictionary<string, RoktEmbeddedView>()
    {
        {"Location1", Location1}
    },
    callbacks: callbacks
);

remarque

For a full list of supported attributes, see Data Attributes.

Your dedicated Rokt team will configure your placement layouts for you so they match your brand and UX style guide.