ThingLink Connect

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.

Thinglink Connect is an OAuth2 –based toolset which allows any third party developer to integrate their site with Thinglink in an easy fashion.

The goal is simple: to allow your users from your site to set up a personal account on thinglink.com, and then automatically install the necessary code to your site so that your users can enjoy image tagging. In order for us to provide that service, we need to identify which Thinglink user owns a particular section of your website.

For example, if you were a blogging host, each of the different blogs on your site would need to encode the blogger’s personal Thinglink ID (in addition to our Javascript) on every page that the blogger has control over. This can be slightly complicated, and the user might need to do manual work, so we have a Javascript library to make it easier. Read on!

Getting the client ID & secret

In order for us to recognize your site, you will need an identifier. You can get a client ID and secret by signing up as a developer on www.thinglink.com/developer, then going to “Developer” section and requesting a new keypair.

You will also need to set up a Redirection URL, which is the location where our authentication popup will take you. At the very least, you should install our “thinglink-connect.html” on your site, which will serve as the endpoint for customer registration.

Authentication using redirect

Authentication using redirects works pretty much the same way as with all other OAuth2-based applications.

• The authentication address is https://www.thinglink.com/auth/connect

These API endpoints are not served over HTTP, only HTTPS.

For example, if you do not wish to use tlconnect.js, you can just simply redirect your user to

https://www.thinglink.com/auth/connect?client_id=YOUR_ID&response_type=code&redirect_uri=YOUR_REDIRECT_URI

If you open the link above in a popup, make sure that you also close the popup in the end.

The Redirect URI

The redirect URI is an endpoint at which the Thinglink login flow ends. It should be on your site, and it will get the ‘code’ as per the OAuth2 spec. Since it ends the flow, it will also need to close its own window, since we run the login path in a popup window.

However, if you’re just integrating with Thinglink and don’t want to perform API calls, you can just grab our own “tlconnect.html” page, place that somewhere on your site, and point the redirect URI to it.

You can download a sample thinglink-connect.html from https://www.thinglink.com/developer/thinglink-connect.html.txt

The “.txt” has been added so that it’s easier for you to download. We promise to get this to GitHub soon...

Using the Javascript library

The basic use case is when you wish to enable Thinglink very easily to your users. First, load the tlconnect.js library

<script src="https://www.thinglink.com/jse/tlconnect.js"></script>

This will create a new global variable called “TLC”, which represents a single way to access the Thinglink Connect data.

To initialize the TLC variable, you will need to call TLC.init(). In order for Thinglink to work properly in the user’s browser, you will need to pass a unique identifier of your site and a user ID to us. The client_id that you received will function as a site ID.

Your site-local ID

In order for Thinglink to bind tagged images to a specific user account, we need to identify your user. In order to do this, we use a combination of your site’s ID (the client ID) and an unique identifier from your site (the user ID).

The user ID can be anything – it can be an UUID, a running number, etc, as long as it’s unique across all of your users. We will treat it as an opaque string (that should not exceed 128 characters in length, and should fall within [a-zA-Z0-9_\+-@\.]).

In this case, the init script should look like this:

TLC.init({client: <id>,user: <user id>,isOwner:true,redirectUri: 'https://xxx/tlconnect.html'});

The “isOwner” parameter is a boolean which you should supply based on whether this is a person who owns this site and should have access to Thinglink. This has the effect of whether the “Sign up for Thinglink” or the “Sign in to Thinglink” buttons will be shown to the user.

By default we’ll put the button inside all of the “<div class=”thinglinkConnect”/>” sections we can find from the page.

If you want to make it more transparent for the users to sign up for thinglink, you can also pass parameters like “email” and “name” to TLC.init(), which will be taken into account during our signup process.

Please note that the client is an opaque string. If you treat it as a number in Javascript, things will not work. So use

TLC.init({client: '123898091'}); instead of TLC.init({client:123898091});<br>

Using meta tags

If you’d prefer to separate the invocation from the code (e.g. you’d like to deploy Thinglink as a single, unchanging blob), you can alternatively set all the parameters using meta tags. For example:

<meta name=”tl:client” content="12345890">
<meta name=”tl:user” content="joifwiQ8cioW">
<meta name=”tl:isOwner” content="true"> <!-- or false, but in that case it’s nicer to just omit this value --><br>

In this case, the script initialization can be done with a simple

TLC.init();

Using Thinglink Connect graphics

Thinglink provides buttons graphics that you can use for sign up and log in to Thinglink. Feel free to download these images to host on your own servers.

• https://www.thinglink.com/gfx/thinglink-connect/thinglink-connect-light.png#

API description

TLC.init()

For meta-parameters, add “tl:” in front of each of these.

TLC.login()

If you don’t want to use our automatic button, you can always trigger the TLC.login() event yourself. First, initialize Thinglink with TLC.init(). For example:

TLC.init({
   client:'1234567890',
   user: 'fjewioqfjWIJQ',
   isOwner: true,
   redirectUri: 'http://localhost:8080/tlc/redirecturi.html'
});
TLC.login( function() {
    alert("User just logged in!");
} );<br>

TLC.login() takes in one parameter, a callback function, which will be called once the login process is complete.

TLC.logout()

Logging out of Thinglink can be accomplished in the same manner. TLC.logout() also takes a callback which is called when the logout is complete.

TLC.loginStatus()

Returns true, if the user is currently logged in to thinglink.com. Note that this will return 'undefined' as long as TLC.init() hasn't completed.