@fire-spark/analytics-ga4 0.19.1 → 0.19.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.ts CHANGED
@@ -30,9 +30,26 @@ type Ga4Options = {
30
30
  measurementId?: string;
31
31
  /**
32
32
  * Web: params of `gtag("config", measurementId, config)`, for example
33
- * `debug_mode`, `send_page_view` or `cookie_domain`.
33
+ * `send_page_view` or `cookie_domain`. DebugView uses `debug`.
34
34
  */
35
35
  config?: Record<string, unknown>;
36
+ /**
37
+ * Web: GA4 DebugView. `true` adds `debug_mode: true` to every
38
+ * `gtag("event")` next to `send_to`, and to the config params.
39
+ * When `debug` is omitted, `config.debug_mode === true` does the same.
40
+ * `false` turns it off and drops the key. GA4 turns debug on for any
41
+ * `debug_mode` value, including `false`, so this adapter never sends
42
+ * `debug_mode: false`.
43
+ *
44
+ * The automatic `page_view` from `gtag("config")` may not be marked as
45
+ * debug with a real Google tag. Consumers who need that hit in
46
+ * DebugView can set `send_page_view: false` and send `page_view` as an
47
+ * event.
48
+ *
49
+ * React Native: ignored. Firebase DebugView uses `adb` or
50
+ * `-FIRDebugEnabled`.
51
+ */
52
+ debug?: boolean;
36
53
  /** Web: consent mode defaults, set before the first `config`. */
37
54
  consentDefaults?: Ga4ConsentDefaults;
38
55
  /** React Native: Firebase `logEvent`. */
package/dist/index.js CHANGED
@@ -110,10 +110,54 @@ const hostLoadsGtag = (win) => {
110
110
  return hasScript(GTAG_ORIGIN, SCRIPT_ID);
111
111
  };
112
112
  /**
113
+ * Hits carry `debug_mode: true` when `debug` is `true`. When `debug` is
114
+ * omitted, `config.debug_mode === true` is the same opt-in. `false` is off.
115
+ */
116
+ const isGa4Debug = (debug, config) => {
117
+ if (debug !== void 0) return debug;
118
+ return config?.debug_mode === true;
119
+ };
120
+ const omitDebugKey = (params) => {
121
+ if (!Object.hasOwn(params, "debug_mode")) return params;
122
+ const { debug_mode, ...rest } = params;
123
+ return rest;
124
+ };
125
+ /**
126
+ * Params of `gtag("config", id, …)`. Adds `debug_mode: true` when debug
127
+ * is on and drops `debug_mode: false`. GA4 treats any `debug_mode` value
128
+ * as debug, including `false`.
129
+ */
130
+ const gtagConfigParams = (config, debug) => {
131
+ const source = config ?? {};
132
+ const enabled = isGa4Debug(debug, source);
133
+ const drop = debug === false || source.debug_mode === false;
134
+ if (!enabled && !drop) return source;
135
+ const base = drop ? omitDebugKey(source) : source;
136
+ if (!enabled) return base;
137
+ return {
138
+ ...base,
139
+ debug_mode: true
140
+ };
141
+ };
142
+ /**
143
+ * Params of `gtag("event", name, …)`. `send_to` routes the hit, then
144
+ * `debug_mode: true` when debug is on. `debug_mode: false` is removed.
145
+ */
146
+ const gtagEventParams = (params, measurementId, enabled) => {
147
+ const dropFalse = params.debug_mode === false;
148
+ if (!enabled && !measurementId && !dropFalse) return params;
149
+ const payload = { ...params };
150
+ if (measurementId) payload.send_to = measurementId;
151
+ if (dropFalse || enabled) delete payload.debug_mode;
152
+ if (enabled) payload.debug_mode = true;
153
+ return payload;
154
+ };
155
+ /**
113
156
  * Installs the official stub when missing, sets the consent defaults before
114
157
  * any `config`, configures each measurement id once and loads gtag.js unless
115
158
  * it is already on the page. Commands stay in `dataLayer` when the script
116
- * fails, and the next call retries the load.
159
+ * fails, and the next call retries the load. When debug is on, that
160
+ * config includes `debug_mode: true`. `debug_mode: false` is omitted.
117
161
  */
118
162
  const setupGtag = (setup) => {
119
163
  const win = browser();
@@ -132,7 +176,7 @@ const setupGtag = (setup) => {
132
176
  };
133
177
  const id = setup.measurementId;
134
178
  if (id && !state.configured.has(id)) {
135
- gtag("config", id, setup.config ?? {});
179
+ gtag("config", id, gtagConfigParams(setup.config, setup.debug));
136
180
  state.configured.add(id);
137
181
  }
138
182
  if (!id || hostLoadsGtag(win)) return {
@@ -188,12 +232,13 @@ const ga4 = (options = {}) => {
188
232
  console.warn(`${WARN_PREFIX} ${message}`);
189
233
  };
190
234
  const gtagSetup = (load) => {
191
- const { measurementId, config, consentDefaults } = options;
235
+ const { measurementId, config, consentDefaults, debug } = options;
192
236
  return setupGtag({
193
237
  measurementId,
194
238
  config,
195
239
  consentDefaults,
196
- load
240
+ load,
241
+ debug
197
242
  });
198
243
  };
199
244
  const applyWebUser = (user) => {
@@ -229,11 +274,8 @@ const ga4 = (options = {}) => {
229
274
  const sendWeb = async (name, params) => {
230
275
  const page = gtagSetup(true);
231
276
  if (!page) return;
232
- const id = options.measurementId;
233
- const payload = id ? {
234
- ...params,
235
- send_to: id
236
- } : params;
277
+ const { measurementId, debug, config } = options;
278
+ const payload = gtagEventParams(params, measurementId, isGa4Debug(debug, config));
237
279
  page.gtag("event", name, payload);
238
280
  await page.ready;
239
281
  };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@fire-spark/analytics-ga4",
3
- "version": "0.19.1",
3
+ "version": "0.19.2",
4
4
  "description": "Fire Spark GA4 analytics adapter (web gtag + RN inject)",
5
5
  "type": "module",
6
6
  "sideEffects": false,
@@ -17,14 +17,14 @@
17
17
  }
18
18
  },
19
19
  "peerDependencies": {
20
- "@fire-spark/analytics": "^0.19.1"
20
+ "@fire-spark/analytics": "^0.19.2"
21
21
  },
22
22
  "devDependencies": {
23
23
  "jsdom": "^22.1.0",
24
24
  "tsdown": "^0.22.14",
25
25
  "typescript": "^7.0.2",
26
26
  "vitest": "^2.1.8",
27
- "@fire-spark/analytics": "0.19.1"
27
+ "@fire-spark/analytics": "0.19.2"
28
28
  },
29
29
  "publishConfig": {
30
30
  "access": "public"