INTEGRATION BASICS

There are a few things to keep in mind when integrating with Outbrain:

• All pieces of content are identified with a URL / permalink. The Outbrain service identifies all discrete pieces of content with a URL.

• All content must be crawlable before it can be recommended. The Outbrain service will automatically crawl the URLs provided by the widgets to automatically keep the index of potential content recommendations current.

• The recommendations provided by the Outbrain service are time sensitive and must be used within one hour. Recommendations are intended for specific users at specific times and any caching or delay in their presentation will have a negative impact on their performance (and user experience). Storage of recommendations with the intent of delaying their presentation on the page and caching of recommendations is prohibited.

• Co-mingling of Outbrain Recommendations with 3rd party links links within the same container is prohibited unless mutually agreed upon between the client and Outbrain.

• Any container displaying Outbrain recommendations must be labeled with a header that is mutually agreed upon between the client and Outbrain.

Outbrain Branding/Disclosures and privacy policy must be displayed where it can be reasonably associated with relevant content as mutually agreed upon between the client and Outbrain.

• Altering or replacing the material content (image, text, etc.) delivered by an Outbrain API is prohibited.

• All Paid recommendations must be labeled in a manner that can be reasonably associated with relevant content as mutually agreed upon between the client and Outbrain. (See the Response Fields table and Notes.)

• Mobile app integrations must follow Outbrain compliance guidelines. Approval from Outbrain QA is required before launch.


 
GETTING RECOMMENDATIONS IN JSON

This Outbrain API documentation defines the acceptable use of the service as prescribed by your contractual agreement with Outbrain. Outbrain reserves the right to revise this API Implementation Guide from time to time as appropriate.

 
1. To begin, you need to include the Outbrain JavaScript client library. Please contact your Outbrain Account Strategist and they will supply this to you.

 
2. Next, prepare the request data object.

The following values are supported:

permalink String required: The crawlable URL of the current page.
Example:

permalink: "http://www.webx0.com/2010/07/some-posthype-thoughts-about-flipboard.html"

widgetId String required: The widget ID as provided by Outbrain. If you have not received one, please contact Outbrain.
Example:

widgetId:"JS_1"

testMode Boolean required during testing: Set to true to avoid registering clicks and impressions with Outbrain during development. This parameter must be removed before releasing to production.
Example:

testMode: true

installationKey String optional: Installation/partner key as provided by Outbrain. If you have not received one, please contact Outbrain. This key is not required for all installations, so you may not be provided one.
Example:

installationKey: "ABC1234567890"

Mobile App Parameters:

userId String required for mobile app installations: It is mandatory to pass the Google or Apple Advertising ID for Outbrain installations in mobile apps, according to Google and Apple guidelines and developer agreements. See this page for Outbrain requirements.

 
Craft a request object as in the following sample code:


var request_data = {
    permalink:"http://www.example.com/permalink.html",
    widgetId: "JS_1"
};

Each request will return multiple recommendations to be displayed together, in the same container. If you are installing the Outbrain service on multiple containers of the same page, please ask your Account Strategist for additional widget IDs (e.g. HP_1, APP_1, APP_2) for use in each distinct container. Your Account Strategist will instruct you on how to use each widget ID to track the performance of Outbrain recommendations and user behavior when interacting with Outbrain recommendations in each distinct container.

 
3. Prepare a callback function to handle the response. For example this function prints the returned recommendations:


var outbrain_callback = function (json) {
    // Iterate through json.doc array
    for (var i = 0; i < json.doc.length; i++) {
        var doc = json.doc[i];
        console.log('Recommendation title:' + doc.content + ' and url: ' + doc.url);
    }
};

An array of recommended links are available in the response in the .doc property of the response object (e.g. json.doc[0] is the first recommendation).

 
Response Fields

Field Description
documents A wrapper for the recommendations array with the total number of recommendations.
doc An array of returned recommendations objects
doc.source_name The name of the section of the site in which this recommendation belongs
doc.pc_id Returns if the recommendation is a paid link[1]
doc.url The tracking URL of Outbrain. This URL must be called in order to register the click in Outbrain’s system. See section 2 of this guide for more information.[2]
doc.orig_url The original URL of the recommendation. See number 2 below of this guide for more information.
doc.content The title of the recommendation
doc.author The author of the recommended article. For paid recommendations this field will usually be blank.
doc.desc Custom values set within your webpage that are mapped to the Outbrain system by an Account Strategist via xpath.
doc.thumbnail Object that contains thumbnail information, if configured to send thumbnails[3]
doc.thumbnail.url The URL of the thumbnail
doc.thumbnail.width The width of the thumbnail
doc.thumbnail.height The height of the thumbnail

