@aranova/tracking-react 0.5.0 → 0.6.0

package/README.md

@@ -0,0 +1,114 @@
+# @aranova/tracking-react
+
+React tracking and consent utilities for Aranova client sites.
+
+## Install
+
+```bash
+npm install @aranova/tracking-react
+```
+
+## Setup
+
+Create one shared tracking module and import the scoped `TrackingProvider` / `useTracking` from that module throughout your app.
+
+```ts
+// 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.
+
+```tsx
+// 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>,
+);
+```
+
+## Manual Events
+
+Manual events must be registered under `triggers.manual` before `trackEvent()` accepts them.
+
+```tsx
+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.
+
+```tsx
+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`
+