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:

 

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.

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.

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.

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.

Conversion (PC Event)

Parameters (all parameters must be URL encoded):

Usage: Fire this event to the Creatable api when a purchase has been completed.