I. Initial Set Up: What your account strategist needs before testing.
II. The Outbrain JS: What our code looks like and how to install it.
III. Indexing URLs & Learning About Content: How we index your site and learn about your content.
IV. Testing and Styling: How we validate the code and implement styling.
V. Launch

Appendix A: Supported Microdata
Appendix B: Mobile App Compliance Requirements
Appendix C: Dynamic Widget Loading


I. Initial Set Up

Here is a list of items your account strategist will need in order to prepare your site for launch:

  • Where do you plan to install Outbrain?
    Outbrain supports multiple page types such as articles, blogs, slideshows, and videos.
  • What areas of your site would you like to recommend in the Outbrain widget?
    Outbrain can set up content whitelists if you only want to recommend specific sections of your site.
  • What do you want the Outbrain widget to look like?
    Our widget is a humble guest on your page and will inherit CSS to remain consistent with your site design. If you have something specific in mind, let us know. You name it, we can probably do it.
  • Quality image file of logo.
    Send us a high-quality file of your site’s logo and we’ll attach it to any article that doesn’t have a thumbnail. That way great, image-free content gets the chance to shine in image-based widgets.


II. The Outbrain JS

You can start working with the code as soon as the initial set up is complete. We take the quality of our products very seriously. Every pixel and line of code we download to your page has an essential function. Here are a few facts that illustrate our commitment:

  • The Outbrain widget JS is lightweight and uses Google Closure Compiler to optimize our JavaScript into compact, high-performing code.
  • When serving thumbnails, we only serve images in the exact size of the thumbnail, which means our total impact on page size and load time is minimal. We also load images and other resources only when needed.
  • Our widget loads asynchronously, and therefore will not delay page loading.
  • We pre-render most of the widget logic on Outbrain servers to reduce client-side effort.
  • We use CDN and browser cache for JavaScript, to optimize our response time and improve security.

Beyond the proactive measures we have taken to minimize our impact on publisher page load (read more here), please also check out our tips to help you speed up page load when implementing Outbrain widgets.


Please Note With the installation of the Outbrain JS you can run Smartfeed™, Smartlogic™ and Keystone™.

Implementing the code involves two simple steps:

    1. Implement the widgets integration code:
      Place the code your account strategist provides in the area of your site where you would like our widget to appear. Please note that your setup may require multiple pieces of code.Here is a typical example of our code:

      <aside><div class="OUTBRAIN" data-src="DROP_PERMALINK_HERE" data-widget-id="WIDGET_ID"></div></aside>
      <script type="text/javascript" async="async" src="https://widgets.outbrain.com/outbrain.js"></script>

      * This code is not for use on your site. Your account strategist will provide you with the proper WIDGET_ID values for each placement.

Accessibility note: In order to comply with WCAG (Web Content Accessibility Guidelines), we recommend you wrapping our <div> tag in an <aside> tag as above example.

  1. Populate mandatory attributes of data-src and data-widget-id:
    Pass a dynamic value with the data-src attribute (highlighted above). This value should be the URL of the page on which the widget is loading.We recommend using the canonical or og:url of the page, as long as one of these is consistently used across the site. A couple of reasons why canonical and og:urls are great:

      • Outbrain won’t crawl URLs with extraneous parameters like marketing codes, sessionIDs, referrer strings, etc. Crawling URLs with any of these parameters causes duplication in our system and prevents us from being able to serve the best recommendations to your readers.
        ✗  http://m.nypost.com/;s=C1RQpzi9IBXYhst_quWLp36/f/mobile/news/local/newark_tsa_bomb_boozled_


    • Outbrain will only crawl the first page of a multi-page story, which also prevents us from recommending any of the secondary pages in your widget. This is particularly relevant for slideshows.


    If you don’t use canonical or og:urls and cannot implement them, the href location is your next best option.

    Your account strategist will provide you with the proper WIDGET_ID values for each placement to send with the data-widget-id attribute.


Security Provisions for attribute values:

