@aranova/tracking-browser

v0.20.0

Published

2 days ago

Aranova tracking global browser script (CDN / <script> install). Serve via jsDelivr, not as an npm import.

0High
0Medium
0Low

riteshahlawat

@aranova/tracking-browser

Global browser script for Aranova tracking on sites that cannot use the React or Next.js packages.

This package is intended for CDN/script-tag installs, not application imports.

Install

Place the script in the document <head> before the rest of the page can run.

<script src="https://cdn.jsdelivr.net/npm/@aranova/tracking-browser@0/dist/browser/aranova-tracking.global.js"></script>
<script>
  const ARANOVA_TRACKING_CONFIG = {
    cdnUrl: "https://demos.aranova.io/tracking-config/v1/<business_id>-production.json",
    businessId: "<business_id>",
    environment: "production",
  };

  window.AranovaTracking.init({
    apiKey: "aranv_pk_...",
    endpoint: "https://aranovainternal-production.up.railway.app/tracking",
    trackingConfig: ARANOVA_TRACKING_CONFIG,
    triggers: {
      automatic: {
        page_view: {},
        time_on_site: { thresholdSeconds: 60 },
        specific_page_visit: {
          pages: [{ name: "contact_page", pathPattern: /^\/(contact|book|get-started)/ }],
        },
      },
      manual: {
        form_submit: {},
        phone_click: {},
        cta_click: {},
      },
    },
  });
</script>

Pin an exact version for production when possible, for example @aranova/[email protected].

Tracking is on by default (consent v2, opt-out model) — the script ships no consent banner and the old renderConsentBanner option is a deprecated no-op. Wire a footer "cookie preferences" control to the consent API (see Consent below) and disclose the tracking + opt-out in the site's privacy policy.

Legacy static gtag IDs

gtagId and gtagIds remain compatibility APIs. Do not use them for new installs: static IDs cannot consume dashboard tag changes or tombstones without a site edit. If maintaining a legacy install, gtagIds loads every entry and takes precedence over gtagId.

<script>
  window.AranovaTracking.init({
    apiKey: "aranv_pk_...",
    endpoint: "https://aranovainternal-production.up.railway.app/tracking",
    environment: "production",
    gtagIds: { production: "AW-111111111", test: "AW-222222222" },
    triggers: { automatic: { page_view: {} } },
  });
</script>

Manual Events

The browser package validates manual events at runtime. If an event is not registered under triggers.manual, or the metadata shape is invalid, the SDK warns and drops the event.

<form id="lead-form" action="/api/lead">
  <select name="service_interest" aria-label="Service interest">
    <option value="cleaning">Cleaning</option>
    <option value="teeth_whitening">Teeth whitening</option>
  </select>
  <label>
    <input name="is_existing_patient" type="checkbox" />
    Existing patient
  </label>
  <button type="submit">Submit</button>
</form>

<script>
  document.getElementById("lead-form").addEventListener("submit", function (event) {
    var form = event.currentTarget;
    var data = new FormData(form);

    window.AranovaTracking.trackEvent("form_submit", {
      form: {
        id: form.id,
        action: form.getAttribute("action"),
        fields: [
          {
            name: "service_interest",
            type: "select",
            label: "Service interest",
            value: String(data.get("service_interest") || ""),
          },
          {
            name: "is_existing_patient",
            type: "checkbox",
            label: "Existing patient",
            value: data.get("is_existing_patient") === "on",
          },
        ],
      },
      page: { path: window.location.pathname },
    });
  });
</script>

fields[].value can be any JSON value: string, number, boolean, null, array, or object and is stored as first-party JSONB. Intentionally submitted lead fields may include raw names, emails, phone numbers, addresses, selections, free-text messages, and submitted file data for first-party analytics and lead operations. Build the array explicitly from the submitted form; the SDK never scrapes arbitrary DOM fields. File/Blob objects must be converted to a JSON representation, and the complete event metadata must fit the 4 KB limit; upload larger files separately and send their storage reference. Never send passwords, authentication tokens, payment-card/bank credentials, or private keys. Apply the client's privacy notice, consent, retention, and regulated-data requirements. Google offline matching uses normalized, server-side SHA-256-hashed identifiers — not raw free-text/file metadata.

Phone clicks (`tel:` taps) — manual or auto-capture

Opt into auto-capture and every tel: link is tracked with no per-link code — add autoCapture to the phone_click registration in init():

manual: {
  phone_click: { autoCapture: {} }, // default selector: a[href^="tel:"]
  // or narrow it: { autoCapture: { selector: "a.call" } }
},

Then use ordinary phone links — a single delegated listener does the rest:

<a href="tel:+14165550199" data-aranova-section="header">(416) 555-0199</a>

The number is read from the href (normalized to E.164); section comes from an optional data-aranova-section. Unlike cta_click, a phone_click also fires the Google Ads conversion for a linked phone-call goal (a CLICK_TO_CALL action) — auto-fired the moment the tap is captured, so you never call trackConversion. (Firing needs trackingConfig wired; see below.)

Prefer to instrument links yourself? Fire it per element instead — this fires the conversion the same way:

