Xsolla Metrika

A lightweight integration library for Xsolla Metrics (XMTS) that simplifies user tracking and analytics setup. Supports SPA and classic sites, works in all modern browsers (including IE11), and provides full TypeScript support.

Table of Contents

• Features
• Installation
  • npm / yarn
  • CDN (jsDelivr / unpkg)
• Usage
  • ESM
  • CommonJS
  • IIFE
  • IIFE (BOOTSTRAP)
• Configuration
  • Parameters Table
• Sending data
• API Reference
  • Instance Methods
• Trackers
• What Data Is Sent
• TypeScript Support
• Migration from v1
• Browser Support
• License

Features

• 📦 Tiny: Minimal bundle size, no heavy dependencies.
• 🧑‍💻 TypeScript-first: Full type definitions out of the box.
• ⚡ SPA-ready: Tracks navigation in React, Vue, Angular, etc.
• 🖱️ Auto-tracking: Clicks, scrolls, external links, performance, and more.
• 🧬 Device fingerprinting.
• 🌍 Flexible delivery: Works with sendBeacon and fetch.
• 🔌 Custom events: Send any data, integrate with A/B tests, etc.

Installation

Bundles

Xsolla Metrika provides several bundle formats for different use cases:

npm / yarn

npm install @xsolla/metrika
# or
yarn add @xsolla/metrika

CDN (jsDelivr / unpkg)

<!-- jsDelivr (IIFE, 2.2.3) -->
<script src="https://cdn.jsdelivr.net/npm/@xsolla/metrika@2.2.3"></script>
<!-- unpkg (IIFE, 2.2.3) -->
<script src="https://unpkg.com/@xsolla/metrika@2.2.3"></script>
<!-- For other bundle formats, use: -->
<script src="https://unpkg.com/@xsolla/metrika@2.2.3/dist/xsolla-metrika.umd.js"></script>

Note: You can omit the version (@xsolla/metrika instead of @xsolla/metrika@2.2.3) to always use the latest library version, but this is not recommended for production.

Usage

ESM

import XsollaAnalytics from '@xsolla/metrika';

(async () => {
  const analytics = await XsollaAnalytics.init({
    id: 'YOUR_COUNTER_ID',
    hit: true,
    navigation: true,
    // ...other options
  });

  analytics.hit(window.location.href);
  analytics.elementClick('my-button');
})();

CommonJS

const XsollaAnalytics = require('@xsolla/metrika').default;

XsollaAnalytics.init({ id: 'YOUR_COUNTER_ID', hit: true }).then((analytics) => {
  analytics.hit(window.location.href);
});

IIFE

<script src="https://cdn.jsdelivr.net/npm/@xsolla/metrika@2.2.3"></script>
<script>
  window.XsollaAnalytics.init({
    id: 'YOUR_COUNTER_ID',
    hit: true,
    navigation: true,
  }).then(function (analytics) {
    analytics.hit(window.location.href);
  });
</script>

IIFE (BOOTSTRAP)

A special bootstrap IIFE bundle: dist/xsolla-metrika.bootstrap.js and its minified version dist/xsolla-metrika.bootstrap.min.js.
This bundle allows you to specify configuration parameters directly via data-attributes on the <script> tag. The analytics instance is then automatically created and becomes available as window.analytics.

<script
  src="https://cdn.jsdelivr.net/npm/@xsolla/metrika@2.2.3/dist/xsolla-metrika.bootstrap.min.js"
  data-id="123456"
  data-hit="true"
  data-click="true"
  data-ext-link="true"
  data-site-domains='["example.com","sub.example.com"]'
></script>

Note:

• All parameters must be specified in kebab-case format.
• All values that require parsing (such as arrays or objects) must be enclosed in single quotes.

Configuration

Parameters Table

Sending Data

By default, Xsolla Metrika sends all events using sendBeacon for maximum reliability (especially during page unload).

• Global setting:
  If you want to use regular fetch instead of sendBeacon for manual methods (hit, externalLink, elementClick, etc.), set the useBeacon: false parameter during initialization:

  XsollaAnalytics.init({
    id: 'YOUR_COUNTER_ID',
    useBeacon: false,
    // ...
  });

• Important:
  Automatic trackers (such as auto pageview, click, scroll tracking, etc.) always use sendBeacon regardless of the global parameter.

• Override per event:
  In any manual method (hit, externalLink, elementClick, etc.), you can explicitly specify the sending method using the useBeacon option:

  analytics.hit(window.location.href, {}, false); // sends via fetch
  analytics.hit(window.location.href, {}, true); // sends via sendBeacon

• Retries with fetch:
  If sendBeacon is not available or fails, or if you explicitly use fetch for sending, the library will automatically retry the request up to two additional times (total of 3 attempts) in case of network errors or server errors.

