Integrating Outbrain’s recommendations into mobile or OTT (over-the-top) applications is easy. This guide details how to integrate Outbrain into applications written specifically for these platforms.

Any installation in an application needs certain configuration instructions from Outbrain, so please be sure your Outbrain Account Strategist is involved in your project.

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.

This guide is intended for client to server integrations (invocations of the API directly from browsers or apps). Server to server integrations are not supported. Unverified implementations will be barred from generating revenue.


INTEGRATION OVERVIEW

The integration of Outbrain-powered recommendations into any application happens via web endpoints. There are two endpoints used for the two major components of an integration:

  • Requesting recommendations: This endpoint asks the Outbrain service for recommendations based on a user’s visit to a specific piece of content (identified by a permalink). The response is a listing of recommendations that should be interesting for this user at this time.
  • Registering a Click: This endpoint tells Outbrain that a visitor has clicked on a recommendation that Outbrain provided. 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.


GUIDE OVERVIEW

I. Integration Basics: Basic information about how the integration works

II. Endpoint Details: Defines how to use the endpoints including example requests and responses

III. Sample Code: A sample of Java code that uses the endpoints defined in section 2


I. Integration Basics

Limitations:

  • Endpoint API is not supported alongside standard (regular JS) Outbrain widgets.


Pre-Development Checklist:
Client must agree to these terms before beginning development.

  • No pre-fetching or caching of Outbrain recommendations

  • No hiding Outbrain recommendations

  • Support of user opt-out across platforms


Requirements:

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

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

  3. The recommendations provided by the Outbrain service are time sensitive and must be used immediately. 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.

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

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

  6. Outbrain 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.

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

  8. 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).

  9. 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=, which will opt-out the user.

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


