Menu

Monetize with Clean, Relevant Advertising

Implementing 140 Proof Ads

Basics

There are two ways to serve 140 Proof ads. The main difference between the two approaches is "who handles rendering the ad":

  1. Javascript "Loader": 140 Proof renders the ad
  2. API (XML, JSON, JSONp): You render the ad

The javascript loader works like other standard "ad tags": configure the url parameters and drop the script tag on the page/view; done. It is substantially easier to implement than the API method.

The 140 Proof Ads API gives you the most flexibility and control. The work here is rendering the ad, and handling various events (ad loaded, ad clicked, social actions, etc.).

Integration Process

Once you decide how you're going to implement 140 Proof Ads, the process goes something like this:

  1. Check out the docs; determine how you're going to proceed.
  2. Implementation/Development cycle: Do you have your app_id?
  3. Verification: Once you've completed the integration, we need to check things out to ensure everything is working properly.
    • Ad is called correctly (check params, no errors, etc)
    • Ad renders correctly (visual inspection)
    • Impression events fire (verification pixels load, etc.)
    • Ad events work and track (click, social actions, etc.)
  4. Go live!: 140 Proof enables paid campaigns on your app_id

Method 1: Loader

The loader method works like a standard ad tag. It's comprised of a javascript tag and some specific url paramters and values. 140 Proof will tell you which version to use based on your app's characteristics.

General format
/*
    common additional url paramters:
    style=
    width=
    lat=
    long=
*/
<script src="//api.140proof.com/javascripts/loader.js?app_id=1&hb=36246663"></script>
Blog specific format
<script src="//api.140proof.com/javascripts/loader_blog.js?app_id=1&bt=tumblr"></script>

Method 2: API

The API affords you the most flexibility and control when implementing 140 Proof ads. It also allows a very deep integration with your native app code.

While it's nice to be able to have that control, that control comes at a slight cost: you also need to pay particular attention to a small handful of Ad events.

Example request
// html: renders an html version of the ad
curl http://api.140proof.com/ads/user.html?app_id=1&hb=59593&unique_id=aaa-bbb-ccc&width=480

// json (by far, the most popular API format used)
curl http://api.140proof.com/ads/user.json?app_id=1&hb=59593&unique_id=aaa-bbb-ccc&width=480

// jsonp
curl http://api.140proof.com/ads/user.js?app_id=1&hb=59593&unique_id=aaa-bbb-ccc&width=480&callback=yourCallbackFunctionName

// xml
curl http://api.140proof.com/ads/user.xml?app_id=1&hb=59593&unique_id=aaa-bbb-ccc&width=480
Example response
{
  "ads":[
    {
      "text":"NEW #Mets 2010 Alternate Jersey can be ordered here --> http://bit.ly/8P6xYm",
      "image_url":"http://img.tweetimag.es/i/mets_b",
      "byline":"<a id=\"byline\" href=\"http://www.140proof.com/learn-more/1\" target=\"_blank\">ads by 140 Proof</a>",
      "user":{
        "id":39367703,
        "name":"New York Mets",
        "screen_name":"Mets",
        "profile_image_url":"http://img.tweetimag.es/i/mets_b",
        "kind":"house"
      },
      "status":{
        "id":6017128450,
        "id_str":"6017128450"
      },
      "action_urls":{
        "click_url":"http://api.140proof.com/clicks/create.json?ad_id=1&impression_id=4228762625&app_id=1&user_id=105216102",
        "favorite_url":"http://api.140proof.com/favorites/create.json?ad_id=1&impression_id=4228762625&app_id=1&user_id=105216102",
        "friendship_url":"http://api.140proof.com/friendships/create.json?ad_id=1&impression_id=4228762625&app_id=1&user_id=105216102",
        "impression_url":"http://api.140proof.com/impressions/verify.json?ad_id=1&impression_id=4228762625&app_id=1&user_id=105216102",
        "reply_url":"http://api.140proof.com/replies/create.json?ad_id=1&impression_id=4228762625&app_id=1&user_id=105216102",
        "reply_intent_url":"http://api.140proof.com/replies/intent.json?ad_id=1&impression_id=4228762625&app_id=1&user_id=105216102",
        "retweet_url":"http://api.140proof.com/retweets/create.json?ad_id=1&impression_id=4228762625&app_id=1&user_id=105216102",
        "tracking_pixel":"http://jm3.net/images/spacer.gif"}
      }
    ]
}

/*
    ads                : an array of ads, typically only contains 1 ad object
    ads[0]             : an ad object
    ads[0].text        : ad text
    ads[0].image_url   : the icon to show with the ad text
    ads[0].byline      : 140 Proof ads attribution; links to an informational page
    ads[0].user        : twitter user object; 140 Proof advertiser;
                         used to get render/formatting information; i.e. name + screen_name
    ads[0].status      : twitter status id information (the ad is associated with a real tweet)
    ads[0].action_urls : a set of urls used to signal specific actions/events to the server
*/
Events / Lifecycle

When your app requests an ad, it is not necessary to render it immediately. While you don't want the ad to get "stale", this allows you to mitigate problems like slow networks and network latency.

Do not cache any requests/responses including images. These urls are often used as "beacons" by ad networks.

  • Request

    • Ad is requested by client
    • On Success/200: do nothing
    • On error/4XX-5XX: retry
  • Render

    1. Render/show ad.image_url
    2. Ping ad.action_urls.impression_url
      • This is when the impression is "counted" on our side
    3. Ping ad.action_urls.tracking_pixel
      • This is a third party url, for accounting on external systems
  • Click

    1. The entire ad area should be "hot"/clickable.
    2. When the user clicks the ad, a full screen view should load ad.action_urls.click_url
  • Twitter specific events

    1. favorite: User favorites tweet with id: ads.status.id_str
    2. follow: User successfully follows/friends the twitter user with id: ads.user.id
    3. reply: User successfully replies to tweet with id: ads.status.id_str
      • reply_intent: When the user triggers the action "intends to reply"
    4. retweet: User successfully retweets tweet with id: ads.status.id_str

Params glossary

name type description
app_id integer 140 Proof app identifier
bt string Blog type (tumblr, wordpress)
hb integer Twitter numeric user id
fb integer Facebook numeric user id
lat float Geo coordinate: latitude
long float Geo coordinate: longitude
style string Rendering option (sban, mban, mrec)
unique_id string Persistent and unique device id
width integer Size of ad container in pixels
root string * DOM element id; used as ad's parent container when rendered (default is document.body)
bg_color string * hex color; specified without the #: red = ff0000
text_color string * hex color; specified without the #: red = ff0000
link_color string * hex color; specified without the #: red = ff0000
click_url url * Macro to inject a redirect url via the ad request. Your url must allow for a url to be appended to it (string concatentated); and redirect to that url.
custom custom Got interesting data? We <3 interesting data. Let us know what you got ;)

* only used by the 'loader' or api.html method