• Customizing retries:
  You can control the number of retry attempts and delay between them using the retryOptions parameter during initialization:

  XsollaAnalytics.init({
    id: 'YOUR_COUNTER_ID',
    retryOptions: {
      retries: 5, // Number of retry attempts (default: 2)
      retryDelay: 1000, // Delay between retries in ms (default: 500)
    },
  });

  If retryOptions is not specified, the default is 2 retries with a 500ms delay.

This allows you to flexibly control how events are sent depending on your needs.

API Reference

Instance Methods

Note: When sending data using any method (hit, externalLink, elementClick, formData, customEvent, etc.), you can temporarily extend the global extraValues or abParams by passing them in the data object:

analytics.hit(window.location.href, {
  exv: { extraKey_1: 'extraValue_1', extraKey_2: 'extraValue_2' },
  abParams: { abKey_1: 'abValue_1', abKey_2: 'abValue_2' },
});

Values passed this way will be added only to the current event and will not modify the global parameters set during initialization.

Example

analytics.hit(window.location.href);
analytics.externalLink('https://external.com');
analytics.elementClick('my-button');
analytics.formData('signup', { email: 'test@example.com' });
analytics.customEvent('my-event', { foo: 1 });
analytics.setAbParams({ experiment: 'A' });
analytics.destroy();

List of Event Types

See docs/event-types.md for details.

Trackers

Xsolla Metrika includes several built-in trackers. Enable them via config flags:

See docs/trackers.md for details.

What Data Is Sent

Xsolla Metrika collects and sends only technical and anonymized data required for analytics and improving user experience.
No personal user data is collected or transmitted by default.

Example of the event data structure

{
  "et": 1, // Event type (e.g., HIT, CLICK, etc.)
  "library_version": "2.2.3", // Library version
  "counter_id": "YOUR_COUNTER_ID", // Your project counter ID
  "dfp": "fingerprint_hash", // Device fingerprint
  "xsollauid": "user_id", // Xsolla user ID
  "eid": 123456, // External ID (if there is)
  "ident": {
    "ntf": 1, // Notifications enabled (1/0)
    "net": "4g", // Network type
    "t": "Page Title", // Document title
    "pc": "UTF-8", // Charset
    "la": "en", // Language
    "tz": -180, // Timezone offset (minutes)
    "wcw": 1920, // Viewport width
    "wch": 1080, // Viewport height
    "sw": 1920, // Screen width
    "sh": 1080, // Screen height
    "j": 0, // Java enabled (1/0)
    "c": 1, // Cookies enabled (1/0)
    "sc": 24, // Color depth
    "ifr": 0, // Is in iframe (1/0)
    "adb": 0, // AdBlock detected (1/0)
    "gacid": "123456789.1234567890", // Google Analytics CID (if there is)
    "clid": "1733820844784899640", // Client ID
    "vid": "1747380405323933016", // Visitor ID,
    "plt": 356, // Page load time (ms),
    "lcp": 567 // Largest Contentful Paint (ms)
    // ...additional cookies (for example: yid, pv, cv, etc.)
  },
  "user_agent": "...", // User-Agent string
  "browser_major": "125", // Browser major version
  "browser_name": "Chrome", // Browser name
  "title": "Page Title", // Document title
  "utm": {
    "utm_source": null,
    "utm_medium": null,
    "utm_campaign": null,
    "utm_content": null,
    "utm_term": null
  },
  "openstat": {
    "openstat_service": null,
    "openstat_campaign": null,
    "openstat_ad": null,
    "openstat_source": null
  },
  "url": "https://your.site/page", // Current page URL
  "referer": "https://referrer.site/", // Referrer URL
  "exv": {}, // Extra values (if there is)
  "abParams": {} // A/B test params (if there is)
  // ...event-specific fields (for example: value, en, form, metricData, etc.)
}

TypeScript Support

• 100% typed API, no need for @types packages.
• Works out of the box with TypeScript 5.8+.
• See docs/ts-support.md for troubleshooting and tips.

Migration from v1

• Async initialization: use await XsollaAnalytics.init(...).
• Device Fingerprinting has become more reliable.
• Events are sent via sendBeacon by default, with fallback to fetch.
• The method dfpGet has been renamed to getFingerprintHash.
• The method keyDfpGet has been renamed to getFingerprintData.
• Retry logic for failed fetch requests.
• See docs/migration/v1_v2.md for a full migration guide.

Browser Support

• All modern browsers (Chrome, Firefox, Edge, Safari, Opera, Samsung Internet, etc.)
• IE11+
• See docs/browser-support.md for the full list.

License

MIT © Xsolla