Getting Started with Innovid's Open Creative API

Last Updated: September 17, 2024 14:22

Description: Innovid's Open Creative API provides a solution for developers looking to hand-code their own HTML ads and upload them into Innovid's platform.

Standard Creatives

Standard Creatives Are Defined As:

Ads that don’t have any kind of interactivity.
Ads that have just one click-through.
Ads that don’t need any other reporting than just click-through tracking.
These can be both HTML ads or just JPGs.

Innovid API requirements for Standard Creatives

API is not needed at all on standard creatives
JPGs and HTML can be directly uploaded to CMT without having to add any extra Innovid related custom code.
Once the ad is uploaded in CMT, Innovid will automatically add a click area over the whole ad and the redirect URL will be handled from CMT.

Specs for Standard Creatives

If it is an old Sizmek unit, remove Sizmek’s API code as described here
For JPGs, 2x ad sizes can be uploaded to ensure the best quality on retina screens. E.g. you can upload a 600x500 ad size and select CMT 300x250 as the final ad size.
For HTML, a .zip file with the HTML, javascript, fonts, and assets is required for uploading to CMT.
Innovid follows all the IAB specs and best practices to serve display ads.

Interactive HTML Creatives

Interactive Creatives Are Defined As:

Ads that have more than one click-through
Ads that require user interaction e.g., to mute or unmute a video
Ads that need specific reporting parameters for interaction or engagement.
Only HTML ads are allowed in this case

Innovid API Requirements for Interactive Creatives

The API is needed in these kinds of creatives to enable interactions, meaning click-throughs and reporting events must be set up manually following the API documentation in the API usage section.
Click-through labels must be manually set up and communicated to the AM or TPM representative to set those in CMT and assign redirection URLs to them.

Specs for Interactive Creatives

If it is an old Sizmek unit, remove Sizmek’s API code as described here
A .zip file with the HTML, javascript, fonts, and assets is required for uploading to CMT
You can use 2x assets inside the HTML to get better quality on retina screens but the ad size can’t be 2x like it happens with jpegs mentioned above.
Any other spec or creative best practice is the same as Standard Creatives and follow the same IAB Specs

Creative API Usage

Load the innovid_display_connector.js at the <head> of your HTML file like so:

This script will expose a window-level object named “IVD” which holds all of the objects and functions of the API (listed below). Make sure you load it before any of your code executes.

Important Note: Please add the following size meta tag to your HTML page, in order for Innovid’s system to detect the ad’s size automatically:

For example, for a 300x250 pixel ad, add this tag:
<meta name="ad.size" content="width=300,height=250">

API Reference

Since IVD is window level - you can access it anywhere in your code.

Interactivity & Reporting Functions

These are the functions available within our API:

IVD.enableInteractions() -function

Call this function once at the beginning of the ad if the ad needs to be interactive.

IVD.enableInteractions();

Make sure to call it before any user interaction can occur.

Note: If you do not call this function, interactions for your ad will be blocked, and instead, the entire ad will clickthrough upon click/tap to a URL you or your Innovid Account Manager sets in Innovid’s CMT (Campaign Management Tool). You can have a different URL for each version, in the case of a DCO campaign.

IVD.clickthru(label, URL) -function

label:String, URL:String (optional)

Call this function when a user interacts to open a clickthrough (open a web page). Avoid using “main” as the label.

IVD.clickthru("More_Info");

You can enter a URL for the label, or have your Innovid Account Manager enter it, in the CMT per the label you declare in this function.. In this case you need to set the desired URL per the label “More_Info” in CMT

Note 1: The ad code must open URLs only with this function, and not native calls like window.open, otherwise it will not be reported.

IVD.engage(label, value) -function

label:String, value:String (optional)

Use this function to report user interactions that are not clickthrus, like browsing a gallery, hovering on hotspots, etc.

Use the optional value property for second-level reporting.

Example use: report user browsing to a specific image in a gallery -

IVD.engage("Gallery_Browse", "Product_3");

Note: Label reports appear automatically in Innovid’s analytics dashboard. Value reports are available upon request.

IVD.report(label, value) -function

label:String, value:String (optional)

Use this function to report events or data that are not a result of user interaction.

Use the optional value property for second-level reporting.

Example use: to report on a creative that shows one of 5 products randomly

IVD.report("Product_"+randomlySelectedNumber+"_Shown");

Note: Label reports appear automatically in Innovid’s analytics dashboard. Value reports are available upon request.

IVD.feed -object

This object will hold all the key/value pairs from the feed that is connected to this creative. Keys are used as-is, so if one of your keys has whitespace, access it like so: IVD.feed[“my key”].

Example use: dynamically inject the source of an image -

document.getElementById(“my_image”).src = IVD.feed[“product image URL”];

See the section “Size Specific Feed Data” below for more info on the IVD.feed object.

