# Cordova SDK+ Integration Guide

> Product: Rokt Ecommerce
>
> Intended implementer: Rokt Ecommerce partner
>
> Integration surface: The partner’s owned website, app, or transaction experience
>
> Not intended for: Advertisers implementing Rokt Ads
>
> Canonical documentation: [https://docs.rokt.com/integration-guides/ecommerce/sdk/cordova/](https://docs.rokt.com/integration-guides/ecommerce/sdk/cordova/)
>
> This is a complete machine-readable guide generated from the same MDX source as the rendered documentation. Read the complete guide before implementing the integration, and do not edit this generated file directly.

These SDK+ integration guides are for Rokt Ecommerce partners—ecommerce businesses integrating Rokt into transaction experiences they own, including websites, apps, carts, checkouts, payment pages, and confirmation flows.
They are not implementation guides for advertisers using Rokt Ads to acquire customers across the Rokt Network. References to advertiser offers describe content rendered within an ecommerce partner’s owned experience. Advertisers should use the [Rokt Ads integration guides](https://docs.rokt.com/integration-guides/ads/).

This page explains how to implement the Rokt Ecommerce Cordova SDK+. The SDK+ passes user and transaction data to Rokt on configured screens so Rokt can render relevant experiences, such as offers on confirmation screens.

Use the **Target** and **Language** selectors above to choose your deployment platform and the native code examples you want to follow.

## 1. Add the Rokt SDK+ to Your Cordova App

Install the SDK+ and the Rokt kit plugin:

### Install Cordova plugins

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

## 2. Initialize the Rokt SDK+

Insert the following initialization snippet in the relevant native entry point for each platform. The SDK+ must be initialized before any other SDK+ API calls. Replace `your-key` and `your-secret` with the key and secret provided by your Rokt team.

You can find a full example in the [example app](https://github.com/mParticle/cordova-plugin-mparticle/tree/main/example).

### Target: iOS and Android

When inserting the initialization snippet, you will see customizable fields for:

#### 1. Entering your Rokt key and secret

Set `your-key` and `your-secret` to the values provided by your Rokt account manager. (iOS uses `optionsWithKey:secret:`. Android uses `.credentials(...)`.)

#### 2. Setting your data environment

Set the SDK+ environment to development while testing to route data to the Development environment, and to production to send live customer activity to Production. (iOS: `MPEnvironmentDevelopment` / `MPEnvironmentProduction`. Android: `MParticle.Environment.Development` / `MParticle.Environment.Production`.)

#### 3. Identifying your user and setting attributes

In `identifyRequest`, pass the user's raw, un-hashed email. For hashed emails and other identifiers, see [Supported user identifiers](https://docs.rokt.com/integration-guides/ecommerce/sdk/cordova/#supported-user-identifiers). Once identified, set additional user attributes via the success callback (iOS: `onIdentifyComplete`. Android: wire the request into the options builder via `.identify(identifyRequest)` and use a success listener — see [Step 3: Identify the User](https://docs.rokt.com/integration-guides/ecommerce/sdk/cordova/#identify-cordova) for the pattern).

> **Note**
>
> Always include `identifyRequest` in the initialization snippet. If you don't have the user's email at initialization, omit the email assignment (iOS) or the `.email(...)` call (Android) — the SDK+ will still initialize, and you can identify the user later via [3. Identify the User](https://docs.rokt.com/integration-guides/ecommerce/sdk/cordova/#identify-cordova). See [Error Handling](https://docs.rokt.com/integration-guides/ecommerce/sdk/cordova/#error-handling) for how to handle identify failures — without error handling you may see data consistency issues at scale.

### Target: iOS

#### AppDelegate initialization (iOS)

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

@implementation AppDelegate

- (BOOL)application:(UIApplication*)application didFinishLaunchingWithOptions:(NSDictionary*)launchOptions
{
  MParticleOptions *mParticleOptions = [MParticleOptions optionsWithKey:@"your-key"
                                                                 secret:@"your-secret"];
  // Specify the data environment:
  // Set it to MPEnvironmentDevelopment if you are still testing your integration.
  // Set it to MPEnvironmentProduction if your integration is ready for production data.
  // The default is MPEnvironmentAutoDetect which attempts to detect the environment automatically.
  mParticleOptions.environment = MPEnvironmentDevelopment;

  // Identify the current user:
  // If you do not have the user's email address, you can pass in a null value
  MPIdentityApiRequest *request = [MPIdentityApiRequest requestWithEmptyUser];

  // Preferred: pass the customer's raw, unhashed email address in 'email'.
  // If you can only provide a SHA-256-hashed email, set it in 'other' instead of email — do not pass both.
  request.email = @"j.smith@example.com";
  // [request setIdentity:@"sha256 hashed email goes here" identityType:MPIdentityOther]; // only if raw email unavailable

  mParticleOptions.identifyRequest = request;
  mParticleOptions.onIdentifyComplete = ^(MPIdentityApiResult * _Nullable apiResult, NSError * _Nullable error) {
      if (apiResult) {
          // If the user is identified, set additional user attributes
          [apiResult.user setUserAttribute:@"example attribute key" value:@"example attribute value"];
      }
  };

  [[MParticle sharedInstance] startWithOptions:mParticleOptions];

  self.viewController = [[MainViewController alloc] init];
  return [super application:application didFinishLaunchingWithOptions:launchOptions];
}

@end
```

### Target: Android

#### MainActivity initialization (Android)

```java
import com.mparticle.MParticle;
import com.mparticle.MParticleOptions;

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

      // Identify the current user:
      // If you do not have the user's email address, you can pass in a null value
      IdentityApiRequest identifyRequest = IdentityApiRequest.withEmptyUser()
          // Preferred: pass the customer's raw, unhashed email via .email().
          // If you can only provide a SHA-256-hashed email, remove .email() and use .userIdentity(Other) instead — do not pass both.
          .email("j.smith@example.com")
          // .userIdentity(MParticle.IdentityType.Other, "SHA-256 hashed email")  // only if raw email unavailable
          // If you can only provide a SHA-256-hashed mobile number, use 'other2' instead of MobileNumber — do not pass both.
          // .userIdentity(MParticle.IdentityType.Other2, "SHA-256 hashed mobile number")  // only if raw mobile unavailable
          .userIdentity(MParticle.IdentityType.MobileNumber, "+13125551515")
          .customerId("cust_10482")
          .build();

      MParticleOptions options = MParticleOptions.builder(this)
          .credentials(
              "your-key",   // The key provided by your Rokt account manager
              "your-secret" // The secret provided by your Rokt account manager
          )
          // 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.
          .environment(MParticle.Environment.Development)
          .identify(identifyRequest)
          .build();

      MParticle.start(options);
  }
}
```

## 3. Identify the User

The [SDK+ initialization script](https://docs.rokt.com/integration-guides/ecommerce/sdk/cordova/#initialize-cordova) identifies the current user using the identifiers you provided in the script's `identifyRequest` object. After SDK initialization, you should keep the user's identity in sync whenever they log in, log out, or otherwise provide an identifier (for example, during checkout) using the appropriate method as described below.

### Supported user identifiers

### Show supported user identifiers

| Field          | Type   | Description                                                                                                                                                      |
| -------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `email`        | string | Pass the customer's raw, unhashed email address.                                                                                                                 |
| `mobile`       | string | Pass the customer's phone number in E.164 format.                                                                                                                |
| `customerid`   | string | Pass your internal customer/account identifier. Send on every screen for logged-in users.                                                                        |
| `other`        | string | Pass a SHA-256-hashed email. **Only use when the raw email cannot be provided — do not pass both `email` and `other`.** (Android path only.)                     |
| `other2`       | string | Pass a SHA-256-hashed mobile number. **Only use when the raw mobile number cannot be provided — do not pass both `mobile` and `other2`.** (Android path only.)   |
| `emailSha256`  | string | Pass a SHA-256-hashed email. **Only use when the raw email cannot be provided — do not pass both `email` and `emailSha256`.** (iOS path only.)                   |
| `mobileSha256` | string | Pass a SHA-256-hashed mobile number. **Only use when the raw mobile number cannot be provided — do not pass both `mobile` and `mobileSha256`.** (iOS path only.) |

To identify the user:

### 1. Create an identifyRequest object

Create an `identifyRequest` object to contain the user's identifiers. You should integrate the user's raw, unhashed email address into the `email` field.

### 2. Create an identityCallback

To set additional user attributes, create an `identityCallback`. If the `identifyRequest` succeeds, then any user attributes you set inside the callback are assigned to the identified user.

### 3. Send the request using the method that matches the user's action

Pass the `identifyRequest` (and optional `identityCallback`) to the method that matches the user's action:

- **`identity.login`:** call when the user logs in or creates an account.
- **`identity.identify`:** call when you obtain the user's email mid-session without a login transition (for example, a guest enters their email at checkout).
- **`identity.logout`:** call when the user logs out.

Calling these methods transitions the SDK's record of the current user's state. The `login` and `logout` methods also automatically log a corresponding event to improve Rokt's attribution.

For example, to identify a user named Jane Smith with the email address `j.smith@example.com`, mobile number `+13125551515`, and customer ID `cust_10482`:

#### Identify Jane Smith

```javascript
// 1. Create the identifyRequest object
var identifyRequest = new mparticle.IdentityRequest();
// Preferred: pass the customer's raw, unhashed email address.
// If you can only provide a SHA-256-hashed email, use setUserIdentity with 'other' instead — do not pass both.
identifyRequest.setEmail('j.smith@example.com');
identifyRequest.setUserIdentity(mparticle.UserIdentityType.Other, 'SHA-256 hashed email'); // only if raw email unavailable
// If you can only provide a SHA-256-hashed mobile number, use 'Other2' instead of 'MobileNumber' — do not pass both.
// (Called 'other2' on Android and 'mobileSha256' on iOS; both use this same field.)
identifyRequest.setUserIdentity(mparticle.UserIdentityType.Other2, 'SHA-256 hashed mobile number'); // only if raw mobile unavailable
identifyRequest.setUserIdentity(mparticle.UserIdentityType.MobileNumber, '+13125551515');
identifyRequest.setCustomerId('cust_10482');

// 2. Optionally set user attributes once the request succeeds.
var identityCallback = {
  onSuccess: function(userID) {
      var user = new mparticle.User(userID);
      user.setUserAttribute('firstname', 'Jane');
      user.setUserAttribute('lastname', 'Smith');
  },
  onError: function(errorResponse) {
      console.error('Identify error: ' + JSON.stringify(errorResponse));
  }
};

// 3. Call one of the following methods that best matches the user's action:
var identity = new mparticle.Identity();
identity.login(identifyRequest, identityCallback.onSuccess); // Call when the user logs in or creates an account
identity.identify(identifyRequest, identityCallback.onSuccess); // Call when you obtain the user's email mid-session, but not during a login
identity.logout({}); // Call when the user logs out
```

## 4. Set User Attributes

Set user attributes **progressively** as the user navigates your app, not just at checkout. The more attributes you set, the better Rokt can resolve the customer and deliver relevant offers.

### Set user attributes

```javascript
var identity = new mparticle.Identity();

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

  // Once you have successfully set the current user, 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', 'John');
  currentUser.setUserAttribute('lastname', 'Doe');
  // 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('billingcity', 'Brooklyn');
  currentUser.setUserAttribute('billingstate', 'NY');
  currentUser.setUserAttribute('billingzipcode', '123456');
  currentUser.setUserAttribute('dob', 'yyyymmdd');
  currentUser.setUserAttribute('title', 'Mr');
  currentUser.setUserAttribute('language', 'en');
  currentUser.setUserAttribute('predictedltv', '136.23');

  // You can create a user attribute to contain a list of values
  currentUser.setUserAttributeArray('favorite-genres', ['documentary', 'comedy', 'romance', 'drama']);

  // To remove a user attribute, call removeUserAttribute and pass in the attribute name.
  // All user attributes share the same key space.
  currentUser.removeUserAttribute('attribute-to-remove');
});
```

### User attributes

Set as many of the following as you can collect:

### Show all user attributes

| Field                | Type    | Description                                                                                                            |
| -------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------- |
| `firstname`          | string  | Customer's first name. Used for personalization.                                                                       |
| `lastname`           | string  | Customer's last name. Used for personalization.                                                                        |
| `mobile`             | string  | Phone number formatted as `1112345678` or `+1 (222) 345-6789`. Used for identity resolution and relevance.             |
| `age`                | integer | Customer's age. Alternate to `dob`. Used for eligibility and relevance.                                                |
| `dob`                | string  | Date of birth, `yyyymmdd`. Alternate to `age`. Used for eligibility and relevance.                                     |
| `gender`             | string  | Customer's gender. For example, `M`, `F`, `Male`, or `Female`. Used for relevance.                                     |
| `title`              | string  | Honorific. For example, `Mr`, `Mrs`, `Ms`. Used for personalization.                                                   |
| `language`           | string  | ISO 639-1 language code associated with the purchase. Used for relevance.                                              |
| `billingcity`        | string  | Billing city. Used for relevance.                                                                                      |
| `billingstate`       | string  | Billing state / province / region. Used for relevance and eligibility.                                                 |
| `billingzipcode`     | string  | Full ZIP or postcode (US preference is ZIP+4). Used for identity resolution and relevance.                             |
| `billingaddress1`    | string  | Billing street address line 1. Used for identity resolution and relevance.                                             |
| `billingaddress2`    | string  | Billing street address line 2. Used for identity resolution.                                                           |
| `country`            | string  | ISO 3166-1 alpha-2 country code (e.g. `US`, `GB`, `AU`). Used for eligibility and relevance.                           |
| `birthyear`          | integer | Customer's birth year (e.g. `1990`). Used for eligibility and relevance.                                               |
| `newcustomer`        | boolean | Whether this is a first-time buyer. Used for relevance.                                                                |
| `customertype`       | string  | Whether the user is authenticated (`guest` / `logged_in`). Used for relevance.                                         |
| `loyaltytier`        | string  | Partner loyalty program tier. Used for relevance and eligibility.                                                      |
| `loyaltyid`          | string  | Loyalty program member ID. Used for identity resolution.                                                               |
| `predictedltv`       | decimal | Predicted total lifetime value, typically from a partner ML model. Used for relevance.                                 |
| `subscriptionstatus` | string  | Subscription state if applicable (`active`, `trial`, `churned`, `paused`, `none`). Used for relevance and eligibility. |
| `customersegment`    | string  | Partner internal segmentation (e.g. `vip`, `at_risk`, `new`, `reactivated`). Used for relevance.                       |
| `acquisitionchannel` | string  | Channel through which the customer was acquired. Used for relevance.                                                   |

All user attributes (including list attributes) must have distinct names.

## 5. Track Funnel Events

Track screen views, commerce events, and custom events so Rokt can understand where each customer is in their journey.

### Event category: Screen views

Call `mparticle.logScreenEvent` with the name of the screen (e.g. `'homepage'`, `'product_detail_page'`). Include any additional custom attributes in the info object.

#### Log a screen view

```javascript
mparticle.logScreenEvent('homepage', { 'custom-attribute': 'custom-value' });
```

### Event category: Commerce events

Commerce events carry product-level details for the user's journey. Trigger a separate commerce event for each product action the customer takes.

Investing in full commerce event coverage is one of the highest-leverage things you can do during your integration. Each event tells Rokt something different about where the customer is in their journey: a product view signals exploration, an add-to-cart signals consideration, a checkout start signals purchase intent, and a completed purchase confirms conversion. With a richer signal, Rokt can personalize offers more effectively, measure placement performance accurately, and attribute conversions to the right touchpoints. Doing this work during your initial integration also avoids a retrofit later. The signal compounds over time: each event Rokt receives adds context used to sharpen personalization, improve attribution accuracy, and better resolve and segment your customer base on future visits.

Commerce events are logged with `mparticle.eCommerce.logProductAction`, using a product action type that identifies the customer action (viewing a product, adding to cart, starting checkout, completing a purchase, etc.).

#### Show all product action types

| Customer action            | Product action type                              |
| -------------------------- | ------------------------------------------------ |
| Product detail page viewed | `mparticle.ProductActionType.ViewDetail`         |
| Product clicked            | `mparticle.ProductActionType.Click`              |
| Item added to cart         | `mparticle.ProductActionType.AddToCart`          |
| Item removed from cart     | `mparticle.ProductActionType.RemoveFromCart`     |
| Item added to wishlist     | `mparticle.ProductActionType.AddToWishlist`      |
| Item removed from wishlist | `mparticle.ProductActionType.RemoveFromWishlist` |
| Checkout flow initiated    | `mparticle.ProductActionType.Checkout`           |
| Checkout option selected   | `mparticle.ProductActionType.CheckoutOption`     |
| Order confirmed            | `mparticle.ProductActionType.Purchase`           |
| Order refunded             | `mparticle.ProductActionType.Refund`             |

Tracking a commerce event takes three phases:

#### 1. Define the product

Build a product with `mparticle.eCommerce.createProduct`. Set additional fields like `Category`, `Brand`, and `Position` directly on the returned object.

##### Define a product

```javascript
var product = mparticle.eCommerce.createProduct(
  'Double Room - Econ Rate', // Name
  'econ-1',                  // SKU
  100.00,                    // Price
  4                          // Quantity
);
product.Category = 'room';
product.Brand = 'lodge-o-rama';
product.Variant = 'standard';
```

#### 2. Summarize the transaction

Build a `transactionAttributes` object for `Purchase`, `Checkout`, and `CheckoutOption` events. Use PascalCase keys (`Id`, `Revenue`, `Tax`, `Shipping`, `Coupon`). Order-level coupons belong here, not on individual products.

##### Summarize the transaction

```javascript
var transactionAttributes = {
  Id:       'ORDER-12345',
  Revenue:  149.99,
  Tax:      12.50,
  Shipping: 5.99,
  Coupon:   'SUMMER20'
};
```

#### 3. Log the commerce event

Call `mparticle.eCommerce.logProductAction`, passing the product action type, your product(s), event-level attributes, optional custom flags, and (when applicable) the `transactionAttributes`. Pick the customer action you want to log:

##### Commerce event: PLP impression

Log a product listing page (or category page) view as a product impression. Pass every visible product in a single impression call, and set the list name to the list / category the customer is browsing.

| Field      | Type   | Required | Description                                                               |
| ---------- | ------ | -------- | ------------------------------------------------------------------------- |
| `Name`     | string | yes      | List or category name (e.g. `"Mens Running Shoes"`). Becomes `list_name`. |
| `Products` | array  | yes      | Product objects from `createProduct`. Set `Position` to each item's rank. |
| `currency` | string | yes      | ISO 4217 currency code (passed as event-level custom attribute).          |

###### Example PLP impression event

```javascript
var product = mparticle.eCommerce.createProduct(
  'Trail Runner v3', // Name
  'SKU-001',         // SKU
  129.95,            // Price
  1                  // Quantity
);
product.Category = 'Shoes';
product.Brand = 'BrandX';
product.Position = 1;

