@aranova/tracking-next 0.6.1 → 0.7.0

package/README.md

@@ -78,6 +78,35 @@ export default function RootLayout({ children }: { children: React.ReactNode })
 }
 ```
 
+### 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.
+
+```tsx
+<GoogleAdsTracking
+  gtagIds={{
+    production: 'AW-111111111',  // real client account
+    test: 'AW-222222222',         // test MCC for development
+  }}
+/>
+```
+
+The labels are arbitrary and surface in the Aranova dashboard's SDK versions table. Also pass `environment` to the factory so events are tagged with the deployment context for dashboard filtering:
+
+```ts
+// lib/tracking.ts
+createTracking({
+  apiKey: process.env.NEXT_PUBLIC_ARANOVA_TRACKING_API_KEY!,
+  endpoint: process.env.NEXT_PUBLIC_ARANOVA_TRACKING_ENDPOINT!,
+  environment: process.env.NEXT_PUBLIC_TRACKING_ENVIRONMENT,  // 'production' | 'development'
+  gtagIds: {  // optional — reports the configured tags in heartbeat metadata
+    production: process.env.NEXT_PUBLIC_GTAG_PROD!,
+    test: process.env.NEXT_PUBLIC_GTAG_TEST!,
+  },
+  triggers: { /* ... */ },
+});
+```
+
 ## Manual Events
 
 Import `useTracking` from your local `lib/tracking` module, not directly from the package.

package/dist/index.d.mts

@@ -1,5 +1,5 @@
-import { C as ConsentState, T as TrackingInstallSurface, a as TrackingClientContext, b as TrackingParams, c as TrackingEventCreatePayload, d as TrackingSessionUpsertPayload } from './types-B4VZHWnc.mjs';
-export { e as TrackingInitConfig } from './types-B4VZHWnc.mjs';
+import { C as ConsentState, T as TrackingInstallSurface, a as TrackingEnvironment, b as TrackingClientContext, c as TrackingParams, d as TrackingEventCreatePayload, e as TrackingSessionUpsertPayload, G as GtagEnvironmentMap } from './types-D0Vm9WRC.mjs';
+export { f as TrackingInitConfig } from './types-D0Vm9WRC.mjs';
 import { z } from 'zod';
 import * as src from 'src';
 import * as react_jsx_runtime from 'react/jsx-runtime';
@@ -28,6 +28,8 @@ interface TrackingContextInput {
     referrer?: string | null;
     sdkVersion?: string | null;
     siteOrigin?: string | null;
+    environment?: TrackingEnvironment | null;
+    activeGtagIds?: Record<string, string> | null;
 }
 interface TrackingEventInput {
     eventType: string;
@@ -129,6 +131,7 @@ declare const sdkHeartbeatMetadataSchema: z.ZodObject<{
         manual: string[];
     }>;
     trigger_config: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>>>>;
+    configured_gtag_ids: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodString>>>;
 }, "strict", z.ZodTypeAny, {
     sdk_version: string;
     package_name: string | null;
@@ -138,6 +141,7 @@ declare const sdkHeartbeatMetadataSchema: z.ZodObject<{
         manual: string[];
     };
     trigger_config?: Record<string, Record<string, unknown>> | null | undefined;
+    configured_gtag_ids?: Record<string, string> | null | undefined;
 }, {
     sdk_version: string;
     package_name: string | null;
@@ -147,6 +151,7 @@ declare const sdkHeartbeatMetadataSchema: z.ZodObject<{
         manual: string[];
     };
     trigger_config?: Record<string, Record<string, unknown>> | null | undefined;
+    configured_gtag_ids?: Record<string, string> | null | undefined;
 }>;
 type SdkHeartbeatMetadata = z.infer<typeof sdkHeartbeatMetadataSchema>;
 /**
@@ -882,6 +887,7 @@ declare const EVENT_REGISTRY: {
                 manual: string[];
             }>;
             trigger_config: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>>>>;
+            configured_gtag_ids: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodString>>>;
         }, "strict", z.ZodTypeAny, {
             sdk_version: string;
             package_name: string | null;
@@ -891,6 +897,7 @@ declare const EVENT_REGISTRY: {
                 manual: string[];
             };
             trigger_config?: Record<string, Record<string, unknown>> | null | undefined;
+            configured_gtag_ids?: Record<string, string> | null | undefined;
         }, {
             sdk_version: string;
             package_name: string | null;
@@ -900,6 +907,7 @@ declare const EVENT_REGISTRY: {
                 manual: string[];
             };
             trigger_config?: Record<string, Record<string, unknown>> | null | undefined;
+            configured_gtag_ids?: Record<string, string> | null | undefined;
         }>;
         readonly configSchema: z.ZodObject<{}, "strict", z.ZodTypeAny, {}, {}>;
     };
@@ -1250,19 +1258,26 @@ declare function useTrackingParams(): TrackingParams;
  */
 declare function useConsentState(): ConsentState;
 
-interface GoogleAdsTrackingProps {
-    /**
-     * Google Ads tag id, for example `AW-123456789`.
-     */
+/**
+ * Props for the Next.js Google Ads tracking component.
+ *
+ * Accepts either a single `gtagId` (legacy) or a labelled `gtagIds` map
+ * where ALL entries are loaded simultaneously via `gtag('config', ...)`.
+ */
+type GoogleAdsTrackingProps = {
     gtagId: string;
-}
+    gtagIds?: undefined;
+} | {
+    gtagId?: undefined;
+    gtagIds: GtagEnvironmentMap;
+};
 /**
  * Next.js client component that loads Google Ads gtag with Consent Mode.
  *
  * Render in the root layout `<head>` when the client site runs paid Google
  * Ads. The component injects Next `<Script>` tags and renders no visible UI.
  */
-declare function GoogleAdsTracking({ gtagId }: GoogleAdsTrackingProps): react_jsx_runtime.JSX.Element;
+declare function GoogleAdsTracking(props: GoogleAdsTrackingProps): react_jsx_runtime.JSX.Element | null;
 
 interface CreateTrackingOptions<TRegistry extends TriggerRegistryConfig> {
     /**
@@ -1279,6 +1294,19 @@ interface CreateTrackingOptions<TRegistry extends TriggerRegistryConfig> {
      * Trigger registry that controls automatic events and typed manual events.
      */
     triggers: TRegistry;
+    /**
+     * Deployment environment label reported in session context.
+     */
+    environment?: TrackingEnvironment;
+    /**
+     * Labelled map of Google Ads tag IDs. Included in session context and
+     * heartbeat metadata so the dashboard can show what's configured.
+     *
+     * This does NOT load the gtag scripts — use `<GoogleAdsTracking gtagIds={...} />`
+     * in the root layout for that. This option only controls what's reported
+     * in the tracking payload context.
+     */
+    gtagIds?: Record<string, string>;
     /**
      * Validate manual event metadata at runtime before queueing.
      *

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { C as ConsentState, T as TrackingInstallSurface, a as TrackingClientContext, b as TrackingParams, c as TrackingEventCreatePayload, d as TrackingSessionUpsertPayload } from './types-B4VZHWnc.js';
-export { e as TrackingInitConfig } from './types-B4VZHWnc.js';
+import { C as ConsentState, T as TrackingInstallSurface, a as TrackingEnvironment, b as TrackingClientContext, c as TrackingParams, d as TrackingEventCreatePayload, e as TrackingSessionUpsertPayload, G as GtagEnvironmentMap } from './types-D0Vm9WRC.js';
+export { f as TrackingInitConfig } from './types-D0Vm9WRC.js';
 import { z } from 'zod';
 import * as src from 'src';
 import * as react_jsx_runtime from 'react/jsx-runtime';
@@ -28,6 +28,8 @@ interface TrackingContextInput {
     referrer?: string | null;
     sdkVersion?: string | null;
     siteOrigin?: string | null;
+    environment?: TrackingEnvironment | null;
+    activeGtagIds?: Record<string, string> | null;
 }
 interface TrackingEventInput {
     eventType: string;
@@ -129,6 +131,7 @@ declare const sdkHeartbeatMetadataSchema: z.ZodObject<{
         manual: string[];
     }>;
     trigger_config: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>>>>;
+    configured_gtag_ids: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodString>>>;
 }, "strict", z.ZodTypeAny, {
     sdk_version: string;
     package_name: string | null;
@@ -138,6 +141,7 @@ declare const sdkHeartbeatMetadataSchema: z.ZodObject<{
         manual: string[];
     };
     trigger_config?: Record<string, Record<string, unknown>> | null | undefined;
+    configured_gtag_ids?: Record<string, string> | null | undefined;
 }, {
     sdk_version: string;
     package_name: string | null;
@@ -147,6 +151,7 @@ declare const sdkHeartbeatMetadataSchema: z.ZodObject<{
         manual: string[];
     };
     trigger_config?: Record<string, Record<string, unknown>> | null | undefined;
+    configured_gtag_ids?: Record<string, string> | null | undefined;
 }>;
 type SdkHeartbeatMetadata = z.infer<typeof sdkHeartbeatMetadataSchema>;
 /**
@@ -882,6 +887,7 @@ declare const EVENT_REGISTRY: {
                 manual: string[];
             }>;
             trigger_config: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>>>>;
+            configured_gtag_ids: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodString>>>;
         }, "strict", z.ZodTypeAny, {
             sdk_version: string;
             package_name: string | null;
@@ -891,6 +897,7 @@ declare const EVENT_REGISTRY: {
                 manual: string[];
             };
             trigger_config?: Record<string, Record<string, unknown>> | null | undefined;
+            configured_gtag_ids?: Record<string, string> | null | undefined;
         }, {
             sdk_version: string;
             package_name: string | null;
@@ -900,6 +907,7 @@ declare const EVENT_REGISTRY: {
                 manual: string[];
             };
             trigger_config?: Record<string, Record<string, unknown>> | null | undefined;
+            configured_gtag_ids?: Record<string, string> | null | undefined;
         }>;
         readonly configSchema: z.ZodObject<{}, "strict", z.ZodTypeAny, {}, {}>;
     };
@@ -1250,19 +1258,26 @@ declare function useTrackingParams(): TrackingParams;
  */
 declare function useConsentState(): ConsentState;
 
-interface GoogleAdsTrackingProps {
-    /**
-     * Google Ads tag id, for example `AW-123456789`.
-     */
+/**
+ * Props for the Next.js Google Ads tracking component.
+ *
+ * Accepts either a single `gtagId` (legacy) or a labelled `gtagIds` map
+ * where ALL entries are loaded simultaneously via `gtag('config', ...)`.
+ */
+type GoogleAdsTrackingProps = {
     gtagId: string;
-}
+    gtagIds?: undefined;
+} | {
+    gtagId?: undefined;
+    gtagIds: GtagEnvironmentMap;
+};
 /**
  * Next.js client component that loads Google Ads gtag with Consent Mode.
  *
  * Render in the root layout `<head>` when the client site runs paid Google
  * Ads. The component injects Next `<Script>` tags and renders no visible UI.
  */
-declare function GoogleAdsTracking({ gtagId }: GoogleAdsTrackingProps): react_jsx_runtime.JSX.Element;
+declare function GoogleAdsTracking(props: GoogleAdsTrackingProps): react_jsx_runtime.JSX.Element | null;
 
 interface CreateTrackingOptions<TRegistry extends TriggerRegistryConfig> {
     /**
@@ -1279,6 +1294,19 @@ interface CreateTrackingOptions<TRegistry extends TriggerRegistryConfig> {
      * Trigger registry that controls automatic events and typed manual events.
      */
     triggers: TRegistry;
+    /**
+     * Deployment environment label reported in session context.
+     */
+    environment?: TrackingEnvironment;
+    /**
+     * Labelled map of Google Ads tag IDs. Included in session context and
+     * heartbeat metadata so the dashboard can show what's configured.
+     *
+     * This does NOT load the gtag scripts — use `<GoogleAdsTracking gtagIds={...} />`
+     * in the root layout for that. This option only controls what's reported
+     * in the tracking payload context.
+     */
+    gtagIds?: Record<string, string>;
     /**
      * Validate manual event metadata at runtime before queueing.
      *

package/dist/index.js

@@ -82,7 +82,9 @@ function createTrackingClientContext(surface, input = {}) {
     package_name: input.packageName ?? null,
     site_origin: input.siteOrigin ?? (typeof window === "undefined" ? null : window.location.origin),
     page_title: input.pageTitle ?? (typeof document === "undefined" ? null : document.title || null),
-    referrer: input.referrer ?? (typeof document === "undefined" ? null : document.referrer || null)
+    referrer: input.referrer ?? (typeof document === "undefined" ? null : document.referrer || null),
+    environment: input.environment ?? null,
+    active_gtag_ids: input.activeGtagIds ?? null
   };
 }
 function createTrackingSessionUpsertPayload(trackingParams, input, context) {
@@ -114,6 +116,10 @@ function createTrackingEventCreatePayload(trackingParams, input, context) {
 }
 
 // ../tracking-core/src/gtag.ts
+var GTAG_ID_PATTERN = /^[A-Z]{1,3}-[A-Za-z0-9_-]+$/;
+function isValidGtagId(id) {
+  return GTAG_ID_PATTERN.test(id);
+}
 function createConsentDefaultScript() {
   return `
 window.dataLayer = window.dataLayer || [];
