Web and React Native SDK

Use this SDK to add Metrickle to a website, a single-page app or a React Native app. On the web it records pageviews, friction and accessibility settings on its own, so most sites only add a few track() calls for the moments that matter. If you just want the snippet, see Install Metrickle. For what each event means and how to name your own, see Events, people and properties.

Accessibility-first product analytics and UX research for web and React Native.

On web, the SDK captures pageviews, sessions, sources, web vitals, outbound links, rage clicks, errors and friction (dead clicks, u-turns, form abandonment) automatically. It also records accessibility context such as reduced motion, contrast, text size and keyboard navigation, so you can segment every journey by assistive tech. Surveys, the feedback widget, heatmaps and session replay are configured in the Metrickle dashboard. Their UI and recorder load only when you turn them on.

Install

npm install @metrickle/sdk

Web

import { init } from "@metrickle/sdk";

const metrickle = init({
  writeKey: "mk_pub_...", // from your app's Settings page
  // cookieless: true,    // no localStorage; no consent banner needed
});

metrickle.track("signup", { plan: "pro" });
metrickle.identify(user.id, { plan: user.plan }); // after login
metrickle.reset();                                // on logout

// Research features (enable under Settings → Research)
metrickle.consent({ replay: true }); // from your consent banner
metrickle.feedback.open();           // open the feedback dialog from your own button

The SDK tracks SPA navigations through the History API by default. It honors Do Not Track and Global Privacy Control by default (respectDnt).

Options

Script tag

If you don't use a bundler, paste this before </head>:

<script defer src="https://app.metrickle.com/m.js" data-key="mk_pub_..."></script>

This exposes window.metrickle. Add data-cookieless for cookieless tracking, and data-link-domains="example.com shop.example.net" for linkDomains.

Signed-in users and devices

Call identify(user.id) after sign-in and reset() on sign-out. Metrickle then counts one person as one visitor: what they did before signing in, after it, and on every other device they sign in on. Send an opaque id, not an email. A refund or cancel you send from your server with only the user id lands on the same person, so it takes back the right completion.

More than one domain

If people move between your own domains (a marketing site and the app, a store and its checkout), list them:

init({ writeKey: "mk_pub_...", linkDomains: ["example.com", "checkout.example.net"] });

Install the SDK with the same write key on each domain, and add every domain to the app's allowed origins. Links and forms between them carry a short-lived _mk parameter with the anonymous and session ids. The page it lands on removes it from the address bar straight away. It only counts within two minutes and from a listed domain, so a copied URL can't merge two people. It never carries the user id. Without it, a funnel that crosses domains shows everyone leaving at the hand-off.

Cart value

Put a numeric value on the events that change what someone is about to buy:

metrickle.track("cart_updated", { value: 89.5, currency: "EUR", items: 3 });

When a task attempt is abandoned, the last such value inside it is what was at stake, and cases count it as money lost. Attempts without one count at the average value of a success. Only revenue counts as revenue, so cart values never inflate it.

Revenue from Stripe or RevenueCat

Connect your Stripe account or RevenueCat project in the dashboard (Integrations → Revenue) and purchases, renewals, refunds and subscription cancels arrive server-side, without track() calls. A refund then takes back the task that person completed, and subscription_canceled can be a task's revoke step. Give the provider the same id you pass to identify():

// Server, when you create the Checkout Session
await stripe.checkout.sessions.create({
  // …
  client_reference_id: user.id,
  subscription_data: { metadata: { metrickle_user_id: user.id } }, // subscriptions
});
// Or once on the customer: metadata: { metrickle_user_id: user.id }

With RevenueCat in a React Native app, log in with the same id: await Purchases.logIn(user.id). If you already send revenue on a client-side purchase event, drop it there so revenue isn't counted twice.

The feedback button

When the floating feedback button is on, it stays clear of keyboard focus on your page: the widget sets scroll-padding-bottom on <html> to the button's height plus its margin, and adds the same space at the end of the page, so a focused link or field is never scrolled underneath it (WCAG 2.4.11 and 2.4.12). It does this only when your page hasn't set its own scroll-padding-bottom; set one, even 0, to manage the space yourself. On screens 480px wide or less the button shows its icon only, keeping its label as the accessible name.

Survey follow-ups and studies

A survey can end with an invite into a study: a booked video call (moderated) or a self-guided usability test (unmoderated). You set this up in the dashboard, and the web SDK shows the invite in the survey card when the answers match. It only shows when the study is still taking people.

Participants in an unmoderated test arrive on your site with #mk_study=<token> in the URL. The SDK takes the token off the URL before the first pageview, then shows each task in a docked panel. The panel never takes focus on its own, and participants can fold it away while they work. It notices when a task's success step happens, counts friction during each task and asks how easy it was. It also keeps its place across page loads in the same tab. While a test runs, surveys wait. If the participant agreed to recording on the study page, the session is recorded even when replay is off for your app. Cookieless mode records nothing.

In a moderated session, a participant who opens a link with the same kind of token sees a small notice that the visit is shared with the research team, with an "End session" button.

React Native

npm install @metrickle/sdk @react-native-async-storage/async-storage

import AsyncStorage from "@react-native-async-storage/async-storage";
import { AccessibilityInfo, AppState, Dimensions, PixelRatio, Platform } from "react-native";
import { init } from "@metrickle/sdk/react-native";

export const metrickle = init({
  writeKey: "mk_pub_...",
  storage: AsyncStorage,
  appState: AppState,
  os: Platform.OS,
  osVersion: String(Platform.Version),
  screen: Dimensions.get("screen"),
  appVersion: "1.0.0",
  accessibility: AccessibilityInfo,   // screen reader, reduced motion, bold text, …
  fontScale: PixelRatio.getFontScale, // reports large_text above 1.15
});

// With React Navigation: onStateChange={() => metrickle.screen(currentRouteName)}
metrickle.screen("Home");
metrickle.track("checkout_started", { items: 3 });

// Render surveys with your own components
metrickle.surveys.onShow((survey) => showSurveySheet(survey)); // survey.shown(), answer(), complete() / dismiss()

// After the last answer: offer the follow-up study, if there is one
if (survey.qualifies()) {
  const url = await survey.invite(); // null: no invite, show your thank-you
  if (url) {
    survey.followUpOffered();
    // on "Choose a time" / "Take part": survey.followUpAccepted(); Linking.openURL(url);
  }
}

// Feedback (screenshot optional, as a data URL)
await metrickle.feedback.submit({ category: "bug", message: "Pay button does nothing" });

Feedback can be switched off per platform under Settings → Research in the dashboard. While it's off, metrickle.feedback.isEnabled is false and submit sends nothing, so use it to hide your feedback button.

Other platforms

@metrickle/sdk/core exports the platform-agnostic MetrickleClient. You provide the storage and transport. For Swift, Kotlin, Flutter or server code, post batches to the HTTP API at POST https://in.metrickle.com/v1/batch.