var impression = {
  Name: 'Mens Running Shoes',
  Products: [product]
};

mparticle.eCommerce.logImpression(impression, { 'currency': 'USD' });
```

##### Commerce event: ViewDetail

Log when a customer opens a product detail page.

| Field         | Type    | Required | Description                         |
| ------------- | ------- | -------- | ----------------------------------- |
| `productsku`  | string  | yes      | Product SKU.                        |
| `productname` | string  | yes      | Display name.                       |
| `itemprice`   | decimal | yes      | Per-unit price at the time of view. |
| `currency`    | string  | yes      | ISO 4217 currency code.             |
| `list_name`   | string  | no       | Set if the user arrived from a PLP. |

###### Example ViewDetail event

```javascript
var product = mparticle.eCommerce.createProduct(
  'Trail Runner v3', // Name
  'SKU-001',         // SKU
  129.95,            // Price
  1                  // Quantity
);

mparticle.eCommerce.logProductAction(
  mparticle.ProductActionType.ViewDetail,
  [product],
  { 'currency': 'USD', 'list_name': 'PLP-Running' }
);
```

##### Commerce event: AddToCart

Log when a customer adds an item to the cart.

| Field        | Type    | Required | Description                                 |
| ------------ | ------- | -------- | ------------------------------------------- |
| `productsku` | string  | yes      | Product SKU.                                |
| `quantity`   | integer | yes      | Units added.                                |
| `itemprice`  | decimal | yes      | Per-unit price at time of add.              |
| `currency`   | string  | yes      | ISO 4217 currency code.                     |
| `couponCode` | string  | no       | Order-level coupon, if applied at add-time. |

###### Example AddToCart event

```javascript
var product = mparticle.eCommerce.createProduct(
  'Trail Runner v3', // Name
  'SKU-001',         // SKU
  129.95,            // Price
  1                  // Quantity
);

