ThingLink Image App Support Library

Note: the following documentation applies to content created in the old ThingLink image editor. If you'd like access to API for content from our new editor, please contact us at support@thinglink.com or submit a request for Technical Support with a description of your use case.

While you may develop your app as a fully standalone Rich Media Tag, we also provide a JavaScript library to support your most common use cases.

Note that this library is also needed if you need to register clicks from inside your tag. We add an automatic click handler for all of your <a> -tags inside your tag that will report back to thinglink.com. Just including the library is sufficient.

Setup

To load the ThingLink support library, add the following to the header of your application:

<script type="text/javascript" src="//cdn.thinglink.me/jse/thinglink.js"></script> 

The thinglink.js file will load jQuery (currently v1.6.4) unless jQuery is already loaded, and will then load a modified version of Ben Alman's jQuery PostMessage plug-in.

Receiving notifications

To receive a notification of when the API is ready, register a callback function as in the below example:

// When API is ready, do stuff
thinglink.setOnReadyCallback(function() {
  // Do stuff
});<br>

If you do not care to receive a notification, you can determine whether the API is ready at any time via examining the value of thinglink.isReady, as below:

// If API is ready, do stuff
if (thinglink.isReady) {
    // Do stuff
} 

Resizing your tag

To resize the current iframe, simply call

    thinglink.resize(width, height)  

The provided values are width and height in pixels.

When resize is called before the API is ready, the call will be sent when jQuery and Postmessaging have been loaded.

To only resize in one dimension, simply omit or set the other dimension to null or undefined or 0, for example thinglink.resize(250) to set iframe width to 250px, or thinglink.resize(null, 250) to set the iframe height to 250px. The other dimension is not changed.

You can also adjust the width or height of a tag automatically to its contents. This can be done by setting the value to "auto". For example, thinglink.resize(null,"auto") keeps the width the same but resizes the height of the tag automatically. To resize automatically in both dimensions, use thinglink.resize("auto","auto").

Please mind that with old browsers such as IE7 the messaging system used by the iframe resize mechanism is based on polling, so you must avoid using resizing excessively, and never fire two resize messages within approximately 100ms. So if you want to resize both width and height, do it in one call rather than two sequential calls. The minimum height/width of a tag is 50 px, and the maximum is 400 px. 

Creating sticky tags

Sometimes you'd very much like to have the tag NOT go away when the user moves the mouse out of it. This you can accomplish by calling

    thinglink.setSticky(true); 

This creates a close button on the top-right corner, as well as makes the tag sticky: it will not go away until the user explicitly closes it using the button.

You may also make a tag unsticky simply by calling

    thinglink.setSticky(false); 

For example, if you have a video player, you could make the tag unsticky again after the video has stopped playing.

Defining nubbin (icon) click action

On default clicking on a tag icon opens up the tag URL in a new window/tab. However, in some cases this is not intended as you might want to open a different URL or not open any URL at all. Custom target URL can be set with

    thinglink.setNubbinClickUrl('https://mynewurl.com/...');

It can also be disabled overall by passing no arguments to the function at all, i.e.

    thinglink.setNubbinClickUrl(); 

Events not calculated correctly

In some cases, custom tag content may interfere with Thinglink statistics. A couple of tips below to solve those issues:

1. If you have other click tracking on the page, make sure you use "event.preventDefault()" instead of "return false" in your click handlers. Otherwise, Thinglink may not receive information about clicks that have occurred.
2. If you load jQuery inside the tag, make sure that the jQuery is loaded synchronously and that the loading of jQuery occurs before loading the "thinglink.js" script.

If these do not help, be in contact with the Thinglink team to analyse further where the issues with the tags are occurring and what to do about them.