Metrical SDK for the browser.
To get started with using Metrical Browser SDK, install the package to your project via npm, yarn or script loader.
This SDK is available as a package on npm registry named @metrical-io/metrical-browser
. You can install the package using npm or yarn CLI.
npm install @metrical-io/metrical-browser
# yarn
yarn add @metrical-io/metrical-browser
Import the package into your project and initialize it with your API key.
import { Metrical } from '@metrical-io/metrical-browser';
const client = new Metrical({ writeKey: '<write key>' });
This SDK is also available through CDN.
<script type="application/javascript" src="https://cdn.jsdelivr.net/npm/@metrical-io/metrical-browser/dist/index.iife.min.js"></script>
<script type="text/javascript">
const client = new Metrical({ writeKey: '<write key>' });
</script>
You can track an event by calling client.track()
with the event name and its properties.
client.track({ event_name: 'My Custom Event', properties: { my_property: 'property_value' }});
The following properties are default properties automatically included with every track event:
- Screen Height
- Screen Width
- Referrer
- Referring Domain
- Operating System
- Device Type
- Browser
- Browser Version
All events are sent via HTTPS.
You can track a page view event by calling client.trackPageView()
. By default, 'Page View' is used as the event name, and the following properties are recorded:
- The page title.
- The page location.
- The page protocol.
- The page domain.
- The page path.
- The page query parameters.
You can always specify a custom name and add additional properties as shown below:
client.trackPageView({ event_name: 'My Custom Event', properties: { my_property: 'property_value' }}));
Page View events can be tracked automatically on every page load by enabling the defaultTrackingConfig.pageViews
during client creation (disabled by default), as shown below:
const client = new Metrical({ writeKey: '<write key>', defaultTrackingConfig: { pageViews: { enabled: true }}});
Dynamic page views in single-page applications are tracked on any URL changes by default. You can control this behavior with the defaultTrackingConfig.pageViews.singlePageAppTracking
option, as shown below:
// Track any URL changes.
const client = new Metrical({ writeKey: '<write key>', defaultTrackingConfig: { pageViews: { enabled: true, singlePageAppTracking: 'any' }}});
// Track when the path or query string changes, ignoring changes in the hash.
const client = new Metrical({ writeKey: '<write key>', defaultTrackingConfig: { pageViews: { enabled: true, singlePageAppTracking: 'path-with-query' }}});
// Only track when the path changes, disregarding changes in the query string or hash.
const client = new Metrical({ writeKey: '<write key>', defaultTrackingConfig: { pageViews: { enabled: true, singlePageAppTracking: 'path' }}});
// Disable dynamic page views tracking in single-page applications.
const client = new Metrical({ writeKey: '<write key>', defaultTrackingConfig: { pageViews: { enabled: true, singlePageAppTracking: 'disabled' }}});
The library will automatically populate Page View events with any UTM parameters (utm_source
, utm_campaign
, utm_medium
, utm_term
, utm_content
) or advertising click IDs (dclid
, fbclid
, gbraid
, gclid
, ko_click_id
, li_fat_id
, msclkid
, rtd_cid
, ttclid
, twclid
, wbraid
) that are present on the page.
This default behavior can be turned off by disabling the defaultTrackingConfig.marketingAttribution
option during client creation, as shown below:
const client = new Metrical({ writeKey: '<write key>', defaultTrackingConfig: { pageViews: { enabled: true }, marketingAttribution: false }});
You can manage user identity through the client.identify()
and client.reset()
methods. Utilizing these methods correctly ensures that events are appropriately linked to the user, regardless of their transitions across devices and browsers.
You can identify a user with a unique ID to monitor their activity across devices and associate them with their events. Once you have the current user's identity, you should call identify()
as shown below, typically after they log in or sign up:
client.identify({ user_id: '<user id>' });
When your users logout you can trigger a reset method which will help reset the user identity. We’ll disassociate all future tracked events from the currently identified user.
client.reset();
By default, cookies with a localStorage fallback are used to store state in the browser. You can control this behavior with the storageType
option, as shown below:
// Use cookies explicitly.
const client = new Metrical({ writeKey: '<write key>', storageType: 'cookies'});
// Use localStorage explicitly.
const client = new Metrical({ writeKey: '<write key>', storageType: 'localStorage'});
Metrical prioritizes user privacy while providing flexibility in data collection. By default, Metrical is configured to transmit tracking data, but you have options to control this behavior.
To prioritize user privacy, you can proactively disable tracking during initialization of the Metrical client. Set the disableTrackingByDefault
property to true
:
const client = new Metrical({ writeKey: '<write key>', disableTrackingByDefault: true });
Metrical client allows you to dynamically manage tracking based on user preferences or specific scenarios. Use the following methods:
-
client.enableTracking()
activates the transmission of tracking data (this is the default state). -
client.disableTracking()
deactivates the transmission of tracking data.
For more precise control over user privacy, Metrical offers the option to specifically toggle the tracking of IP address and geolocation information. Use the trackIpAndGeolocation
property during initialization:
const client = new Metrical({
writeKey: '<write key>',
trackIpAndGeolocation: false // Disable IP and geolocation tracking
});