mparticle.eCommerce.logProductAction(
  mparticle.ProductActionType.AddToCart,
  [product],
  { 'currency': 'USD' }
);
```

##### Commerce event: RemoveFromCart

Log when a customer removes an item from the cart.

| Field        | Type    | Required | Description             |
| ------------ | ------- | -------- | ----------------------- |
| `productsku` | string  | yes      | Product SKU.            |
| `quantity`   | integer | yes      | Units removed.          |
| `currency`   | string  | yes      | ISO 4217 currency code. |

###### Example RemoveFromCart event

```javascript
var product = mparticle.eCommerce.createProduct(
  'Trail Runner v3', // Name
  'SKU-001',         // SKU
  129.95,            // Price
  1                  // Quantity
);

mparticle.eCommerce.logProductAction(
  mparticle.ProductActionType.RemoveFromCart,
  [product],
  { 'currency': 'USD' }
);
```

##### Commerce event: Cart page view

Log when the customer arrives on the cart page. Since cart page views do not have a native product action, use `mparticle.logEvent` with the event name `'view_cart'` and `mparticle.EventType.Other`. Pass the full cart contents as a custom attribute.

| Field           | Type      | Required | Description                                                                |
| --------------- | --------- | -------- | -------------------------------------------------------------------------- |
| `event_name`    | string    | yes      | Always `'view_cart'`.                                                      |
| `event_type`    | EventType | yes      | Use `mparticle.EventType.Other`.                                           |
| `cartitems`     | array     | yes      | Full cart contents, JSON-stringified before passing as a custom attribute. |
| `cartitemcount` | integer   | yes      | Number of cart lines.                                                      |
| `totalprice`    | decimal   | yes      | Cart total.                                                                |
| `currency`      | string    | yes      | ISO 4217 currency code.                                                    |
| `couponcode`    | string    | no       | Order-level promo, if applied.                                             |

Each entry in the `cartitems` array has the following shape:

| Field             | Type    | Description                                                                                                                                                                                      |
| ----------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `cartitemid`      | string  | Stable partner-side cart-line identifier. Usually equals `productsku` when there is one line per SKU; use a unique value if you allow multiple lines for the same SKU (e.g. gift-wrap variants). |
| `productsku`      | string  | Product SKU / stock identifier.                                                                                                                                                                  |
| `productname`     | string  | Product display name.                                                                                                                                                                            |
| `productcategory` | string  | Product category / taxonomy leaf.                                                                                                                                                                |
| `productbrand`    | string  | Product brand.                                                                                                                                                                                   |
| `productvariant`  | string  | Variant identifier (size, color, etc.).                                                                                                                                                          |
| `itemprice`       | decimal | Per-unit price at event time.                                                                                                                                                                    |
| `unitprice`       | decimal | Per-unit list price pre-discount. Omit if equal to `itemprice`.                                                                                                                                  |
| `quantity`        | integer | Units in this line.                                                                                                                                                                              |
| `currency`        | string  | ISO 4217 code. Omit if matches the top-level currency.                                                                                                                                           |
| `couponcode`      | string  | Coupon applied to this line (if any). Order-level promos belong in `transactionAttributes.Coupon`.                                                                                               |
| `productposition` | integer | 1-indexed rank of the product within a list or search results.                                                                                                                                   |

###### Example cart page view event

```javascript
var cartItems = JSON.stringify([
  { cartitemid: 'SKU-001', productsku: 'SKU-001', productname: 'Trail Runner v3', itemprice: 129.95, quantity: 1 },
  { cartitemid: 'SKU-002', productsku: 'SKU-002', productname: 'Cushion Insole',  itemprice: 19.95,  quantity: 2 }
]);

