Client-Side Tracking

The Gro tracking SDK is a lightweight browser library (about 5KB minified, 2KB gzipped) that captures page views, custom events, and user identities and sends them to Gro. Use it to power analytics, build segments, and trigger automations from real customer behaviour on your storefront or web app.

Get an API key

Every tracking call is authenticated with an API key.

In the dashboard, go to Settings › API Keys and click New API Key.
Give it a name and choose the SDK type. This is the key used for all tracking calls.
The key is shown only once. Copy it and store it somewhere safe.

Keys look like gro_live_.... SDK keys are safe to embed in your public page source, so there is no need to hide them.

Install with the snippet

Paste this snippet into the <head> of your site. It loads asynchronously and will not block page rendering. Replace the key with your own.

<script>
  !(function () {
    var g = (window.gro = window.gro || []);
    if (g.init && g._loaded) return;
    g.methods = ["init", "track", "page", "identify"];
    g.factory = function (m) {
      return function () {
        var a = Array.prototype.slice.call(arguments);
        a.unshift(m);
        g.push(a);
        return g;
      };
    };
    for (var i = 0; i < g.methods.length; i++) {
      var k = g.methods[i];
      g[k] = g.factory(k);
    }
    g.load = function (apiKey, opts) {
      var s = document.createElement("script");
      s.type = "text/javascript";
      s.async = !0;
      s.src = (opts && opts.sdkUrl) || "https://cdn.usegro.net/sdk/v1/gro.js";
      var f = document.getElementsByTagName("script")[0];
      f.parentNode.insertBefore(s, f);
      if (apiKey) {
        g.init(opts || { apiKey: apiKey });
      }
    };
    g._snippet = !0;
  })();

  gro.load("gro_live_your_api_key_here");
  gro.page(); // Track initial page view
</script>

The snippet queues any track, page, or identify calls you make before the SDK finishes loading, then replays them once it is ready, so you can start calling gro.* immediately.

Install with npm

If you build your frontend with a bundler, install the package instead:

npm install @gro/tracking-sdk

Then initialize it once when your app starts:

import gro from "@gro/tracking-sdk";

gro.init({
  apiKey: "gro_live_your_api_key_here",
  trackingUrl: "https://tracking.usegro.net", // optional
  debug: false, // optional
  autoPageView: true, // optional (default: true)
});

With autoPageView enabled (the default), the SDK records a page view automatically on initialization.

Track custom events

Use gro.track(eventName, properties) to record any custom event:

// Track a custom event
gro.track("Product Viewed", {
  product_id: "123",
  product_name: "Premium Widget",
  price: 29.99,
  category: "Electronics",
});

// Track button clicks
gro.track("Button Clicked", {
  button_id: "signup-cta",
  location: "homepage",
});

Track page views

Page views are recorded automatically on initialization. You can also record them manually, which is useful for single-page apps that change route without a full reload:

// Track a page view
gro.page();

// Track with a page name
gro.page("Product Page");

// Track with properties
gro.page("Product Page", {
  category: "Electronics",
  referrer: document.referrer,
});

Identify users

Link an anonymous visitor to a known customer when they sign up or log in. Everything they did before identifying is stitched to their profile:

// Identify with email only
gro.identify("user@example.com");

// Identify with email and traits
gro.identify("user@example.com", {
  firstName: "John",
  lastName: "Doe",
  plan: "premium",
});

// Identify with an object
gro.identify({
  email: "user@example.com",
  id: "user_123",
  firstName: "John",
  lastName: "Doe",
});

Prevent duplicate events

By default every event gets a unique auto-generated event_id. To guard against duplicates (for example when a customer refreshes an order confirmation page), pass your own event_id in the properties. Events sharing an event_id are stored only once:

gro.track("Order Completed", {
  event_id: "ord_123", // Only the first event with this id is stored
  order_id: "ord_123",
  total: 99.99,
});

What gets captured automatically

Every event the SDK sends is enriched for you:

Identifiers: a persistent anonymous ID and a session ID, stored in cookies so returning visitors are recognised.
Page context: page URL, title, referrer, and screen dimensions.
Server-side enrichment: the tracking endpoint adds the user agent, IP address, and geo (country and city) from the request.

Next steps

Not everything happens in the browser. To send events from your backend (order webhooks, cron jobs, subscription lifecycle events), see Server-Side Tracking.