Skip to main content
Sign in

Search

Flight Control Help Center

Clinch SDK API Reference

  • Updated

Main API Methods

clinchSdk.getFCDynamicData(cb, params)

  • Used for: Retrieving the dynamic data that has been decided during the impression decision path (products/locations/creative dynamic parameters).
  • Method Inputs
    • cb:
      • JavaScript callback method to receive.
      • The cb should receive a data input parameter.
      • The return data object holds all the values from the dynamic parameters of the template and has 3 getter methods:
        • getValue(key, itemIndex)
          • Returns a single value for the dynamic parameter that matches the key input.
          • "itemIndex" is an optional input that defines the product index for product-related dynamic parameters, starting with 0.
          • It is equivalent to getValues(key)[i].
        • getValues(key)
          • Returns an array of values for the dynamic parameter that matches the key input. 
          • This method should be used for product-related parameters (such as product price, discount) in the case of multiple products.
        • getKeys()
          • Returns an array of the dynamic parameter keys. 
          • key = <category>_<param name>.
    • params object (used for development mode only):
      • JSON object, which includes parameters. This parameter should be omitted in the Production environment.
      • Reference Creating "Custom Coded HTML Ads" using the ClinchSdk for a list of supported parameters.
      • You can manually setup the feed from where you want the products to be fetched, as well as the Product IDs (thus the number of products to receive).
      • You can manually define the Location feed and the Location ID to fetch.

Important Notes

  • The returned data is always in the context of the format.
  • All access to feeds is done through dynamic parameters. It is then possible to set the dynamic parameter source to be taken from the Product feed, Location feed, or a static value. This paradigm guarantees that source changes will not require code changes and re-publish.
  • The key convention for a dynamic parameter name is: <category>_<name>.
    • Spaces within the category convert to ‘_’.
    • Spaces within the name get trimmed.
    • Example: the key of a dynamic parameter named 'Main Label' in category Message 1 will be: Messages_1_MainLabel.
    • Note: During development, if you're unsure about what the key of a certain parameter is, you can use the getKeys() function to retrieve the keys associated with the template.
  • The number of products (items) returned in the dynamic data is defined by the number (range) of products set in the Template Info panel.

Code Example

Click here to access a ZIP file that includes a code example.

clinchSdk.click(params)

  • Used for: reporting click-through actions on the ad.
  • Method Inputs
    • params object:
      • params.url: click-through URL (string, optional)
      • params.type: click Type (button name or identifier) (string, optional)
      • params.x: click coordinate x (integer, optional)
      • params.y: click coordinate y (integer, optional)
  • The method will:
    • Open the landing page (either from the params object, if provided, or the landing page configured in the campaign setup in Flight Control). 
    • The landing page will be injected with UTM parameters configured in the Clinch campaign and wrapped with click trackers appended in the click chain.
    • Fire ‘click’ tracking pixel to Clinch + all other 3rd party ‘click’ pixels configured in the Clinch campaign.
    • Optional {{click_type}} and {{click_tags}} macros in the landing page and trackers will be expanded according to the param object
    • Cache-buster macros will be expanded or added, if needed.

Important Notes

  1. The ad should always use this click() method for click-throughs and never open a landing page or fire any trackers itself. Doing so will override the tracking mechanism for Clinch, the DSP and other vendors configured in the campaign.

clinchSdk.engage(params)

  • Used for: report engagement/interaction with the ad not resulting in a click-through.
  • Method Inputs
    • params object:
      • params.type: engage Type (button name or identifier) (string, optional)
      • params.x: click coordinate x (integer, optional)
      • params.y: click coordinate y (integer, optional)
  • The method will:
    • Fire ‘engage’ tracking pixel to Clinch + all other 3rd party ‘engage’ pixels configured in the Clinch campaign
    • Optional {{engage_type}} and {{engage_tags}} macros in the tracking pixels will be expanded accordingly
    • Cache-buster macros will be expanded or added, if needed.

Important Notes

  1. The ad should always use this engage() method for reporting ad interactions and never fire any trackers itself. Doing so will override the tracking mechanism for Clinch, the DSP and other vendors configured in the campaign.

clinchSdk.getDynImgUrl(url, w, h, resizeOption, barsColor, verticalAlign, horizontalAlign)

  • Used for: Wrapping an image URL for serving it through Clinch CDN and resizing the image, if needed.
  • Method Inputs
    • url: The original image to be resized
    • w: requested width
    • h: requested height
    • resizeOption:
      • 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
    • barsColor (optional):
      • Colors for the bars added (in case resizeOption=2)
      • format: 255a255a255a255 (each number is the color value from 0-255 in RGBA order)
      • If you're using the verticalAlign and horizontalAlign parameters but do not need to set a barsColor, you must pass "undefined" as the barsColor argument.
    • verticalAlign (optional):
      • 1 = CENTER (default)
      • 2 = TOP
      • 3 = BOTTOM
    • horizontalAlign (optional):
      • 1 = CENTER (default)
      • 2 = LEFT
      • 3 = RIGHT

