Overview
Testing & Outbrain Verification
New Partner Requirements
Integration Basics
Requesting Recommendations
The Outbrain Response
— Response Fields
— Tracking and Viewability Actions
— Sample JSON Response
Handling Clicks: Navigating To The Recommendation
User Opt-Out
Overview
This document explains how to use Outbrain’s Endpoint API for server-to-server integrations. It is imperative to adhere to these instructions. Deviation from this guide can result in lost revenue.
Contact your Outbrain Account Manager if you have any questions about the requirements described in this document.
Testing & Outbrain Verification
Before launch, your app will be required to direct requests to a test server for Outbrain verification. To do so, pass “&testMode=true” in the Outbrain request URL. This will prevent clicks and impressions from having any impact on our system while testing and developing.
A test page or finalized build must be sent to Outbrain QA a minimum of 5 business days before your anticipated release date. We may request changes which will require additional development resources and could delay your release.
Outbrain reserves the right to remove our recommendations or restrict the widget from generating Outbrain revenue if required changes are not incorporated prior to release. Contact your Account Manager for submission instructions.
New Partner Requirements
Review all Outbrain compliance requirements listed here and flag any concerns/exceptions with your Partner Manager and Sales Engineer immediately.
Requesting Recommendations
Outbrain’s Endpoint API provides content recommendations based on a user’s most recent visit to a piece of content (URL).
Constructing the Request URL
The Endpoint API request is made by constructing the following URL:
https://odb.outbrain.com/utils/get?url=[PERMALINK_URL]&widgetJSId=[WIDGET_ID]&key=[PARTNER_KEY]&idx=[WIDGET_INDEX]&api_user_id=[UNIQUE_USER_ID]&format=vjnc&installationType=server-side-api&va=true
Request Parameter Overview
| Parameter | Description |
| url | The URL-encoded permalink to identify the currently displayed content. Example: http://www.partnerDomain.com/currentSiteName?oburltocrawl=https://www.referringSite.com/encodedArticleURL * Note: oburltocrawl needs to be URL-encoded as a separate parameter, so it will be double encoded. ** The server must not block requests from Outbrain’s crawlers, which can be identified by the following user agent: Mozilla/5.0 (Java) outbrain |
| widgetJSId | The ID of the widget, used for reporting on activity. Your Outbrain Account Manager will provide you with the value for this parameter. Widget_IDs have a specific number of recommendations and image size associated with them. |
| api_user_id (desktop) | A unique user ID that identifies the user during the application session. This must be provided by the hosting application, and can take any type of value or format. This functions similarly to user identifying cookies on the web. See User Opt-Out instructions. |
| api_user_id (mobile) | It is mandatory to pass the Google or Apple Advertising ID for Outbrain mobile installations, according to Google and Apple guidelines and developer agreements. See User Opt-Out instructions. |
| idx | The current position of the widget relative to other widgets on the page: The first unit on page will have idx=0 while the second unit will have idx=1 and so on. For pages/views with only one widget installed, use idx=0 for each request. |
| key | Unique partner key, provided by Outbrain. |
| location (optional) |
The 2-letter country code of the user’s location: location=US
Warning: Do not send this parameter in production if you are sending the X-Forwarded-For header with the user’s IP. |
| testMode (optional) | While you’re developing, we recommend that you pass “&testMode=true”. This will prevent any clicks and impressions from impacting the Outbrain system while testing and developing. Please remember to remove this parameter before releasing to production. |
| extid (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. |
| t (optional) | This token (the ‘t’ value) is returned from the server on every request and should be used in any consecutive request on the same page. The first request on the page should have idx=0 and no ‘t’ value, while the second request on the same page should use idx=1 and send the ‘t’ value returned by the first request. |
| secured (optional) | For HTTPS support, add “&secured=true” to the request. |
| cmpStat (optional) | Indicates whether the request needs to be treated under GDPR compliance. Value = 1, assumes the request is from a site/app that is always under GDPR. Value = 0 (or no value) individual determination if subject to GDPR or not based on IP Address lookup and Country of the request. |
| cnsnt (optional) | Base64-encoded consent string, as defined by the IAB. If not received (and GDPR is applicable, cmpStat=1) it is assumed no consent is given. |
| ccpa (optional) | 4-character consent string, as defined by the IAB. See U.S. Privacy String. Send 1 character each for Specification Version, Explicit Notice, Opt-Out Sale, and LSPA. Ex: 1YNN |
The Request Header
Before sending the request, the following HTTP header changes must be made:
| Field | Description |
| User-Agent | Pass the user’s UserAgent. |
| X-Forwarded-For | Pass the user’s IP address. Example: X-Forwarded-For: 233.54.67.45 |
The Outbrain Response
After the request is made, Outbrain returns the recommendations in a JSON response (see Sample JSON Response). The recommendations are available in the doc array within the documents property at the root of the response.
Each response returns multiple recommendations intended to be displayed together in the same container.
If you are installing the Outbrain service on multiple containers on the same web page, please ask your Account Manager for additional widget IDs (e.g. HP_1, APP_1, APP_2) for use in each distinct container. Your Account Manager can instruct you on how to track the performance of each Outbrain widget.
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.content | [Required for display] The title of the recommendation 3 |
| doc.source_display_name | [Required for display] The advertiser name. Be sure to use source_display_name and not source_name. |
| doc.pc_id | Returns if the recommendation is a paid link 1 |
| doc.url | [Required for links navigation] 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 2 |
| doc.orig_url | 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.author | The author of the recommended article |
| doc.desc | Custom values set within your web page 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 4 |
| doc.thumbnail.url | 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 |
Tracking and Viewability Actions
The JSON response includes a set of postback URLs that must be triggered on specific events.
Note: If you are unable to support these actions, notify your Partner Manager.
Widget Level
| Field | Required | Description |
| reportServed | True | This event is used to report Outbrain PVs/impressions. Trigger this URL when the Outbrain response is received and rendered on the user’s device. Note: This postback expires after 3 minutes. |
| reportViewed | True | Trigger this URL when the Outbrain recommendation is viewed by the user. Viewed: 50% of the Widget pixels are visible in the browser window for a continuous 1 second. |
Listing Level
| Field | Required | Description |
| on-viewed | True | Trigger this URL when the Outbrain recommendation is viewed by the user. Viewed: 50% of the Listing pixels are visible in the browser window for a continuous 1 second. |
| pixels | True | Pixels are required to support Advertiser/Marketer activity tracking. Response may include multiple pixels, please notice all pixels must be supported. Note: Limited support for pixels may lead to restricted activity |
| jsTrackers | True | JS Tracking pixels are required to support Advertiser/Marketer activity tracking, verification and authentication services Response may include multiple pixels, please notice all pixels must be supported. Note: Limited support for pixels may lead to restricted activity |
Sample JSON Response
outbrain.returnedJsonData(
{
"response": {
"exec_time": 18,
"timestamp": 1568105594265,
"status": {
"id": 0,
"content": "Request succeeded"
},
"request": {
"lang": "EN",
"idx": "0",
"lastIdx": "9999",
"lastCardIdx": "9999",
"did": "2037471612",
"pid": "8337",
"lsd": "db87b8ec-1d06-4057-8199-aa61b69c8c86",
"enu": "6nZAyEc0R6_s3k1T_GsXm-97CJMpF-bSMk-fX-hZmsS_sWTK5VRmoKJvusKAZ_n7",
"t": "YTZmODI3OTlhZmZjNmU4YjI5MDcwMjM4MjE2NzgyODY=",
"pvId": "a6f82799affc6e8b2907023821678286",
"pad": "1",
"org": "0",
"abTestVal": "no_abtest",
"obRecsAbtestAndVars": "532-1682,596-1902,583-1856",
"widgetJsId": "AR_1",
"readerPlatform": "desktop",
"isHttps": "true",
"rtbTest": "false",
"rtbBidTestMode": "false",
"rtbTestRecsNum": "0",
"amplifyEnabled": "true",
"gdpr": "0",
"scrW": "2560",
"scrH": "1440",
"winW": "370",
"winH": "920",
"sid": 6676911,
"wnid": 100,
"req_id": "a6f82799affc6e8b2907023821678286",
"gl": "Lmh4LbF5Bj8uwm_0yxXY3g",
"vid": 0,
"ref": 0
},
"documents": {
"total_count": 1,
"count": 1,
"doc": [
{
"on-viewed": [
"https://log.outbrainimg.com/loggerServices/log-viewability?requestId=a6f82799affc6e8b2907023821678286&position=0"
],
"source_name": "CNN",
"same_source": "false",
"source_display_name": "CNN",
"pc_id": 136178592,
"adv_name": "Selfserve_meden",
"publish_date": "2019-09-08 00:00",
"orig_url": "https://edition.cnn.com/2019/09/08/tennis/bianca-andreescu-us-open-serena-williams-tennis-spt-intl/index.html",
"rec-cats": [
1913
],
"ads_type": 1,
"rec_en_did": "bjVQMWy1_aVKJgzIIM8ftQ",
"url": "https://paid.outbrain.com/network/redir?p=DIbkcScn1O1Wt6ogzQMhyihdL7g-DYWZ3oynJ_2J3u-05wOW9jT_PIQ31Sxmtrm32wErwBqJBTTQoe66eIp6RoAyvofDbz29te1xnFuYbB93Gb8BvpS04Rt4n_x4eaSA3ze6oV_Il1YwJ4AQ_nl-wUi2wbuKfeFRWSvLBao_0op2fwxUIdHGpF7UAC_bKcVxkhMejRODEmaLXF4bi9c2sVkOW9pPElz94HUo6pRexQdaa-fTz6DQEspLnjd5cbzBp6bKLDUC8gmt_P9v04VCvApW9CF1gDFAZYO8KR0-ianewYxMFR24Dal6jFEmwsTiDBMPLi29FFuhuuRHv3oZchR6CqxHoTMZJT8kgAfY4Fmz19jO7wt8ol3-Biwyb6fR14lBnbvUqXjNFr5g9cGdIvmGp3gztstZJb45PEIbuY1oX-6FuzZCHZhnQxef9aCOqs4kSv-3OdrJbwg9nDU1FwEKHzt3w7KsbsPyxDfXavLwwp1FzPtaDbb_VKHFnexR4Y0bnoKEYI-fAyuX0TMa3cFljYsaQQu3fW4pweO4BrHrZ7g17Td9JEsD2W3Vg7H3ZkZXKWOsjFsv5OLbUZrOOl4zk4y0iLkYAewRKaJOCUhnjmqLNLcWRHdrNjHe64H3zeWy7RsKQgRKA_oOHb6ah7wjeU7tH0mB9zykMWifXIz6SFK6Q3iGO0LZ4XXEUg6nNFKz5EWiM4ud_cn8kEvQkbOgl46nWoq-pPriiWw5JgPB4tZclvq3-p694xd8c0XqLTfd3TGccl7Gn-6YSmVchTLnnbNCw-uJ526Jb-DbTuMh_tp4WfeH3xyvAtbjze4EjiKc8CjcJGH3EpTRDLl3byfd13Ra1VrS0EwgcsMUpDEWfQri4lcIOsT8Fu3BpJRFaWlMe8AZ2dUVTR3IqVQ8pthm7shE6j2u_4NzkNRX5Oq8ztyv8rA5yQB7tfo5cZobAXQoGGwzLw23KoEykVx2dalyXYhqccYGLQVpcrpHQ_-MklDnSyuwFn4gbv0BXjHW7Dj9YQUcysJuf5v5lrfgNmctJCZwQLt6CDjQLM3ZOeHv0X_VGdgS6cHAOmelt3-oNm-BNRM2zjy1dW_YIiR2KH1yq3nkk8IEvwBC2DH_esh-XomHwMqRC7Y1uc9DamWUCCcWt0uGk2XhO9DkZl0DpRL5-HfYIvFtT2pTTAgDtyxoB9m7H-yfbdszOwsMZEBcwZ3ey2ivohdimhwJcZGM5ETnVn5Gf2XBgkauRpHiZ87gJlQYNizTjK3XDsS5rRUT&c=80f07eef&v=3",
"author": "",
"content": "Bianca Andreescu: How a fake check inspired the US Open champion",
"pc_cmp_id": 1002332188,
"pixels": [
"https://www.pixel1.com?obRequestId=HBanhEIY3a_2mWt3Ysg7Ke34n8k2QVwD-3FLVEeG0gNoP1boaU8-J45L_2pX3KQp&obTimestamp=1568105594278"
],
"pos": "0",
"ttid": 3,
"jsTrackers": [
"https://cdn.doubleverify.com/dvtp_src.js?obRequestId=HBanhEIY3a_2mWt3Ysg7Ke34n8k2QVwD-3FLVEeG0gNoP1boaU8-J45L_2pX3KQp&obTimestamp=1568105594278"
],
"advId": "13604",
"thumbnail": {
"url": "https://images.outbrainimg.com/transform/v3/eyJpdSI6IjZjM2JlNmVjZDY5Nzc5Yjk1NzNkMTVhNGE2NWQ1Yzk1ODAzODdlNjk0OWI3MGYzNDVkZWRhYTY0YTA1M2QxOWIiLCJ3IjoxNTAsImgiOjE1MCwiZCI6MS41LCJjcyI6MCwiZiI6MH0.jpg",
"width": 150,
"height": 150,
"imageImpressionType": "DOCUMENT_IMAGE"
}
}
]
},
"settings": {
"flagPublisherZappingFeature": true,
"recMode": "odb_dynamic_strip",
"sameSourceVisible": true,
"dynamicWidgetDirection": "LTR",
"apv": true,
"DesignType": 5,
"listingsViewability": true,
"whatIsBrandingType": "Logo + copy",
"displaySameSiteTitle": false,
"dynamicImageHeight": 150,
"dynamicWidgetLayout": "strip",
"openNewTab": false,
"defaultRecNumber": 4,
"globalWidgetStatistics": true,
"fraudDetection": 2,
"raterMode": "none",
"dynamicImageWidth": 150,
"isVisualCuesEnabled": false,
"Paid.Quality.SensitivityExponent": 3.0,
"dynamicTruncateText": true,
"isUIExperimentsEnabled": false,
"wsSampling": 20,
"dynamicSourceFormat": "$SOURCE"
},
"viewability_actions": {
"reportServed": "https://mcdp-chidc2.outbrain.com/l?token=a6f82799affc6e8b2907023821678286_8337_1568105594282",
"reportViewed": "https://log.outbrainimg.com/loggerServices/widgetGlobalEvent?rId=a6f82799affc6e8b2907023821678286&pvId=a6f82799affc6e8b2907023821678286&sid=6676911&pid=8337&idx=0&wId=100&pad=1&org=0&tm=0&eT=3"
}
}
}
Handling Clicks: Navigating To The Recommendation
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.
Use the doc.url as your link when a user clicks that recommendation.
Paid recommendations
When a user clicks a paid recommendation, direct them to the doc.url of that recommendation. Paid recommendation URLs starts with “http://paid.outbrain.com/network/redir”.
Organic recommendations
-
Option 1: Using doc.url
- When a user clicks 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 a recommendation, direct to the doc.orig_url of that recommendation and report the click by sending a separate request to the doc.url.
Browser Requirements
For desktop apps: Recommendations must be opened in a standard web browser.
For mobile apps: Recommendations must be opened in one of the following browsers:
* Safari
* Chrome
* SFViewController
* ChromeCustomTab
User Opt-Out
Outbrain serves personalized recommendations to users based on their history. Users must have the ability to opt out of Outbrain’s user tracking.
Implementing Opt-Out (Desktop)
Option I: Internal Opt-Out Managed by Publisher
-
If there is an opt-out option in the application, pass “&api_user_id=null” in the Outbrain request for users who have opted out.
-
If the Outbrain logo & privacy policy link is not displayed alongside the Outbrain recommendations, you must include a link to https://www.outbrain.com/what-is/ in your internal privacy policy as agreed upon with your Outbrain Account Strategist.
Option II: Outbrain-supported Opt-Out
- Add the Outbrain logo and make it a clickable link:
Logo: https://widgets.outbrain.com/images/widgetIcons/ob_logo_67x12.png
AdChoices Icon: https://widgets.outbrain.com/images/widgetIcons/achoice.svg
Link: https://www.outbrain.com/what-is/?uid=UNIQUE_USER_ID
The user’s unique identifier must be passed in the uid parameter. This is the same value specified in api_user_id.
2. Place the link in the upper right hand side of the widget placement, as shown in the attached example. The “Recommended by” text is optional.
3. The link must open in a web browser which will take the user to Outbrain’s official opt out page. User’s can see their current opt out status, read through Outbrain’s privacy policy, and choose to opt in/out of user personalized recommendations.
Implementing Opt-Out (Mobile)
In compliance with Google and Apple guidelines, if the user opted out of ad tracking, pass “&api_user_id=null” in the Outbrain request URL.
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 is required. Please read Handling Clicks: Navigating To The Recommendation
3 The use of headlines other than the text returned in the doc.content object is prohibited.
4 The use of thumbnails other than the image returned in the doc.thumbnail object is prohibited.