Kotlin Behavior Events

The MovableInk SDK allows you to send specific behavior events that can be later used in your Campaigns.

Setup

Within the application's local.properties, the provided API Key should be specified as follows:

MOVABLE_INK_SDK_API_KEY = "XXX"

Also, in the application manifest file the following meta-data tag should be specified within the application tag:

<meta-data
  android:name="com.movableink.inked.API_KEY"
  android:value="${MOVABLE_INK_SDK_API_KEY}"
/>

Lastly, in the Application level gradle file, under the defaultConfig section:

defaultConfig {

    manifestPlaceholders["MOVABLE_INK_SDK_API_KEY"] = localProperties['MOVABLE_INK_SDK_API_KEY']

}

Configuring The SDK Region:

To ensure compliance with regional requirements , we now require you to specify your region(importantly for EU clients). This is necessary to properly route your data and comply with local regulations.

In your project’s build.gradle (or build.gradle.kts) file, define a gradle property to your project’s defaultConfig block to specify the region:

defaultConfig {
        // Existing configurations...

        // Set your region (default is US, set EU for European clients)
        buildConfigField("String", "MOVABLE_INK_SDK_REGION", "EU")

}

If you don't supply a region, the SDK will default to the US region. If you are unsure which region your company was setup in on the MovableInk Platform, please reach out to your CX team at MovableInk.

After making changes to the gradle file, perform a gradle sync.

Setting MIU (mi_u)

An MIU is an identifier used by your companies marketing team and email/mobile messaging provider, that when shared with MovableInk, allows to uniquely identify each of your customers when they interact with campaigns or any other MovableInk content.

Most distribution partners provide a unique user identifier as an available merge tag that distinctly identifies every recipient on your list(s). Using this merge tag allows MovableInk to provide users with a consistent experience when opening the same email multiple times and across multiple devices. Providing an MIU is required for accurate behavior and conversion tracking.

You'll need to work with your distribution partners to identify a unique user identifier. It must meet the following criteria:

Unique per recipient
Does not vary between individual sends for that channel
A URL-friendly string What does URL friendly mean?
Does not contain personally identifying information (PII) What qualifies as PII?

You should make the following call as soon as the user is identified (usually after logging in) to set the MIU. Double check with your marketing team that the MIU you're using matches the values they are using. It's imperative that they match for accurate behavior event tracking.

MIClient.setMIU(USERS_MIU)

Inherited MIUs

If a user interacts with a MovableInk Link that contains an MIU and deeplinks into your app, the SDK will use that MIU value automatically for all subsequent behavior events if you don't manually set an MIU.

If you manually set an MIU, events will use that instead.

Suggested MIU naming convention

We strongly recommend you use a UUID for MIUs.

If you find your ids include names, email addresses, timestamps, or are easily incremental (1, 2, 3), we suggest using a new naming method that is more secure so that your MIUs are not as easy to guess or impersonate.

Recommended	NOT Recommended
42772706-c225-43ad-837e-c01e94907c3c	user@example.com
d68d3dbe-86e1-43ce-bf5f-2dafd2f6af45	123456789
6ec4f1dd-0998-4ca8-8793-7511c2625a45	john-smith-123

Predefined Events

Starting from version 1.6.0 of our SDK, we are introducing a change to how you make calls to the predifined events. Previously, these methods accepted a Map<String, Any?> as a parameter. However, to improve type safety and developer experience, we are now requiring the use of specific data types. We will maintain support for the previous Map interface.

Category Viewed

Key	Type	Description	Max
id	String, required	The ID of a category	256
title	String	The title of the category	512
url	String	The URL of the category	512

When a user views a category, you can use the Category Viewed Event.

ID must not be an empty string. Sending a proper ID is extremely important as it acts as the primary key which powers multiple use cases. This event will fail if you do not provide an ID.

Before 1.6.0After 1.6.0

MIClient.categoryViewed(properties) takes a Map type as an argument to describe the category.

MIClient.categoryViewed(
  mapOf(
    "id" to "sci-fi",
    "title" to "Sci-Fi",
    "url" to productUrl.toString()
  )
 )

 MIClient.categoryViewed(
  Category(
    id = "books",
    title = "Harry potter",
    url = productUrl.toString()
  )
)

Product Searched

Key	Type	Description	Max
query	String, required	The query the user used for a given search	256
url	String	A URL for the given query	512

When a user searches for a product, you can use the Product Searched Event.

