ThoughtLeadr Javascript API v2

Overview

ThoughtLeadr’s JavaScript API allows publishers to control/report your native advertising inventory in the browser. Calls can be made to load an ad, record user actions, or open an ads target URL.

Requirements

  • Thoughtleadr Publisher Account with Public Key
  • Basic Javascript Knowledge
  • Basic HTML Knowledge

Getting Started

First we want to load the ThoughtLeadr Javascript API, add this snippet to your HTML page:

<script type="text/javascript" src="http://a.thoughtleadr.com/v1/tacos"></script> <

Important If you are testing a development system, make sure to add the query parameter “?debug=true” to the end of the Ad API URL, like so:

<script type="text/javascript" src="http://a.thoughtleadr.com/v1/tacos?debug=true"></script> 

This will give you dummy ads to test against regardless of advertising inventory in production. Additionally, you can add the query parameter “noads=true”, if you want to test to see if the page will work when there is no ad inventory.

Now that you have access to the “tldr” variable within the global javascript scope of the page, you can check to see if there is an available advertisement for the page:

<script type="text/javascript">
if( tldr.ad_available() ){
    // setup ad for the page
    // hook up events
}
</script>

The thumbnail is a small preview version of the advertisement used on home pages or in lists of related articles. Here’s how you would retrieve the thumbnail URL:

tldr.get_thumbnail_url();// http://cdn.thoughtleadr.com/images/123456

These can be used to either directly write out html image tags:

<script type="text/javascript">
var href = tldr.get_thumbnail_url();
document.write("<img src='"+ href + "'/>");
</script>

OR can be incorporated into a more complex frontend framework.

Recording Events

There are two types of events that can be recorded using the TLDR Javascript API, clicks and impressions. Every time either one of those events occur, you need to make a corresponding API call to have it recorded in TLDR’s system. Here’s an example:

//someone clicked on a facebook sharing button
tldr.click(tldr.CLICK_TYPE.fb_share);

//someone viewed a full page image ad
tldr.impression(tldr.IMPRESSION_TYPE.fullpage);

When this call is made, an img tag is added to the page making a request back to TLDR’s system to record the action. For a complete list of impression and click events, please see the TLDR Object Model below.

Ad Data Methods

These methods will allow you to extract information about the ad for the current page.

Method Return Type Description
tldr.ad_available() Boolean Tells you whether or not there is currently ad inventory for the current page.
tldr.get_thumbnail_url() string Provides the URL for the preview image. Can be used to construct an image HTML tag.
tldr.get_title() string Provides the ad title.
tldr.get_caption() string Provides the ad caption text.
tldr.get_page_views() int Provides the ad page view count. This value is cached.
tldr.get_points() int Provides the ad point count. This value is cached.

Ad Event Methods

These methods will record or handle user actions related to TLDR’s ad units.

Method Return Type Description
tldr.click( tldr.CLICK_TYPE ) null This method records a user click action. The first argument must be from the CLICK_TYPE list below, denoting what type of user action the click is.
tldr.impression( tldr.IMPRESSION_TYPE ) null This method records a user impression action. The first argument must be from the IMPRESSION_TYPE list below, denoting the type of impression the user experienced.

Impression Types

The items listed here are properties of the tldr.IMPRESSION_TYPE object. They act as an enumeration for the tldr.impression method.

  • fullpage – this is for the full page ad image.
  • gallery – this is for an impression in the gallery. (Possibly not necessary)
  • preview – this is for an impression of any preview link.

Click Types

The items listed here are properties of the tldr.CLICK_TYPE object. They act as an enumeration for the tldr.click method.

  • preview – this is for an click of any preview link.
  • gallery – this is for an click in the gallery.
  • upvote – if a user click on the upvote arrow.
  • downvote – if a user clicks on a downvote arrow.
  • comment – if a user makes a comment or caption
  • fb_share – if a user click on the facebook share button
  • twitter_share – if a user clicks on the twitter share button
  • tumblr_share – if a user clicks on the tumblr share button
  • reddit_share – you get the idea
  • stumble_share – hopefully.
  • email_share – almost there.
  • other_share – if they click on the plus sign to expand out the sharing widget.

 Questions

If you have any questions about the documentation, please contact todd at thoughtleadr.com OR join the ThoughtLeadr IRC channel at irc.wtower.net #thoughtleadr.