General
- A custom code HTML template consists of a zip file containing a folder per ad size and a manifest.json (optional) file at the root. Within each folder, it includes an index.html file and related assets where the index.html is the "starting point" for the ad.
- The ad file is zipped and uploaded into a Creative Template. The creative content within the index.html should fill the entire width and height of the ad.
- The creative template encapsulates several dynamic parameters (for example, background image, color, text, etc.). These dynamic parameters are shared across all ad formats (ad-size dimensions) within the template. Allowing all ads to display the same design in relation to each format.
Creating the Ad
- Build the structure/shell of your HTML ad using your code editor of choice (e.g., Google Web Designer, Adobe Anime, Sublime, Visual Code Studio, etc.).
-
Insert this script tag inside the HTML HEAD tag:
- <script src="https://cdn.clinch.co/a_js/custom-code-sdk/custom-code-sdk_39.min.js"></script>
-
In the HTML body:
- Use the clinchSdk.getFCDynamicData(cb, params) method to get the dynamic data.
- Use the methods detailed in the API reference document.
Using the ClinchSdk during the design/development phase (sandbox-local environment)
The clinchSdk.getFCDynamicData(cb) method will only work if the ad is served from Clinch after it was uploaded to Flight Control. To receive data during the development phase, ensure that when calling getFCDynamicData(cb, params), it sends the params object as structured below to allow you to develop and QA the ad.
There are two options available: using a Manifest or Live Data.
Manifest
The Manifest.js is a file in the root folder of the Template ZIP that defines dynamic parameter names/values and relevant template settings (e.g. features, fonts, etc.).
Utilizing the manifest feature allows developers to work locally without manually creating template settings and parameters first. Upon upload, the dynamic parameter and template settings will automatically be reflected in Flight Control.
To utilize the manifest in devmode, use the code: var params= {devMode:'manifest'}.
Click here to learn more about the manifest.json file.
Live Data
Allows you to work in a local environment, while still being able to retrieve:
- Products from live feeds
- Location from live location feeds
-
The creative object with the dynamic parameter
- var params = {devMode:'livedata'};
- params.cidEnc = "<CLIENT_ENCODED_ID>";
- params.template = "<CREATIVE_TEMPLATE_ID>";
- params.format = "<AD_SIZE>"; // for example 300x250
- params.feedId = <PRODUCT_FEED_ID>; // optional, to receive products
- params.itemIds = ["itemId1","itemId2",....]; // optional, to receive products
- params.locationFeedId =<LOCATION_FEED_ID>; // optional, to receive location object
- params.bizId = "<REQUESTED_STORE_ID>"; // optional, to receive location object
- params.contentFeedId = <CONTENT_FEED_ID>; // optional, to receive content feed object
- params.contentItemId = "<CONTENT_ITEM_ID>"; // optional, to receive a content item
Request the Client Encoded ID for your account from your Clinch Client Experience representative Ad-Ops representative. This is needed for the params.cidEnc parameter if attempting to pull in account specific feed data, etc.
Note: In case of an error (passing incorrect data), the dynamicData object will return empty but will include an ‘error’ property with the error details.
Important: In the Production environment, the params object should be omitted. Ensure that the params object is removed before uploading the final external ad to Flight Control.
Uploading the Ad to Flight Control
- Archive the Ad into a zip file (make sure the zip file contains all needed assets, an index.html, and manifest.js file, if applicable).
- Go to Admin.clinch.co > Libraries> Creative Templates.
- Follow these steps when uploading a zip file to a new template:
- In the Creative Templates Library, click Create.
- Template Source: select Custom Code.
- Template Type: select HTML or In-Banner Video.
- Upload Formats: search for the zip file using the plus sign button, or drag and drop it.
- Click Submit
- In the Creative Templates Library, click Create.
- Follow these steps when uploading the file to an existing template:
- In the Creative Template library hover over the template row and click 'Edit' to open the Template Editor.
- Expand the Info Panel and click the plus sign (+) next to Format.
- Search for the zip file using the plus sign button, or drag and drop it.
NOTE: To update an existing format, simply upload the zip file with the same format, which will override the existing format.
Important Notes
|
Impression pixels are tracked automatically in Clinch analytics without any action from the ad. |
|
Ad clicks should always use the clinchSdk.click() method and send the landing page to the SDK to open. This allows the SDK to append click trackers and UTM parameters (configured in the Clinch campaign) to the landing page and fire any 3rd party click trackers. |
|
When using the clinchSdk to resize text automatically to fit an element (W/H), do not re-use HTML elements. For example, do not set the text inside a DIV, call the clinchSdk resize method, then change the text and call the clinchSdk resize method again. Instead, create a new fresh element (DIV) for each new text value you want to resize. |