Creatable Support

Guide for Developers

Analytics

Mobile app analytics and conversion tracking

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 4 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

Video view

When a video playback is requested by the user (either via autoplay or user interaction), we record this as a video view.

Trigger

When a video starts playback. This can be either through an autoplay mechanism or a user clicking/tapping on a play button.

Starting playback means that a request to play the video was made and the request starts at the beginning of the video.

Do not trigger a video view if the user pauses the video and clicks/taps play again.

Do trigger a video view if the user watches to the end of the video and the video repeats (“loops”) automatically or if the user clicks/taps on the play button and the video starts over from the beginning.

Implementation

Follow these steps to implement the video view 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 video view, this should always be “vv”	vv
vd	This is the asset ID of the video being played.	1234567890
es	Optional: If you are segmenting creatable analytics by experience, pass the experience tag text string	Creator Storefronts

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

&cid=1248452223d0351913551b6aa370b0d8

&rt=vv

&vd=1234567890

&es=Creator%20Storefronts

Example complete request:

Video view time

During video playback a view time event “heartbeat” is sent. This event enables tracking of how much video content is being consumed by the user.

Trigger

When a video starts playback, after 3 seconds, fire the first view time event. Fire the event every 3 seconds thereafter providing the video is still playing. If video playback is paused, then the view time events should also be paused.

Think of this as a heartbeat that fires every 3 seconds, only during playback.

Implementation

Follow these steps to implement the video view time 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 video view, this should always be “vv”	vv
vd	This is the asset ID of the video being played.	1234567890
vt	This is the length of the segment of time the video was viewed. This value can be calculated for precision, but should always correspond with the heartbeat interval of 3.	3
vct	This is the current point in time during the video’s playback the event is fired. The video player can provide this point in the video’s timeline	9
vdr	This is the duration or length of the video. If your video is 1 minute and 30 seconds long, this would be represented as 90.	90
es	Optional: If you are segmenting creatable analytics by experience, pass the experience tag text string	Creator Storefronts

During normal video playback, this event would be fired every 3 seconds, creating a series of requests that would look something like:

…vt=3&vct=3&vdr=90

…vt=3&vct=6&vdr=90

…vt=3&vct=9&vdr=90

…vt=3&vct=12&vdr=90

…vt=3&vct=15&vdr=90

…and so on.

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

&cid=1248452223d0351913551b6aa370b0d8

&rt=vt

&vd=1234567890

&vt=3

&vct=6

&vdr=90

&es=Creator%20Storefronts

Example complete request:

Photo view

When a photo is viewed by a user, we record this as a photo view. This event is nearly identical to a video view.

Trigger

When a “primary” photo is viewed by the user. The meaning of “primary” here means the subject of what is being displayed to the user. This event is not meant to be triggered if the user is viewing a thumbnail of a photo. If a user taps on a thumbnail of a photo and is presented with a larger version (in a popup modal or other presentation), that is when this event is triggered.

Implementation

Follow these steps to implement the photo view 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 photo view, this should always be “pv”	pv
vd	This is the asset ID of the photo being viewed.	1234567890
es	Optional: If you are segmenting creatable analytics by experience, pass the experience tag text string	Creator Storefronts

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

&cid=1248452223d0351913551b6aa370b0d8

&rt=pv

&vd=1234567890

&es=Creator%20Storefronts

Example complete request: