JavaScript API (Beta)
Last updated
Last updated
Shoplift provides a JavaScript API that you can leverage on your store to create custom script-based tests.
With our API, you can leverage the benefit of Shoplift's visitor allocation, segmentation, and analytics features while defining your own test experiences outside of the framework of template, theme, or URL redirect tests.
While script-based tests are the primary intent of the API, it can also be used to extend the capabilities of template, theme, and URL redirect tests if you wish to implement additional script-based changes for them.
By default, the Shoplift script is inserted directly after the opening <head> tag in your theme.liquid layout files and should be loaded before anything else on your store.
This is important for visitor allocation to variants to be as fast as possible, to ensure minimal disruption or "flicker effect." We strongly recommend keeping the script at the top of your <head>.
If you need to move the scripts location for any reason, it must remain above any usage of the API.
We provide two types of script-based tests. By default, these tests do not do anything except split your visitors into your A and B experiences.
When creating a script-based test, Shoplift creates a control and a variant "hypothesis", each with their own ID. On the test draft screen you are able to see and copy these hypothesis IDs for usage in the API. These IDs will remain the same when the test is launched.
Script tests may use either "automatic" or "manual" approaches to visitor allocation (think of this like a "test trigger."
Tests that use automatic visitor allocation will allocate visitors between A and B experiences in the same way as our theme tests, allocating visitors to an experience on pageload as soon as they first navigate to the store while the test is running. This is a good fit for testing elements that are visible to all visitors, such as chat widgets and popups.
Tests that use manual visitor allocation will only allocate visitors to an A or B experience after calling the isHypothesisActive method (see below). This is a good fit for testing elements that are only visible after a visitor interacts with something, such as mini carts or nested navigation menus.
When the Shoplift script is loaded, we expose a global object called shoplift, which serves as the primary entry point for the API.
The following uses TypeScript type notation.
isHypothesisActive takes a hypothesisId string as its only argument, and returns an async Promise that will resolve to true if the current visitor is assigned to that hypothesis. It will resolve to false if the visitor is not assigned to that hypothesis, or if the test is not actively running.
If the test uses manual visitor allocation, then this method will split the visitor into A or B before returning, and synchronize the determination with Shoplift in the background.
The Promise returned by this function will resolve immediately unless you are using a manual split test that also uses GeoIP targeting. If you are using a manual split test with GeoIP targeting, then we must wait for the GeoIP to resolve before splitting the visitor, which will result in waiting for a network call.
In this example, we have created a test with Manual traffic allocation. To trigger the allocation we can create a simple method that we would then bind to the 'onClick' event of the mini cart:
Assignment to a hypothesis will not happen until the isHypothesisActive() call is triggered.
