Asynchronous Initialization

💡 If you want to learn more about OpenWidget's JS API, check out our official Developers' Documentation.

If you're looking for a way to display your OpenWidget to customers, but only if they've agreed to a cookie consent prompt on your website or perhaps to show it solely for logged-in users, then look no more. Our AsyncInit function available in JS API comes to the rescue! With the help of our JS API, such scenarios do not require the creation of complex code reliant on conditional statements just to load a single code snippet. All of this, and more, can be achieved using just a few lines of code!

What is AsyncInit?

AsyncInit* is an optional feature available for every customer using our OpenWidget. With the use of a simple JavaScript API method, it lets you determine the precise moment when your OpenWidget bubble materializes on a website or within your app. But before you start using it, here are some scenarios where asyncInit is advisable and where it might not be.

*Async, short for asynchronous, denotes task execution after the completion of another task. This approach is frequently employed when awaiting data downloads, such as waiting to display an image once downloaded.

When should asyncInit be utilized? Numerous situations arise where loading a widget on demand or in response to specific actions is advantageous. To better understand its utility, let's explore two common scenarios you can stumble across online.

Whether you're a website owner running a store or a news service, establishing a trustworthy user experience means your customers can make informed choices. One effective means of achieving this is by informing customers about the data or cookies processed by you or third-party vendors on your page.

Typically, a cookie manager or a prompt is employed for customers to access information about cookies and either accept or decline them. However, there's a drawback. Many cookie management solutions fail to prevent the background initialization of third-party software, thereby undermining their purpose. Even if they do manage this, they might not interact smoothly with software like OpenWidget.

Through asyncInit, this predicament can be circumvented by triggering the initialization method only when a user clicks the "Accept" button. And the best part is: it requires no intricate coding, and you can be confident that OpenWidget adheres to your website's cookie policy!

💡 Employ asyncInit when the widget should only load under specific conditions.

But cookie consent is not the only scenario. AsyncInit proves valuable if you're thinking about displaying your widget selectively. For instance, if you intend to show the widget solely to logged-in customers or when a user executes a specific sequence of actions, you can initialize OpenWidget by invoking a simple JS API method when the user meets your criteria.

What to keep in mind?

While we encourage you to leverage the complete potential of your widget, it's essential to recognize scenarios where asyncInit might not be optimal. Remember that OpenWidget inherently features several options which enhance your customers' browsing experience in real time. For example, when OpenWidget is not initialized, features like our Visitor Counter or AI-based Product Recommendations will not be triggered.

How to implement?

With everything in place, you're ready to enable asyncInit. Achieve this by appending the __ow.asyncInit property to your OpenWidget's snippet and setting its value to "true". After implementing this, your code should look like the following example:

window.__ow = window.__ow || {}
window.__ow.organizationId = 'organizationId'
window.__ow.asyncInit = true
;(function (n, t, c) {
  function i(n) {
    return e._h ? e._h.apply(null, n) : e._q.push(n)
  }
  var e = {
    _q: [],
    _h: null,
    _v: '2.0',
    on: function () {
      i(['on', c.call(arguments)])
    },
    once: function () {
      i(['once', c.call(arguments)])
    },
    off: function () {
      i(['off', c.call(arguments)])
    },
    get: function () {
      if (!e._h)
        throw new Error("[OpenWidget] You can't use getters before load.")
      return i(['get', c.call(arguments)])
    },
    call: function () {
      i(['call', c.call(arguments)])
    },
    init: function () {
      var n = t.createElement('script')
      ;(n.async = !0),
        (n.type = 'text/javascript'),
        (n.src = 'https://cdn.openwidget.com/openwidget.js'),
        t.head.appendChild(n)
    },
  }
  !n.__ow.asyncInit && e.init(), (n.OpenWidget = n.OpenWidget || e)
})(window, document, [].slice)

At this point, the asyncInit option is activated!

You can load your widget and its resources on demand from now on by invoking the OpenWidget.init() JavaScript function.

Considering the cookie consent scenario, you can target the "Accept cookies" button and initialize the widget when a user clicks it. Bear in mind that once asyncInit is enabled, it's imperative to ensure that the OpenWidget.init() function is invoked whenever a user navigates to a different page with our code and has consented to cookie usage initially. Otherwise, the widget will vanish following each page reload or navigation event.

A recommended practice is to establish an additional statement that invokes this function whenever a user navigates throughout your website with the __ow.asyncInit parameter appended to your OpenWidget's snippet.

Here's a simple code example demonstrating both initializing OpenWidget after agreeing to cookies and making sure that the widget will be triggered when a user navigates throughout your page:

<html>
  <head>
    <script>
      window.__ow = window.__ow || {}
      window.__ow.organizationId = 'organizationId'
      window.__ow.asyncInit = true
      /* rest of the standard snippet code */
    </script>
  </head>
  <body>
    <button id="cookies-confirmation">Accept cookies</button>
    <script>
      if (window.localStorage.getItem('agreedToCookies') === 'yes') {
        OpenWidget.init()
      }
      const widgetButton = document.getElementById('button_init')
      widgetButton.addEventListener('click', function () {
        // Save an agreedToCookies item in browser’s localStorage and initialize OpenWidget when the user clicks on a button
        window.localStorage.setItem('agreedToCookies', 'yes')
        OpenWidget.init()
      })
    </script>
  </body>
</html>

And that concludes our asyncInit guide!

Remember, the potential applications are limitless—whether addressing the cookie consent management scenario, creating intricate conditions for OpenWidget loading, or exclusively displaying the widget to logged-in users, asyncInit is at your disposal to bring your aspirations to fruition.