mparticle.logEvent(
  'view_cart',
  mparticle.EventType.Other,
  {
      'cartitemcount': '3',
      'totalprice': '169.85',
      'currency': 'USD',
      'couponcode': 'SUMMER20',
      'cartitems': cartItems
  }
);
```

##### Commerce event: Checkout

Log when the customer enters the checkout flow. Send the full set of cart products plus a `transactionAttributes` summary.

| Field           | Type    | Required | Description                                                                |
| --------------- | ------- | -------- | -------------------------------------------------------------------------- |
| `cartitems`     | array   | yes      | Full cart contents, JSON-stringified before passing as a custom attribute. |
| `totalprice`    | decimal | yes      | Cart total before tax/shipping.                                            |
| `cartitemcount` | integer | yes      | Number of cart lines.                                                      |
| `currency`      | string  | yes      | ISO 4217 currency code.                                                    |
| `couponCode`    | string  | no       | Order-level promo, if applied.                                             |

###### Example Checkout event

```javascript
var product1 = mparticle.eCommerce.createProduct('Trail Runner v3', 'SKU-001', 129.95, 1);
var product2 = mparticle.eCommerce.createProduct('Cushion Insole',  'SKU-002', 19.95,  2);

var transactionAttributes = {
  Coupon: 'SUMMER20',
  Revenue: 169.85
};

mparticle.eCommerce.logProductAction(
  mparticle.ProductActionType.Checkout,
  [product1, product2],
  {
      'currency': 'USD',
      'cartitemcount': '3',
      'totalprice': '169.85'
  },
  null,
  transactionAttributes
);
```

##### Commerce event: CheckoutOption (shipping)

Log when the customer completes the shipping step. Use the `mparticle.ProductActionType.CheckoutOption` action and pass `checkoutOption: 'shipping'` along with the shipping selections.

| Field            | Type    | Required | Description                                                                |
| ---------------- | ------- | -------- | -------------------------------------------------------------------------- |
| `cartitems`      | array   | yes      | Full cart contents, JSON-stringified before passing as a custom attribute. |
| `option`         | string  | yes      | Always `'shipping'` for this event.                                        |
| `shippingmethod` | string  | yes      | `standard` / `express` / `next_day`.                                       |
| `zipcode`        | string  | yes      | Shipping ZIP / postcode.                                                   |
| `country`        | string  | yes      | ISO 3166-1 alpha-2 country code.                                           |
| `totalprice`     | decimal | yes      | Cart total.                                                                |
| `currency`       | string  | yes      | ISO 4217 currency code.                                                    |

###### Example CheckoutOption (shipping) event

```javascript
var product1 = mparticle.eCommerce.createProduct('Trail Runner v3', 'SKU-001', 129.95, 1);
var product2 = mparticle.eCommerce.createProduct('Cushion Insole',  'SKU-002', 19.95,  2);

mparticle.eCommerce.logProductAction(
  mparticle.ProductActionType.CheckoutOption,
  [product1, product2],
  {
      'checkoutOption': 'shipping',
      'shippingmethod': 'express',
      'zipcode': '94103',
      'country': 'US',
      'totalprice': '169.85',
      'currency': 'USD'
  }
);
```

##### Commerce event: CheckoutOption (payment)

Log when the customer completes the payment step. Use the `mparticle.ProductActionType.CheckoutOption` action and pass `checkoutOption: 'payment'` along with the payment method selected.

| Field                    | Type    | Required | Description                                                                |
| ------------------------ | ------- | -------- | -------------------------------------------------------------------------- |
| `cartitems`              | array   | yes      | Full cart contents, JSON-stringified before passing as a custom attribute. |
| `option`                 | string  | yes      | Always `'payment'` for this event.                                         |
| `paymenttype`            | string  | yes      | `credit_card` / `paypal` / `apple_pay` / etc.                              |
| `payment_method`         | string  | no       | Specific method when relevant (e.g. card brand).                           |
| `paymentServiceProvider` | string  | no       | PSP identifier (e.g. `stripe`). Must be camelCase.                         |
| `ccbin`                  | string  | no       | First 6-8 digits of the card, if a card was used.                          |
| `totalprice`             | decimal | yes      | Cart total.                                                                |
| `currency`               | string  | yes      | ISO 4217 currency code.                                                    |

###### Example CheckoutOption (payment) event

```javascript
var product1 = mparticle.eCommerce.createProduct('Trail Runner v3', 'SKU-001', 129.95, 1);
var product2 = mparticle.eCommerce.createProduct('Cushion Insole',  'SKU-002', 19.95,  2);

