Clinch SDK Reference for HTML Creative Widgets

General

You can use the Clinch SDK to manage and customize HTML creative widgets.

Important: These methods only apply to widgets used in HTML, in-banner video, and interactive video ads.

ClinchSDK Methods for Creative Widgets

The following methods are available for HTML creative widgets:

clinchSdk.getAdStatus() - Returns the ad's status.
clinchSdk.pause() - Pauses the ad.
clinchSdk.play() - Resumes the ad.
clinchSdk.goTo() - Positions the ad at a certain time point (in milliseconds).
clinchSdk.mute() - Mutes the ad.
clinchSdk.unmute() - Unmutes the ad.
clinchSdk.setVolume() - Sets the ad audio's volume.
clinchSdk.addEventListener() - Subscribes to events that the ad fires.
clinchSdk.removeEventListener() - Unsubscribes from events that the ad fires.
clinchSdk.click() - Initiates a click event.
clinchSdk.engage() - Initiates an engagement event.
clinchSdk.getAdContainer() - Returns the ad's container, used for measuring width and height and adding additional HTML elements (This container scales up/down according to the external container to maintain the ad's aspect ratio).
clinchSdk.getExtAdContainer() - Returns the ad's external container, used for measuring width and height and adding additional HTML elements.
clinchSdk.getDynImgUrl() - Wraps an image URL to serve it through the Clinch CDN and resizes the image if needed.
clinchSdk.resizeFontToFitWidth() - Resizes a font for a text element to fit the element's width.
clinchSdk.resizeFontToFitWidthForMultiLine() - Resizes a font and wraps the text as needed.
clinchSdk.isMobile() - Returns a Boolean value indicating whether the widget/ad is on a mobile device.
clinchSdk.getProductItems() - Returns an array of product items.
clinchSdk.loadScript(url) - Loads the JavaScript file that is used as the widget's Script parameter value.
clinchSdk.loadStyle(url) - Loads the CSS stylesheet file that is used as the widget's Style Sheet parameter value.
clinchSdk.getConfigAndParent() - Returns the config object and parent element. (This method should be used by external scripts loaded via loadScript() when access to the config and parent is required.)

API Methods

clinchSdk.getAdStatus()

Inputs	N/A
Output	status (string): "NA": The ad status can't be detected. "init": The ad is undergoing the initialization process (loading assets). "ready": The ad is ready to play but hasn't started (only relevant when autoplay is disabled). "play": The ad is being played. "paused": The ad is paused. "ended": The ad has been completed, and playback has stopped.
Example Response	`{ status: "<string>", currentTime: <float_seconds>, volume: <float_between_0_and_1>, mute: <boolean> }`

clinchSdk.pause()

Inputs	N/A
Output	N/A
Notes	This is useful when a user performs an engagement that requires the ad animation to be paused, such as opening a "legal drawer."

clinchSdk.play()

Inputs	N/A
Output	N/A

clinchSdk.goTo()

Inputs	Composition time in milliseconds.
Output	N/A
Notes	This method, when used with the play() method, allows for ad replay functionality after an ad has ended. You can also use it to continue playing an ongoing ad from a certain time point without needing to use play().

clinchSdk.mute()

Inputs	N/A
Output	N/A

clinchSdk.unmute()

Inputs	N/A
Output	N/A

clinchSdk.setVolume(volume)

Inputs	volume (float): Any value from 0 to 1 (including decimal values). Setting the volume above 0 will set the ad mute status to "false". Setting the volume to 0 will set the ad mute status to "true".
Output	N/A

clinchSdk.addEventListener(eventType, cb)

Inputs

eventType (string): The chosen event type for the listener, which can be the following:
- "ready_for_play"
- "play"
- "progress"
- "end"
- "click"
- "goto"
cb (object): A JavaScript callback method requiring a custom object for non-click events.
- For the click event type:

{url: "<CLICK_THROUGH_URL>", type: "item_1", event: <NATIVE_EVENT_OBJ>}

For the progress event type:

{type: "progress", event: <ELAPSED_TIME_IN_MILLISECONDS>}

For other event types:

{type: "<THE_EVENT_TYPE>"}

Output N/A

Notes

The "click" event won't be fired if your widget is the one initiating the click using the clinchSdk.click() method.
When clicking on product clickable areas, expect to get type: "item_1" (or items_2, 3, 4, and 5, starting with 1 as the first product). When clicking outside of clickable areas, expect to get "default".
For non-click events, the callback method's custom object is left undefined.

clinchSdk.removeEventListener(eventType, CB)

Inputs	eventType (string): The chosen event type for the listener, which can be the following: "ready_for_play" "play" "progress" "end" "click" "goto" cb (object): A JavaScript callback method.
Output	N/A

