@fire-spark/analytics-ga4 0.19.1 → 0.19.3
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 +18 -1
- package/dist/index.js +51 -9
- package/package.json +3 -3
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
|
-
* `
|
|
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
|
|
233
|
-
const payload =
|
|
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.
|
|
3
|
+
"version": "0.19.3",
|
|
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.
|
|
20
|
+
"@fire-spark/analytics": "^0.19.3"
|
|
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.
|
|
27
|
+
"@fire-spark/analytics": "0.19.3"
|
|
28
28
|
},
|
|
29
29
|
"publishConfig": {
|
|
30
30
|
"access": "public"
|