mparticle.eCommerce.logProductAction(
  mparticle.ProductActionType.CheckoutOption,
  [product1, product2],
  {
      'checkoutOption': 'payment',
      'paymenttype': 'credit_card',
      'payment_method': 'visa',
      'paymentServiceProvider': 'stripe',
      'ccbin': '424242',
      'totalprice': '169.85',
      'currency': 'USD'
  }
);
```

##### Commerce event: Purchase

Log when an order is confirmed. Send the full set of cart products plus a `transactionAttributes` summary including order ID, revenue, tax, shipping, and any order-level coupon.

| Field           | Type    | Required | Description                                                                                 |
| --------------- | ------- | -------- | ------------------------------------------------------------------------------------------- |
| `cartitems`     | array   | yes      | Full cart contents at time of order, JSON-stringified before passing as a custom attribute. |
| `transactionId` | string  | yes      | Order / transaction identifier.                                                             |
| `totalprice`    | decimal | yes      | Order total (Revenue).                                                                      |
| `tax`           | decimal | yes      | Total tax on the order.                                                                     |
| `shipping`      | decimal | yes      | Shipping cost.                                                                              |
| `currency`      | string  | yes      | ISO 4217 currency code.                                                                     |
| `couponCode`    | string  | no       | Order-level promo, if applied.                                                              |
| `cartitemcount` | integer | no       | Number of cart lines.                                                                       |

###### Example Purchase event

```javascript
var product1 = mparticle.eCommerce.createProduct('Trail Runner v3', 'SKU-001', 129.95, 1);
var product2 = mparticle.eCommerce.createProduct('Cushion Insole',  'SKU-002', 19.95,  2);

var transactionAttributes = {
  Id: 'ORDER-10482',
  Revenue: 169.85,
  Tax: 14.20,
  Shipping: 5.99,
  Coupon: 'SUMMER20'
};

mparticle.eCommerce.logProductAction(
  mparticle.ProductActionType.Purchase,
  [product1, product2],
  { 'currency': 'USD', 'cartitemcount': '3' },
  null,
  transactionAttributes
);
```

##### Commerce event: Refund

Log when an order (or a line within it) is refunded. Send only the products being refunded, plus a `transactionAttributes` object referencing the original order.

| Field           | Type    | Required | Description                               |
| --------------- | ------- | -------- | ----------------------------------------- |
| `productsku`    | string  | yes      | SKU of the refunded line(s).              |
| `quantity`      | integer | yes      | Units refunded.                           |
| `transactionId` | string  | yes      | Original order ID being refunded against. |
| `totalprice`    | decimal | yes      | Refunded amount.                          |
| `currency`      | string  | yes      | ISO 4217 currency code.                   |

###### Example Refund event

```javascript
var refundedProduct = mparticle.eCommerce.createProduct('Trail Runner v3', 'SKU-001', 129.95, 1);

var transactionAttributes = {
  Id: 'ORDER-10482',
  Revenue: 129.95
};