It is always preferable to populate the attribute values on the server side and not on the client side. When you must populate values on the client side (e.g. using document.location as the data-src value), you need to validate the input by either encoding it or using some custom validation (e.g accepting only url data prior to # sign). Failing to do so may enable an attacker to inject scripts to your page.


Optional attributes

Besides the mandatory attributes of data-src and data-widget-id there are some additional attributes that can be added to the div if necessary. Please talk to your account manager before using those.


Attribute Name Requirement Description Example value
data-external-id Optional A unique key for report breakdowns. See Engage External Id Report API for details “123abcXYZ”
data-external-secondary-id Optional A secondary key for Engage External Id Report breakdowns as same as external-id. “456defABC”
data-click-url Optional An image pixel URL for tracking clicks on paid recommendations on your side. This click url will be fired as an img once the user clicks on a paid recommendation. “https://yourdomain.com/click?123”
data-consent-string Optional: Only if TCF API is not available. Base64-encoded consent string, as defined by IAB for TCF v2.0 “CO4SiGQO4SiGQAGABBENAzCgAP…(omitted)…YAAAAAAAAAAA”
data-ccpa-string Optional: Only if US API is not available. Four digit US privacy string, as defined by IAB for CCPA compatibility. See about IAB CCPA Compliance Framework here “1YNN”
data-ob-test Optional A boolean flag for testing. Set to true to avoid registering clicks and impressions with Outbrain during development and troubleshooting. This attribute must be removed before releasing to production. “true”
data-ob-ppid Optional

A passed string can represent both the publisher’s first-party IDs and universal IDs. These can be utilized alongside existing user identifiers (our OBUID and universal ID solutions), enhancing addressability and enabling strong audience segmentation.



III. Indexing URLs & Learning About Content

We use the data-src value for two purposes. The first is simply to index the URLs from your site. Outbrain crawls a URL the first time our JavaScript loads on the page. The second is to learn about content on that page.

Indexing URLs:

In order to recommend organic content from your page Outbrain needs to index / crawl your articles. By default this will happen for each page where an outbrain widget is loaded. This way we are automatically understanding all new articles once you are live with the Outbrain widgets on your pages.

During onboarding (when Outbrain widgets are not live yet) Outbrain needs to index your sites pages before launch to ensure the best possible performance with organic recommendations on day one. Indexing in advance also gives us recommendations to display during the testing process.

Here are the ways we can crawl your site before we’re live:

  1. Option A: Implementing a hidden widget in production (preferred method)
    You may add our widget integration code into you production pages with us preventing any visible widget to be rendered into your page. In this scenario, we would hide the widget on our end and just use the code for the purpose of indexing URLs. This means that you could roll the code out to production before the testing phase is complete. 
This also allows us to get a lot of the data needed to better inform our recommendations. Without this data, the recommendations may not be optimal for the first day or two in production. This Option is our preferred best practice for onboarding new partner sites to Outbrain.
  2. Option B: Crawling from RSS Feed
    We can crawl your article also from a valid RSS feed. If you have a list of RSS feeds, please send it to your account strategist.
  3. Option C: Crawl from Sitemap or list of URLs
    No RSS feeds? No problem. We can also use a sitemap or list of URLs.
  4. Option D
    If none of these options are feasible, we will crawl your site whenever the code launches in production. In this scenario, the widget may take a few hours to fully populate with recommendations.

Learning about content:

Outbrain will also crawl information about the URLs we are indexing in order to serve more interesting and relevant recommendations to your readers.

Here’s a list of what we look for:

  • Title
  • Description
  • Publish Date
  • Image
  • Author
  • Content

The best way for us to gather this information is via microdata, like Google’s Schema and Facebook’s Open-graph, or via Outbrain proprietary tags. We highly recommend deploying one of these options across your site and have provided tag examples for each of the above attributes in Appendix A.


IV. Testing and Styling

Now that we have indexed your content and know where to pick up important information, we can begin testing. This process is for validating code and styling the widget(s). Please make sure that the placements and page types in testing mirror the eventual experience in production. Also note that the recommendation results in testing do not reflect what will come through in production since we will not have all possible behavioral data yet.

If you have a test environment …
You will need to do the following in order for the Outbrain widgets to work:

  • Whitelist our crawler IP addresses and user agent (your Account Strategist will provide both sets of IPs if needed). If your test environment is behind a firewall and our crawlers don’t have access, the widget won’t work. Please contact your account strategist for the most up to date crawler IP information.
  • Grant your account strategist access to the test environment. The fastest and most reliable way for Outbrain to validate the code and style the widgets is to do so directly in testing. If needed, your account strategist can provide you with our office IP addresses.
  • Pass production permalinks in testing. It’s ideal if you can pass production URLs into the data-src variable in testing, either dynamically or hard-coded. This prevents us from indexing your test domains. This step is not a requirement for the widgets to work, but streamlines the process and ensures a faster styling turnaround.

If not, don’t worry…
Outbrain can also work without a proper dev site:

  • We can hide the recommendation results so that you can launch the code directly in production. Outbrain has our own shareable draft environment where the results will be visible. We can use this environment to finalize styling and guarantee everything is functioning correctly. See Option A in III. Indexing URLs & Learning About Content
  • You can launch the code visibly on one low-traffic production page.

Once your account strategist has a working test page…
She/he can begin implementing the UI upon which your teams agreed in I. Initial Set Up!


V. Launch

Once Outbrain has validated everything in testing, you can push our JS to production! Just let your account strategist know the expected date and time of launch. If you encounter any issues post-launch, please contact your account strategist.

If you implemented the hidden Outbrain widget directly into your live page, the widget will be pushed live from our side in coordination with you.