Important Notes

  • Must be used for any image coming from the product or store object (Unless you are 100% sure that the original images are received from the Clinch CDN domains and that their dimensions and file size are small enough to fit the ad element)
  • This method serves multiple purposes:
    • It serves the image from Clinch CDN domain which is an allowed domain (All images served by Clinch ads must be served only from allowed domains)
    • It resizes the image if needed, reducing the file size
    • It compresses the image as needed for display and, if needed, serves alternate supported types like webp, for additional size reduction.

API Helper Methods

clinchSdk.resizeFontToFitWidth(className)

  • Used for:
    • Resizing font size on text elements to fit the element width.
    • This is relevant only for text elements that are supposed to be a single line.
    • Applies to: 
      • Text elements that contain simple text directly underneath them: In this case, the font-size for this element will be modified by this method.
      • Elements containing multiple child elements. Where each child contains simple text. In this case, each child element font-size will be modified by this method and not overflow the parent width.
        TIP: Use it for text elements where multiple font sizes should be included in same sentence.
  • Method inputs:
    • className: The className of the HTML elements to apply this rule
  • Usage:
    • Any HTML elements (usually DIVs), with a single line of text, where the text value is injected dynamically, and width overflow is unknown. Requires the className you have chosen for this purpose.
    • For this method to properly work the text elements receiving this class must:
      • Have an explicit width CSS style property.
      • Have a simple text content under it, or child elements with simple text content under them (Do not mix simple text parts with child elements together. Do not add more then one level of child elements under the element receiving the className)
    • If text elements are inserted to the DOM dynamically, be sure to call this method any time a new text layer is added.
    • Do not use CSS to transform text to UPPERCASE - the method does not take it into consideration, alternatively - insert uppercase text in the origin text.
    • Handling multiple text elements with different font-size (see image for example): Screen_Shot_2022-10-20_at_3.25.47_PM.png
      • If text elements are required to be aligned top:
        • Set parent div to align its child to the bottom as follows: 
          display: flex; align-items: baseline;
        • On Each text div element which requires to shift Y, for example if 5px up is required for the element to be aligned to top (before resize), use CSS transform: translateY(5px). 
        • When the resize method executes it detects the translateY value and reduces its value according to the overall resize ratio required.

clinchSdk.resizeFontToFitWidthForMultiLine(className)

  • Used for
    • Resizing font size on text elements to fit the element dimension (width and height)
    • Text elements which might need to multi-line wrap 
    • It can be used only for HTML elements which contain simple text directly inside their innerHTML (for example <div style=”….”>I Am Text</div>)
    • This method will resize the font-size automatically, and wrap the text as needed.
    • If the Line-Height CSS property is set to this element, it will be resized in the same ratio as the font-size.
    • If the inserted original text includes line separators (meaning, the author wants to wrap the text), the method will honor that and not re-wrap the text (only resize the font-size and line-height).
  • Inputs
    • className: The className of the HTML elements to apply this rule
  • Usage
    • Any HTML elements (usually DIVs), with height that can accommodate multiple lines and text directly inside the innerHTML, where the text value is injected dynamically, and you are not sure the text might overflow the element size, should receive the className you choose.
    • In order for this method to properly work the text elements receiving this class must:
      • Have an explicit width and height CSS style properties or alternatively have the width and height provided in the element data set as follows: <div “data-maxWidth”=”200” “data-maxHeight”=”50”>This is my multi line text</div>
    • There is an option to limit the font-size to a minimum value, and in that case the text will be trimmed with ellipsis (…). In order to do so, set the requested minimum font-size in the div data-set attribute as follows: <div “data-minFontSize”=”10”>This is my text</div>
    • If text elements are inserted to the DOM dynamically, be sure to call this method any time a new text layer is added.
    • Do not use CSS to transform text to UPPERCASE - the method does not take it into consideration. Alternatively, insert uppercase text in the origin text.

clinchSdk.isMobile()

  • Used for:
    • This method determines if the ad is currently on a mobile device.
  • Inputs:
    • None. This method doesn't require any parameters.
  • Output:
    • This method returns a Boolean value (True or False) indicating whether the ad is on a mobile device.