Utility Methods and Performance
How it works
Our JavaScript source exposes the following utility methods to help you change how script loads on your page.
Load
You can load a buffered version of our JavaScript that requires you call load explicitly before the script initiates any network activity. This is useful if you want to wait for user consent before you fetch tracking destinations or send buffered events to Customer.io.
You should only call the load method once.
export const analytics = new AnalyticsBrowser()
analytics.identify("hello world")
if (userConsentsToBeingTracked) {
analytics.load({ writeKey: '<YOUR_WRITE_KEY>' }) // destinations loaded, enqueued events are flushed
}
You can also use load if you fetch settings asynchronously.
const analytics = new AnalyticsBrowser()
fetchWriteKey().then(writeKey => analytics.load({ writeKey }))
analytics.identify("hello world")
Ready
The ready method lets you pass a method that is called when Customer.io’s JavaScript finishes initializing, and when all enabled device-mode destinations load. It’s like jQuery’s ready method—but for destinations!
The ready method isn’t invoked if any destination throws an error (Like if your API key expired, your configuration settings were incorrect, or if your destination is blocked by the browser) during initialization.
The code in the ready function only executes after ready is emitted.
If you want to access end-tool library methods that do not match Customer.io methods, like adding an extra setting to Mixpanel, you can use a ready callback so that you’re guaranteed to have access to the Mixpanel object, like this:
analytics.ready(function() {
window.mixpanel.set_config({ verbose: true });
});
The ready method uses the following format, supporting a callback function that’s executed after all enabled destinations have loaded.
analytics.ready(callback);
Debug
The debug method turns on debug mode, which logs messages to the developer console that can help you debug your implementation. The call takes a boolean, where true enables debug mode and false disables it.
//enable debug mode
analytics.debug(true);
Emitter
The global analytics object emits events whenever you call alias, group, identify, track, or page.
Use the on method to set listeners for these events and run your own custom code. You might want to do this if you need to send data to a destination we don’t support.
The call works like this where:
methodis the event you want to listen for—one ofalias,group,identify,track, orpage.callbackis a function that takes place after the method, and takes three argumentsevent,properties, andoptions.
analytics.on('track', function(event, properties, options) {
bigdataTool.push(['recordEvent', event]);
});
This method emits events before they are processed by Customer.io, and may not include some of the normalization we do on the client before sending data to Customer.io.
Page event properties are stored in the options object.
Extending timeouts
The timeout method sets the length of callbacks and helper functions in milliseconds. This is useful if you have multiple scripts that need to fire in your callback or trackLink and trackForm helper functions. For example, if you wanted to set the timeout to 500ms, you’d set it like this:
analytics.timeout(500);
If you trigger ad network conversion pixels, we recommend that you extend the timeout to 500 ms to account for slow load times.
Reset or log out
Calling reset resets the id, including anonymousId, and clears traits for the currently identified user and group. You probably want to do this when a user logs out of your service or revokes consent from tracking cookies.
analytics.reset();
This method only clears cookies and localStorage created by Customer.io. It doesn’t clear data from other integrated tools, as those native libraries might set their own cookies for user tracking, sessions, and to manage states.
We don’t share localStorage across subdomains. If you use our Data Pipelines on multiple subdomains, you need to call analytics.reset() for each subdomain to completely clear out the user session.
Retries
Our JavaScript source automatically retries network and server errors. With persistent retries, Analytics.js:
- Supports offline tracking, queueing your events and delivering them when a user comes back online.
- Handles network issues in the event that you can’t connect to our API. We store the events in the browser to ensure that you don’t lose data.
Analytics.js stores events in localStorage and falls back to in-memory storage when localStorage is unavailable. We’ll retry up to 16 times with an exponentially increasing delay between retries. The maximum retry window is about three hours.
Cross-Subdomain tracking
Analytics.js tracks across subdomains out of the box—for all of our destinations.
Analytics.js Performance
Our JavaScript library and all destination libraries are loaded asynchronously (with the HTML script async tag). This means that we fire Customer.io methods asynchronously, so you should adjust your code accordingly if you want to send events from the browser in a specific order.
We only load libraries required for your enabled destinations. When you disable a destination, Analytics.js stops requesting that library.
Bundle size
Our JavaScript snippet only increases your page size by about 1.1KB.
However, the snippet asynchronously requests and loads a customized JavaScript bundle (analytics.min.js), which contains the code and settings needed to load your direct-mode destinations. This file’s size changes depending on the destinations you enable.
Without any destinations, the analytics.min.js file is about 62 KB.
Local storage cookies used by Analytics.js
Analytics.js uses a few localstorage cookies if you have retries enabled. These cookies keep track of retry timing.
- The
ackcookie is a timer used to determine if another tab should claim the retry queue. - The
reclaimStartandreclaimEndcookies determine if a tab takes over the queue from another tab. - The
inProgressandqueuecookies track events in progress, and events that are queued for retries.
