Control the timing of Optimizely Web Experimentation Event dispatch with holdEvents and sendEvents

Optimizely Web Experimentation snippets that use the /events endpoint log batches of events, rather than generate one network request per event. It sends these batches once per second for the first ten seconds after snippet activation and immediately thereafter. holdEvents and sendEventstogether control the timing of event logging.  You can use them to better control when the snippet begins sending batches of events. This lets you improve page load performance by waiting to send events until the page has loaded or address data discrepancies to align Optimizely Web Experimentation logging with your analytics platform.

After calling sendEvents, the snippet can send batches of queued events at the next polling interval and thereafter. Subsequent batches send once per second until 10 seconds have elapsed since the snippet activated. After that point, individual events send as soon as they are triggered. Any events which have not been sent when a visitor navigates are held in localStorage and sent on the next page where the snippet is implemented, even if the next pageview occurs hours or days later (for example, at the start of a new session).

The three primary use cases for implementing sendEvents and holdEvents each require a distinct implementation strategy.

You improve page performance by reducing the number of requests the browser makes during the first few seconds after a page starts loading. This is when users are most likely to notice that a page is loading slowly. 

You can ensure that Optimizely Web Experimentation does not track any events during this period by calling holdEvents before the snippet activates (as described above) and binding a call to sendEvents to an event fired by the browser when it finishes loading some part of the page.  

For example, you might want to prevent Optimizely Web Experimentation from generating any event requests until after window.load. Your implementation might look something like this:

You must pick the most appropriate event to bind the sendEvents call. The load event happens after all assets have been downloaded, which is late in the page load process. A more aggressive implementation might use the DOMContentLoaded lifecycle event. With sendEvents, you can align the snippet’s logging behavior to whatever best suits your website’s needs.

As discussed in troubleshooting analytics discrepancies, there are several reasons why the numbers you see in Optimizely Web Experimentation may not match what you see in your analytics platform. One common cause of discrepancies is timing.  

Typically, the Optimizely Web Experimentation snippet is implemented high in your page's head. This lets Optimizely Web Experimentation initialize quickly and run variation code to manipulate content without causing page flashing. By contrast, analytics tracking code is frequently implemented to fire later during page load, usually in the body of the document. Analytics libraries are not responsible for manipulating content and do not cause flashing.

This mismatch in timing means that Optimizely Web Experimentation typically start logging events before your analytics platform does, which can be several seconds earlier. This leads to Optimizely Web Experimentation counting more conversions and unique visitors than your analytics platform, as visitors who exit a page very quickly may be tracked by Optimizely Web Experimentation but not your analytics platform.

You can address this timing mismatch by calling holdEvents before the snippet activates and then calling sendEvents from within a callback function provided by your analytics library.

For example, you might want to prevent Optimizely Web Experimentation from generating any event requests until after a Google Analytics tracker object is ready for interaction. You could take advantage of readyCallback to do this. Your implementation might look something like this:

Your implementation varies depending on your analytics platform. Many platforms provide similar callback functionality.

Mixpanel

Use the holdEvents and sendEvents API for granular control over the timing of when the Optimizely snippet sends events to the logging endpoint. Load the snippet before the cookie wall but send events only after the user has accepted the cookie. See GDPR implementation options for information.

When implementing holdEvents and sendEvents, the Optimizely Web Experimentation snippet may experience a delay before it begins to send events. This affects Optimizely Web Experimentation results in two ways:

The magnitude of these effects increases with the time the snippet must wait before it begins to send events. This is desirable if you aim to align Optimizely Web Experimentation's results with your analytics platform.