Note: There are three system-wide mandatory feed keys that are always present in any creative. These are Version ID, Version Name and Version Clickthrough URL. You should not try to access these keys in your creatives, but if you must, note that they appear in the IVD.feed object as versionId, versionName and clickthroughUrl. For example: to get the Version Name in the creative, use IVD.feed[“versionName”]

IVD.ctx -object

This object will hold all the key/value pairs of the personalized data of the ad viewer.

Available keys:

zip, country, city, DMA, state, stateCode, Celsius, Fahrenheit, humidity, uvIndex, precipitation

Note: Weather values will be available only when a weather strategy is set up for the campaign.

Example Usage: Dynamically inject the city name to a text field

document.getElementById(“message”).textContent = "Residents of "+IVD.ctx.city+", have a great day";

IVD.extra -object

This object will hold all the other key/value pairs that are passed into the ad on tag URL params (macros).

Example Usage: Display the user’s name passed in as macro from the publisher.

document.getElementById(“message”).textContent = "Hello "+IVD.extra.name+", have a great day";

Additional Information

1) Size-Specific Feed Data

In your average DCO campaign, you'll want to control several ad sizes from a single feed. In most cases, this means a single feed key (column) will be used to populate data for a single creative element across numerous ad sizes.

However, sometimes you will want to change the data for a single size only
For example, let's say your feed data has a key (column) named “headline_text” and says “Hello there friend, how are you?” which is your primary headline across all your ads. But the 160x600 is not wide enough to handle that much text and you want to shorten the “headline_text” to say just “Hello there friend” only for that size. How do you handle that?

Option 1: Set different keys for different sizes in advance in all your ads at the authoring stage, implementing different columns for each size in advance. This works but may be cumbersome.

Option 2: A more convenient and centralized way of working is to set up size-specific columns only when needed. The way to do that is to create new columns with the same key, followed by ___Width_Height (three underscores).

Continuing the example above: If your feed has a column headline_text, you can create a new column called headline_text___160_600, and fill in headline text in that column for that size only. Innovid’s Open Creative API will automatically override whatever text is in headline_text with the text coming from headline_text___160_600, only for that size. That way you can code all your ad sizes to expect the same feed keys, and control size-specific changes at the feed stage and not at the authoring stage. Note: You can control multiple sizes from a single column, e.g: headline_text___160_600___300_50
To use this feature you need to make sure that in the ad’s index.html file there is a meta tag in the head section during the initial ad authoring stage, holding the ad’s size like so: <meta name="ad.size" content="width=300,height=250"> (replace 300 and 250 with the actual sizes per each banner size).

2) Testing Feed Data Locally

If you want to test your DCO Feed implementation in your ad locally (prior to uploading to Innovid’s platform) you can do so by referencing a local file named ivd_mock_feed.js.

To do so:

Add another script tag before the Innovid Connector script tag like so:

<script type="text/javascript" src="ivd_mock_feed.js"></script>
<script type="text/javascript" src="https://s-files.innovid.com/creative/ct_dev/5/innovid_display_connector.js"></script>
In your project folder, next to the index.html file, create a file named ivd_mock_feed.js and have its content hold a single variable object named ivd_mock_feed like so:
var ivd_mock_feed = {
iv_some_text: "hello world",
iv_some_image: "assets/innovid.png"
};
Replace the example properties iv_some_text and iv_some_image with the key/value pairs you need in your project.
Note: since this mock object represents an Innovid feed, make sure that the values of the object are string types only (i.e not numbers, nested objects, or anything else).
Save your file and open index.html in your browser. Yout dynamic mock data should populate as expected.
Note: This mock feed will work only locally. Once you upload your project to the Innovid platform it will be ignored and only real feed data connected to the ad will populate into the ad’s dynamic elements.

Description: These instructions give step-by-step instructions on how to replace legacy Amazon (Sizmek) code with Innovid’s open creative API.

Removing Sizmek Code Creative

1. HTML FIles

Unlink the Sizmek API from your document by removing the following script tag from your index.html file

If your creative has a single click-through, you probably have a script tag that looks like this:

And another one that looks like this:

<a href="javascript:window.open(window.clickTag)">
some content here
</a>

Both of these should be removed.

2. JS Files

Within your JS files, you remove the API initialization function by deleting the following snippet.

adkit.onReady();

Within your JS files, you probably have some other calls to some of the Sizmek API methods; you will recognize those because of the prefix adkit or EB. Please make sure that all of them are removed. (Here you can check their methods API.)

Make sure that you remove any listeners to specific Sizmek API events. (Here you can check their events API.)

For creatives using the Sizmek video API, please make sure that you update the methods and events to match the HTML 5 API that you can find here.

Useful Links For Additional Reading

Was this article helpful?

0 out of 1 found this helpful