[Dev tools] Embed API – ThingLink

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.

The following documentation is technical in nature. It describes the Thinglink JavaScript code and its API, which is available to anyone wanting to embed Thinglink functionality to their website.

Basics

Thinglink functionality is based on an image tagging API. The API itself is not public at the moment, but there is a JavaScript helper library, which makes it very easy for anybody to embed Thinglink images onto their site.

The embed code comes in two flavours: the single image embed code, and the mass embed code. Physically, they are the exact same JavaScript library, but depending on the arguments you pass, it will function in either mode.

The single image embed code is what you get when you hover over a Thinglink image and select Embed image. It looks something as follows (feel free to try this one out):

<img src="http://www.metrotrains.com.au/gifs/300x278_dwtd.gif#tl-328434239471091714;626328886" width="300" class="alwaysThinglink" /><script async charset="utf-8" src="//cdn.thinglink.me/jse/embed.js"></script>

You can see that the script invocation contains the image URL and a unique identifier (called Scene ID) as a URL hash ( #). This code just displays the respective image with its tags.

The mass embed code looks like this:

<script charset="utf-8" type="text/javascript">
__tlid = '45116017210294279';
setTimeout(function(){(function(d,t){var s=d.createElement(t),x=d.getElementsByTagName(t)[0];
s.type='text/javascript';s.async=true;s.src='//cdn.thinglink.me/jse/embed.js';
x.parentNode.insertBefore(s,x);})(document,'script');},0);
</script>

This code will automatically fetch the tags for all the images (of a user) that are bigger than 130-by-130px. You need to paste in the code only once for each page.

URLs

The Thinglink embed code lives always at

https://cdn.thinglink.me/jse/embed.js

While a regular HTTP version is still available for legacy reasons, we recommend that you always use the HTTPS version.

Controlling the Embed Code

Specifying image attributes

You may add basic height and width attributes to the embed code. For example:

<img src="http://farm1.static.flickr.com/4/8060056_df5ed9e19b.jpg#tl-98899144692727808;353567704" width="200" height="300" class="alwaysThinglink" /><script async charset="utf-8" src="//cdn.thinglink.me/jse/embed.js"></script>

The mass embed code honours the sizes and locations of the <img> tags, so there is no need to do anything special with it.

Special classes

The size limitation of 130-by-130 pixels is usually enough to weed out uninteresting images. However, if there is a particular need to include orexclude images from being Thinglink-ed, you can use a couple of special CSS classes:

alwaysThinglink - the image is always Thinglink-ed, no matter its size
neverThinglink - the image is never Thinglink-ed, no matter its size or other qualifications

For example, the following causes an image to be never Thinglink-ed:

<img src="http://static.thinglink.com/pics/PunavuoriRefugeeCenter.jpg" class="myclass neverThinglink" />

The myclass class is just there to show that you can also specify your own classes for an image.

You may also wrap a bigger section inside a neverThinglink, for example:

<div class="neverThinglink">  
  <img src="pics/image1.jpg"> <!-- Never thinglinked -->
  <img src="pics/image2.jpg"> <!-- Never thinglinked -->
  <img src="pics/image3.jpg"> <!-- Never thinglinked -->
</div>

This is useful for example when you want to disable Thinglink for your side-navigation bar or your ad banner images.

Additional settings to embed code

Tag bubbles to open inside the images

You can force tags to open inside the images by checking Keep tags inside images on the embed code page.

You can further modify the code to fit your needs by modifying the vOverflow and hOverflow attributes in the __tlconfig variable of your embed code. To allow tags to appear above the images set "vOverflow":true and to allow tags to appear on the sides of the images set "hOverflow":true.

Image sharing and activation

When one of your users wants to share your Thinglink-ed image they are given a special URL that points to your web page. The special URL contains a string "#tl=", which lets Thinglink know which image on the page the user has shared. Thinglink script automatically scrolls at the proper image, but if your site does not use scrolling (for example when your images are all shown in a lightbox) then you may override it by adding the following JavaScript into your page, prior to loading the Thinglink JavaScript.

<script type="text/javascript">
  function gotoMyImage( img ) {
     // Activate your image here.
  }
  __tlconfig = {};
  __tlconfig.activateImage = gotoMyImage;
</script>

To completely disable the scrolling, add the following lines to your code (before the Thinglink JavaScript code)

<script type="text/javascript">
  __tlconfig = {};
  __tlconfig.activateImage = null;
</script>

(If you need to know, the parameter after "tl=" is simply Math.abs(adler32(url)) in hex, where adler32() is the 32-bit Adler checksum, and url is the URL of the image.)

Adjusting time that icons are displayed when image comes into view

To control time that nubbins are displayed before mousing over it, adjust the number in the following code:

<script>
  __tlconfig = {};
  __tlconfig.initialNubbinShowDuration = 5000;
</script>

You can also make the icons show all the time:

<script>
  __tlconfig = {};
  __tlconfig.makeNubbinsSticky = true;
</script>

However, keep in mind that animated icons usually attract more attention plain static ones.

Programmatic control

The __thinglink object exposes a number of functions for your disposal:

openEditor(img) opens the editor popup.
openShare(img) opens the share dialog.

The img parameter should be a DOM object pointing at the image. For example, with jQuery you could state:

 <img id="myimage" src="http://myimages.com/1.jpg">
   <a href="#" id="popup">Pop up the share window</a>
   <script>
      $('#popup').click( function() {
          __thinglink.openShare( $('#myimage')[0] ); // Find the image, take the DOM object from jQuery, pass it to openShare()
          return false; // Don't do the default action of the link, which would be to open '#'
      });
   </script>

This would open the embed dialog whenever the user clicked on the Pop up the embed window link.

Tips and Gotchas

If you are downloading images using AJAX, or otherwise modify the DOM after the Thinglink embed code has been loaded (e.g. resize the images on the fly), you can refresh the tags by calling

__thinglink.rebuild();

If you call it without arguments, it will rebuild all the images on the page. You can also pass an URL, if you are rebuilding just a single image and happen to know which one that is. For example

__thinglink.rebuild('http://example.com/pics/picture.jpg');

If you resize an image, you can reposition existing tags on the new spots by calling

__thinglink.reposition(image);

The parameter image can be an img DOM element. If it is left empty, tags on all rendered images get repositioned. On window resize Thinglink will call the reposition function automatically for you.

Perma-URL to be used in ThingLink Share

A website can have a perma-URL defined to be shared on social services using Thinglink functionality. This is expecially handy for blogs, which have dynamic URLs or on pages that have the image appearing inside an iframe, like for example on Facebook.

You can specify a perma-URL with the "identifier-URL" meta tag:

<meta name="identifier-URL" content="http://www.mycoolsite.com/postABC" />

Events

NB: Events are only available to selected third parties for now. Please contact sales@thinglink.com for further information.

You may specify an event callback in the tlconfig variable:

<script>
__tlconfig = {
    eventCallback: function(e) {
        console.log(“Received event: “+e.event);
    }
}
</script>

Event object description

In addition to the fields below, there is a common “ts” element which is the timestamp of the event.

Event	Event fields	Description
Hover on tag	event	String literal "tagHover"
	scene	ID of the scene
	tag	ID of the tag
	image	The DOM object which triggered this event
Click on tag	event	String literal "tagClick"
	scene	ID of the scene
	tag	ID of the tag
	image	The DOM object which triggered this event

Note that “tagHover” events are filtered and asynchronous; they occur a few hundred milliseconds after the hover has occurred (to keep network communication from interfering with the appearance of the tag). Also they are only fired once every few seconds to filter out very jittery users or browsers. Filtering occurs on a per-tag basis.

The tagClick event, however, is synchronous.