Creatable for Mobile Apps

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”