Size and website load impact

We are passionate about quick website load times, and have reduced the impact of loading our signal code to almost none: It’s less than 200 bytes.

The signal code is what loads the Symmetrics script that in turn enables tracking on your site, but it does so asynchronously. That means that web browsers will prioritize loading and rendering everything else first.

It’s good practice to also keep all your script tags near the ending </body> tag on your website. This includes the Symmetrics signal code.

How the signal works

The first time a client (for example a visitor) triggers an event (for example a page view), our servers will generate a completely anonymous visitorId.

Usually, in other website analytics tools, visitorIds are based on information about the visitor, such as the client IP address, or the user agent (client browser information). Ours are not. They are completely random.

The visitorId is stored on the client (within the context of your website) as a first-party cookie, and then sent to our servers with subsequent events.

When making requests towards our APIs, or downloading datasets, all the visitorIds are replaced and randomized once again. That means account owners or integrations will never be able to see the real ID.

Install the signal through npm

You can also install the Symmetrics signal in your application with npm and the Symmetrics package. Look at the npm page for usage information.

npm install symmetrics

Tracking virtual page views

Out of the box, Symmetrics does not track virtual page views. To do this, simply fire a page view event when you know the URL has changed.

You should not fire this event on page load, as Symmetrics automatically tracks that initial page view. Only do this on subsequent, virtual views.

Example

window.symmetrics('event', 'page_view', {url: window.location.href});

Tracking custom events & collecting custom data

Tracking custom events is simple. Use the global symmetrics function that is placed on the window. The first argument should be event, and the second is your event name.

Example

window.symmetrics('event', 'user_signup');

Your event name cannot start with symmetrics:, as those are reserved.

Custom data parameters must be prefixed by custom. Just remember that with great power comes great responsibility.

Example

window.symmetrics('event', 'user_signup', {customSignupButtonColor: 'red'});

Collecting data that infringes upon the privacy of your users is a direct violation of our terms of service.

Customizing visitor ID storage method

The client visitorId can be stored in a cookie (default), or using localStorage. We recommend using cookies, as it enables visitor recognition across subdomains. More on signal options here.

However, changing your preferred storage method is simple. Just add this code above your symmetrics signal code:

window.symmetricsOptions = {storage: 'local_storage'};

Remember to wrap it in <script> tags!

Options

You can add options to customize the signal behavior by including this script before the signal code:

window.symmetricsOptions = {
    storage: 'cookie', // 'cookie' | 'local_storage'
    automaticallySendPageViewEvent: true // true | false
};

storage
Preferred client storage method. Cookie storage is recommended.Default: cookie

automaticallySendPageViewEvent
Enables or disables automatically sending page views.Default: true

ignoredQueryKeys
Removes specified query keys from all URLs before sending them to Symmetrics. Should be an array of strings.Default: undefined

Example

ignoredQueryKeys: ['email-address', 'user-id', 'order-id']

rewriteUrl
Function to rewrite the URL before sending it to Symmetrics. Should be used to remove sensitive information. Must return a valid URL.Default: undefined

Example

Uses regular expressions to replace the path suffix of /user/152 with xxx.

rewriteUrl: (url) => (
    url.replace(/\/user\/(\d*)/, 'xxx')
)