Measuring Experiments

Using Autocapture

Sidecar comes loaded with an event collection tool that will autocapture various web activities, allowing you to create both simple and complex Metrics within Statsig console without writing a line of code.

Autocapture tracks the following events and properties automatically:

auto_capture::click

Property	description	example value (strings)
value	Tag name of clicked element	button
metadata.content	innerText value of the clicked element	Add to Cart
metadata.page_url	Current URL with path and parameters	https://www.FULL-URL.com/?utm=FALL_2024

auto_capture::page_view

Property	description	example value (strings)
value	Current URL with path and parameters	https://www.FULL-URL.com/?utm=FALL_2024
metadata.page_url	Current URL with path and parameters	https://www.FULL-URL.com/?utm=FALL_2024
metadata.queryParams	A json representation of query string params	{\"utm\":\"FALL_2024\"}
metadata.referrer	URL of the prior page	https://www.google.com
metadata.title	Title of the current webpage from <title>	Homepage

auto_capture::page_view_end

Property	description	example value (strings)
value	Current URL with path and parameters	https://www.FULL-URL.com/?utm=FALL_2024
metadata.pageViewLength	total number of milliseconds spent on the page	6137
metadata.page_url	Current URL with path and parameters	https://www.FULL-URL.com/?utm=FALL_2024
metadata.scrollDepth	percentage of page scrolled (integer 0-100)	47

auto_capture::form_submit

Property	description	example value (strings)
value	Fixed string	"form"
metadata.action	action attribute on the form element	/submit.php
metadata.formId	id attribute on the form element	user-info
metadata.formName	name attribute on the form element	user-info
metadata.method	Http method on the form element	POST
metadata.page_url	Current URL with path and parameters	https://www.FULL-URL.com/?utm=FALL_2024

auto_capture::performance

Property	description	example value (strings)
value	Current URL with path and parameters	https://www.FULL-URL.com/?utm=FALL_2024
metadata.dom_interactive_time_ms	Time until DOM is qualified as interactive as implemented by browser performanceTiming API	1807.90
metadata.first_contentful_paint_time_ms	First contentful paint metric as implemented by browser performanceTiming API	1523.90
metadata.load_time_ms	Total load time as implemented by browser performanceTiming API	2766.90
metadata.page_url	Current URL with path and parameters	https://www.FULL-URL.com/?utm=FALL_2024
metadata.transfer_bytes	Total number of bytes transferred in document body as implemented by browser performanceTiming API	48360

Disabling Autocapture

To disable autocapture, simply append the following query string parameter to the Sidecar script URL: &autostart=0.

Auto Capturing Data Attributes

Data attribute tags will automatically be added to the event metadata object. Note that this is available for click events only for now!

The metadata will be in the format of data-(camelCasedAttributeName). For example:

<button data-button-attribute="important button attribute">Add to Cart</button>
<a href="/checkout" data-a-tag-attribute="important a tag attribute">Checkout</a>

Metadata on the events tab will be

{
  "content": "Add to Cart",
  "data-buttonAttribute": "important button attribute",
  "page_url": "http://localhost:4200/",
  "sessionID": "7ccb4e03-3599-443e-8d41-4b89f7168728",
  "tagName": "button"
}

{
  "content": "Checkout",
  "data-aTagAttribute": "important a tag attribute",
  "href": "/checkout",
  "page_url": "http://localhost:4200/",
  "sessionID": "7ccb4e03-3599-443e-8d41-4b89f7168728",
  "tagName": "a"
}

Setting User Identity and Attributes

By default, Autocapture uses stableID (an auto-generated device-level guid that gets stored in the user's localStorage) for tracking purposes. If you wish to enrich autocapture events with known user identities and attributes, you can define the following object prior to autocapture/sidecar being loaded.

window.statsigUser = {
  userID: "<USER ID>",
  custom: { // optional attributes object
     isLoggedIn: false 
  }
}

Using the tracking API

You can track events manually for actions that are not autocaptured by the feature described above. To track events back to Statsig, you can call StatsigSidecar.logEvent which takes the same arguments as the Statsig JS SDK as documented here. This method can be called prior to completion of the init routine.

// example order event
StatsigSidecar.logEvent('Order', null, {
  total: 54.66,
  units: 3,
  unitAvgCost: 18.22
});

Post-Experiment Callback for outbound integrations

You can bind a callback that gets invoked after Sidecar has run experiments (also gets called when there are no experiments), allowing you to run code that processes the experiment assignments as needed.

This method should be defined anywhere prior to the Sidecar client script.

window.postExperimentCallback = function(statsigClient, experimentIds) {
  /** 
   * add your own callback routine here
   * ie; annotating 3rd party analytics tools with assignment info
      
    var evarValue = [];
    experimentIds.forEach(function(expId) {
      var inExp = statsigClient.getExperimentWithExposureLoggingDisabled(expId).getGroupName();
      if(inExp) {
        evarValue.push(expId + ':' + inExp);
      }
    });
    evarValue = evarValue.join(',');
   */
}

Accessing the Statsig js client

For accessing the underlying Statsig js client instance, you can call StatsigSidecar.getStatsigInstance().

Persisting stableID across subdomains

Statsig uses localStorage as the preferred mechanism for storing the user's stableID. Localstorage keys do not persist across any origin boundaries including across subdomains. For example, a user visiting https://example.com, https://show.example.com and https://account.example.com would be issued three distinct stableIDs.

If you are assigning a user to a test on one subdomain, and tracking behavior for metrics purposes on a different subdomain, you'll need to have this solution in place to ensure Statsig can properly attribute cross-origin behavior to the Test Group assignment that took place on the initial experiment domain.

To install, simply paste the first script tag shown below directly above your Sidecar script.

<!-- cross domain id script -->
<script>!function(){let t="STATSIG_LOCAL_STORAGE_STABLE_ID";function e(){if(crypto&&crypto.randomUUID)return crypto.randomUUID();let t=()=>Math.floor(65536*Math.random()).toString(16).padStart(4,"0");return`${t()}${t()}-${t()}-4${t().substring(1)}-${t()}-${t()}${t()}${t()}`}let i=null,n=localStorage.getItem(t)||null;if(document.cookie.match(/statsiguuid=([\w-]+);?/)&&([,i]=document.cookie.match(/statsiguuid=([\w-]+);?/)),i&&n&&i===n);else if(i&&n&&i!==n)localStorage.setItem(t,i);else if(i&&!n)localStorage.setItem(t,i);else{let o=e();localStorage.setItem(t,o),function t(i){let n=new Date;n.setMonth(n.getMonth()+12);let o=window.location.host.split(".");o.length>2&&o.shift();let s=`.${o.join(".")}`;document.cookie=`statsiguuid=${i||e()};Expires=${n};Domain=${s}`}(o)}}();</script>

<!-- Manually attach stableID from local storage -->
<script>
if(localStorage.getItem('STATSIG_LOCAL_STORAGE_STABLE_ID')) {
  window.statsigUser = {
    customIDs: {stableID: localStorage.getItem('STATSIG_LOCAL_STORAGE_STABLE_ID')}
  }
}
</script>

<!-- sidecar script below -->
<script src="https://cdn.jsdelivr.net/npm/statsig-sidecar/dist/index.min.js?apikey=[client-YOUR-STATSIG-CLIENT-KEY]"></script>