Cordova Plugin Integration Guide

This page explains how to implement the Cordova SDK for Rokt Ads 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 Cordova 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

cordova plugin add @mparticle/cordova-sdk
cordova plugin add @mparticle/cordova-rokt-kit

2. Initialize the Rokt SDK

To initialize the SDK, insert the following initialization snippet in the relevant section of the native codebase e.g. AppDelegate on iOS.

You can find a full example of how to complete this integration in our [https://github.com/mParticle/cordova-plugin-mparticle/tree/main/example](example app).

attention

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

iOS

#import "AppDelegate.h"
#import "MainViewController.h"
#import "mParticle.h"

@implementation AppDelegate

- (BOOL)application:(UIApplication*)application didFinishLaunchingWithOptions:(NSDictionary*)launchOptions
{
    MParticleOptions *mParticleOptions = [MParticleOptions optionsWithKey:@"REPLACE_ME_API_KEY" secret:@"REPLACE_ME_API_SECRET"];
    
    //Please see the Identity page for more information on building this object
    MPIdentityApiRequest *request = [MPIdentityApiRequest requestWithEmptyUser];
    request.email = @"j.smith@example.com";

    mParticleOptions.identifyRequest = request;
    mParticleOptions.onIdentifyComplete = ^(MPIdentityApiResult * _Nullable apiResult, NSError * _Nullable error) {
        NSLog(@"Identify complete. userId = %@ error = %@", apiResult.user.userId, error);
    };
    
    [[MParticle sharedInstance] startWithOptions:mParticleOptions];
    
    [MParticle sharedInstance].logLevel = MPILogLevelVerbose;
    
    self.viewController = [[MainViewController alloc] init];
    return [super application:application didFinishLaunchingWithOptions:launchOptions];
}

@end

Android

public class MainActivity extends CordovaActivity
{
    @Override
    public void onCreate(Bundle savedInstanceState)
    {
        super.onCreate(savedInstanceState);

        // enable Cordova apps to be started in the background
        Bundle extras = getIntent().getExtras();
        if (extras != null && extras.getBoolean("cdvStartInBackground", false)) {
            moveTaskToBack(true);
        }

        // Set by <content src="index.html" /> in config.xml
        loadUrl(launchUrl);

        // Initialize MParticle
        IdentityApiRequest identifyRequest = IdentityApiRequest.withEmptyUser()
                .email("j.smith@example.com")
                .build();

        MParticleOptions options = MParticleOptions.builder(this)
                .credentials("REPLACE_ME_API_KEY", "REPLACE_ME_API_SECRET")
                .identify(identifyRequest)
                .logLevel(MParticle.LogLevel.VERBOSE)
                .build();
        MParticle.start(options);
    }
}

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 mparticle.IdentityRequest();
identifyRequest.setEmail('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:

var identity = new mparticle.Identity();

identity.identify(identifyRequest, function (userID) {
    console.log('Identify Success: ' + userID);
});

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 mparticle.IdentityRequest();
identifyRequest.setEmail('j.smith@example.com');

var identity = new mparticle.Identity();

identity.identify(identifyRequest, function (userID) {
    console.log('Identify Success: ' + userID);
});

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 identity = new mparticle.Identity();

identity.getCurrentUser(function(userID) {
    var user = new mparticle.User(userID);

    // Once you have successfully set the current user to `currentUser`, you can set user attributes with:
    user.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:
    user.setUserAttribute(mparticle.UserAttributeType.FirstName, 'Jane');
    user.setUserAttribute(mparticle.UserAttributeType.LastName, 'Smith');

    // Phone numbers can be formatted either as '1234567890', or '+1 (234) 567-8901'
    user.setUserAttribute(mparticle.UserAttributeType.MobileNumber, '3125551515');
    user.setUserAttribute(mparticle.UserAttributeType.Age, '33');
    user.setUserAttribute(mparticle.UserAttributeType.Gender, 'M');
    user.setUserAttribute(mparticle.UserAttributeType.City, 'Brooklyn');
    user.setUserAttribute(mparticle.UserAttributeType.State, 'NY');
    user.setUserAttribute(mparticle.UserAttributeType.Zipcode, '123456');


    user.setUserAttribute('dob', 'yyyymmdd');
    user.setUserAttribute('title', 'Mr');
    user.setUserAttribute('language', 'en');
    user.setUserAttribute('value', '52.25');
    user.setUserAttribute('predictedltv', '136.23');

    // You can create a user attribute to contain a list of values
    user.setUserAttributeArray('favorite-genres', ['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.logScreenEvent('homepage', { 'custom-attribute': 'custom-value' });

6. Track Conversions

To track a conversion, run the following code snippet on the most appropriate page that's loaded after a customer converts, such as a purchase confirmation or "thank you" page.

When pasting the code snippet into your site, make sure to:

1. Replace the sample user attributes in the setUserAttribute calls the actual values for your user or customer. Rokt recommends setting at least the following user attributes:
   • firstname
   • lastname
   • zipcode
   • mobile
2. Replace the sample conversion event attributes with with actual values from your conversion event.

When logging a conversion event, you should include as many user attributes and event attributes as possible to improve Rokt's ability to optimize your campaigns.

var identity = new mparticle.Identity();

identity.getCurrentUser(function(userID) {
    var user = new mparticle.User(userID);

    user.setUserAttribute(mparticle.UserAttributeType.FirstName, 'Jane');
    user.setUserAttribute(mparticle.UserAttributeType.LastName, 'Smith');
    user.setUserAttribute(mparticle.UserAttributeType.Zipcode, '123456');
    user.setUserAttribute(mparticle.UserAttributeType.MobileNumber, '3125551515');
});

mparticle.logEvent(
    'conversion',
    mparticle.EventType.Transaction,
    {
        'conversiontype': 'signup', // type of conversion
        'confirmationref': '54321', // Transaction ID / Order ID
        'amount': '',               // Transaction amount e.g. 300.5
        'currency': '',             // Transaction currency e.g. USD
        // You can track your own custom event attributes!
        'CUSTOM_EVENT_ATTRIBUTE_NAME' : 'CUSTOM_EVENT_ATTRIBUTE_VALUE'
    }
);