Implementing Creatable in a Mobile App
Adding Creatable to a mobile application is easy using our REST APIs. To implement Creatable, you first need data, then you can render the video/photo/product experiences however you would like, as further illustrated below.
Video & Photo Data
You can access video and photo data in 2 ways. The first way is via a Creatable “channel”. A “channel” is a configuration for dynamic content output and can be created on the Creatable dashboard under “Content > Channels”.
Example:
https://app.tvpage.com/api/channels/212444614/contents?X-login-id=1759320
The above url is an API call to a channel within a test account. It will return content from the account. You will want to change the X-login-id parameter and the Channel ID to retrieve content from your Creatable account.
To fetch a single asset, you can use this API call:
https://app.tvpage.com/api/videos/212483874?X-login-id=1759320
These data objects provide all the information you need to ingest content within a mobile app.
Product Data
Getting product information for a given video or photo asset is easy. This API call will enable you to display products alongside a video:
https://app.tvpage.com/api/videos/212483874/products?X-login-id=1759320
Identifying Mobile App Users
In the “Analytics” section of this article, you will note the need to create a unique identifier for a user. On the web, we use a hashed value stored in a cookie to track the user engagement and connect it with conversions.
For users who engage on the web, then click a product link and open up a mobile app, we have the ability to continue tracking that user, by accessing the “deeplink” functionality of the operating system. For example, in iOS, the NSUserActivity object contains a property called NSUserActivity.webpageURL. If you parse this URL, you will find a “cid” parameter. This is effectively the hashed value of the cookie that was set in the user’s browser.
Take this “cid” value and utilize it with all Analytics API calls. If you do not have this information available for a given user, then simply follow the steps outlined in the Analytics section to generate a unique identifier for the user’s mobile device. If you end up needing to generate a unique ID, then that ID should persist for the user indefinitely.
Analytics
Creatable Analytics is powered by 2 types of analytics calls. The first type is engagement, which directly relates to users interacting with content. The following list are engagement events:
- Video View (VV event)
- Photo View (PV event)
- Product Click (PK event, associated with a video or photo)
- View Time (VT event, amount of video that has been watched, in 3 second increments)
Note: View Time is an event that powers view-through metrics on the Creatable analytics dashboard, it is not considered an engagement event for purposes of attribution, but is a required metric to send to Creatable.
The second type of analytics call is a conversion event. There is only one event type to record a conversion (PC event). A conversion event contains a different set of information to send to the Creatable analytics system, which includes the Transaction ID (a unique identifier for an order) and an array of data that represents the items that were purchased by the user.
Event Examples
Firing events to the Creatable analytics system involved sending an HTTPS GET request to our system for a 1x1 pixel GIF image:
Production URL:
https://api.tvpage.com/api/__tvpa.gif
Testing URL:
https://stage.tvpage.com/api/__tvpa.gif
Each event type has a specific set of parameters that needs to be included in each request. Failure to provide these parameters will result in rejected analytics calls, with the following HTTP responses:
200 |
Valid request |
201 |
Invalid event type |
205 |
Invalid request |
Be sure to inspect the network traffic for these event calls to validate the HTTP response codes.
Video View (VV Event)
Parameters (all parameters must be URL encoded):
Usage: Fire this event to the Creatable api when a video has been viewed, for at least 3 seconds. An easy way to implement this is when a video is viewed, start a timer, after 3 seconds, fire this event.
Parameter |
Definition |
Example |
li |
Creatable Login ID |
1759320 |
nt |
Cache busting parameter |
microtime() |
hn |
Hostname (for web) or Application Name (for mobile app) |
www.domain.com or My Mobile App |
rf |
Event Referring URL/URN (for web) or Mobile app referring navigation identifier |
www.domain.com/product1 or product1 detail screen |
url |
URL/URN for the source of the event |
www.domain.com/product1/video or product1 video playback screen |
ul |
ISO formatted Browser or Device Language |
en-US |
tv |
Tracking library version (Use the example value provided) |
0.2.23 |
dt |
Title of page URL/URN |
Product1 Detail Page |
cid |
Unique identifier for Device: - |
9721660fd0a24b90b3974ecb4ab3aee6-1759320 |
rt |
Request Type (must be all lowercase) |
vv |
vd |
Asset ID of the asset being viewed (number) |
1234567890 |
Photo View (PV Event)
Parameters (all parameters must be URL encoded):
Usage: Fire this event to the Creatable api when a photo has been viewed, for at least 3 seconds. An easy way to implement this is when a photo is viewed, start a timer, after 3 seconds, fire this event.
Parameter |
Definition |
Example |
li |
Creatable Login ID |
1759320 |
nt |
Cache busting parameter |
microtime() |
hn |
Hostname (for web) or Application Name (for mobile app) |
www.domain.com or My Mobile App |
rf |
Event Referring URL/URN (for web) or Mobile app referring navigation identifier |
www.domain.com/product1 or product1 detail screen |
url |
URL/URN for the source of the event |
www.domain.com/product1/video or product1 video playback screen |
ul |
ISO formatted Browser or Device Language |
en-US |
tv |
Tracking library version (Use the example value provided) |
0.2.23 |
dt |
Title of page URL/URN |
Product1 Detail Page |
cid |
Unique identifier for Device: - |
9721660fd0a24b90b3974ecb4ab3aee6-1759320 |
rt |
Request Type (must be all lowercase) |
pv |
vd |
Asset ID of the asset being viewed (number) |
1234567890 |
Product Click (PK Event)
Parameters (all parameters must be URL encoded):
Usage: Fire this event to the Creatable api when a product associated to a video or photo is clicked/tapped.
Parameter |
Definition |
Example |
li |
Creatable Login ID |
1759320 |
nt |
Cache busting parameter |
microtime() |
hn |
Hostname (for web) or Application Name (for mobile app) |
www.domain.com or My Mobile App |
rf |
Event Referring URL/URN (for web) or Mobile app referring navigation identifier |
www.domain.com/product1 or product1 detail screen |
url |
URL/URN for the source of the event |
www.domain.com/product1/video or product1 video playback screen |
ul |
ISO formatted Browser or Device Language |
en-US |
tv |
Tracking library version (Use the example value provided) |
0.2.23 |
dt |
Title of page URL/URN |
Product1 Detail Page |
cid |
Unique identifier for Device: - |
9721660fd0a24b90b3974ecb4ab3aee6-1759320 |
rt |
Request Type (must be all lowercase) |
pk |
vd |
Asset ID of the asset associated with the product (number) |
1234567890 |
ct |
Asset ID of the product being clicked |
9876543210 |
View Time (VT Event)
Note: This event only applies during video playback
Parameters (all parameters must be URL encoded):
Usage: Fire this event to the Creatable api during playback of a video to record incremental amounts of watched video.
Parameter |
Definition |
Example |
li |
Creatable Login ID |
1759320 |
nt |
Cache busting parameter |
microtime() |
hn |
Hostname (for web) or Application Name (for mobile app) |
www.domain.com or My Mobile App |
rf |
Event Referring URL/URN (for web) or Mobile app referring navigation identifier |
www.domain.com/product1 or product1 detail screen |
url |
URL/URN for the source of the event |
www.domain.com/product1/video or product1 video playback screen |
ul |
ISO formatted Browser or Device Language |
en-US |
tv |
Tracking library version (Use the example value provided) |
0.2.23 |
dt |
Title of page URL/URN |
Product1 Detail Page |
cid |
Unique identifier for Device: - |
9721660fd0a24b90b3974ecb4ab3aee6-1759320 |
rt |
Request Type (must be all lowercase) |
vt |
vd |
Asset ID of the video asset being viewed (number) |
1234567890 |
vtype |
Type of video being viewed |
mp4, youtube |
vt |
Amount of seconds of video watched |
3 (event should be fired every 3 seconds of playback) |
vvs |
UUID for viewing event |
15652845992081d412638-4402-0c62-fc2e-62a8a5309416 (dynamically pass a new UUID for each VT event) |
vct |
Current time position of playback |
6 (this should be the current position of the video playback, in this example, the video seekbar would be at the 6 second mark) |
vdr |
Video duration |
10 (this is the total duration of the video) |
Conversion (PC Event)
Parameters (all parameters must be URL encoded):
Usage: Fire this event to the Creatable api when a purchase has been completed.
Parameter |
Definition |
Example |
li |
Creatable Login ID |
1759320 |
nt |
Cache busting parameter |
microtime() |
hn |
Hostname (for web) or Application Name (for mobile app) |
www.domain.com or My Mobile App |
rf |
Event Referring URL/URN (for web) or Mobile app referring navigation identifier |
www.domain.com/checkout/step2 or step 2 checkout screen |
url |
URL/URN for the source of the event |
www.domain.com/checkout/thankyou or purchase confirmation screen |
ul |
ISO formatted Browser or Device Language |
en-US |
tv |
Tracking library version (Use the example value provided) |
0.2.23 |
dt |
Title of page URL/URN |
Order Confirmation |
cid |
Unique identifier for Device: - |
9721660fd0a24b90b3974ecb4ab3aee6-1759320 |
rt |
Request Type (must be all lowercase) |
pc |
tid |
Transaction ID |
(1111111111) The specific order confirmation number given to the User’s order |
map |
The purchase data format mapping |
sku,price,quantity (must use this value) |
pr |
Array of strings representing the items purchased |
“sku1,price1,qty1”,”sku2,price2,qty2”,”sku3,price3,qty3” |