mparticle.eCommerce.logProductAction(
  mparticle.ProductActionType.Refund,
  [refundedProduct],
  { 'currency': 'USD' },
  null,
  transactionAttributes
);
```

### Event category: Custom events

Track custom events using `mparticle.logEvent`, passing an event name, event type, and optional custom attributes.

#### Show custom event types

| Type                                 | Use for                                                       |
| ------------------------------------ | ------------------------------------------------------------- |
| `mparticle.EventType.Navigation`     | User navigation flows and screen transitions within your app. |
| `mparticle.EventType.Location`       | Location-based interactions and movements.                    |
| `mparticle.EventType.Search`         | Search queries and search-related actions.                    |
| `mparticle.EventType.Transaction`    | Financial transactions and purchase-related activity.         |
| `mparticle.EventType.UserContent`    | User-generated content like reviews, comments, or posts.      |
| `mparticle.EventType.UserPreference` | User settings, preferences, and customization choices.        |
| `mparticle.EventType.Social`         | Social media interactions and sharing activities.             |
| `mparticle.EventType.Other`          | Anything that doesn't fit the categories above.               |

#### Log a custom event

```javascript
mparticle.logEvent(
  'video_watched',
  mparticle.EventType.Navigation,
  { 'category': 'Destination Intro', 'title': 'Paris' }
);
```

## 6. Show a Placement

Call `mparticle.Rokt.selectPlacements` on every payment and confirmation screen you want Rokt to render content on. Include one of the following page identifiers to specify the screen type and whether it's for testing or production:

- `stg.rokt.conf`: A confirmation screen in a staging (or testing) environment.
- `prod.rokt.conf`: A confirmation screen in a production environment.
- `stg.rokt.payments`: A payments screen in a staging (or testing) environment.
- `prod.rokt.payments`: A payments screen in a production environment.

### Placement attributes

Pass these attributes in the `attributes` map of `selectPlacements`. Always supply the most recent value — attributes passed here override any earlier `setUserAttribute` calls.

### Show all placement attributes

| Field                    | Type    | Description                                                                                                                                                                                                                                                                                                                                                           |
| ------------------------ | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `email`                  | string  | Customer email (unhashed). Used for identity resolution.                                                                                                                                                                                                                                                                                                              |
| `firstname`              | string  | Customer first name. Used for personalization.                                                                                                                                                                                                                                                                                                                        |
| `lastname`               | string  | Customer last name. Used for personalization.                                                                                                                                                                                                                                                                                                                         |
| `mobile`                 | string  | Customer mobile number in E.164 format. Used for identity resolution.                                                                                                                                                                                                                                                                                                 |
| `confirmationref`        | string  | Order / confirmation reference number. Used for relevance and deduplication.                                                                                                                                                                                                                                                                                          |
| `currency`               | string  | Transaction currency (ISO 4217, e.g. `USD`, `GBP`, `AUD`). Used for relevance.                                                                                                                                                                                                                                                                                        |
| `country`                | string  | ISO 3166-1 alpha-2 country code. Used for eligibility and relevance.                                                                                                                                                                                                                                                                                                  |
| `language`               | string  | Customer's preferred language (ISO 639-1). Used for relevance.                                                                                                                                                                                                                                                                                                        |
| `totalprice`             | decimal | Total cart value including tax and shipping. Used for relevance.                                                                                                                                                                                                                                                                                                      |
| `amount`                 | string  | Cart subtotal before tax and shipping. Distinct from `totalprice`. Used for relevance.                                                                                                                                                                                                                                                                                |
| `couponCode`             | string  | Promo code applied to the order, if any. Used for relevance.                                                                                                                                                                                                                                                                                                          |
| `newcustomer`            | boolean | Whether this is a first-time buyer. Used for relevance.                                                                                                                                                                                                                                                                                                               |
| `customertype`           | string  | `guest` or `logged_in`. Used for relevance.                                                                                                                                                                                                                                                                                                                           |
| `value`                  | decimal | Customer's cumulative purchase value (e.g. `"2340.00"`). Used for relevance.                                                                                                                                                                                                                                                                                          |
| `subscriptionstatus`     | string  | Subscription state if applicable (`active`, `trial`, `churned`, `paused`, `none`). Used for relevance and eligibility.                                                                                                                                                                                                                                                |
| `customersegment`        | string  | Partner internal segmentation (e.g. `vip`, `at_risk`, `new`, `reactivated`). Used for relevance.                                                                                                                                                                                                                                                                      |
| `paymenttype`            | string  | Payment method selected (`credit_card`, `paypal`, `apple_pay`, etc.). Used for Pay+ eligibility.                                                                                                                                                                                                                                                                      |
| `paymentServiceProvider` | string  | Comma-separated list of payment methods accepted on the page (e.g. `applepay,paypal,cardpayment`). Values must be lowercase with no spaces. See [Payment Service Provider](https://docs.rokt.com/developer-reference/product-deep-dives/pay-plus/partners/data-integration#payment-service-provider) for the full list of accepted values. Used for Pay+ eligibility. |
| `ccbin`                  | string  | Credit card BIN (6-8 digits). Used for relevance.                                                                                                                                                                                                                                                                                                                     |
| `billingname`            | string  | Billing name. Used for identity resolution.                                                                                                                                                                                                                                                                                                                           |
| `billingaddress1`        | string  | Billing street address. Used for identity resolution and relevance.                                                                                                                                                                                                                                                                                                   |
| `billingaddress2`        | string  | Billing apartment / unit. Used for identity resolution.                                                                                                                                                                                                                                                                                                               |
| `billingcity`            | string  | Billing city. Used for relevance.                                                                                                                                                                                                                                                                                                                                     |
| `billingstate`           | string  | Billing state or province. Used for relevance.                                                                                                                                                                                                                                                                                                                        |
| `billingzipcode`         | string  | Billing ZIP / postcode. Used for identity resolution and relevance.                                                                                                                                                                                                                                                                                                   |
| `shippingmethod`         | string  | Shipping method selected (`standard`, `express`, `next_day`). Used for relevance.                                                                                                                                                                                                                                                                                     |
| `shippingname`           | string  | Shipping name. Used for relevance.                                                                                                                                                                                                                                                                                                                                    |
| `shippingaddress1`       | string  | Shipping street address. Used for relevance.                                                                                                                                                                                                                                                                                                                          |
| `shippingcity`           | string  | Shipping city. Used for relevance.                                                                                                                                                                                                                                                                                                                                    |
| `shippingstate`          | string  | Shipping state or province. Used for relevance.                                                                                                                                                                                                                                                                                                                       |
| `shippingzipcode`        | string  | Shipping ZIP or postcode. Used for relevance.                                                                                                                                                                                                                                                                                                                         |
| `shippingcountry`        | string  | Shipping country (ISO 3166-1 alpha-2). Used for relevance.                                                                                                                                                                                                                                                                                                            |
| `cartItems`              | string  | JSON-serialized array of cart items. Used for relevance.                                                                                                                                                                                                                                                                                                              |
| `adsexperience`          | string  | Pass `"shoppable"` when deliberately targeting a Shoppable Ads experience.                                                                                                                                                                                                                                                                                            |

### Placement position: Overlay

Overlay placements render on top of your confirmation screen in a Rokt-managed container, requiring no changes to your app's existing layout.

To insert an overlay placement, call `selectPlacements` once the confirmation screen loads:

#### Overlay placement

```javascript
var attributes = {
  // Identity
  'email': 'j.smith@example.com',
  'firstname': 'Jenny',
  'lastname': 'Smith',
  'mobile': '+13125551515',

  // Transaction
  'confirmationref': '54321',
  'currency': 'USD',
  'country': 'US',
  'language': 'en',
  'totalprice': '149.99',
  'couponCode': 'SUMMER20',

  // Customer context
  'newcustomer': 'false',
  'customertype': 'logged_in',
  'value': '2340.00',
  'subscriptionstatus': 'active',
  'customersegment': 'vip',

  // Payment (include paymenttype and paymentServiceProvider for Pay+)
  'paymenttype': 'credit_card',
  'paymentServiceProvider': 'cardpayment',
  'ccbin': '411112',

  // Billing address
  'billingaddress1': '123 Main St',
  'billingcity': 'Brooklyn',
  'billingstate': 'NY',
  'billingzipcode': '11201',

  // Shipping
  'shippingmethod': 'express',
  'shippingaddress1': '175 Varick St',
  'shippingcity': 'New York',
  'shippingstate': 'NY',
  'shippingzipcode': '10014',
  'shippingcountry': 'US'
};

var config = {
  colorMode: mparticle.Rokt.ColorMode.LIGHT
};

mparticle.Rokt.selectPlacements(
  'RoktExperience',
  attributes,
  config
);
```

### Placement position: Embedded

Embedded placements render inline at a fixed position in your app that you control (for example, above the payment options on a cart screen). Both Thanks and Pay+ use embedded placements, but Pay+ must use embedded placements.

To insert an embedded placement, pass the embedded view identifier in your `selectPlacements` call:

#### Embedded placement

```javascript
var attributes = {
  'email': 'j.smith@example.com',
  'firstname': 'Jenny',
  'lastname': 'Smith',
  'billingzipcode': '90210',
  'confirmationref': '54321'
};

var config = {
  colorMode: mparticle.Rokt.ColorMode.LIGHT
};

mparticle.Rokt.selectPlacements(
  'RoktExperience',
  attributes,
  config,
  'RoktEmbedded1'  // The embedded view identifier
);
```

> **Caution: Pay+**
>
> For Pay+ placements, include `paymenttype` and `paymentServiceProvider` in the `selectPlacements` call on each screen. `paymentServiceProvider` communicates what payment methods are available on the payment screen; `paymenttype` communicates what method the user paid with.

### Placement position: Interstitial (iOS only)

Interstitial placements are rendered between the payment and confirmation screens, allowing customers to purchase additional products. Interstitial placements are used by Shoppable Ads.

> **Note**
>
> Interstitial placements are supported on **iOS only** in the Cordova SDK+. The Android path of this plugin does not support interstitial placements. Do not invoke interstitial placement logic on Android.

> **Note: Apple Pay setup required**
>
> To enable Shoppable Ads with Apple Pay on iOS, your native iOS project must have `RoktPaymentExtension` registered in `AppDelegate` after `MParticle.start` and before `selectPlacements`. Follow the [Apple Pay iOS setup guide](https://docs.rokt.com/developer-reference/product-deep-dives/shoppable-ads/payment-methods/apple-pay#ios-setup) to create a merchant ID, configure your Xcode project, and register the payment extension.

On iOS, interstitial placements are triggered through the same `selectPlacements` call used for overlay and embedded placements. The iOS native layer handles the interstitial UI; your JavaScript code triggers it and listens for the resulting events.

To implement an interstitial placement on iOS, call `selectPlacements` from your confirmation screen logic. Pass the same comprehensive attributes you use for overlay placements:

#### Interstitial placement (iOS only)

```javascript
// Guard: only invoke on iOS
if (cordova.platformId === 'ios') {
  var attributes = {
      // Identity
      'email': 'j.smith@example.com',
      'firstname': 'Jenny',
      'lastname': 'Smith',
      'mobile': '+13125551515',

      // Transaction
      'confirmationref': '54321',
      'currency': 'USD',
      'country': 'US',
      'language': 'en',
      'totalprice': '149.99',
      'amount': '137.50',
      'couponCode': 'SUMMER20',

      // Customer context
      'newcustomer': 'false',
      'customertype': 'logged_in',
      'value': '2340.00',

      // Payment
      'paymenttype': 'credit_card',
      'paymentServiceProvider': 'cardpayment',
      'ccbin': '411112',

      // Billing address
      'billingaddress1': '123 Main St',
      'billingcity': 'Brooklyn',
      'billingstate': 'NY',
      'billingzipcode': '11201',

      // Shipping (required for Shoppable Ads fulfillment)
      'shippingaddress1': '175 Varick St',
      'shippingcity': 'New York',
      'shippingstate': 'NY',
      'shippingzipcode': '10014',
      'shippingcountry': 'US'
  };

  var config = {
      colorMode: mparticle.Rokt.ColorMode.LIGHT
  };

  mparticle.Rokt.selectPlacements(
      'RoktExperience',
      attributes,
      config
  );
}
```

> **Note**
>
> If your app does not have shipping address details (for example, for ticket or digital goods purchases), pass **billing address** details instead. Rokt will provide a UI for the customer to confirm or edit their shipping address before completing the purchase.

### Optional functions

| Function                 | Purpose                        |
| ------------------------ | ------------------------------ |
| `mparticle.Rokt.close()` | Auto-close overlay placements. |

### Additional configuration

Pass optional parameters such as a `config` object to customize the placement UI (e.g. dark/light mode, caching).

### selectPlacements with config

```javascript
var config = {
  colorMode: mparticle.Rokt.ColorMode.LIGHT,
  cacheConfig: {
      cacheDurationInSeconds: 1200,
      cacheAttributes: {
          'email': 'j.smith@example.com',
          'orderNumber': '123'
      }
  }
};