@@ -129,6 +135,7 @@ gtag('consent', 'default', {
 `.trim();
 }
 function createGtagInitScript(gtagId) {
+  if (!isValidGtagId(gtagId)) return "";
   return `
 window.dataLayer = window.dataLayer || [];
 function gtag(){dataLayer.push(arguments);}
@@ -150,6 +157,17 @@ if (window.gtag && (consentState === 'granted' || consentState === 'denied')) {
 }
 `.trim();
 }
+function createGtagInitScriptMulti(gtagIds) {
+  const safeIds = gtagIds.filter(isValidGtagId);
+  const configs = safeIds.map((id) => `gtag('config', '${id}');`).join("\n");
+  return `
+window.dataLayer = window.dataLayer || [];
+function gtag(){dataLayer.push(arguments);}
+window.gtag = gtag;
+gtag('js', new Date());
+${configs}
+`.trim();
+}
 
 // ../tracking-core/src/tracking.ts
 var TRACKING_COOKIE_MAX_AGE_SECONDS = 7776e3;
@@ -384,7 +402,7 @@ function serializeValue(value) {
   }
   return value;
 }
-function buildHeartbeatMetadata(surface, sdkVersion, packageName, triggers) {
+function buildHeartbeatMetadata(surface, sdkVersion, packageName, triggers, gtagIds = null) {
   const automaticNames = triggers ? Object.keys(triggers.automatic) : [];
   const manualNames = triggers?.manual ? Object.keys(triggers.manual) : [];
   let triggerConfig = null;
@@ -417,7 +435,8 @@ function buildHeartbeatMetadata(surface, sdkVersion, packageName, triggers) {
       automatic: automaticNames,
       manual: manualNames
     },
-    trigger_config: triggerConfig
+    trigger_config: triggerConfig,
+    configured_gtag_ids: gtagIds
   };
 }
 
@@ -426,14 +445,16 @@ var DEFAULT_FLUSH_INTERVAL_MS = 2e3;
 var DEFAULT_MAX_QUEUE_SIZE = 10;
 var HARD_MAX_BATCH = 50;
 var API_KEY_HEADER = "X-Aranova-Api-Key";
-function buildContext(surface, sdkVersion, packageName) {
+function buildContext(surface, sdkVersion, packageName, environment, activeGtagIds) {
   return {
     surface,
     sdk_version: sdkVersion,
     package_name: packageName,
     site_origin: typeof window === "undefined" ? null : window.location.origin,
     page_title: typeof document === "undefined" ? null : document.title || null,
-    referrer: typeof document === "undefined" ? null : document.referrer || null
+    referrer: typeof document === "undefined" ? null : document.referrer || null,
+    environment,
+    active_gtag_ids: activeGtagIds
   };
 }
 function readTrackingParams() {
@@ -493,6 +514,8 @@ function createTrackingClient(config) {
   const maxQueueSize = Math.min(config.maxQueueSize ?? DEFAULT_MAX_QUEUE_SIZE, HARD_MAX_BATCH);
   const sdkVersion = config.sdkVersion ?? null;
   const packageName = config.packageName ?? null;
+  const environment = config.environment ?? null;
+  const activeGtagIds = config.activeGtagIds ?? null;
   const endpointBase = config.endpoint.replace(/\/$/, "");
   const eventsUrl = `${endpointBase}/events`;
   let queue = [];
@@ -509,7 +532,8 @@ function createTrackingClient(config) {
       config.surface,
       sdkVersion,
       packageName,
-      config.triggers ?? null
+      config.triggers ?? null,
+      activeGtagIds
     );
     queue.push({
       event_type: "sdk_heartbeat",
@@ -528,7 +552,7 @@ function createTrackingClient(config) {
     }
     sessionId = rotated.id;
     const params = readTrackingParams();
-    const context = buildContext(config.surface, sdkVersion, packageName);
+    const context = buildContext(config.surface, sdkVersion, packageName, environment, activeGtagIds);
     return {
       session_id: sessionId,
       visitor_id: visitorId,
@@ -650,7 +674,8 @@ var sdkHeartbeatMetadataSchema = import_zod3.z.object({
   package_name: import_zod3.z.string().nullable(),
   surface: import_zod3.z.enum(["next", "react", "script"]),
   triggers: sdkHeartbeatTriggersSchema,
-  trigger_config: import_zod3.z.record(import_zod3.z.string(), import_zod3.z.record(import_zod3.z.string(), import_zod3.z.unknown())).nullable().optional()
+  trigger_config: import_zod3.z.record(import_zod3.z.string(), import_zod3.z.record(import_zod3.z.string(), import_zod3.z.unknown())).nullable().optional(),
+  configured_gtag_ids: import_zod3.z.record(import_zod3.z.string(), import_zod3.z.string()).nullable().optional()
 }).strict();
 var sdkHeartbeatConfigSchema = import_zod3.z.object({}).strict();
 
@@ -1139,17 +1164,22 @@ function useConsentState() {
 // src/GoogleAdsTracking.tsx
 var import_script = __toESM(require("next/script"));
 var import_jsx_runtime2 = require("react/jsx-runtime");
-function GoogleAdsTracking({ gtagId }) {
+function GoogleAdsTracking(props) {
+  const { gtagId, gtagIds } = props;
+  const allIds = gtagIds ? Object.values(gtagIds) : gtagId ? [gtagId] : [];
+  if (allIds.length === 0) return null;
+  const loaderId = allIds[0];
+  const initScript = allIds.length === 1 ? createGtagInitScript(allIds[0]) : createGtagInitScriptMulti(allIds);
   return /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)(import_jsx_runtime2.Fragment, { children: [
     /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(import_script.default, { id: "consent-default", strategy: "beforeInteractive", children: createConsentDefaultScript() }),
     /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(
       import_script.default,
       {
-        src: `https://www.googletagmanager.com/gtag/js?id=${gtagId}`,
+        src: `https://www.googletagmanager.com/gtag/js?id=${encodeURIComponent(loaderId)}`,
         strategy: "afterInteractive"
       }
     ),