Before 1.6.0After 1.6.0

MIClient.productSearched(properties) takes a Map type as an argument to describe the query of the search.

MIClient.productSearched(
  mapOf(
    "query" to "Hyperion",
    "url" to searchResultsUrl.toString()
  )
)

MIClient.productSearched(
  ProductSearched(
    url = searchResultsUrl.toString(),
    query = "Hyperion"
  )
)

Product Viewed

Key	Type	Description	Max
id	String, required	The ID of a product	256
title	String	The title of the product	512
price	String	The price of the product in Dollars and Cents. Do not include currency or any other non-decimal digit characters.
url	String	The URL of the product	512
categories	List	A list of categories associated with the product. A category must contain an id (String) and optionally a url (String) and/or title (String)	10 Items
meta	Map	An open Map of any extra data you'd like to associate to this event. The value must be either a String, Boolean, or Numeric. Meta does not accept nested objects or arrays.	20 Items

When a user views a product in your app, you can use the Product Viewed Event.

ID must not be an empty string. Sending a proper ID is extremely important as it acts as the primary key which powers multiple use cases. This event will fail if you do not provide an ID.

Before 1.6.0 After 1.6.0

MIClient.productViewed(properties) takes a Map type as an argument to describe the product.

MIClient.productViewed(
  mapOf(
    "id" to "1",
    "title" to "Hyperion",
    "price" to "15.99",
    "url" to "https://inkrediblebooks.com/hyperion-dan-simmons",
    "categories" to
      listOf(
        mapOf(
          "id" to "scifi",
          "title" to "Sci-Fi",
          "url" to "https://inkrediblebooks.com/categories/scifi",
        ),
        mapOf(
          "id" to "fiction",
          "title" to "Fiction",
          "url" to "https://inkrediblebooks.com/categories/fiction",
        ),
      ),
    "meta" to mapOf("pages" to 496),
  ),
)

MIClient.productViewed(
  ProductProperties(
    id = "1",
    title = "Hyperion", 
    price = "15.99",
    url = "https://inkrediblebooks.com/hyperion-dan-simmons",
    categories = listOf(
      Category(
        title = "scifi",
        id = "1",
        url = "https://inkrediblebooks.com/categories/scifi"
      ),
      Category(
        title = "fiction",
        id = "1",
        url = "https://inkrediblebooks.com/categories/fiction"
      ),
    ),
    meta = mapOf("pages" to 496)
  )
)

Product Added

Key	Type	Description	Max
id	String, required	The ID of a product	256
title	String	The title of the product	512
price	String	The price of the product in Dollars and Cents. Do not include currency or any other non-decimal digit characters.
url	String	The URL of the product	512
categories	List	A list of categories associated with the product. A category must contain an id (String) and optionally a url (String) and/or title (String)	10 Items
meta	Map	An open Map of any extra data you'd like to associate to this event. The value must be either a String, Boolean, or Numeric. Meta does not accept nested objects or arrays.	20 Items

When a user adds a product to the cart in your app, you can use the Product Added Event.

IDs must not be an empty string. Sending a proper ID is extremely important as it acts as the primary key which powers multiple use cases. This event will fail if you do not provide an ID.

Before 1.6.0 After 1.6.0

MIClient.productAdded(properties) takes a Map type as an argument to describe the product.

MIClient.productAdded(
  mapOf(
    "id" to "1",
    "title" to "Hyperion",
    "price" to "15.99",
    "url" to "https://inkrediblebooks.com/hyperion-dan-simmons",
    "categories" to
      listOf(
        mapOf(
          "id" to "scifi",
          "title" to "Sci-Fi",
          "url" to "https://inkrediblebooks.com/categories/scifi",
        ),
        mapOf(
          "id" to "fiction",
          "title" to "Fiction",
          "url" to "https://inkrediblebooks.com/categories/fiction",
        ),
      ),
    "meta" to mapOf("pages" to 496),
  ),
)

MIClient.productAdded(
  ProductProperties(
    id = "1",
    title = "Hyperion",
    price = "15.99",
    url = "https://inkrediblebooks.com/hyperion-dan-simmons",
    categories = listOf(
      Category(
        title = "scifi",
        id = "1",
        url = "https://inkrediblebooks.com/categories/scifi"
      ),
      Category(
        title = "fiction",
        id = "1",
        url = "https://inkrediblebooks.com/categories/fiction"
      ),
    ),
    meta = mapOf("pages" to 496)
  )
)