mparticle.Rokt.selectPlacements(
  'RoktExperience',
  attributes,
  config
);
```

> **Note**
>
> 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.

### Events API

The SDK+ provides placement lifecycle events you can subscribe to. Use the `onEvent` callback in your `selectPlacements` call to respond to load state, engagement, and failures.

### Subscribe to placement events

```javascript
mparticle.Rokt.selectPlacements(
  'RoktExperience',
  attributes,
  config,
  null,
  function(event) {
      // Handle placement events
      if (event && event.eventType) {
          console.log('Rokt event: ' + event.eventType);
      }
  }
);
```

#### Standard events

### Show all standard events

| Event                   | Description                                                                                                                                                                                                               | Params                                                                                                                                                                                  |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ShowLoadingIndicator    | Triggered before the SDK+ calls the Rokt backend.                                                                                                                                                                         |                                                                                                                                                                                         |
| HideLoadingIndicator    | Triggered when the SDK+ receives a success or failure from the Rokt backend.                                                                                                                                              |                                                                                                                                                                                         |
| PlacementInteractive    | Triggered when a placement has been rendered and is interactable.                                                                                                                                                         | placementId: String                                                                                                                                                                     |
| PlacementReady          | Triggered when a placement is ready to display but has not rendered content yet.                                                                                                                                          | placementId: String                                                                                                                                                                     |
| OfferEngagement         | Triggered when the user engages with the offer.                                                                                                                                                                           | placementId: String                                                                                                                                                                     |
| PositiveEngagement      | Triggered when the user positively engages with the offer.                                                                                                                                                                | placementId: String                                                                                                                                                                     |
| FirstPositiveEngagement | Triggered when the user positively engages with the offer for the first time.                                                                                                                                             | placementId: String, fulfillmentAttributes: Object                                                                                                                                      |
| OpenUrl                 | Triggered when the user presses a URL that is configured to be sent to the partner app.                                                                                                                                   | placementId: String, url: String                                                                                                                                                        |
| PlacementClosed         | Triggered when a placement is closed by the user.                                                                                                                                                                         | placementId: String                                                                                                                                                                     |
| PlacementCompleted      | Triggered 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                                                                                                                                                                     |
| PlacementFailure        | Triggered when a placement could not be displayed due to some failure or when no placements are available to show.                                                                                                        | placementId: String (optional)                                                                                                                                                          |
| CartItemInstantPurchase | Triggered when the catalog item purchase is initiated by the user (iOS only).                                                                                                                                             | placementId: String, cartItemId: String, catalogItemId: String, currency: String, description: String, linkedProductId: String, totalPrice: Number, quantity: Number, unitPrice: Number |

## 7. Appendix

### Appendix A: App configuration

Applications can pass configuration settings through the `config` object so the SDK+ uses your app's custom configuration instead of system defaults.

#### ColorMode object

| Value    | Description                               |
| -------- | ----------------------------------------- |
| `LIGHT`  | Application is in Light Mode              |
| `DARK`   | Application is in Dark Mode               |
| `SYSTEM` | Application defaults to System Color Mode |

```javascript title="selectPlacements with ColorMode"
var config = {
    colorMode: mparticle.Rokt.ColorMode.LIGHT
};

mparticle.Rokt.selectPlacements(
    'RoktExperience',
    attributes,
    config
);
```

#### CacheConfig object

| Parameter                | Description                                                                                                                                                              |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `cacheDurationInSeconds` | Optional duration in seconds for which the Rokt SDK+ should cache the experience. Maximum allowed value is 90 minutes; default is 90 minutes if not provided or invalid. |
| `cacheAttributes`        | Optional attributes to be used as cache key. If null, all attributes sent in `selectPlacements` will be used as the cache key.                                           |

```javascript title="Cache for 1200 seconds"
// Cache the experience for 1200 seconds, using email and orderNumber as the cache key.
var config = {
    cacheConfig: {
        cacheDurationInSeconds: 1200,
        cacheAttributes: {
            'email': 'j.smith@example.com',
            'orderNumber': '123'
        }
    }
};

mparticle.Rokt.selectPlacements(
    'RoktExperience',
    attributes,
    config
);
```

#### EdgeToEdgeDisplay (Android only)

Controls whether the Rokt overlay respects Android's edge-to-edge display mode. This configuration applies to the **Android** path only; iOS does not use this flag.

| Value            | Description                                            |
| ---------------- | ------------------------------------------------------ |
| `true` (default) | Application supports edge-to-edge display mode         |
| `false`          | Application does not support edge-to-edge display mode |

The Cordova SDK+ does not currently expose `EdgeToEdgeDisplay` as a JavaScript config option. If your Android app opts out of edge-to-edge display and the overlay renders incorrectly, configure it in your native Android code:

```kotlin title="EdgeToEdgeDisplay (native Android — RoktConfig)"
import com.mparticle.rokt.RoktConfig

val roktConfig = RoktConfig.Builder()
    .edgeToEdgeDisplay(false) // set to false if your app does not use edge-to-edge
    .build()
