JS API Guide

New Partner Requirements

Review all Outbrain compliance requirements listed here and flag any concerns/exceptions with your Partner Manager and Sales Engineer immediately.

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.

Getting Recommendations

JavaScript Library

To begin, you need to include the Outbrain JavaScript library.

<script type="text/javascript" async="async" src="https://widgets.outbrain.com/outbrain.js"></script>

Making a Recommendation Request

Craft a request object as in the following sample code:

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

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.

Request Data Object – Placement property

Either of the following property is required to make a request. Use the correct property and value which were advised by your Sales Engineer to represent where the widget is served.

Property Name Type Integration type Description Example
permalink String Direct Web The crawlable URL of the current page “http://www.webx0.com/2010/07/some-posthype-thoughts-about-flipboard.html”
contentUrl String Web Mediation The crawlable URL of the placement “http://www.webx0.com/2010/07/some-posthype-thoughts-about-flipboard.html”
bundleUrl String App The store URL of the App “https://play.google.com/store/apps/details?id=com.outbrain”
portalUrl String Native Environment A URL representing the context where the ad placement is presented to users. Does not need to be a reachable/crawlable URL. “http://www.chatPortal.com”

Request Data Object – Additional properties

Property Name Type Requirement Description Example
widgetId String Required The widget ID as provided by Outbrain. “JS_1”
installationKey String Required  Installation/partner key as provided by Outbrain. “ABC1234567890”
userId String Required for App  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. “EA7583CD-A667-48BC-B806-42ECB2B48606”
language String Required for App & Native Environment  The 2-letter language code (ISO-639-1-alpha-2). Must be added if bundleUrl or portalUrl is sent. “en”
maxNumAds Integer Only if instructed by SE, Optional Number of ads to fetch. Typically, a static number of ads is configured for each Outbrain placement (widgetId). Only use maxNumAds param if you require a variable number of ads on each request. 5
psub String Only if instructed by SE, Optional for App & Native Environment  String value for additional section-level reporting breakdowns. Allowed characters: alphanumeric and underscore ‘_’. Requires permission from your Sales Engineer or Partner Manager. “minus1”
testMode Boolean Optional 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 true
extId String Optional String value with maximum of 70 characters for use with the Engage Variant Reporting API. A maximum of 10K IDs/hour are supported. Contact your Partner Manager for API access. “id123”
consentString String Optional:Only if TCF API is not available Base64-encoded consent string, as defined by IAB for TCF v2.0 “CO4SiGQO4SiGQAGABBENAzCgAP…(omitted)…YAAAAAAAAAAA”
consentVersion String Optional Version of consent string “2”

Consent String

Our JS Library is fully compliant to TCF v2.0 and it will automatically fetch consent string from CMPs, so there’s no need to pass consent string manually. However, if the WebView does not support TCF API, it’s possible to pass consent string directly to widgets by using the consentString property.

Handling Recommendation Response

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);
    }
};

Prepare a callback function to handle an error response

var outbrain_callback_error = function (error) {
    // Do something with Error
};

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

 

 

Response Field Requirement Description
documents – A wrapper for the recommendations array with the total number of recommendations
doc – An array of returned recommendations objects
doc.content Required The title of the recommendation
doc.url Required The redirect URL of Outbrain. This URL must be used to navigate the user to the outbrain paid recommendation when a user is clicking on paid a recommendation, and can be used for organic recommendations.
doc.orig_url Optional for Organic The original URL of the recommendation. This should not be used to navigate the user to paid recommendations, and can only be used for organic recommendations.
doc.source_display_name Required for Ads  The advertiser name. Be sure to use this source_display_name and not source_name.
doc.pc_id – Returns if the recommendation is a paid link
doc.author Optional for Organic The author of the recommended article. For paid recommendations this field will usually be blank.
doc.desc Optional The Description of the recommendation.
doc.thumbnail – Object that contains thumbnail information, if configured to send thumbnails
doc.thumbnail.url Required The URL of the thumbnail
doc.thumbnail.width – The width of the thumbnail
doc.thumbnail.height – The height of the thumbnail
doc.isVideo – Indicate if the doc is a video recommendation
doc.predictedRpm – The estimated RPM of each ad. It’s not a guaranteed RPM. Ask your Sales Engineer to enable.

 

 

Handling Clicks

Registering a user click is critical for tracking performance and algorithmic optimization. All clicks are registered through the Outbrain redirect (provided in the Outbrain JSON response), even in the case of a user right clicking to open a link in a new tab.

Paid recommendations

When a user clicks on a paid recommendation, it must direct them to the doc.url of that recommendation without any additional redirect URL or UX disturbance. Paid recommendation URLs start with http://paid.outbrain.com/network/redir. This registers a click in Outbrain reporting.

Organic recommendations

 

Option 1: Using doc.url When a user clicks on an organic recommendation, direct the user to the doc.url of that recommendation. Organic recommendations URLs “http://traffic.outbrain.com/network/redir”. Option 2: Using doc.orig_url + doc.url When a user clicks on an organic recommendation, direct the user to the doc.orig_url of that recommendation and report the click by sending a separate request to the doc.url using OBR.extern.callClick() function in parallel.

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

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);

Make a call to the following to catch errors

OBR.extern.callRecs(request_data, outbrain_callback, outbrain_callback_error); // catch errors

A working example is available here

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: "JS_1", installationKey: "DEMOP1MN24J3E1MGLQ92067LH" };

2/ Receive this JSON with recommendations:

{ "total_count": 1, "count": 1, "doc": [ { "source_name": "Web X.0 - Internal", "source_display_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);

VIEWABILITY EVENTS

Widget-Level Viewability (Deprecated)

There is one reportViewed event per Outbrain response. Trigger this event using the function OBR.extern.callViewed() when the top of the Outbrain recommendations become visible in the viewport for a continuous 1 second.

Listing-Level Viewability

There is one on-viewed event per Outbrain listing (multiple on-viewed per response). Trigger this URL when each Outbrain recommendation is viewed by the user. Viewed: 50% of the Listing pixels are visible in the viewport for a continuous 1 second.

Opt Out

Users must have the ability to opt out of Outbrain’s user tracking. Possible exceptions:

  • Application with universal opt-out
  • Notifications which users can block in browser settings
  • Partner Terms of Service includes link to Outbrain privacy policy (Only accepted on Web client side integration and requires Partner Manager Permission)

Please reach out to you Partner Manager if you think one of the above exceptions apply to your activity.

To support Outbrain opt-out:

Add the Outbrain logo plus the AdChoices Icon and make it a clickable link pointing to the Outbrain Privacy Policy URL as stated below.

Outbrain Logo: https://widgets.outbrain.com/images/widgetIcons/OB-Logo-2019-Web-Orange.png

AdChoices Icon: https://widgets.outbrain.com/images/widgetIcons/achoice.svg

Privacy Policy URL: https://www.outbrain.com/what-is/