Product Removed

Key	Type	Description	Max
id	String, required	The ID of a product	256
title	String	The title of the product	512
price	String	The price of the product in Dollars and Cents. Do not include currency or any other non-decimal digit characters.
url	String	The URL of the product	512
categories	List	A list of categories associated with the product. A category must contain an id (String) and optionally a url (String) and/or title (String)	10 Items
meta	Map	An open Map of any extra data you'd like to associate to this event. The value must be either a String, Boolean, or Numeric. Meta does not accept nested objects or arrays.	20 Items

When a user removes a product from the cart in your app, you can use the Product Removed Event.

ID must not be an empty string. Sending a proper ID is extremely important as it acts as the primary key which powers multiple use cases. This event will fail if you do not provide an ID.

Before 1.6.0 After 1.6.0

MIClient.productRemoved(properties) takes a Map type as an argument to describe the product.

MIClient.productRemoved(
  mapOf (
    "id" to "56544",
    "title" to "All-Purpose Cleaning Wipes",
    "price" to "1.99",
    "url" to "https://www.example.com/variants_id/5f08cb918dcc595aa74b0fbc",
    "categories" to listOf(
        mapOf(
          "id" to "bathroom",
          "title" to "Bathroom",
          "url" to "https://example.com/cat/bathroom"
        )
    ),
    "meta" to mapOf(
      "color" to "green"
    )
  )
)

MIClient.productRemoved(
  ProductProperties(
    id = "56544",
    title = "All-Purpose Cleaning Wipes",
    price = "1.99",
    url= "https://www.example.com/variants_id/5f08cb918dcc595aa74b0fbc",
    categories = listOf(
        Category(
          id = "bathroom",
          title = "Bathroom",
          url = "https://example.com/cat/bathroom"
        ),
        Category(
          title = "fiction",
          id = "1",
          url = "https://inkrediblebooks.com/categories/fiction"
        ),
    ),
    meta = mapOf("color" to "green")
  )
)

Order Completed

Key	Type	Description	Max
id	String	The ID of a order	256
revenue	String	The total of the order in Dollars and Cents. Do not include currency or any other non-decimal digit characters.
products	List	A list of the products in an order. A Product must contain an id (String), and optionally a price (String), quantity (Number), title (String), and/or url (String).	100 Items

When a user checks out and completes an order, you can use the Order Completed Event.

IDs must not be an empty string. Sending a proper ID is extremely important as it acts as the primary key which powers multiple use cases. This event will fail if you do not provide an ID.

Before 1.6.0 After 1.6.0

MIClient.orderCompleted(
  mapOf(
    "id" to "1",
    "revenue" to "15.99",
    "products" to
      listOf(
          mapOf(
            "id" to "1",
            "price" to "15.99",
            "title" to "Hyperion",
            "url" to "https://inkrediblebooks.com/hyperion-dan-simmons",
            "quantity" to 1
        )
      )
  )
)

MIClient.orderCompleted(
  OrderCompletedProperties(
    id = "1",
    revenue = "23.00",
    orderProducts = listOf(
      OrderProduct(
        id = "1",
        title ="Hyperion",
        url = "https://inkrediblebooks.com/hyperion-dan-simmons",
        price = "14.7",
        quantity = 1
      )
    )
  )
)

Custom Events

In addition to the pre-defined events we provide, you can log custom events tailored to your business specific requirements. This flexibility enables you to monitor and understand user interactions beyond what our pre-defined events offer.

This type of event has a custom name, such as video_started, and optional parameters as the payload.

The name and properties of a custom event must first be defined on your companies account. Please reach out to your CX Team at MovableInk to get started with this.

val properties = mapOf(
  "title" to "Cat Bloopers 1000",
  "tags" to listOf("comedy", "cats"),
  "total" to 14,
  "daily_watched" to listOf(1, 0, 3, 2, 1, 6)
)

MIClient.logEvent("video_started", properties)

Note

Note that the value of price in any predefined event is in dollars and cents such as "15.99".

Testing Behavior Events

When you're ready to test an event, you need to set the MIU to a known value. You should let your CX Team know that you're ready to start testing events and give them the MIU that you are going to use before you do so. This will allow them to verify that the events are being sent correctly.

We usually use an empty UUID for testing, such as 00000000-0000-0000-0000-000000000000.

When you send an event, you should see the event logged in the console. If the event was structured correctly, you should see a success message in the console alongside the event name.