```

Pass `roktConfig` to `selectPlacements` in your native Android layer, or raise this with your Rokt account manager if you need Cordova-level support.

### Appendix B: Native UI components

The Cordova SDK+ uses native Rokt UI components rendered by the underlying iOS and Android SDK+s. There is no Cordova-specific declarative UI component (equivalent to Jetpack Compose or SwiftUI). The placement UI is managed entirely by the native layer and surfaced through the `selectPlacements` API.

### Appendix C: Error handling

The IDSync API is intended to be central to your app's state and is designed to be fast and highly-available. Similar to how your app may prevent users from logging in, logging out, or modifying their state without an internet connection — treat these APIs as gating operations to maintain a consistent user state. The SDK+ will not retry API calls automatically, but provides callback APIs so you can do so according to your business logic.

If you do not implement error handling, you may see data consistency issues at scale.

The Cordova SDK+'s `mparticle.Identity.identify()` callback pattern surfaces errors through the `onError` handler. Inspect the `errorResponse` object to determine the appropriate action:

```javascript title="IDSync error handling"
var identifyTask = {
    onSuccess: function(userID) {
        // IDSync succeeded — proceed with the identified user
        console.log('Identify success, userID: ' + userID);
    },
    onError: function(errorResponse) {
        if (errorResponse && errorResponse.httpCode !== undefined) {
            if (errorResponse.httpCode === -1) {
                // Device is likely offline (maps to UNKNOWN_ERROR on Android,
                // MPIdentityErrorResponseCodeClientNoConnection on iOS) — retry the request
            } else if (errorResponse.httpCode === 429) {
                // Throttled — retry with exponential backoff
            } else if (errorResponse.httpCode >= 500) {
                // Server-side error — contact your account representative
            } else {
                // Inspect errorResponse for implementation issues (e.g. 400 invalid request, 401 auth error)
                console.error('Identity error: ' + JSON.stringify(errorResponse));
            }
        }
    }
};

var identity = new mparticle.Identity();
identity.identify(identifyRequest, identifyTask.onSuccess);
```

#### iOS error codes

On iOS, the native SDK+ maps failures to `MPIdentityErrorResponseCode` values. The Cordova bridge surfaces these as the `httpCode` in the JavaScript error response. Key codes to handle:

| Code                                            | Meaning                                  | Action                                                      |
| ----------------------------------------------- | ---------------------------------------- | ----------------------------------------------------------- |
| `MPIdentityErrorResponseCodeClientNoConnection` | Device offline or no network             | Retry the request                                           |
| `MPIdentityErrorResponseCodeClientSideTimeout`  | TCP connection timed out                 | Retry the request                                           |
| `MPIdentityErrorResponseCodeRequestInProgress`  | Another IDSync request already in flight | Inspect implementation; retry if infrequent                 |
| `MPIdentityErrorResponseCodeRetry`              | SDK+-level retry signal                  | Retry the request                                           |
| `429` (HTTP)                                    | Rate-limited by Rokt servers             | Retry with exponential backoff                              |
| `400` (HTTP)                                    | Invalid request body                     | Inspect `errorResponse` — typically an implementation issue |
| `401` (HTTP)                                    | Authentication error                     | Verify your API key                                         |

#### Android error codes

On Android, the native SDK+ returns `IdentityApi.UNKNOWN_ERROR` for client-side failures (device offline, client-side timeout, invalid requests). A `429` response maps to `IdentityApi.THROTTLE_ERROR`. Both signal the appropriate retry strategy:

- **`UNKNOWN_ERROR`** (device offline or client-side issue): retry the request once connectivity is restored.
- **`THROTTLE_ERROR` / 429**: retry with exponential backoff. This can indicate a user "hotkey" or a higher-than-expected IDSync volume — inspect your implementation if it occurs frequently.

### Appendix D: Passing session ID from web to native

When a user journey spans both web and native platforms, you can maintain a consistent Rokt session by passing the session ID from the Web SDK+ to the Cordova SDK+. This is useful for hybrid flows where users complete an action in a WebView (such as a payment page) and return to the native app for confirmation.

#### Getting the session ID from Web SDK+

After calling `selectPlacements`, the session ID is available on the selection context:

```javascript title="Retrieve sessionId from the selection context"
const selection = await launcher.selectPlacements({
    identifier: "checkout",
    attributes: {
        email: "user@example.com",
        // ... other attributes
    }
});

const sessionId = await selection.context.sessionId;
```

> **Note**
>
> The **session ID** is a unique GUID assigned to the current user journey. It is useful for debugging and for correlating a user's activity across your web and native surfaces.

#### Passing to native app via deep link

Pass the session ID to your native app using a deep link:

```javascript title="Deep-link to native app"
const deepLink = `myapp://confirmation?sessionId=${encodeURIComponent(sessionId)}`;
window.location.href = deepLink;
```

#### Setting the session ID

Extract the session ID from the deep link and pass it to the SDK+ before calling `selectPlacements`.

```javascript title="Set sessionId in Cordova"
// Extract the sessionId from your deep link handler and set it before selectPlacements
var sessionId = getSessionIdFromDeepLink(); // Your deep link parsing logic

if (sessionId) {
    mparticle.Rokt.setSessionId(sessionId);
}

// Then proceed with selectPlacements
mparticle.Rokt.selectPlacements('RoktExperience', attributes, config);
```

#### Notes

- Call `setSessionId` before `selectPlacements` to ensure the session is used.
- Empty strings are ignored and will not update the session.
- Always URL-encode the session ID when passing as a query parameter.

## 8. Test Your Integration

To confirm the SDK+ initializes and events log correctly:

### 1. Enable verbose SDK+ logging

Enable verbose SDK+ logging before initialization so you can see what's being sent.

#### Target: iOS

```objectivec title="Enable verbose SDK+ logging (iOS)"
[MParticle sharedInstance].logLevel = MPILogLevelVerbose;
```

#### Target: Android

```java title="Enable verbose SDK+ logging (Android)"
MParticleOptions options = MParticleOptions.builder(this)
    .credentials("your-key", "your-secret")
    .environment(MParticle.Environment.Development)
    .logLevel(MParticle.LogLevel.VERBOSE)
    .build();
```

### 2. Build and run your app

Build and run your app against a development key with the environment set to Development on both platforms.

### 3. Trigger selectPlacements

Trigger `selectPlacements` on the screen where the placement should render and confirm the placement loads.

### 4. Verify events

Verify the events are logged and the `identifyRequest` call succeeds.

### Troubleshooting

If the placement doesn't render or events don't appear, check the native device logs (Xcode console for iOS, Android Logcat for Android) for Rokt SDK+ errors. Common issues:

#### Initialization errors

- Confirm the key and secret match the values from your Rokt account manager on both iOS (`your-key` / `your-secret` in `optionsWithKey:secret:`) and Android (`.credentials("your-key", "your-secret")`).
- Confirm `MParticle.start` (Android) and `[[MParticle sharedInstance] startWithOptions:options]` (iOS) run before any `selectPlacements` or `logEvent` call.

#### Identity errors

If the identify callback fires with an error, see [Error Handling](https://docs.rokt.com/integration-guides/ecommerce/sdk/cordova/#error-handling) for the error codes and retry guidance. Without error handling you may see data consistency issues at scale.

#### Placement not rendering

- Confirm the placement `identifier` (e.g. `RoktExperience`) matches what your Rokt account manager configured.
- For embedded placements, confirm the embedded view identifier (e.g. `RoktEmbedded1`) matches the layout configuration.
- Check that the attributes map contains at least `email`, `firstname`, `lastname`, `billingzipcode`, and `confirmationref`.