<a
  href="tel:+14165550199"
  onclick="window.AranovaTracking.trackEvent('phone_click', {
  phone_number: '+14165550199',
  page: { path: window.location.pathname },
  section: 'header'
})"
  >(416) 555-0199</a
>

CTA clicks — manual or auto-capture

Fire cta_click per element with an inline handler, or opt into auto-capture and skip the handlers entirely. Add autoCapture to the cta_click registration in init():

manual: {
  cta_click: { autoCapture: {} }, // default selector: [data-aranova-cta]
  // or target existing classes: { autoCapture: { selector: "a.cta, .btn-primary" } }
},

Then tag your CTAs with data attributes — a single delegated listener does the rest:

<a href="/booking" data-aranova-cta="Book now" data-aranova-section="hero">Book now</a>
<button data-aranova-cta="Get a quote">Get a quote</button>

cta_name resolves to the data-aranova-cta value, else the element's trimmed text (capped 120 chars), else tag#id. section comes from an optional data-aranova-section; href/destination_url and a short element descriptor are captured automatically. Point the selector at real CTAs (an explicit attribute is the safe default) — every matching click is counted, including ones that later stopPropagation.

Automatic dwell + exit (`page_exit`)

page_exit is captured automatically — no registration. On navigation, tab hide, and page unload it records the active (visible) time spent on the page plus the max scroll depth reached, delivered via a keepalive beacon so the final page still counts. This powers per-page dwell and drop-off in the dashboard Analytics tab; there is nothing to configure.

Global API

window.AranovaTracking.init(config);
window.AranovaTracking.trackEvent(eventType, metadata);
window.AranovaTracking.captureTrackingParams();
window.AranovaTracking.getTrackingParams();
window.AranovaTracking.sales().record({ ... }); // record a sale / conversion

Consent (v2 — opt-out model)

Tracking is on by default; only a stored, unexpired explicit decline blocks gtag, the Meta Pixel, and conversion firing. A decline is honored for 90 days; a grant never expires. Wire a footer control to:

window.AranovaTracking.optOut(); // explicit decline (90 days)
window.AranovaTracking.optIn(); // explicit grant (never expires)
window.AranovaTracking.resetConsent(); // clear the choice → back to default-granted
window.AranovaTracking.getConsentChoice(); // { state, source, updatedAt, expiresAt }
window.AranovaTracking.getConsentState(); // effective "granted" | "denied"

<button onclick="window.AranovaTracking.optOut()">Opt out of ad measurement</button>

setConsentState('granted' | 'denied') remains for compatibility.

sales() returns a client bound to the public key and endpoint you passed to init(), so it can only write conversions (record). All reads — list, summary (tz-aware aggregations), the phone-keyed customers.* roster, business.config(), update, delete — require a secret key (aranv_sk_…) and must run server-side via the React/Next packages. See the sales-tracking guide.

On-site conversion firing

Pass the generated ARANOVA_TRACKING_CONFIG reference to init(). The browser SDK shares one R2 runtime for Google tag loading, page views, automatic goals, and AranovaTracking.sales() firing. It confirms the current object before any Google command; dashboard tag changes, goal remaps, and higher-version disabled tombstones propagate under public, max-age=60, must-revalidate with no CLI run or site redeploy.

<script>
  const ARANOVA_TRACKING_CONFIG = {
    cdnUrl: "https://demos.aranova.io/tracking-config/v1/<business_id>-production.json",
    businessId: "<business_id>",
    environment: "production",
  };

  window.AranovaTracking.init({
    apiKey: "aranv_pk_...",
    endpoint: "https://api.example.com/tracking",
    triggers: {
      automatic: { page_view: {}, scroll_depth: { thresholds: [50] } },
      manual: { phone_click: {} },
    },
    trackingConfig: ARANOVA_TRACKING_CONFIG,
  });

  // Automatic event-goals (scroll/time/page-view/…) fire THEMSELVES — no code.
  // init() also binds the sales client to the config, so these fire too:
  window.AranovaTracking.sales().recordSale({
    currency: "CAD",
    amount_total_cents: 25000,
    service: "tires",
  }); // records + fires
  window.AranovaTracking.sales().trackConversion("phone_click"); // fires a manual event-goal only
</script>

Firing is consent-gated and de-duped by transaction_id. Remapping an existing key needs no codegen. A new manual goal key still requires tracking-cli gen to refresh the generated key list and site code that calls trackConversion(key). conversionConfig: { cdnUrl } and generated ARANOVA_CONFIG_URL remain legacy compatibility APIs; do not use them for new installs. See conversion-config-schema.md.

Automatic Events

Configured automatic events are fired by the SDK:

page_view
time_on_site
specific_page_visit
scroll_depth
multi_page_session
form_start

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@aranova/tracking-browser

Install

Legacy static gtag IDs

Manual Events

Phone clicks (tel: taps) — manual or auto-capture

CTA clicks — manual or auto-capture

Automatic dwell + exit (page_exit)

Global API

Consent (v2 — opt-out model)

On-site conversion firing

Automatic Events

Phone clicks (`tel:` taps) — manual or auto-capture

Automatic dwell + exit (`page_exit`)