.png?height=120&name=Creatable_logo_white%20(1).png){kind=logo}
This document describes the required structure for sending/receiving analytics data events in the context of a mobile application and switching between internal webviews.
Implementing Creatable analytics requires 2 primary functions:
- State management - the process of initializing the analytics system and maintaining a user identifier.
- Event management - the process of triggering events that sends specific data to Creatable.
Each of the events in the Event management section can use either a “Staging” URL or “Production” URL. This allows testing to be performed without affecting production data. All examples below utilize the “Staging” URL.
Staging Base URL: https://stage.tvpage.com/api/__tvpa.gif
Production Base URL: https://api.tvpage.com/api/__tvpa.gif
State management
State management for Creatable analytics is easy to get up and running. It involves generating a Unique User ID, storing that ID and passing the ID between mobile app context and “web view” context as needed. The ID is used in the Event management section of this document and is referenced as “cid”. When a user opens the mobile app for the first time, they are assigned a Unique User ID.
Getting a Unique User ID
Perform a GET request to the following URL to generate a “cid” for the current User:
https://stage.tvpage.com/api/__tvpa.gif?rt=cid
This request returns a JSON object that contains the “cid”:
{
"cid": "1248452223d0351913551b6aa370b0d8"
}
Maintaining the Unique User ID
Once you have this ID, you simply need to store and maintain it within the mobile app context. This could also be stored in a centralized remote location and utilized if the user has multiple instances of the mobile app installed across their devices, but generally speaking, 1 unique user id per device is acceptable.
Transitioning between mobile app context and web view context
In order to carry this “cid” value forward into a web view that contains a Creatable experience, you must pass the “cid” via the URL. Do this by appending “_cid=” to the URL of the Creatable experience. This enables Creatable to fire additional user engagement events that will register the same Unique User ID in the analytics.
Event management
There are 2 primary events that apply to tracking Creatable user activity in the context of a mobile app.
Product link clicks
Inbound deep link URLs that contain the “_dl” parameter trigger the product link click event. This event signals to Creatable that a product link is being accessed and should be tracked for attribution purposes. This link could originate from the web, communication apps or other apps that allow creators to interact with customers.
Trigger:
The “_dl” parameter is found in the inbound URL. Scan the inbound link for the “_dl” parameter. If the parameter is found, construct and perform a GET request to Creatable analytics.
Implementation:
Follow these steps to implement the product link click event.
First we acquire the value of the “_dl” parameter from the URL. The format of this value is:
_dl={{user_id}};{{asset_id}}
In the case of the example below:
_dl=266882;239166328
Note the use of a semi-colon “;” as a separator.
Create the request by assembling the following URL parameters (note: these parameters must be url encoded).
|
Parameter |
Description |
Example |
|
li |
Your Creatable account ID |
1759724 |
|
hn |
A hostname of the source of the event |
yourstoredemo.com |
|
rf |
A referring URL to the screen the event was executed on |
A URL as a string |
|
url |
The URL the event was executed on |
A URL as a string |
|
cid |
Unique User ID, generated from state management. |
1248452223d0351913551b6aa370b0d8 |
|
rt |
This is the analytics event request type. For product purchase, this should always be “pc” |
pc |
|
ui |
The Creatable ID of the user from the “_dl” parameter |
266882 |
|
ct |
The Creatable ID of the product from the "_dl" parameter |
239166328 |
Note: When passing complete URLs as parameters, those URLs themselves must be URL encoded, as you can see below.
Examples by URL parameter:
?li=1759724
&hn=yourstoredemo.com
&rf=https%3A%2F%2Fyourstoredemo.com%2F
&url=https%3A%2F%2Fwww.yourstoredemo.com%2Fp%2Fforever-skin-contour-stick-pimprod2047285%3Fsku%3D2629065%26global_YS%3Dsi%26sharedID%3D266882%26Tier%3DBronze%26st_num%3D%26name%3DMartha%2BHernandez%26_dl%3D266882%253B239166328
&cid=1248452223d0351913551b6aa370b0d8
&rt=dl
&ui=266882
&ct=239166328
Example complete request:
https://stage.tvpage.com/api/__tvpa.gif?li=1759724&hn=yourstoredemo.com&rf=https%3A%2F%2Fyourstoredemo.com%2F&url=https%3A%2F%2Fwww.yourstoredemo.com%2Fp%2Fforever-skin-contour-stick-pimprod2047285%3Fsku%3D2629065%26global_YS%3Dsi%26sharedID%3D266882%26Tier%3DBronze%26st_num%3D%26name%3DMartha%2BHernandez%26_dl%3D266882%253B239166328&cid=1248452223d0351913551b6aa370b0d8&rt=dl&ui=266882&ct=239166328
Product purchase
When a product purchase is completed, we record the contents of that purchase (the items from the cart), and relate that back to the unique user identifier (user id). This allows us to connect user actions with purchases for reporting.
Trigger:
When a user completes a purchase, construct and perform a GET request to Creatable analytics.
Implementation:
Follow these steps to implement the purchase event.
Create the request by assembling the following URL parameters (note: these parameters must be url encoded).
|
Parameter |
Description |
Example |
|
li |
Your Creatable account ID |
1759724 |
|
hn |
A hostname of the source of the event |
yourstoredemo.com |
|
rf |
A referring URL to the screen the event was executed on |
A URL as a string |
|
url |
The URL the event was executed on |
A URL as a string |
|
cid |
Unique User ID, generated from state management. |
1248452223d0351913551b6aa370b0d8 |
|
rt |
This is the analytics event request type. For product purchase, this should always be “pc” |
pc |
|
tid |
The transaction ID from the customer purchase |
“6240307347778” or “M123456789” |
|
map |
The data mapping of the request. This value is always the same. |
sku,price,quantity |
|
pr[] |
An array of strings that represents the items from a customer purchase. The format is sku/product ID, price, quantity. |
8203053465922,15.99,1 |
Here’s an example of a JSON array of strings that is converted into a URL friendly set of parameters. This example illustrates 3 products that were purchased.
[
{ “sku,quantity,price” },
{ “sku,quantity,price” },
{ “sku,quantity,price” }
]
When converted into URL friendly parameters, it looks like this:
pr[]=sku,quantity,price&pr[]=sku,quantity,price&pr=sku,quantity,price
Then like all other parameters, the values are URL encoded:
pr[]=sku%2Cquantity%2Cprice&pr[]=sku%2Cquantity%2Cprice&pr=sku%2Cquantity%2Cprice
Append this to the final URL before making the request. This tells our analytics what items were purchased, the unit price of each item and the quantity.
Examples, by URL parameter:
?li=1759724
&hn=yourstoredemo.com
&rf=https%3A%2F%2Fyourstoredemo.com%2F
&url=https%3A%2F%2Fyourstoredemo.com%2Fcheckouts%2Fcn%2F78e7f9b18e13db5cb022705b638825da%2Fthank_you
&cid=1248452223d0351913551b6aa370b0d8
&rt=pc
&tid=6240307347778
&map=sku%2Cprice%2Cquantity
&pr[]=8203053465922%2C15.99%2C1
&pr[]=8203049533762%2C22.49%2C2
&pr[]=5337628203049%2C9.99%2C3
Example complete request:
https://stage.tvpage.com/api/__tvpa.gif
?li=1759724&hn=mystoredemo.com&rf=https%3A%2F%2Fyourstoredemo.com%2F&url=https%3A%2F%2Fyourstoredemo.com%2Fcheckouts%2Fcn%2F78e7f9b18e13db5cb022705b638825da%2Fthank_you&cid=1248452223d0351913551b6aa370b0d8&rt=pc&map=sku%2Cprice%2Cquantity&pr[]=8203053465922%2C15.99%2C1&pr[]=5337628203049%2C9.99%2C3&tid=6240307347779