II. Known Limitation

Endpoint API is not supported along with standard Outbrain widgets

 

III. Supported  Features

1)     Targeting widget recommendations by user*

2)     Editorial tools – Link zapping will only be supported from within the Outbrain dashboard

3)     Tracking clicks*

4)     Conversion pixels*

5)     Calling positions separately (Infinite Scroll/ Endless River) – Client must control; Client will need to send new requests for each position and ensure to increment the data-idx parameter. The different requests for the different positions on the same page must be called sequentially and must contain the ‘t’ parameter in order to enable deduping. 

6)     Context rules – Note that some context rules will require additional parameters to be sent by Client.  For example, a screen-size-based context rule will require the user’s screen’s width and height parameters.zdasdas

7)     Disclosure/Opt out – Client must control; the disclosure will be based on api_user_id. Since Outbrain has no control of the api_user_id, if the user opts-out of the Client’s Outbrain widget, then Client should send Outbrain api_user_id=null instead of api_user_id=<user id>, which will opt-out the user.

8)     Multimedia creatives (Video Overlays) – Client needs to implement; Video recommendations will be flagged as such, allowing Client add additional creatives.

9)     Deduping*

* Features that are subject to the “Known Limitation” detailed in section II above.

 

 

 

 

 

 

IV. Testing

Before launch, Client will be required to direct requests to a test server for Outbrain verification.  The Client’s Outbrain Account Manager will share instructions on getting access to a test server with the client at that stage.

 

V. Integration Basics

 

Outbrain Endpoint API Integration assumptions:

_      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 up-to-date.

_      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). Storing recommendations with the intent of delayed presentation and caching of recommendations is prohibited.

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

_      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.

_      The Outbrain Disclosure and privacy policy must be displayed where they 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. (the Response Fields table and Notes under Endpoint Details).

_      Outbrain cookie values with the latest values from the service must be included in all requests made after a user’s first click on a recommendation.

 

 

 

VI. Endpoint Details

1) Requesting Recommendations

This Endpoint API provides content recommendations from the Outbrain service based on a user’s most recent visit to a piece of content (URL).

Constructing the Request

This endpoint is available by constructing the following URL:

http://odb.outbrain.com/utils/get?url=PERMALINK_URL&widgetJSId=WIDGET_ID&key=PARTNER_KEY&idx=WIDGET_INDEX&api_user_id=APP_GENERATED_USER_KEY&format=vjnc&installationType=server-side-api

Where the following values are replaced:

_      PERMALINK_URL: The permalink for the currently displayed content, URL encoded. For example: http%3A%2F%2Fwww.webx0.com%2F2010%2F07%2Fsome-posthype-thoughts-about-flipboard.html

_      Outbrain crawlers must have access to this URL. This requires:

_      The content of the page to be accessible without needing to execute JavaScript.

_      The server must not block requests from Outbrain’s crawlers, which identify using the following user agent: Mozilla/5.0 (Java) outbrain.

_      WIDGET_ID: The ID of the widget, used for reporting on activity. Your Outbrain Account Manager will provide you with the value for this parameter. For example, “APP_1” For proper tracking of performance and user behavior use a different widget_id for each separate container where Outbrain recommendations are displayed. Contact your Account Manager for additional WIDGET_IDs.

_      API_USER_ID: A unique id that will help us to identify 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.

_      WIDGET_INDEX: The current position of the widget relative to other widgets on the page: 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.

_      PARTNER_KEY: Unique partner key, provided by Outbrain.

 

2) Making the Request

The user agent HTTP header sent in the request must match the user’s User-Agent. 

Another HTTP header that must be sent is the X-Forwarded-For with the user’s IP.

Example; X-Forwarded-For: 233.54.67.45

 

3) Additional Parameters

Some additional parameters are available for various use cases.

_      testMode (boolean): 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.

_      t  (string): 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. 

 

4) Response

