Getting Started

Metrix Web SDK records users, events, attribution, web push subscriptions, and on-site messages for your website.

Prerequisites

• An APP_ID and API_KEY from your Metrix dashboard.
• A browser with JavaScript enabled.
• HTTPS for web push. localhost is also accepted for local development by browsers.

Install with npm

Install @metrixorg/websdk:

npm install @metrixorg/websdk

Initialize the SDK once, as early as possible in your application:

import { init } from '@metrixorg/websdk';
 
init(APP_ID, API_KEY);

The SDK must be initialized before calling any other Metrix API. Calling init more than once has no effect.

Use a script tag

If you cannot install the npm package, add the browser bundle inside the <head> of your page. Pin a version in production; use latest only when you intentionally want automatic updates.

<script src="https://cdn.metrix.ir/sdk/web/metrix.umd-2.8.1.js"></script>
<script>
  Metrix.init('APP_ID', 'API_KEY');
</script>

To always load the latest published bundle, replace 2.8.1 with latest.

For TypeScript projects using the script-tag integration, declare the global before using it:

declare const Metrix: {
  init: (appId: string, apiKey: string, config?: Record<string, unknown>) => void;
};
 
Metrix.init(APP_ID, API_KEY);

Initialization configuration

The third init argument is optional. Import SDKConfig for type checking:

import { init, SDKConfig } from '@metrixorg/websdk';
 
const config: SDKConfig = {
  sessionTracking: {
    enabled: true,
    packageName: 'my-web-app',
  },
  push: {
    enabled: true,
    publicKey: 'YOUR_VAPID_PUBLIC_KEY',
    showBell: true,
    showBackdrop: false,
    hasSW: false,
  },
  onSiteMessaging: {
    enabled: true,
  },
};
 
init('APP_ID', 'API_KEY', config);

SDKConfig supports these optional sections:

Keep the API key private to your application configuration where possible, and do not expose server-side secrets in frontend code.

• How to find APP ID
• How to find API KEY

What’s Next?

After initializing the SDK, explore these features:

• Tracking Users — Identify and manage user information
• Tracking Events — Record user interactions and events
• Attribution — Track install and conversion attribution
• Web Push — Send push notifications to subscribed users
• On-Site Messaging — Display in-app messages to users

Prefer to watch instead of read? The Web SDK video tutorials walk through the same material — setup, identifying users, and sending events.

Common Questions

Do I need to authorize the user before tracking?

Most features work without user authorization. However, to associate events with a user identity, call authorizeUser() before sending events:

import { authorizeUser, newEvent } from '@metrixorg/websdk';
 
authorizeUser('user123');
newEvent('EVENT_SLUG');

Can I use the SDK with single-page applications?

Yes. The SDK is designed for single-page applications (SPAs) and handles page transitions automatically. If you need to track SPA route changes as sessions, configure session tracking in the init config.

What data does the SDK collect automatically?

The SDK automatically collects:

• Device metadata: OS, OS version, device language, screen resolution
• Browser metadata: Browser name, version, timezone, timezone offset
• Session data (if enabled): Session duration and activity flow

Optional with configuration:

• Location data (if location.enabled: true): Latitude, longitude
• Session tracking (if sessionTracking.enabled: true): Duration and activity flow

How do I track conversions and install attribution?

See the Attribution documentation for detailed setup instructions.

Is HTTPS required?

HTTPS is required for:

• Web push notifications
• Some browser APIs used by the SDK

For local development on localhost, most browsers allow HTTP. However, push notifications still require HTTPS even on localhost.

Does the SDK work in WebViews?

If your application runs as a WebView inside an Android app, refer to the Android SDK documentation  for proper integration.

Troubleshooting

”Init called more than once” warning

The SDK automatically ignores multiple init calls. This is safe and expected behavior if your app architecture calls init in multiple places. Only the first call takes effect.

Events not appearing in the dashboard

1. Verify init is called before any other SDK methods
2. Confirm APP_ID and API_KEY are correct
3. Check the browser console for errors
4. Use authorizeUser() to associate events with a user (optional but recommended)
5. Ensure the event slug exists in your Metrix dashboard

Push notifications not working

1. Confirm HTTPS is enabled (or using localhost)
2. Verify the Service Worker file is accessible at the root of your domain
3. Check browser permissions for notifications
4. Ensure push.enabled: true and publicKey are set in the init config
5. Call subscribePush() and grant the browser permission when prompted

Support

For more help, see:

• Metrix Help Center 
• Web SDK npm package