Imgur Ad API v1 Documentation

Overview

The JavaScript API allows users to control TLDR’s social advertising inventory in the browser. Calls can be made to load an ad, record user actions, or open an ads target URL.

Requirements

You must have an account with ThoughtLeadr setup for each domain you serve ads from.

Getting Started

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

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

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> <!-- Development URL -->

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>

Depending on the page, you may want to grab either the thumbnail or image ad. The thumbnail is a small preview version of the advertisement used on gallery pages or in discovery widgets. The image ad is shown when the preview image has been clicked or if its been cycled to in the course of the normal user experience of the site. Here’s how you would retrieve the thumbnail:

tldr.get_thumbnail_id();// provides the id for the thumbnail, ex. "JL1Sq"

To get the id for the main ad image:

tldr.get_image_id(); // Produces the id for the image, ex "JL1Sa"

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

<script type="text/javascript">
var href = "http://i.imgur.com/" + tldr.get_thumbnail_id() + ".png";
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_position() int In situations where an ad is placed in a list, get_position() provides an index for what index position the ad should be placed at. It is a zero-based index.
tldr.get_thumbnail_id() string Provides the id for the preview image on Imgur. Can be used to construct an image URL.
tldr.get_image_id() string Provides the id for the full image on Imgur. Can be used to construct an image URL.
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.
tldr.open_redirect() null This will open up a new tab in the browser with the target URL for the ad.

Impression Types

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

  • discovery – this is for the thumbnail image on the right side of a single image page. (ex. tldr.IMPRESSION_TYPE.discovery )
  • fullpage – this is for the full page ad image.
  • gallery – this is for an impression in the gallery. (Possibly not necessary)

Click Types

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

  • discovery – this is for the thumbnail image on the right side of a single image page. (ex. tldr.CLICK_TYPE.discovery )
  • 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.