The response is returned as JSON. The recommendations are available in the doc array within the documents property at the root of the response. Each response will return multiple recommendations intended to be displayed together, in the same container. If you are installing the Outbrain service on multiple containers of 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.

 

5) 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 redirect URL of Outbrain. 

This URL must be used to navigate the user to the an outbrain paid recommendation when a user is clicking on paid a recommendations, and can be used for organic recommendations.

Please read VI. Handling a click – navigating to the recommendation

doc.orig_url

The original URL of the recommendation. This should not be used to navigate the user for paid recommendations, and can be used for organic recommendations.

Please read VI. Handling a click – navigating to the recommendation

doc.content

The title of the recommendation

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[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

doc.isVideo

Indicate if it is a video recommendation

 

 

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.

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.

 

VII. Handling a click – navigating to the recommendation:

Paid recommendation:

When a user is clicking on a paid recommendation,navigate the user using the Outbrain redirect URL. The redirect URL is represented with the doc.url as part of the recommendation response, and starts with “http://paid.outbrain.com/network/redir”.

 

Organic recommendation:

Option 1: Using Outbrain redirect URL

When a user is clicking on an organic recommendation, navigate the user with the Outbrain redirect URL. The redirect URL is represented with the doc.url as part of the recommendation response, and starts with “http://traffic.outbrain.com/network/redir”.

Option 2:

When a user clicks on a recommendation, navigate to the recommendation using the doc.orig_url and report the click using traffic.outbrain.com endpoint, with the doc.url.

Registering a click is critical for tracking performance and algorithmic optimization. All clicks must be registered through an Outbrain redirect, even in the case of a user right clicking to open a link in a new tab.

The endpoints for registering clicks do not need to be manually constructed; they are provided in the JSON response when requesting recommendations. Simply save the doc.url and use it as your link when a user consumes that recommendation. 

 

 

 

For Web Application installations:

 

 

Widget Request Type

 

 

Client to Outbrain Server

Server to Outbrain Server

 

Request to Outbrain

api_user_id parameter:

 

NA

 

api_user_id parameter:

 

Provide a unique and persistent User ID

 

installationType parameter:

 

Not needed

 

installationType parameter:

 

“S2s”

 

X-Forwarded-For header:

 

Not needed

 

 

X-Forwarded-For header:

Send the user’s IP address

Ex.

 X-Forwarded-For: 233.54.67.45

 

User-agent header:

NA (handled by browser)

 

User-agent header:

Required

 

Response from Outbrain

How to handle paid clicks:

 

Use the “url” value from returned JSON object (Refer to “Section 4 Response”).  This will start with “http://paid.outbrain.com

 

Ex.   

“url”: “http://paid.outbrain.com/network/redir?key=917…

 

How to handle organic clicks:

 

Use the “url” value from returned JSON object (Refer to “Section 4 Response”).  This will start with “http://traffic.outbrain.com

Ex.  

“url”: “http://traffic.outbrain.com/network/redir?key=972…

 

 

 

 

 

 

 

 

 

 

 

 

For Mobile Application installation:

 

 

Widget Request Type

 

 

Client to Outbrain Server

Server to Outbrain Server

 

Request to Outbrain

api_user_id parameter:

Google/Apple Advertising ID

or

“null” (for opted out users)

 

installationType parameter:

 

“App_end_point”

 

installationType parameter:

 

“S2s”

 

app_ver parameter:

 

Specify the version number of your application

 

X-Forwarded-For header:

Send the user’s IP address

Ex.

X-Forwarded-For: 233.54.67.45

 

User-agent header :

 

Required

 

Response from Outbrain

How to handle paid clicks:

 

Use the “url” value from returned JSON object (Refer to “Section 4 Response”).  This will start with “http://paid.outbrain.com

and 

Click must open link in one of the following mobile browsers: 

 

– SFViewController

– Safari

– ChromeCustomTab 

– Chrome

 

How to handle organic clicks:

 

Use the “orig_url“ value from returned JSON object (Refer to “Section 4 Response”)

and

Use “Outbrain redirect URL”

 

 

 

 

 

 

Example JSON Response

{
“response”: {
    “exec_time”: 81,
    “status”: {
        “id”: 0,
        “content”: “Request succeeded”
    },
    “request”: {
        “idx”: “0”,
        “pid”: “23”,
        “did”: “161493740”,
        “widgetJsId”: “AR_1”,
        “req_id”: “4b6b18f800fc00e76c1b52c09bf23715”,
        “t”: “MV85ZmI5MzE3NzJkMDYwNThiNzg2ZWRmMjRmNjExODNmOF8w”
    },
    “score”: {
        “preferred”: “average”,
        “personal”: {
            “score”: 0,
            “rounded_score”: 0,
            “ratings”: {
                “count_users”: 0
            }
        },
        “average”: {
            “score”: 0,
            “rounded_score”: 0,
            “ratings”: {
                “count_users”: 0,
                “wcount_users”: 0,
                “wsum_ratings”: 0,
                “neg_ratings”: 0,
                “pos_ratings”: 0
            }
        }
    },
    “documents”: {
        “total_count”: 8,
        “count”: 8,
        “doc”: [
            {
                “source_name”: “Big4.com”,
                “same_source”: “false”,
                “pc_id”: “12225159”,
                “adv_name”: “Selfserve_Big4”,
                “publish_date”: “2013-01-04 00:00”,
                “orig_url”: “http://www.big4.com/rsm-mcgladrey/mcgladrey-principal-partner-for-risk-advisory-services-job/”,
                “url”: “http://paid.outbrain.com/network/redir?key=17fbf812f733a2bfa892c4216f03ccbf&rdid=161493740&type=EXP_C0/RF_la&in-site=false&idx=0&pc_id=12225159&req_id=4b6b18f800fc00e76c1b52c09bf23715&agent=blog_JS_rec&recMode=13&reqType=1&wid=100&imgType=4&adsCats=1210,-1,-1&refPub=23&prs=true&scp=false&fcapElementId=5822”,
                “author”: “”,
                “content”: “McGladrey :Principal/ Partner for Risk Advisory Services Job”,
                “thumbnail”: {
                    “url”: “http://images.outbrain.com/imageserver/s/2905796/d-big4_jpg-s2905796-109×109.jpg&did=Tz3o0”,
                    “width”: 109,
                    “height”: 109,
                    “imageImpressionType”: “SOURCE_DEFAULT”
                }
            },
            {
                “source_name”: “Web X.0”,
                “same_source”: “true”,
                “publish_date”: “2006-04-21 00:00”,
                “orig_url”: “http://galai.typepad.com/blog/2006/04/quigos_6th_anni_1.html”,
                “url”: “http://traffic.outbrain.com/network/redir?key=2412e3f9bac091d4c23ed3d942735b10&rdid=161493740&type=MRD_/RF_la&in-site=true&idx=0&req_id=4b6b18f800fc00e76c1b52c09bf23715&agent=blog_JS_rec&recMode=13&reqType=1&wid=100&imgType=2&refPub=23&prs=true&scp=false”,
                “author”: “”,
                “content”: “Quigo’s 6th anniversary”,
                “thumbnail”: {
                    “url”: “http://images.outbrain.com/imageserver/s/6/JBLjpbrAkdTCPtPZQnNbEAee-0-109×109.jpg&did=OJ5Qu”,
                    “width”: 109,
                    “height”: 109,
                    “imageImpressionType”: “DOCUMENT_IMAGE”
                }
            },
            {
                “source_name”: “www.zdnet.com”,
                “same_source”: “false”,
                “pc_id”: “10795870”,
                “adv_name”: “Selfserve_Outbrain_janesmith”,
                “publish_date”: “2012-10-23 00:00”,
                “orig_url”: “http://www.zdnet.com/service-helps-small-businesses-build-visibility-for-marketing-content-7000006249/”,
                “url”: “http://marketing.outbrain.com/network/redir?key=ed31508c783519203e27f5bc5c09bfba&rdid=161493740&type=CAD_C0/RF_la&in-site=false&idx=1&pc_id=10795870&req_id=4b6b18f800fc00e76c1b52c09bf23715&agent=blog_JS_rec&recMode=13&reqType=1&wid=100&imgType=0&adsCats=1210,-1,-1&refPub=23&prs=true&scp=false&fcapElementId=5119”,
                “author”: “”,
                “content”: “How to get help your small business build visibility for marketing content”,
                “thumbnail”: {
                    “url”: “http://images.outbrain.com/imageserver/s/1130171/7TFQjHg1GSApJW8XAmugee-0-109×109.jpg&did=RBK1w”,
                    “width”: 109,
                    “height”: 109,
                    “imageImpressionType”: “UNKNOWN”
                }
            },
            {
                “source_name”: “Incion”,
                “same_source”: “false”,
                “pc_id”: “11676649”,
                “adv_name”: “Selfserve_Incion”,
                “publish_date”: “2012-12-11 00:50”,
                “orig_url”: “http://blog.incion.com/WebDesign/essential-features-for-your-website-along-with-web-design”,
                “url”: “http://paid.outbrain.com/network/redir?key=80d6e892d5e7dbfc888d8c9616504337&rdid=161493740&type=CAD_C0/RF_la&in-site=false&idx=2&pc_id=11676649&req_id=4b6b18f800fc00e76c1b52c09bf23715&agent=blog_JS_rec&recMode=13&reqType=1&wid=100&imgType=0&adsCats=1210,-1,-1&refPub=23&prs=true&scp=false&fcapElementId=5592”,
                “author”: “”,
                “content”: “Essential Features for your Website along with Web Design”,
                “thumbnail”: {
                    “url”: “http://images.outbrain.com/imageserver/s/4033696/gNboktXn2yIjYyWFlBDNwee-0-109×109.jpg&did=T7upk”,
                    “width”: 109,
                    “height”: 109,
                    “imageImpressionType”: “UNKNOWN”
                }
            },
            {
                “source_name”: “Web X.0”,
                “same_source”: “true”,
                “publish_date”: “2007-07-22 00:00”,
                “orig_url”: “http://www.webx0.com/great_quotes/”,
                “url”: “http://traffic.outbrain.com/network/redir?key=f2e9326da11b20e7eeca45db2b4594e0&rdid=161493740&type=MV_d/RF_la&in-site=true&idx=1&req_id=4b6b18f800fc00e76c1b52c09bf23715&agent=blog_JS_rec&recMode=13&reqType=1&wid=100&imgType=2&refPub=23&prs=true&scp=false”,
                “author”: “”,
                “content”: “Waiting for the duck”,
                “thumbnail”: {
                    “url”: “http://images.outbrain.com/imageserver/s/6/8ukybaEbIOfuykXbK0WU4Aee-0-109×109.jpg&did=BeeKE”,
                    “width”: 109,
                    “height”: 109,
                    “imageImpressionType”: “DOCUMENT_IMAGE”
                }
            },
            {
                “source_name”: “Ladezign”,
                “same_source”: “false”,
                “pc_id”: “12207935”,
                “adv_name”: “Selfserve_ladezign”,
                “publish_date”: “2013-01-03 03:00”,
                “orig_url”: “http://www.ladezign.com/websitedesign-seo-blog/twitter-thursdays/use-buffer-for-a-smarter-way-to-share.htm”,
                “url”: “http://paid.outbrain.com/network/redir?key=917591d5a714d44b78658a923ea655e2&rdid=161493740&type=CAD_C0/RF_la&in-site=false&idx=3&pc_id=12207935&req_id=4b6b18f800fc00e76c1b52c09bf23715&agent=blog_JS_rec&recMode=13&reqType=1&wid=100&imgType=0&adsCats=1210,-1,-1&refPub=23&prs=true&scp=false&fcapElementId=8953”,
                “author”: “”,
                “content”: “Use Buffer for ”A Smarter Way to Share””,
                “thumbnail”: {
                    “url”: “http://images.outbrain.com/imageserver/s/4323521/kXWR1acU1Et4ZYqSPqZV4gee-0-109×109.jpg&did=Twsql”,
                    “width”: 109,
                    “height”: 109,
                    “imageImpressionType”: “UNKNOWN”
                }
            },
            {
                “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?hl=2”,
                “url”: “http://traffic.outbrain.com/network/redir?key=9729d77c3bf2c284296b8e4e5c5d810d&rdid=161493740&type=MRD_/RF_la&in-site=true&idx=2&req_id=4b6b18f800fc00e76c1b52c09bf23715&agent=blog_JS_rec&recMode=13&reqType=1&wid=100&imgType=3&refPub=23&prs=true&scp=false”,
                “author”: “”,
                “content”: “An alternative Plan B for Microsoft”,
                “thumbnail”: {
                    “url”: “http://images.outbrain.com/imageserver/s/6/lynXfDvywoQpa45OXF2BDQee-0-109×109.jpg&did=RtgJ1”,
                    “width”: 109,
                    “height”: 109,
                    “imageImpressionType”: “TEXT_IMAGE”
                }
            },
            {
                “source_name”: “Web X.0”,

  “isVideo”:”true”,

                “same_source”: “true”,
                “publish_date”: “2008-04-13 00:00”,
                “orig_url”: “http://www.webx0.com/aniboom/”,
                “url”: “http://traffic.outbrain.com/network/redir?key=3fe19d454a8325fbd9aaa73d102494d2&rdid=161493740&type=MRD_/RF_la&in-site=true&idx=3&req_id=4b6b18f800fc00e76c1b52c09bf23715&agent=blog_JS_rec&recMode=13&reqType=1&wid=100&imgType=2&refPub=23&prs=true&scp=false”,
                “author”: “”,
                “content”: “Aniboom & Radiohead”,
                “thumbnail”: {
                    “url”: “http://images.outbrain.com/imageserver/s/6/PpGdRUqDJfvZqqc9ECSU0gee-0-109×109.jpg&did=Tp4qT”,
                    “width”: 109,
                    “height”: 109,
                    “imageImpressionType”: “DOCUMENT_IMAGE”
                }
            }
        ]
    },
    “settings”: {
        “recsTarget”: “\” data-ht=\”morestoriesoutbrain1″,
        “recMode”: “odb_stripDual”,
        “showMp”: false,
        “openNewTab”: false,
        “noRecsBorder”: false,
        “timeCounter”: “0|10000|0”,
        “postSingleRecHTML”: “HO\n”,
        “displaySameSiteTitle”: false,
        “locationString”: “<span class=’rec-src-link’> (<span class=’obClass_$SOURCE_NAME’></span>$SOURCE_NAME)</span>”,
        “widgetStatistics”: true,
        “logLottery”: 1000000,
        “nanoOrganicsHeader”: “hi hi\n”,
        “descriptionDisplayEnabled”: true,
        “whatIsType”: “pop”,
        “apv”: true,
        “preSingleRecHTML”: “\n”,
        “nanoCustomCss”: “.obClass_Web{color:red;}”,
        “postRecsHtml”: “SHOK\n”,
        “preRecsHtml”: “KOKO”,
        “nanoAdsHeader”: “wallaaaaaaaa\n”,
        “sameSourceVisible”: true,
        “stripFlavor”: “rows”,
        “isAdsIcon”: false,
        “raterMode”: “none”,
        “defaultRecNumber”: 6
    }
}}