-    /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(import_script.default, { id: "gtag-init", strategy: "afterInteractive", children: createGtagInitScript(gtagId) }),
+    /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(import_script.default, { id: "gtag-init", strategy: "afterInteractive", children: initScript }),
     /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(import_script.default, { id: "consent-restore", strategy: "afterInteractive", children: createConsentRestoreScript() })
   ] });
 }
@@ -1158,13 +1188,13 @@ function GoogleAdsTracking({ gtagId }) {
 var import_navigation = require("next/navigation");
 
 // package.json
-var version = "0.6.1";
+var version = "0.7.0";
 
 // src/factory.tsx
 var import_react3 = require("react");
 var import_jsx_runtime3 = require("react/jsx-runtime");
 function createTracking(options) {
-  const { apiKey, endpoint, triggers, debug } = options;
+  const { apiKey, endpoint, triggers, environment, gtagIds, debug } = options;
   if (!apiKey || !endpoint) {
     if (apiKey || endpoint) {
       console.warn(
@@ -1199,6 +1229,8 @@ function createTracking(options) {
           packageName: "@aranova/tracking-next",
           sdkVersion: version,
           triggers,
+          environment,
+          activeGtagIds: gtagIds,
           debug
         }),
         triggers,
@@ -1213,6 +1245,8 @@ function createTracking(options) {
         surface: "next",
         packageName: "@aranova/tracking-next",
         triggers,
+        environment,
+        activeGtagIds: gtagIds,
         debug
       });
       fireManualPageView(rawClient);
@@ -1226,6 +1260,8 @@ function createTracking(options) {
         surface: "next",
         packageName: "@aranova/tracking-next",
         triggers,
+        environment,
+        activeGtagIds: gtagIds,
         debug
       });
       for (const { name, pathPattern } of specificPageVisitConfig.pages) {
@@ -1248,6 +1284,8 @@ function createTracking(options) {
         surface: "next",
         packageName: "@aranova/tracking-next",
         triggers,
+        environment,
+        activeGtagIds: gtagIds,
         debug
       });
       return attachBfcacheRestore(rawClient);
@@ -1260,6 +1298,8 @@ function createTracking(options) {
         surface: "next",
         packageName: "@aranova/tracking-next",
         triggers,
+        environment,
+        activeGtagIds: gtagIds,
         debug
       });
       return attachTimeOnSite(rawClient, timeOnSiteConfig);
@@ -1294,7 +1334,10 @@ function createTracking(options) {
             endpoint,
             surface: "next",
             packageName: "@aranova/tracking-next",
+            sdkVersion: version,
             triggers,
+            environment,
+            activeGtagIds: gtagIds,
             debug
           });
           rawClient.trackEvent({
@@ -1318,6 +1361,8 @@ function createTracking(options) {
         surface: "next",
         packageName: "@aranova/tracking-next",
         triggers,
+        environment,
+        activeGtagIds: gtagIds,
         debug
       });
       const scrollDepth = triggers.automatic.scroll_depth;