Testing:

  • Installations require Outbrain approval prior to launch. Please allow 2-3 weeks for Outbrain testing and any additional development work by your team to meet Outbrain requirements.


    II. Endpoint Details

    a. Requesting Recommendations

    This endpoint provides content recommendations from the Outbrain service based on the 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 Strategist 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 Strategist for additional widget_ids.
    • PARTNER_KEY: Unique partner key provided by Outbrain Account Strategist.
    • WIDGET_INDEX: The current position of the widget inside 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.
    • APP_GENERATED_USER_KEY 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.
    • VJNC and SERVER-SIDE-API: This is static for all requests.


    Mobile App Parameters

    • Google and Apple Advertising ID: 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. Pass this value to the api_user_id when constructing the request:

      api_user_id=GOOGLE_APPLE_ADVERTISING_ID

    • Mobile Opt-out: In compliance with Google and Apple guidelines, the Google or Apple Advertising ID must be null if the user opts out of ad tracking. This should be tested before submitting your app to Outbrain QA.


    Additional Parameters

    • testMode (boolean): While in development, it is required to pass “testMode=true”. This will prevent any clicks or impressions from having any impact on our system while you are testing and developing. This parameter must be removed 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.


    User Agent Header

    For mobile installs, the user agent sent in the request must match the mobile device. Otherwise, non-mobile recommendations will be returned and Outbrain reporting will not distinguish tablet traffic from mobile traffic.

    The following code snippets will be helpful in getting the user agent:

    Android (Java):

    httpCilent.getParams().setParameter(CoreProtocolPNames.USER_AGENT, System.getProperty("http.agent"));

    iOS (Objective-C):

    UIWebView* webView = [[UIWebView alloc] initWithFrame:CGRectZero];
    
    NSString* userAgent = [webView stringByEvaluatingJavaScriptFromString:@"navigator.userAgent"];
    
    [request setValue:userAgent forHTTPHeaderField:@"User-Agent"];
    


    Infinite Scroll/ Endless River

    Client will need to send new requests for each position and increment the idx parameter. The unique requests for different positions on the same page must be called sequentially and must contain the ‘t’ parameter in order to enable recommendation deduping.


    Response

    The response is returned as JSON. The recommendations are available in the doc array within the documents object.

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

    Example JSON Response

    {
        "response": {
            "exec_time": 46,
            "status": {
                "id": 0,
                "content": "Request succeeded"
            },
            "request": {
                "lang": "en",
                "idx": "0",
                "did": "1106185170",
                "pid": "100",
                "lsd": "0s0ss00s-000s-0s00-0s00-0000s0s00s00",
                "t": "MV8yNGU5ZWFkYWU5MzMwN2RjNWE5M2UyMzBkNDI5NmU4MF8w",
                "pvId": "24e9eadae93307dc5a93e230d4296e80",
                "pad": "4",
                "org": "0",
                "widgetJsId": "APP_1",
                "readerPlatform": "mobile",
                "sid": 1111111,
                "wnid": 172,
                "req_id": "24e9eadae93307dc5a93e230d4296e80"
            },
            "documents": {
                "total_count": 4,
                "count": 4,
                "doc": [{
                    "source_name": "TheHill.com",
                    "same_source": "false",
                    "pc_id": 44860814,
                    "adv_name": "Allison+Partners NY",
                    "publish_date": "2015-09-10 00:00",
                    "orig_url": "http://thehill.com/policy/cybersecurity/253282-poll-clinton-best-candidate-to-defend-us-from-hackers",
                    "rec-cats": [1708],
                    "ads_type": 1,
                    "rec_en_did": "nMsoXjv3pepISxSruEyHrA",
                    "url": "http://paid.outbrain.com/network/redir?p=Y-rjHD__HU27WTb5e2470IyhNKvaF8xBp2s5zCrkxBgbfq83oyUxMptirZe9xdyCgp-X_PBX5K42Lo6dsteTxMVe0KrHf-6oIqzhrUAQrbTQK8bh1ashVKOo7AXx_AxCG99M2XhVYQg2FUC0DDDvryNTfVSzQe_r4OMP62TwFwHTji2a7M8xGpZGKEBpzeQYtXZnSghRCPPAhzHLVWBefX8QIelTTQnDSyyfEoq8SZJUSegpfLGNbSqnMuc_mIKW675RiE7vDuXpdVc4yEG_xvjl2BpKFNbwcKIUo2DpoqLHXvN4SnwF3XH2ROQDqxJV7Vla4k-x389H6GvqCUv2fEkXgPhihLNvZ100FPL0BpIzcN2BQpKGdAiS5rQOrJDMRTp0wcNKt88Rz57MmM7w_axKceVILKsc-WpfAK768tKjiGGm-vd_lbDBqT5KZy0Maudp8b9ULNUj1yDGTxnCWf3Q0mSV16WJibe6Rl7futQMZv87iFH-qtIxaqDh2SihZQxf7zksNAh56MGodHARw5fuU_YA_iGhdSleweJ-vSMoxZUgiSPlMqr71bO8gQNSg5wTrl6LN48DRHwEQJA0xg&c=400b4ad6&v=3",
                    "author": "",
                    "content": "The voters have spoken: Hillary 'Most Qualified' to protect America against cyber-attacks",
                    "thumbnail": {
                        "url": "http://images.outbrain.com/imageserver/v2/s/1v03/a/1ClmdF/32ELW/8HW6/1ClmdF-q4i-200x180.jpg",
                        "width": 200,
                        "height": 180,
                        "imageImpressionType": "DOCUMENT_IMAGE"
                    }
                }, {
                    "source_name": "Route Fifty",
                    "same_source": "false",
                    "pc_id": 44767202,
                    "adv_name": "Selfserve_katezevnik",
                    "publish_date": "2015-09-11 00:00",
                    "orig_url": "http://www.routefifty.com/2015/09/baltimore-mayor-wont-run/120827/?oref=ob",
                    "rec-cats": [1708],
                    "ads_type": 1,
                    "rec_en_did": "SEyWf2XDOATk7_FlAquo5A",
                    "url": "http://paid.outbrain.com/network/redir?p=rLZ9g3vMga6S7pXm4OxzmMomFcn19UxuF5NNfhS1wkly3NzmxRBrPJ4uNlPN0OBICJz6Mvqkus2PsbrdRRzT4R4uAguFsZfYxR1qTfe1v3GXDm1r_Ullco3qqctlXHPGy4ZCvCaJ72MHNycq0bpM-aR3VN9a2PMFrXc43O6N_mVo8TJT9KB3dfolLBUjhOs28DQxJGa3vutXTTZrOVd_sR2RHq9mcULNQ5csm6CgVA1p65HwJ6cGP7s2lBYhH8SpaIuUd2SUP4wnAiTYoOoi42f7FfL9hRnEeT3D5pVo0Yip-jk7RbYb7MfirEH9GXE_gzmHp0PQwQceH5xOZ4gNCMRzDSbAAhmhuZu22D8Mhl1Axxbs8wkzVwCkXLDYNi9WIZELhije6RVdwGQSWeUegCnjPNeF70PifymujnvErexV6UAT_lg6ll-uCuRvyhuExQ33eK5x8bToexTJOMw3mXmvdc1AnMl_ulPLUbAoyUzesXYIFZ7JpKMh_DYeW_k0yfEQtVoZx39b9PL5q_eYAC-5kJLtiph5lNljrtwi_JKZF6k7Ez3BbuzUklsMBDah1IzpgTerRpalinN8iDTe9Q&c=7b6a6793&v=3",
                    "author": "",
                    "content": "Why is Mayor Rawlings-Blake Bowing out for Reelection?",
                    "thumbnail": {
                        "url": "http://images.outbrain.com/imageserver/v2/s/Mvig/a/1CckB3/31pze/8Bzu/1CckB3-q4i-200x180.jpg",
                        "width": 200,
                        "height": 180,
                        "imageImpressionType": "DOCUMENT_IMAGE"
                    }
                }, {
                    "source_name": "Unilever brightFuture",
                    "same_source": "false",
                    "pc_id": 44569793,
                    "adv_name": "Unilever brightFuture",
                    "publish_date": "1969-12-31 19:00",
                    "orig_url": "https://bs.serving-sys.com/BurstingPipe/adServer.bs?cn=tf&c=20&mc=click&pli=14628103&PluID=0&ord=[timestamp]",
                    "rec-cats": [1505, 1505, 1602],
                    "ads_type": 1,
                    "rec_en_did": "9ggQm2zDlDdZse2jCJ0eHg",
                    "url": "http://paid.outbrain.com/network/redir?p=s9dcgdjpPN77lTUrdvtvshJOzkBcUs4q0yCJDc3rWp1zw3bTlufyG0Z0wN3PG1APBSCPOln4M11p6Emjfx00gWzOIzxJ4NvTMniBlok38oegPPusEP665eKipLzyJhwVba8aEzs964EAIoWCn3IwDJYaYnXzxrJPBCw3YJw-PTI5aQundENnHGyvZe9gL4-0SIHg_4kXzu5hbnwB6T5BH_OfQgPvmI3GkYXam8Ohk_8l-a8rMI9yAayZZjGgBUuUMn0WjnFeVADO2helP_DWChZjMewJd1DQVNQIBxWMjYs7W5Z2cbcNd7u_tM9wTwqJ5cmMnXF6RbuqyJb-v_0Ne47nfx1u73xW9telyJNL1cmFUgL7DMCA_B4UVcm3RhwJN-ePKXZ9f8MGBCE6uP0j5smlXQ7fgEF2fP2hSS1J8EsL4M4mrFiJbWs1lCfI55aIwrWyQFBcCTCfqVOLbZ2kCxbwFnDha_Zzp1H71yDEZ8sCZV16vLOpAUyyWfQnD9GZRfFgkfpq_RYneFb45TIJJLeq0LNi04rExF3amlH5KYy-yBH_o-lc6YjdIYG5na560QkeYM0j4xrFL7_f4p4oFw&c=b382410b&v=3",
                    "author": "",
                    "content": "These 4 Surprising Products Come From Trees",
                    "thumbnail": {
                        "url": "http://images.outbrain.com/imageserver/v2/s/Mwqk/a/1CGrA8/310dd/80am/1CGrA8-q4i-200x180.jpg",
                        "width": 200,
                        "height": 180,
                        "imageImpressionType": "DOCUMENT_IMAGE"
                    }
                }, {
                    "source_name": "Petco",
                    "same_source": "false",
                    "pc_id": 44291071,
                    "adv_name": "Petco",
                    "publish_date": "2015-08-19 00:00",
                    "orig_url": "https://community.petco.com/t5/Blog/The-Scoop-on-Small-Animal-Poo/ba-p/59884?utm_source=outbrain&utm_medium=referral&utm_content=the%20scoop%20on%20small%20animal%20Poo&utm_campaign=nutrition",
                    "rec-cats": [1805],
                    "ads_type": 1,
                    "rec_en_did": "q5-L34ilh3meEtim1f_oxw",
                    "url": "http://paid.outbrain.com/network/redir?p=3rC3KW5ClRUoOf91U1Jy8_EP5AV1Gel-sBuyv6iAj_45v5ktKoqPNIDKRn2fy64q6OcQP3hF9M1g8MtIJOYV-kZv4k_E3H46LLzIpllhZK7fwd4Tr5o_yAJ2jQhH28bF4Kh4kINqiRcBD2s0XtFjD8mL8FqZ8UI4Jq14tfdPbQTpHNT-gXlKzgK7XKJK-UNsXDvl3jhu3H2-4rhKkMjzjNl1HCd8BHEWrc-JRkMFphzsim2n0slsH2gtSw8Sq4dTQFOygDe69nIO8HZcUOiSBoKZr7te2TbVgiPrV0lcmTsh2BchPQvIcQws7PK7xGj3yRj6Z7lmin7ZOE4B7DpROWhdLadgs6OxOxuyNGDDUhcgYeVl3mMKwEoadHF_-tfaz0l5XmsPAD390SQSceUZUzuavjonR_Y4pxZj7nCgYrCMgjGFBGnQxjr9SOJqxK48N8mRUDYxoqjQbsrWzwU36jEbmmyQcXmkuzQnzJOG-EnjaT6GUkKCXNh1mjwjSdIfJ7T314F6vZMPAubu183uO1t9_VCWaoNta2j38v8dK-06_j_QSdjmk6fBVsGJf7g1HFbxVOfkhsLavKHC0dI0tA&c=6e62eb9a&v=3",
                    "author": "",
                    "content": "Pet Poo Chart: Is Your Pet's Stomach Doing Okay?",
                    "thumbnail": {
                        "url": "http://images.outbrain.com/imageserver/v2/s/MXKZ/n/1B29lA/abc/17VCEL/1B29lA-q4i-200x180.jpg",
                        "width": 200,
                        "height": 180,
                        "imageImpressionType": "DOCUMENT_IMAGE"
                    }
                }]
            },
            "settings": {
                "flagPublisherZappingFeature": true,
                "recMode": "odb_jsonData",
                "globalWidgetStatistics": true,
                "apv": true,
                "InstallationType": "mobile-app-api"
            }
        }
    }
    
    

    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.
    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 b. registering a click, 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.


    b. Registering 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.