Notes:
1. Text returned by doc.source_name must be displayed as subtext to the Recommendation link when doc.pc_id = true
2. Registration of clicks using doc.url or manual registration as defined by section 5, even in the case of a user right clicking a link to open, is required.
3. The use of thumbnails other than the image returned in the doc.thumbnail object is prohibited.
4. The use of headlines other than the text returned in the doc.content object is prohibited.

An example JSON response is on the next page. The “url” attribute (not the “orig_url” property) is highly recommended as the best click registration mechanism. The “url” property includes Outbrain’s redirect server, which tracks click activity and improves recommendations. Registration of clicks ensures your Outbrain recommendations will improve by benefitting from our machine-learning technology. If you choose not to use the redirect server, you must manually register clicks on Outbrain links, see number 5 below for manually registering clicks. Failure to register clicks is prohibited as neglecting click registration will harm the performance of your Outbrain modules.

 
4. Finally, make the call to Outbrain to fetch the JSON, which is then transmitted to your callback function.

OBR.extern.callRecs(request_data, outbrain_callback);

A working example is available here:
http://widgets.outbrain.com/external/demos/ClientApiDemo/clientApiDemo.html

 
5. Registering clicks with Outbrain: As mentioned above, if you use doc.url you can skip this section. Otherwise you must register clicks on Outbrain links by using the OBR.extern.callClick() function and transmitting the ‘url’ attribute from the response:

var reqData = {
    link: 'http://traffic.outbrain.com/network/redir?....'
};
var callBackFuncObj = function(json)
{
    console.log('Fired manual click to Outbrain.');
};
OBR.extern.callClick(reqData, callBackFuncObj);

Registering Clicks is required even in the event of a user right clicking to open a link.

If you have any questions or troubles, please contact support@outbrain.com

 
SAMPLE REQUEST AND RESPONSE

1. When a visitor visits this page:
http://www.webx0.com/2011/02/acquiring-surphace.html

We construct this request to get recommendations:

var request_data = {
    permalink: "http://www.webx0.com/2011/02/acquiringsurphace.html",
    widgetId: "APP_1"
};

2. Receive this JSON with recommendations:

{
    "total_count": 1,
    "count": 1,
    "doc": [
        {
            "source_name": "Web X.0",
            "same_source": "true",
            "publish_date": "2008-06-15 00:00",
            "orig_url": "http://www.webx0.com/2008/06/an alternative.html?u=1513",
            "url": "http://traffic.outbrain.com/network/redir?                                       key=711dda7e7cb9f70314aaa935032d136e&rdid=185479104&type=MRD_/c0_stg&in-site=true&req_id=3c470cbcccd581f85d3e9f02c8b12abf&agent=blog_JS_rec&recMode=10&reqType=1&wid=123&imgType=3&refPub=0&prs=true&scp=false",
            "author": "",
            "content": "An alternative Plan B for Microsoft",
            "thumbnail": {
                "url": "http://images.outbrain.com/imageserver/s/6/cR3afny59wMUqqk1Ay0Tbgee-0-109x109.jpg&did=M7IZy",
                "width": 109,
                "height": 109,
                "imageImpressionType": "TEXT_IMAGE"
            }
        }
    ]
}

3. Display this link as a recommendation to users:

Title: “An alternative Plan B for Microsoft”
Link: one of the two links below.

May use this link to use Outbrain’s Redirect Server:

http://traffic.outbrain.com/network/redir?key=711dda7e7cb9f70314aaa935032d136e&rdid=185479104&type=MRD_/c0_stg&in-site=true&req_id=3c470cbcccd581f85d3e9f02c8b12abf&agent=blog_JS_rec&recMode=10&reqType=1&wid=123&imgType=3&refPub=0&prs=true&scp=false

Or

May use this link to skip the redirect server

http://www.webx0.com/2008/06/an-alternative.html?u=1513

and must manually register the click, using:

var reqData = {
    link: 'http://traffic.outbrain.com/network/redir?key=711dda7e7cb9f70314aaa935032d136e&rdid=185479104&type=MRD_/c0_stg&in-site=true&req_id=3c470cbcccd581f85d3e9f02c8b12abf&agent=blog_JS_rec&recMode=10&reqType=1&wid=123&imgType=3&refPub=0&prs=true&scp=false'
};
var callBackFuncObj = function(json){
    console.log('Fired manual click to Outbrain servers.');
};
OBR.extern.callClick(reqData, callBackFuncObj);