@twinalyze/web-analytics

Twinalyze Web Analytics SDK for tracking page views, sessions, user activity, custom events, user identities, device properties, and FCM tokens.

Installation

npm

npm install @twinalyze/web-analytics

CDN

<script src="https://cdn.jsdelivr.net/npm/@twinalyze/web-analytics/dist/cdn.global.min.js"></script>

Quick Start

npm

import TwinalyzeAnalytics from "@twinalyze/web-analytics";

TwinalyzeAnalytics.init({
  apiKey: "YOUR_API_KEY",
  secretKey: "YOUR_SECRET_KEY",

});

CDN

<script src="https://cdn.jsdelivr.net/npm/@twinalyze/web-analytics@YOUR_VERSION/dist/cdn.global.min.js"></script>

<script>
  window.addEventListener("load", function () {
    if (!window.TwinalyzeAnalytics) {
      console.error("[Twinalyze] SDK failed to load");
      return;
    }

    window.TwinalyzeAnalytics.init({
      apiKey: "YOUR_API_KEY",
      secretKey: "YOUR_SECRET_KEY",
    });
  });
</script>

Automatic Events

The SDK can automatically track:

• pageView
• scrollDepth
• elementClick
• searchResultsView
• formStart
• formSubmit
• fileDownload

Custom Events

Use track() to send custom events.

TwinalyzeAnalytics.track("buttonClicked", {
  buttonName: "Start Free Trial",
});

Example:

TwinalyzeAnalytics.track("purchaseCompleted", {
  orderId: "order_123",
  revenue: 1499,
  currency: "INR",
});

Identify Users

Use identify() after the user logs in or becomes known.

TwinalyzeAnalytics.identify(user.id, {
  name: user.name,
  email: user.email,
  plan: user.plan,
});

Use a stable internal user ID whenever possible.

Automatically Collected Data

The SDK may collect:

• Browser name and version
• Operating system
• Device type
• Screen and viewport size
• Device language
• Network information
• Session ID
• Landing URL
• UTM parameters
• Advertising click IDs
• Notification permission status
• FCM token when available

Firebase Cloud Messaging

The SDK can collect the browser FCM token and save it as:

{
  fcm: "FCM_TOKEN"
}

Enable FCM:

TwinalyzeAnalytics.init({
  apiKey: "YOUR_API_KEY",
  secretKey: "YOUR_SECRET_KEY",

  fcm: {
    enabled: true,
    configUrl: "/twinalyze-fcm-sw.js",
  },
});

Create this file:

public/twinalyze-fcm-sw.js

The final URL must be:

https://your-domain.com/twinalyze-fcm-sw.js

Use:

self.TWINALYZE_FCM_CONFIG = {
  firebaseConfig: {
    apiKey: "YOUR_FIREBASE_API_KEY",
    authDomain: "YOUR_PROJECT.firebaseapp.com",
    projectId: "YOUR_PROJECT_ID",
    storageBucket: "YOUR_PROJECT.firebasestorage.app",
    messagingSenderId: "YOUR_SENDER_ID",
    appId: "YOUR_APP_ID",
  },

  vapidKey: "YOUR_PUBLIC_VAPID_KEY",
};

importScripts(
  "https://www.gstatic.com/firebasejs/10.13.2/firebase-app-compat.js"
);

importScripts(
  "https://www.gstatic.com/firebasejs/10.13.2/firebase-messaging-compat.js"
);

firebase.initializeApp(
  self.TWINALYZE_FCM_CONFIG.firebaseConfig
);

const messaging = firebase.messaging();

messaging.onBackgroundMessage((payload) => {
  const data = payload.data || {};
  const notification = payload.notification || {};

  const title =
    notification.title ||
    data.title ||
    "Notification";

  const body =
    notification.body ||
    data.body ||
    data.description ||
    "";

  const icon =
    notification.icon ||
    data.icon ||
    data.iconURL ||
    data.largeIconURL ||
    "/favicon.ico";

  const clickURL =
    data.clickURL ||
    data.url ||
    "/";

  return self.registration.showNotification(title, {
    body,
    icon,
    data: {
      ...data,
      clickURL,
    },
  });
});

self.addEventListener("notificationclick", (event) => {
  event.notification.close();

  const clickURL =
    event.notification.data?.clickURL ||
    event.notification.data?.url ||
    "/";

  event.waitUntil(
    clients.openWindow(clickURL)
  );
});

The SDK does not automatically request notification permission.

Request permission from a user action:

const permission =
  await Notification.requestPermission();

console.log(permission);

Recommended payload:

data: {
  title: "Special Offer",
  body: "Get 20% off today",
  iconURL: "https://example.com/icon.png",
  clickURL: "https://example.com/offers",
  notificationType: "promotion",
}

All FCM data values should be strings.

Public Methods

init(config)

Initializes the SDK.

TwinalyzeAnalytics.init({
  apiKey: "YOUR_API_KEY",
  secretKey: "YOUR_SECRET_KEY",
});

track(eventName, properties)

Tracks a custom event.

TwinalyzeAnalytics.track("productViewed", {
  productId: "product_123",
});

identify(userId, properties)

Identifies a known user.

TwinalyzeAnalytics.identify("user_123", {
  email: "[email protected]",
});

Debugging

Enable debug logs:

debug: true

Disable them in production:

debug: false

Important Notes

• Initialize the SDK only once.
• Use HTTPS in production.
• FCM requires notification permission.
• The service worker must be available from the website root.
• Never expose Firebase service-account credentials in frontend code.
• Use stable user IDs with identify().

Support

Visit:

https://www.twinalyze.com