Appendix C: Dynamic Widget Loading

Dynamic Widget Loading

In some circumstances you might want to inject widgets on the page dynamically related to user actions. Since the regular flow is designed for more static placement on initial page load, this might need some workaround.

Understanding the regular flow

When outbrain.js script is loaded in a page, it starts to look for widget containers in its HTML until the DOM is ready. All containers that were found in this process are marked and requests for recommendations are made for each of them and rendered accordingly. In case the container lookup needs to be triggered after the regular process has finished, we support following methods.

The outbrain.js script must be loaded prior to the use of these methods. Recommended to be placed statically under tag.

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

Research method

It will look again at the DOM for empty widget containers that were not found in the initial lookup and make request for additional recommendations. The widgets found by this method will be considered as the same page view of the initial page view.

Use cases: Dynamic widgets load on the page after the regular flow. e.g.) Lazy loading, Infinite Scroll pages, etc.

Example steps
  1. Initial page load together with outbrain.js, a content and widget containers (Widgets rendered, 1 page view)
  2. User action of page scroll
  3. Load additional widget containers with relevant permalink
  4. Call Research method (Additional widgets rendered)

Reload method

It will look again at the DOM for empty widget containers that were not found in the initial lookup and make request for additional recommendations. The widgets found by this method will be considered as a new page view.

Use cases: Navigation actions on a page which does not trigger a page load, but needs to be considered as a new page view such as Single Page Applications, Progressive Web Apps, etc.
*We recommend using Research instead of Reload on Infinite Scroll pages since the scrolling is a much passive action than a proactive click navigation. It can easily inflate PVs and result in lower performances if every scroll being counted as a new PV.

Example steps
  1. Initial page load together with outbrain.js, a content and widget containers (Widgets rendered, 1 page view)
  2. User action of page navigation (Browser does not trigger page load)
  3. Load a new content and new widget containers with relevant permalink.
  4. Call Reload method (New widgets rendered, +1 page view)

Refresh method

It clears all the current existing widget state and simulates a new page view of the existing widgets. It will not lookup for the empty containers.

Use cases: Navigation actions on a page which does not trigger a page load, but needs to be considered as a new page view. Similar to the reload situation, but widget containers remain in DOM and need to be re-rendered.

Example steps
  1. Initial page load together with outbrain.js, a content and widget containers (Widgets rendered, 1 page view)
  2. User action of page navigation (Browser does not trigger page load)
  3. Load a new content. Widget containers remain the same.
  4. Call Refresh method with a new permalink as a parameter (Existing widgets re-rendered, +1 page view)
    *Automatic refresh of the widgets or the page itself without interaction of user is prohibited and misuse of this method may impact the performance.

Debugging

The widget flow can be exposed to the developer using the print log method.

Summary

Method Usage Use case Page view count Container lookup
Research OBR.extern.researchWidget(); Lazy loading, Infinite Scroll Same page view Yes
Reload OBR.extern.reloadWidget(); Navigation actions on SPA Considered as a new page view Yes
Refresh OBR.extern.refreshWidget("NEW_PERMALINK"); Navigation actions on SPA Considered as a new page view No
Print Log OBR.printLog(); Debugging – –

JavaScript Framework Support

The JavaScript framework uses its own render logic and above workaround with our outbrain.js library does not work. To use vanilla JavaScript library with your JavaScript framework, you need to create a custom component and handle its logic manually.

Currently we support React components