clinchSdk.click(params)

Inputs	params (object): params.url (optional; string): Enter your desired click-through URL. params.type (optional; string): If your widget implements a carousel clicking on product cards, set the type to "item_1" or "item_2" and so on. Otherwise, you can use any alphanumeric string value containing dashes (-) and underscores (_). If you're unsure, leave the value empty. params.x (optional; integer): The horizontal coordinate of the click event, usually relative to the ad container. params.y (optional; integer): The vertical coordinate of the click event, usually relative to the ad container.
Output	N/A
Notes	The widget should always use this click() method for reporting ad interactions and opening the click-through URL and never fire any trackers on its own, as this will override the tracking mechanism for Flight Control, the DSP, and other vendors configured in the campaign. Cache-buster macros will be expanded or added if needed.

clinchSdk.engage(params)

Inputs	params (object): params.url (optional; string): Enter your desired click-through URL. params.type (optional; string): If your widget implements a carousel for product cards, set the type to "item_1" or "item_2" and so on. Otherwise, you can use any string value containing alpha-numeric dashes (-) and underscores (_). If you're unsure, leave the value empty. params.x (optional; integer): The horizontal coordinate of the event. params.y (optional; integer): The vertical coordinate of the event.
Output	N/A
Notes	The widget should always use this engage() method for reporting ad interactions and never fire any trackers, as this will override the tracking mechanism for Flight Control, the DSP, and other vendors configured in the campaign. Cache-buster macros will be expanded or added if needed.

clinchSdk.getAdContainer()

Inputs	N/A
Output	The ad container's size (example: 300x250).
Notes	Note that if the Clinch ad is placed inside an external container that has different dimensions then the ad size, the ad container will be scaled up/down to be contained in the external ad container. In this case, left/right paddings to top/bottom paddings might be added. Any additional HTML you append in the ad container will be scaled up/down as well. This method is only applicable if the ClinchSdk is not within an iframe (in an iframe this method won't exist).

clinchSdk.getExtAdContainer()

Inputs	N/A
Output	The external ad container's size (example: 300x250).
Notes	This external ad container dimensions might not fit exactly the native ad size (see explanation above in the getAdContainer() section). This method is only applicable if the ClinchSdk isn’t within an iframe (in an iframe this method won't exist).

clinchSdk.getDynImgURL(url, w, h, resizeOption, barsColor)

Inputs	url (string): The URL of the image to be resized. w (integer): The desired width of the resized image. h (integer): The desired height of the resized image. resizeOption (integers 1 through 3): 1 = CROP (Part of the content will be cropped to fit the requested aspect ratio.) 2 = FIT (Bars will be added in the sides or top/bottom so the image content will be contained inside the final image dimension) 3 = DO_NOT_RESIZE (The image won't be resized.) barsColor (required if resizeOption = 2; string): The desired color value for the added bars, from 0 to 255 in RGBA order (example: "255a255a255a255").
Output	The Clinch CDN URL of the resized image.
Notes	This method must be used for any image (unless you are certain that the original images received from Clinch CDN domains and their dimensions and file sizes are small enough to fit the ad element). This method: Serves the image from the Clinch CDN domain which is an allowed domain (All images served by Clinch Ads must be served only from allowed domains) Resizes the image if needed, reducing the file size. Compresses the image as needed for display and, if needed, serves alternate supported types, like WEBP, for additional size reduction.

clinchSdk.resizeFontToFitWidth(className)

Inputs	className: The "class name" of the HTML element to which you want to apply this rule.
Output	N/A

clinchSdk.resizeFontToFitWidthForMultiLine(className)

Inputs	className: The "class name" of the HTML element to which you want to apply this rule.
Output	N/A
Notes	For this method to work, the text elements receiving this class must have explicit width and height CSS style properties or have the width and height provided in the element data set. If text elements are inserted into the DOM dynamically, you should call this method whenever a new text layer is added.

clinchSdk.isMobile()

Inputs	N/A
Output	Boolean value (True or False)

clinchSdk.getProductItems()

Inputs	N/A
Outputs	An array of product items

clinchSdk.loadScript(url)

Inputs	url (string): A script URL (the URL used as the widget's Script parameter value).
Outputs	A promise that is resolved when the file is loaded.

clinchSdk.loadStyle(url)

Inputs	url (string): A stylesheet URL (the URL used as the widget's Style Sheet parameter value).
Outputs	A promise that is resolved when the file is loaded.

clinchSdk.getConfigAndParent()

Inputs N/A

Output

params (object): Contains the widget's configuration data from the manifest (config) and the parent element, which is useful for external scripts that the widget loads:

{ config: { /* manifest data */ }, parent: HTMLElement }