ThoughtLeadr Integration: PHP

For integration with ThoughtLeadr, you will need to handle both ad previews and the full-page content. A preview may be the thumbnail or teaser that a user clicks on to go to the full article, image, video, or other media.

You will need an account with ThoughtLeadr to integrate ads on your site. We will provide you with public and private API keys, and you will have multiple key pairs if you wish to run different sets of ads on each subsection or region of your site.

Setting Up Preview Links

We provide a JavaScript API to setup preview links on the homepage or section pages of your site. Previews link will drive traffic from the other pages our your site to the promoted content. Very often the preview links will be placed within the body of the homepage, like listed below.

To get started, include our targeting JavaScript file in your page:

[cc lang=”html”]

[/cc]

This will provide a tldr object with methods for retrieving information about a targeted ad. More on this later.

For testing, you may specify a debug query parameter to get test ads for testing purposes (don’t use this in production):

[cc lang=”html”]

[/cc]

If you want to how your page will work with no ad inventory, you can use the “noads” parameter:

[cc lang=”html”]

[/cc]

You will now have access to a tldr object, which you may use to determine whether or not there is an ad available to be shown:

[cc lang=”javascript”]
if(tldr.ad_available()) {
// set up event hooks and write preview ad to page
}
[/cc]

We provide a variety of ad attributes exposed through the tldr methods to fit into the format of your preview:

  • Title: tldr.get_title()
  • Caption: tldr.get_caption()
  • Thumbnail Image: tldr.get_thumbnail_url()
  • Sponsor URL: tldr.get_sponsor_url()
  • Media Type: tldr.get_media_type()

For example, you may do something like the following in a front page listing, a sidebar, or anywhere else you’d like to put your ad preview:

[cc lang=”javascript”]

[/cc]

This snippet of code is generated a promoted content link using the sites own HTML structure and CSS styles. For your own site, you would change the HTML structure to match the one that best fits your site.

Setting Up Full Page Content

When you set up an account with ThoughtLeadr, you will provide a template for the URLs where sponsored content will be.

As an example, you may wish for a piece of sponsored content to be at the following URL (where example.com is your own domain, and {id} represents the ID for the content):

[cc]http://www.example.com/sponsored/{id}[/cc]

In this case, you provide us with http://www.example.com/sponsored/{id} as the template.

In the preview example above tldr.get_sponsor_url() gives the destination URL for the full page ad. In our example, if the “ad id” currently running was “123” then tldr.get_sponsor_url() would return http://www.example.com/sponsored/123.

With this in mind, the next step will be to integrate our method for displaying full page ads on such URLs in your content management system. We provide a PHP library to help with this. The usage is similar to that of the JavaScript API: we provide an object with methods to get the attributes for an ad:

  • Title: $ad->getTitle()
  • Caption: $ad->getCaption()
  • Thumbnail Image URL: $ad->getThumbnailURL();
  • Media Type: $ad->getMediaType()

Depending on the media type, there are additional properties for the ad:

  • Video (media type “video”)
    • Embed code: $ad->getEmbedCode()
  • Image (media type “image”)
    • Full image URL: $ad->getFullImageURL()
  • Audio (media type “audio”)
    • Embed code: $ad->getEmbedCode()
  • Article or Blog post (media type “article”)
    • Article text (HTML): $ad->getArticleBody()

What follows is a very simple illustration of how it might be used:

[cc lang=”php”]
?>

 


 

break;
case “image”:
print “” . “” . $ad->getCaption() . ““;
break;
default:
print $ad->getEmbedCode() . “” . $ad->getCaption() . ““;
break;
}?>

[/cc]

Within a CMS or PHP framework, you can utilize your normal templating system to reuse your standard site HTML/CSS for this placement.

Recording User Actions

Most campaigns are billed on some form of user-initiated action, like viewing promoted content or clicking on a sharing button. As such, we need to make sure all the user’s impressions and clicks are recorded properly using ThoughtLeadr’s Javascript API.

In order to record impressions, clicks (including shares), and other user events, we provide a direct.js Javascript file to include in your promoted content pages. This is very similar to the targeting.js inclusion:

[cc lang=”html”]

[/cc]

This also provides a tldr object with methods to record impressions and clicks. You may use the tldr object in either the targeting.js API or the direct.js API for recording events, but the direct.js API is used strictly for full page integration; you cannot use it for the preview page.

An impression may be recorded in the following way:

[cc lang=”html”]

[/cc]

This should be included with the full page.

Clicks may be recorded by binding the tldr.click() method to page elements such as links and buttons. For recording a Facebook share for instance, you should call tldr.click(tldr.CLICK_TYPE.fb_share):

[cc lang=”javascript”]
document.getElementById(“facebook-share-button”).onclick = function() {
tldr.click(tldr.CLICK_TYPE.fb_share);
};
[/cc]

Impression types (arguments to tldr.impression())

  • Preview impression: tldr.IMPRESSION_TYPE.preview
  • Full page impression: tldr.IMPRESSION_TYPE.fullpage

Click types (arguments to tldr.click())

  • Thumbnail click: tldr.CLICK_TYPE.thumbnail
  • Upvote: tldr.CLICK_TYPE.upvote
  • Downvote: tldr.CLICK_TYPE.downvote
  • Comment: tldr.CLICK_TYPE.comment
  • E-mail share: tldr.CLICK_TYPE.email_share
  • Facebook share: tldr.CLICK_TYPE.fb_share
  • Google+ share: tldr.CLICK_TYPE.google_share
  • Pinterest share: tldr.CLICK_TYPE.pinterest_share
  • Reddit share: tldr.CLICK_TYPE.reddit_share
  • StumbleUpon share: tldr.CLICK_TYPE.stumble_share
  • Tumblr share: tldr.CLICK_TYPE.tumblr_share
  • Twitter share: tldr.CLICK_TYPE.twitter_share
  • Other share: tldr.CLICK_TYPE.other_share

Contact

Having trouble?
Contact Todd Cullen via email: todd@thoughtleadr.com.
IRC: irc.wtower.com #thoughtleadr
Skype: todd.cullen