@aranova/tracking-react

React tracking and consent utilities for Aranova client sites.

Install

npm install @aranova/tracking-react

Setup

Create one shared tracking module and import the scoped TrackingProvider / useTracking from that module throughout your app.

// src/lib/tracking.ts
import { createTracking } from '@aranova/tracking-react';

export const { TrackingProvider, useTracking } = createTracking({
  apiKey: import.meta.env.VITE_ARANOVA_TRACKING_API_KEY,
  endpoint: import.meta.env.VITE_ARANOVA_TRACKING_ENDPOINT,
  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: {},
    },
  },
  debug: import.meta.env.MODE !== 'production',
});

Mount the provider at the root of your React tree.

// src/main.tsx
import { createRoot } from 'react-dom/client';
import { App } from './App';
import { TrackingProvider } from './lib/tracking';

createRoot(document.getElementById('root')!).render(
  <TrackingProvider gtagId={import.meta.env.VITE_GTAG_ID}>
    <App />
  </TrackingProvider>,
);

Multiple gtag IDs

To install multiple Google Ads tags simultaneously (for example a production MCC and a test MCC for verifying conversion actions before they touch the live account), pass gtagIds instead of gtagId. Every entry fires gtag('config', ...) on every page — gtag natively supports multiple configured tags.

<TrackingProvider
  gtagIds={{
    production: 'AW-111111111',  // real client account
    test: 'AW-222222222',         // test MCC for development
  }}
>
  <App />
</TrackingProvider>

The labels are arbitrary and surface in the Aranova dashboard's SDK versions table. You can also stamp events with a deployment environment so the dashboard can filter out test traffic:

createTracking({
  apiKey: import.meta.env.VITE_ARANOVA_TRACKING_API_KEY,
  endpoint: import.meta.env.VITE_ARANOVA_TRACKING_ENDPOINT,
  environment: import.meta.env.MODE,  // 'production' | 'development'
  triggers: { /* ... */ },
});

Manual Events

Manual events must be registered under triggers.manual before trackEvent() accepts them.

import { useTracking } from './lib/tracking';

export function LeadForm() {
  const tracking = useTracking();

  function handleSubmit(event: React.FormEvent<HTMLFormElement>) {
    const form = event.currentTarget;
    const data = new FormData(form);

    tracking.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 },
    });
  }

  return <form id="lead-form" action="/api/lead" onSubmit={handleSubmit}>{/* fields */}</form>;
}

fields[].value can be any JSON value: string, number, boolean, null, array, or object. Values must be JSON-serializable because events are stored as JSONB. Only send reviewed, allowlisted, non-sensitive values; do not send names, emails, phone numbers entered by the visitor, addresses, payment data, medical details, passwords, file contents, or free-text messages.

tracking.trackEvent('phone_click', {
  phone_number: '+14165550199',
  page: { path: window.location.pathname },
  section: 'header',
});

Exports

• createTracking()
• TrackingProvider and scoped useTracking
• GoogleAdsTracking
• ConsentBanner
• useTrackingParams(), useGclid(), useConsentState()
• Event metadata/config types such as FormSubmitMetadata, PhoneClickMetadata, and JsonValue