ThingLink Image Apps – 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.

How ThingLink Image Apps Work

A ThingLink Image App is a tiny web page, designed to be shown inside an iframe element on an image. The size of the web page is arbitrary, but in general you will want it to be between 80x50 to 300x300 pixels in size. Smaller or larger tags than that may start to experience problems.

When the user hovers on a ThingLink Tag, our embed code opens the tag container and creates an iframe for your application. Hence the loading of the iframe occurs during hovers. While the loading is happening, a spinner element is shown.

What are typical ThingLink Image Apps?

Basically, a ThingLink Image App only needs two things to be useful. You need to have:

Data which can be easily represented in a small window
Permalinks to each individual data item

For example, a shop app where you have unique URLs for each item in your shop and you want your users (or anyone) to be able to link to them.

How to get your app installed?

Since the app system is currently under heavy development, you should always check with us the latest requirements, but in general in order to review and accept your application we need

Domain and regexp with which we can recognize your application (e.g. myapp.com and listing/(\d+) would match links likehttps://myapp.com/listing/1234567)
The link to your ThingLink Image application with the parameters you want (e.g. https://myapp.com/ThingLink/{1} , where {1} will be replaced dynamically with the captured id.
What is the initial size of your iframe? (e.g 300px width, 200px height) The size of the iframe may be changed after loading.

We reserve the right to refuse an App or remove it without a warning period.

The App can be created at our developer site https://www.thinglink.com/developer.

As of 14. April 2014 you must also provide a secure version of the tag, i.e. a destination URL which uses https. This is to ensure that the tags function properly also on modern browsers which don't allow mixed content.

Simple PHP base to kickstart your development

Clone our ThingLink PHP base from GitHub https://github.com/alizbazar/ThingLink-tag-development-base to kickstart your tag development. Place your backend stuff into myTag.php and frontend into myTagTemplate.php, drop the code onto your server and add the app to your app list.

Tag design & implementation tips

Thinglink tags should have as small as possible initial width and height. A good initial size of tags is typically around 230x150 pixels.

When the users interact with the tags, the size of them can be increased to display extended content about the elements. An example of this would be a Twitter tag, which initially displays only link to Twitter and when expanded, also the latest tweet. Instructions for how to resize tags can be found in Thinglink help (ThingLink Image App Support Library). Basically, resizing the tag requires just making a call of javascript, for example "thinglink.resize(230, 300);".

To have tag margins etc work correctly in Thinglink tags, copy to the common tag css styles of Thinglink (http://cdn.thinglink.me/css/themes/common.css). It is better to copy the styles rather than hotlinking to the file because the file content might change with time.

In the bottom-right corner of Thinglink tags a gray link of the format "websitename.com" is normally displayed. The link leads to the target web page that corresponds to the tagged element. The styling for this link is included in the "common.css" file. To have the link render correctly, its structure should be: <div id="source_footer"> <a href="https://websitename.com/path/to/linked-element-12345" target="_blank">websitename.com</a> </div>

Long text elements should be shortened with an ellipsis (...) in tags to not have them take too much space. A reliable plugin for this is "dotdotdot" (https://dotdotdot.frebsite.nl/).

Supported browsers for Thinglink tags are IE7-IE10 and latest versions of modern browsers (Safari, Chrome, Firefox and Opera). For Opera and IE7-8 it is OK to downgrade the tags without aiming for exact visual similarity.

A good basis for styling fields, buttons and other UI elements is the bootstrap library (https://github.com/twitter/bootstrap). However, for the buttons and fields, it makes sense to reduce the height and width of the elements (and their padding) using css to make them fit better in the small space of tags.

Example Twitter App

Let’s examine how a Twitter ThingLink App might be built. The sample code here is JSP EL using Stripes framework, but the same basic principle works whether your main language is Ruby, PHP, or whatever.

We use Twitter as an example – just simply because everyone else uses Twitter as the canonical API example as well. To avoid hitting server API limits, we’ll hit Twitter API on the client side using jQuery.

<%@ page language="java" contentType="text/html; charset=UTF-8" 
pageEncoding="UTF-8"%> 
<html> 
<head> 
<script type="text/javascript" src="https://platform.twitter.com/widgets.js"></script> 
<script type="text/javascript" src="//ajax.googleapis.com/ajax/libs/jquery/1.4.4/jquery.min.js"></script> 
</head> 
<body> 
<div id="tweeter"> 
<div id="profile_picture_container"> 
</div> 
<div id="right_panel"> 
<div id="screen_name_container"></div> 
<div id="name_container"></div> 
</div> 
<div id="follow_button_container"></div> 
<a id="twitterLink" href="https://www.twitter.com/" target="_blank">&nbsp;</a> 
</div> 
<script> 
function populate(tweeter) { 
var intentString = '<a href="https://www.twitter.com/intent/user?screen_name=' + tweeter.screen_name + '" target="_blank">'; 
$("#profile_picture_container").append(intentString + '<img src="' + tweeter.profile_image_url + '" /> </a>'); 
$("#screen_name_container").append($(intentString + '@' + tweeter.screen_name + '</a>')); 
$("#name_container").append($(intentString + tweeter.name + '</a>')); 
$("#follow_button_container").append(intentString + 'Follow me</a>'); 
} 
</script> 
<script type="text/javascript" src="https://api.twitter.com/1/users/show.json?screen_name=${params.name}&callback=populate"></script> 
</body> 
</html><br>

In this application, the ${name} is expanded to the Twitter username. This is a self-contained JSP-file on a server, and forms a complete App. Now, you would register this to ThingLink via telling us the following:

App Name: Twitter
App Size: 170x65 px
Domain twitter.com from which the urls are mapped and pattern (?:#!/)?(\w+), which is matched to the path part of the URL.
Gets transformed to: https://mysite.com/twitterapp.jsp?name={1}
Finally a test url is given to verify that the mapping is correctly.

All the fields are mandatory.Now, whenever a user links to say, twitter.com/ThingLink, the regexp picks it up and an iframe is created with its contents loaded from {mysite.com/twitterapp.jsp?name=ThingLink}. From there on, you are responsible for the content.

The picture above shows how the tag is constructed: The iframe content is placed inside a narrow border in the tag itself.

If the tag has a description, it will be shown on top of the tag, right above the iframe content. Note however how the link is gone, when you compare to regular ThingLink tags.

The regular expression above match domains www.twitter.com and twitter.com. When you specify a certain domain for an application, it will also map all the subdomains to it. Only one application can exists per domain.

Additional parameters

When we make the call to your application, we also append some extra parameters to the GET request:

tlOrigUrl : This is the original URL that the user typed in, URL-encoded.
tlScene : The Thinglink Scene ID, which uniquely identifies the image. It is unique for each user.
tlThing : An unique identifier for the tag within the scene.

For example, you could dispense with the regexp hassles and just parse the original URL directly from the request.

Sizing your iframe

If you need to dynamically change the iframe size, please check out the Thinglink Javascript Library library, which provides a convenient method for doing this.

Before you ask…

Your favorite feature is probably on our roadmap. So we’re working on the following things already:

Access to our image/tag database (“ThingLink API”)
Smarter loading of Apps.
Addition of affiliate models (this requires modifications to our user preferences, so it takes a bit more work – but we can still accommodate you if you so wish.)

UX considerations

Since your application will appear as if it were a ThingLink tag, you will need to pay attention on the user experience. The Apps should be unobtrusive, fast and informative with clear user benefit. There are a number of Do’s and Don’ts when developing a ThingLink App:

DO:

Try to keep the amount of information to the bare minimum. Overloading the tag with a lot of different kind of content will confuse the user, and make the tag load slower.
Show a spinning logo if your tag takes a long time to load (center on background) to avoid people from dehovering on your app.
Use a basic white background.
Use color sparingly. The ThingLink color space is mostly black-n-white to ensure that it fits well with all kinds of pages without standing out.
If your app is interactive, make it clear what elements are actionable and what are not. Buttons and links should look like buttons and links.
Be polite. Showing your app to the user is essentially the same as if they were coming to your website. So make sure that you represent yourself well.

DON’T:

Require the user to log in in order to enjoy your app
Show any additional popups unless the user specifically asks you to
Require the user to click something before they can use your app
Make your app really big. Quite a few websites have aggressive overflow limits, and your app might not work properly if you go outside the image by a lot.
Use scroll bars if your app is big! Scrolling in a tiny iframe is quite annoying and may interfere with the sites own navigation.

Example CSS

Here is an example CSS which shows a good starting point for your application, including things like fonts so that you can blend in to other ThingLink applications.

Note however the max-width and max-height definitions – you might want to set these to your application size. Also important is the “overflow:hidden” which prevents scroll bars from appearing.

body {    
    font-family: 'Trebuchet MS', 'Myriad Pro', Arial, sans-serif;
    font-weight: normal;
    color: #000;
    background-color: #fff;
    font-size: 12px;
    padding:7px;
    max-width:170px;
    max-height:65px;
    overflow:hidden;
}<br>

You may download a copy of a good CSS starting point from https://cdn.thinglink.me/css/themes/common.css.

Performance considerations

The performance of your application is highly important to us, since every user will perceive any latencies or performance issues as a part of the ThingLink experience as well. We may refuse poorly performing applications.

In general, your app should strive to load in less than 2000 ms (including delays, DNS, etc). Remember that every 100ms you can shave off that is likely to increase your conversion rates. You will very likely want to cache most of your content in an aggressive way and avoid costly API calls, as well as keep the amount of content down or spread it to CDNs.

Having said that, there are a number of techniques you can successfully use to make sure your App is displayed as expediently as possible. It’s recommended that you read the basic tutorials on this subject, and analyse your application with tools like YSlow, PageSpeed, Yottaa or HttpWatch. It’s also recommended that you read books by Steve Souders and others on HTTP performance optimization.

A few basic Do’s and Don’ts:

DO:

Use tools like YSlow, Pagespeed, etc. to figure out the bottlenecks on your app
Take advantage of browser caching (and your own caching, e.g. with Varnish or something)
Use a spinner or other loading indicator if your app may take a long time
Parallelize any API calls as much as possible
Be wary of latency – in ThingLink Apps latency is more important than bandwidth. You can always optimize later for bandwidth with compression, tuning image sizes, minification, etc., but you always want your app to show as fast as possible.