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
- Initial page load together with outbrain.js, a content and widget containers (Widgets rendered, 1 page view)
- User action of page scroll
- Load additional widget containers with relevant permalink
- 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
- Initial page load together with outbrain.js, a content and widget containers (Widgets rendered, 1 page view)
- User action of page navigation (Browser does not trigger page load)
- Load a new content and new widget containers with relevant permalink.
- 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
- Initial page load together with outbrain.js, a content and widget containers (Widgets rendered, 1 page view)
- User action of page navigation (Browser does not trigger page load)
- Load a new content. Widget containers remain the same.
- 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