@shware/analytics 15.0.1 → 16.1.0

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.
Files changed (260) hide show
  1. package/README.md +164 -36
  2. package/dist/native/fbsdk.cjs +44 -1
  3. package/dist/native/fbsdk.cjs.map +1 -1
  4. package/dist/native/fbsdk.d.cts +23 -1
  5. package/dist/native/fbsdk.d.cts.map +1 -1
  6. package/dist/native/fbsdk.d.mts +23 -1
  7. package/dist/native/fbsdk.d.mts.map +1 -1
  8. package/dist/native/fbsdk.mjs +44 -3
  9. package/dist/native/fbsdk.mjs.map +1 -1
  10. package/dist/native/firebase.cjs +27 -0
  11. package/dist/native/firebase.cjs.map +1 -1
  12. package/dist/native/firebase.d.cts +11 -0
  13. package/dist/native/firebase.d.cts.map +1 -1
  14. package/dist/native/firebase.d.mts +11 -0
  15. package/dist/native/firebase.d.mts.map +1 -1
  16. package/dist/native/firebase.mjs +27 -2
  17. package/dist/native/firebase.mjs.map +1 -1
  18. package/dist/next/index.cjs +10 -123
  19. package/dist/next/index.cjs.map +1 -1
  20. package/dist/next/index.d.cts +2 -31
  21. package/dist/next/index.d.cts.map +1 -1
  22. package/dist/next/index.d.mts +2 -31
  23. package/dist/next/index.d.mts.map +1 -1
  24. package/dist/next/index.mjs +10 -123
  25. package/dist/next/index.mjs.map +1 -1
  26. package/dist/react/index.cjs +45 -0
  27. package/dist/react/index.cjs.map +1 -0
  28. package/dist/react/index.d.cts +15 -0
  29. package/dist/react/index.d.cts.map +1 -0
  30. package/dist/react/index.d.mts +15 -0
  31. package/dist/react/index.d.mts.map +1 -0
  32. package/dist/react/index.mjs +43 -0
  33. package/dist/react/index.mjs.map +1 -0
  34. package/dist/react/use-feature-flag.cjs +23 -0
  35. package/dist/react/use-feature-flag.cjs.map +1 -0
  36. package/dist/react/use-feature-flag.d.cts +10 -0
  37. package/dist/react/use-feature-flag.d.cts.map +1 -0
  38. package/dist/react/use-feature-flag.d.mts +10 -0
  39. package/dist/react/use-feature-flag.d.mts.map +1 -0
  40. package/dist/react/use-feature-flag.mjs +22 -0
  41. package/dist/react/use-feature-flag.mjs.map +1 -0
  42. package/dist/server/conversions-api-error.cjs +20 -0
  43. package/dist/server/conversions-api-error.cjs.map +1 -0
  44. package/dist/server/conversions-api-error.d.cts +17 -0
  45. package/dist/server/conversions-api-error.d.cts.map +1 -0
  46. package/dist/server/conversions-api-error.d.mts +17 -0
  47. package/dist/server/conversions-api-error.d.mts.map +1 -0
  48. package/dist/server/conversions-api-error.mjs +19 -0
  49. package/dist/server/conversions-api-error.mjs.map +1 -0
  50. package/dist/server/google-data-manager.cjs +24 -26
  51. package/dist/server/google-data-manager.cjs.map +1 -1
  52. package/dist/server/google-data-manager.d.cts +13 -5
  53. package/dist/server/google-data-manager.d.cts.map +1 -1
  54. package/dist/server/google-data-manager.d.mts +13 -5
  55. package/dist/server/google-data-manager.d.mts.map +1 -1
  56. package/dist/server/google-data-manager.mjs +24 -27
  57. package/dist/server/google-data-manager.mjs.map +1 -1
  58. package/dist/server/index.cjs +11 -0
  59. package/dist/server/index.d.cts +10 -7
  60. package/dist/server/index.d.mts +10 -7
  61. package/dist/server/index.mjs +9 -7
  62. package/dist/server/linkedin-conversions-api.cjs +29 -23
  63. package/dist/server/linkedin-conversions-api.cjs.map +1 -1
  64. package/dist/server/linkedin-conversions-api.d.cts +7 -2
  65. package/dist/server/linkedin-conversions-api.d.cts.map +1 -1
  66. package/dist/server/linkedin-conversions-api.d.mts +7 -2
  67. package/dist/server/linkedin-conversions-api.d.mts.map +1 -1
  68. package/dist/server/linkedin-conversions-api.mjs +29 -24
  69. package/dist/server/linkedin-conversions-api.mjs.map +1 -1
  70. package/dist/server/meta-capi.cjs +32 -31
  71. package/dist/server/meta-capi.cjs.map +1 -1
  72. package/dist/server/meta-capi.d.cts +12 -3
  73. package/dist/server/meta-capi.d.cts.map +1 -1
  74. package/dist/server/meta-capi.d.mts +12 -3
  75. package/dist/server/meta-capi.d.mts.map +1 -1
  76. package/dist/server/meta-capi.mjs +33 -33
  77. package/dist/server/meta-capi.mjs.map +1 -1
  78. package/dist/server/microsoft-conversions-api.cjs +33 -28
  79. package/dist/server/microsoft-conversions-api.cjs.map +1 -1
  80. package/dist/server/microsoft-conversions-api.d.cts +14 -2
  81. package/dist/server/microsoft-conversions-api.d.cts.map +1 -1
  82. package/dist/server/microsoft-conversions-api.d.mts +14 -2
  83. package/dist/server/microsoft-conversions-api.d.mts.map +1 -1
  84. package/dist/server/microsoft-conversions-api.mjs +33 -29
  85. package/dist/server/microsoft-conversions-api.mjs.map +1 -1
  86. package/dist/server/openai-conversions-api.cjs +20 -18
  87. package/dist/server/openai-conversions-api.cjs.map +1 -1
  88. package/dist/server/openai-conversions-api.d.cts +7 -0
  89. package/dist/server/openai-conversions-api.d.cts.map +1 -1
  90. package/dist/server/openai-conversions-api.d.mts +7 -0
  91. package/dist/server/openai-conversions-api.d.mts.map +1 -1
  92. package/dist/server/openai-conversions-api.mjs +21 -20
  93. package/dist/server/openai-conversions-api.mjs.map +1 -1
  94. package/dist/server/reddit-conversions-api.cjs +20 -18
  95. package/dist/server/reddit-conversions-api.cjs.map +1 -1
  96. package/dist/server/reddit-conversions-api.d.cts +8 -1
  97. package/dist/server/reddit-conversions-api.d.cts.map +1 -1
  98. package/dist/server/reddit-conversions-api.d.mts +8 -1
  99. package/dist/server/reddit-conversions-api.d.mts.map +1 -1
  100. package/dist/server/reddit-conversions-api.mjs +21 -20
  101. package/dist/server/reddit-conversions-api.mjs.map +1 -1
  102. package/dist/server/setup-conversions.cjs +62 -0
  103. package/dist/server/setup-conversions.cjs.map +1 -0
  104. package/dist/server/setup-conversions.d.cts +97 -0
  105. package/dist/server/setup-conversions.d.cts.map +1 -0
  106. package/dist/server/setup-conversions.d.mts +97 -0
  107. package/dist/server/setup-conversions.d.mts.map +1 -0
  108. package/dist/server/setup-conversions.mjs +60 -0
  109. package/dist/server/setup-conversions.mjs.map +1 -0
  110. package/dist/setup/index.cjs +4 -4
  111. package/dist/setup/index.cjs.map +1 -1
  112. package/dist/setup/index.d.cts +16 -6
  113. package/dist/setup/index.d.cts.map +1 -1
  114. package/dist/setup/index.d.mts +16 -6
  115. package/dist/setup/index.d.mts.map +1 -1
  116. package/dist/setup/index.mjs +4 -4
  117. package/dist/setup/index.mjs.map +1 -1
  118. package/dist/tanstack/index.cjs +0 -2
  119. package/dist/tanstack/index.d.cts +1 -2
  120. package/dist/tanstack/index.d.mts +1 -2
  121. package/dist/tanstack/index.mjs +1 -3
  122. package/dist/third-parties/analytics-props.cjs +28 -0
  123. package/dist/third-parties/analytics-props.cjs.map +1 -0
  124. package/dist/third-parties/analytics-props.d.cts +23 -0
  125. package/dist/third-parties/analytics-props.d.cts.map +1 -0
  126. package/dist/third-parties/analytics-props.d.mts +23 -0
  127. package/dist/third-parties/analytics-props.d.mts.map +1 -0
  128. package/dist/third-parties/analytics-props.mjs +26 -0
  129. package/dist/third-parties/analytics-props.mjs.map +1 -0
  130. package/dist/third-parties/google-analytics.cjs +32 -0
  131. package/dist/third-parties/google-analytics.cjs.map +1 -1
  132. package/dist/third-parties/google-analytics.d.cts +11 -1
  133. package/dist/third-parties/google-analytics.d.cts.map +1 -1
  134. package/dist/third-parties/google-analytics.d.mts +11 -1
  135. package/dist/third-parties/google-analytics.d.mts.map +1 -1
  136. package/dist/third-parties/google-analytics.mjs +32 -1
  137. package/dist/third-parties/google-analytics.mjs.map +1 -1
  138. package/dist/third-parties/index.cjs +16 -0
  139. package/dist/third-parties/index.d.cts +9 -7
  140. package/dist/third-parties/index.d.mts +9 -7
  141. package/dist/third-parties/index.mjs +9 -7
  142. package/dist/third-parties/integration.cjs +46 -0
  143. package/dist/third-parties/integration.cjs.map +1 -0
  144. package/dist/third-parties/integration.d.cts +61 -0
  145. package/dist/third-parties/integration.d.cts.map +1 -0
  146. package/dist/third-parties/integration.d.mts +61 -0
  147. package/dist/third-parties/integration.d.mts.map +1 -0
  148. package/dist/third-parties/integration.mjs +43 -0
  149. package/dist/third-parties/integration.mjs.map +1 -0
  150. package/dist/third-parties/linkedin-insight-tag.cjs +29 -0
  151. package/dist/third-parties/linkedin-insight-tag.cjs.map +1 -1
  152. package/dist/third-parties/linkedin-insight-tag.d.cts +14 -8
  153. package/dist/third-parties/linkedin-insight-tag.d.cts.map +1 -1
  154. package/dist/third-parties/linkedin-insight-tag.d.mts +14 -8
  155. package/dist/third-parties/linkedin-insight-tag.d.mts.map +1 -1
  156. package/dist/third-parties/linkedin-insight-tag.mjs +29 -1
  157. package/dist/third-parties/linkedin-insight-tag.mjs.map +1 -1
  158. package/dist/third-parties/meta-pixel.cjs +32 -0
  159. package/dist/third-parties/meta-pixel.cjs.map +1 -1
  160. package/dist/third-parties/meta-pixel.d.cts +7 -0
  161. package/dist/third-parties/meta-pixel.d.cts.map +1 -1
  162. package/dist/third-parties/meta-pixel.d.mts +7 -0
  163. package/dist/third-parties/meta-pixel.d.mts.map +1 -1
  164. package/dist/third-parties/meta-pixel.mjs +33 -2
  165. package/dist/third-parties/meta-pixel.mjs.map +1 -1
  166. package/dist/third-parties/microsoft-uet.cjs +54 -0
  167. package/dist/third-parties/microsoft-uet.cjs.map +1 -1
  168. package/dist/third-parties/microsoft-uet.d.cts +36 -0
  169. package/dist/third-parties/microsoft-uet.d.cts.map +1 -1
  170. package/dist/third-parties/microsoft-uet.d.mts +36 -0
  171. package/dist/third-parties/microsoft-uet.d.mts.map +1 -1
  172. package/dist/third-parties/microsoft-uet.mjs +52 -1
  173. package/dist/third-parties/microsoft-uet.mjs.map +1 -1
  174. package/dist/third-parties/openai-pixel.cjs +29 -0
  175. package/dist/third-parties/openai-pixel.cjs.map +1 -1
  176. package/dist/third-parties/openai-pixel.d.cts +7 -0
  177. package/dist/third-parties/openai-pixel.d.cts.map +1 -1
  178. package/dist/third-parties/openai-pixel.d.mts +7 -0
  179. package/dist/third-parties/openai-pixel.d.mts.map +1 -1
  180. package/dist/third-parties/openai-pixel.mjs +30 -2
  181. package/dist/third-parties/openai-pixel.mjs.map +1 -1
  182. package/dist/third-parties/posthog.cjs +97 -4
  183. package/dist/third-parties/posthog.cjs.map +1 -1
  184. package/dist/third-parties/posthog.d.cts +56 -1
  185. package/dist/third-parties/posthog.d.cts.map +1 -1
  186. package/dist/third-parties/posthog.d.mts +56 -1
  187. package/dist/third-parties/posthog.d.mts.map +1 -1
  188. package/dist/third-parties/posthog.mjs +91 -2
  189. package/dist/third-parties/posthog.mjs.map +1 -1
  190. package/dist/third-parties/reddit-pixel.cjs +30 -0
  191. package/dist/third-parties/reddit-pixel.cjs.map +1 -1
  192. package/dist/third-parties/reddit-pixel.d.cts +7 -0
  193. package/dist/third-parties/reddit-pixel.d.cts.map +1 -1
  194. package/dist/third-parties/reddit-pixel.d.mts +7 -0
  195. package/dist/third-parties/reddit-pixel.d.mts.map +1 -1
  196. package/dist/third-parties/reddit-pixel.mjs +31 -2
  197. package/dist/third-parties/reddit-pixel.mjs.map +1 -1
  198. package/dist/track/fbq.cjs +6 -1
  199. package/dist/track/fbq.cjs.map +1 -1
  200. package/dist/track/fbq.d.cts +2 -0
  201. package/dist/track/fbq.d.cts.map +1 -1
  202. package/dist/track/fbq.d.mts +2 -0
  203. package/dist/track/fbq.d.mts.map +1 -1
  204. package/dist/track/fbq.mjs +6 -2
  205. package/dist/track/fbq.mjs.map +1 -1
  206. package/dist/track/index.cjs +7 -7
  207. package/dist/track/index.cjs.map +1 -1
  208. package/dist/track/index.d.cts.map +1 -1
  209. package/dist/track/index.d.mts.map +1 -1
  210. package/dist/track/index.mjs +7 -7
  211. package/dist/track/index.mjs.map +1 -1
  212. package/dist/track/oaiq.cjs +5 -0
  213. package/dist/track/oaiq.cjs.map +1 -1
  214. package/dist/track/oaiq.d.cts +2 -0
  215. package/dist/track/oaiq.d.cts.map +1 -1
  216. package/dist/track/oaiq.d.mts +2 -0
  217. package/dist/track/oaiq.d.mts.map +1 -1
  218. package/dist/track/oaiq.mjs +5 -1
  219. package/dist/track/oaiq.mjs.map +1 -1
  220. package/dist/track/rdt.cjs +5 -0
  221. package/dist/track/rdt.cjs.map +1 -1
  222. package/dist/track/rdt.d.cts +2 -0
  223. package/dist/track/rdt.d.cts.map +1 -1
  224. package/dist/track/rdt.d.mts +2 -0
  225. package/dist/track/rdt.d.mts.map +1 -1
  226. package/dist/track/rdt.mjs +5 -1
  227. package/dist/track/rdt.mjs.map +1 -1
  228. package/dist/visitor/index.cjs +3 -3
  229. package/dist/visitor/index.cjs.map +1 -1
  230. package/dist/visitor/index.mjs +3 -3
  231. package/dist/visitor/index.mjs.map +1 -1
  232. package/package.json +11 -39
  233. package/dist/react-router/index.cjs +0 -160
  234. package/dist/react-router/index.cjs.map +0 -1
  235. package/dist/react-router/index.d.cts +0 -22
  236. package/dist/react-router/index.d.cts.map +0 -1
  237. package/dist/react-router/index.d.mts +0 -22
  238. package/dist/react-router/index.d.mts.map +0 -1
  239. package/dist/react-router/index.mjs +0 -159
  240. package/dist/react-router/index.mjs.map +0 -1
  241. package/dist/server/legacy.cjs +0 -3
  242. package/dist/server/legacy.d.cts +0 -2
  243. package/dist/server/legacy.d.mts +0 -2
  244. package/dist/server/legacy.mjs +0 -1
  245. package/dist/server/meta-conversions-api.cjs +0 -205
  246. package/dist/server/meta-conversions-api.cjs.map +0 -1
  247. package/dist/server/meta-conversions-api.d.cts +0 -8
  248. package/dist/server/meta-conversions-api.d.cts.map +0 -1
  249. package/dist/server/meta-conversions-api.d.mts +0 -8
  250. package/dist/server/meta-conversions-api.d.mts.map +0 -1
  251. package/dist/server/meta-conversions-api.mjs +0 -201
  252. package/dist/server/meta-conversions-api.mjs.map +0 -1
  253. package/dist/tanstack/analytics.cjs +0 -184
  254. package/dist/tanstack/analytics.cjs.map +0 -1
  255. package/dist/tanstack/analytics.d.cts +0 -33
  256. package/dist/tanstack/analytics.d.cts.map +0 -1
  257. package/dist/tanstack/analytics.d.mts +0 -33
  258. package/dist/tanstack/analytics.d.mts.map +0 -1
  259. package/dist/tanstack/analytics.mjs +0 -183
  260. package/dist/tanstack/analytics.mjs.map +0 -1
package/README.md CHANGED
@@ -16,27 +16,25 @@ pnpm add @shware/analytics zod
16
16
  ```
17
17
 
18
18
  Every framework and platform integration is an optional peer dependency: install only what your
19
- entry point imports (`next`, `@tanstack/react-start`, `react-router`, `posthog-js`, the `expo-*`
19
+ entry point imports (`next`, `@tanstack/react-start`, the `expo-*`
20
20
  modules for `/native`, `react-native-fbsdk-next` for `/native/fbsdk`, and so on).
21
21
 
22
22
  ## Entry points
23
23
 
24
- | Import | Runs on | What it is for |
25
- | ----------------------------------------- | ------- | --------------------------------------------------------------------------- |
26
- | `@shware/analytics` | client | `setupAnalytics`, `track`, `identify`, `reset`, `sendFeedback`, links, bots |
27
- | `@shware/analytics/web` | browser | `storage`, `getTags`, `getDeviceId` for `setupAnalytics` on the web |
28
- | `@shware/analytics/native` | Expo | The same for React Native, plus `deepLink` and `useAppAnalytics` |
29
- | `@shware/analytics/native/firebase` | Expo | `sendFirebaseEvent`, a third-party tracker for Firebase Analytics |
30
- | `@shware/analytics/native/fbsdk` | Expo | `sendFBEvent`, a third-party tracker for the Facebook SDK |
31
- | `@shware/analytics/next` | browser | `<Analytics />` for the Next.js App Router |
32
- | `@shware/analytics/tanstack` | both | `<Analytics />` and `createClickIdMiddleware` for TanStack Start |
33
- | `@shware/analytics/react-router` | browser | `<Analytics />` for React Router |
34
- | `@shware/analytics/third-parties` | browser | GA4, Meta Pixel, Reddit, LinkedIn, OpenAI and UET trackers and setters |
35
- | `@shware/analytics/third-parties/posthog` | browser | `sendPosthogEvent` and `setPosthogUser` |
36
- | `@shware/analytics/server` | server | Conversions APIs: Meta, Google Ads, Microsoft, Reddit, LinkedIn, OpenAI |
37
- | `@shware/analytics/server/legacy` | server | The old Meta sender built on `facebook-nodejs-business-sdk` |
38
- | `@shware/analytics/attribution` | server | `classifyTouch` and the channel vocabulary for reading sessions |
39
- | `@shware/analytics/ads` | server | Pulling spend and performance from Google Ads and Meta |
24
+ | Import | Runs on | What it is for |
25
+ | ----------------------------------- | ------- | --------------------------------------------------------------------------- |
26
+ | `@shware/analytics` | client | `setupAnalytics`, `track`, `identify`, `reset`, `sendFeedback`, links, bots |
27
+ | `@shware/analytics/web` | browser | `storage`, `getTags`, `getDeviceId` for `setupAnalytics` on the web |
28
+ | `@shware/analytics/native` | Expo | The same for React Native, plus `deepLink` and `useAppAnalytics` |
29
+ | `@shware/analytics/native/firebase` | Expo | `firebaseAnalytics()`, the integration for Firebase Analytics |
30
+ | `@shware/analytics/native/fbsdk` | Expo | `metaAppEvents()`, the integration for Facebook App Events |
31
+ | `@shware/analytics/next` | browser | `<Analytics />` for the Next.js App Router |
32
+ | `@shware/analytics/react` | browser | `<Analytics />` for any React router (TanStack Router, React Router, …) |
33
+ | `@shware/analytics/tanstack` | both | `createClickIdMiddleware` for TanStack Start |
34
+ | `@shware/analytics/third-parties` | browser | GA4, Meta Pixel, Reddit, LinkedIn, OpenAI and UET trackers and setters |
35
+ | `@shware/analytics/server` | server | Conversions APIs: Meta, Google Ads, Microsoft, Reddit, LinkedIn, OpenAI |
36
+ | `@shware/analytics/attribution` | server | `classifyTouch` and the channel vocabulary for reading sessions |
37
+ | `@shware/analytics/ads` | server | Pulling spend and performance from Google Ads and Meta |
40
38
 
41
39
  ## Client-side only
42
40
 
@@ -56,10 +54,9 @@ Call `setupAnalytics` once, at module scope of the client entry, before anything
56
54
 
57
55
  ```ts
58
56
  import { setupAnalytics } from '@shware/analytics';
59
- import { sendGAEvent, setGAUser } from '@shware/analytics/third-parties';
60
- import { sendPosthogEvent, setPosthogUser } from '@shware/analytics/third-parties/posthog';
61
57
  import { getDeviceId, getTags, storage } from '@shware/analytics/web';
62
58
  import { version } from '../package.json';
59
+ import { integrations } from './integrations';
63
60
 
64
61
  setupAnalytics({
65
62
  storage,
@@ -68,13 +65,63 @@ setupAnalytics({
68
65
  release: version,
69
66
  platform: 'web',
70
67
  environment: process.env.NODE_ENV === 'development' ? 'development' : 'production',
71
- // Optional: every tracked event is also handed to these, and identify / reset to the setters.
72
- thirdPartyTrackers: [sendGAEvent, sendPosthogEvent],
73
- thirdPartyUserSetters: [setGAUser, setPosthogUser],
74
68
  endpoint: 'https://api.example.com/v1/analytics',
69
+ integrations,
70
+ // Still sent to the analytics server, but to no integration: report them server-side instead.
71
+ excludeFromIntegrations: ['purchase', 'refund'],
75
72
  });
76
73
  ```
77
74
 
75
+ ### Integrations
76
+
77
+ Each third party is one `integrations` entry that carries everything about it: how events reach it, how it learns the signed-in user (`identify` / `reset()`), and the ids of the script it needs. Pass the same array to `<Analytics integrations>`, which renders those scripts, so an id is written once.
78
+
79
+ ```ts
80
+ // integrations.ts
81
+ import {
82
+ googleAnalytics,
83
+ linkedInAds,
84
+ metaAds,
85
+ microsoftAds,
86
+ posthogAnalytics,
87
+ } from '@shware/analytics/third-parties';
88
+
89
+ export const integrations = [
90
+ googleAnalytics({ id: 'G-XXXXXXX', debug: import.meta.env.DEV }),
91
+ posthogAnalytics({
92
+ token: 'phc_XXXXXXX',
93
+ config: { api_host: 'https://us.i.posthog.com', defaults: '2026-01-30' },
94
+ }),
95
+ metaAds({ pixelId: '1234567890', customEvents: ['onboarding_completed'] }),
96
+ linkedInAds({ partnerId: '123456', conversions: { sign_up: 7654321 } }),
97
+ microsoftAds({ tagId: '987654', customerId: '1234' }),
98
+ ];
99
+ ```
100
+
101
+ | Type | Integrations | Receives |
102
+ | ----------- | ------------------------------------- | ------------------------------------------------------------------------------------------ |
103
+ | `analytics` | `googleAnalytics`, `posthogAnalytics` | every event |
104
+ | `ads` | `metaAds`, `redditAds`, `openaiAds` | the events it maps to its own standard events, plus `customEvents` |
105
+ | `ads` | `linkedInAds` | the events in `conversions`, each as its conversion id |
106
+ | `ads` | `microsoftAds` | `events` (the GA4 conversion events, `CONVERSION_EVENTS`, by default), plus `customEvents` |
107
+
108
+ An ad platform needs conversions to optimize and build audiences, not the product's day-to-day events, which are behavior analysis for GA4 and PostHog. `excludeFromIntegrations` applies to every integration, analytics included. PostHog loads from its HTML snippet like the pixels, so `posthog-js` is not bundled: the library comes from PostHog's assets host after the page loads, and `config` (only its JSON survives) goes to `posthog.init`. Until it loads, `window.posthog` is a stub that queues calls returning nothing (`capture`, `identify`, `onFeatureFlags`) and replays them, while calls returning a value (`getFeatureFlag`) return `undefined`. So: `getPosthog()` for queued calls, `getLoadedPosthog()` (undefined until loaded) for values, and `useFeatureFlag(key)` from `@shware/analytics/react` in components. `useFeatureFlag` renders the default until flags arrive, then the variant. To show a `<Suspense>` fallback until then instead, wait for them with React 19.3's `browser()` (so the server renders the fallback) and `posthogFlagsReady()` (one promise per page, resolving when flags load or after a 3 s timeout, for when an ad blocker stops the library):
109
+
110
+ ```tsx
111
+ import { useFeatureFlag } from '@shware/analytics/react';
112
+ import { posthogFlagsReady } from '@shware/analytics/third-parties';
113
+ import { use } from 'react';
114
+ import { browser } from 'react-dom';
115
+
116
+ function Checkout() {
117
+ use(browser());
118
+ use(posthogFlagsReady());
119
+ return useFeatureFlag('new-checkout') === 'test' ? <NewCheckout /> : <OldCheckout />;
120
+ }
121
+ ```
122
+
123
+ With server-evaluated flags in `config.bootstrap` the wait ends as soon as the library loads. On Next.js its snippet uses `next/script`'s `beforeInteractive`, so the stub exists before hydration tracks anything; render `<Analytics>` in the root layout for that. `<Analytics>` also preconnects to PostHog's assets host (`Integration.preconnect`, through `react-dom`'s `preconnect`), so `array.js` starts sooner. The `PostHog` and `PostHogConfig` types come from `posthog-js`: install it as a dev dependency for them. In an app, `firebaseAnalytics()` (every event) and `metaAppEvents({ customEvents })` (the conversions Meta maps, like `metaAds`) are the `integrations`. A platform the SDK does not cover is an object implementing `Integration` (`type`, `track`, and optionally `setUser` and `script`).
124
+
78
125
  `getHeaders` is also accepted, for a backend that wants extra headers on the analytics requests.
79
126
 
80
127
  React Native (Expo):
@@ -108,16 +155,23 @@ so screen changes are tracked as page views.
108
155
  ### The `<Analytics />` component (web)
109
156
 
110
157
  Each web framework entry exports an `Analytics` component. Render it once in the document head:
111
- it tracks page views, outbound clicks and web vitals, and loads the pixels whose ids you pass
112
- (`gaId`, `metaPixelId`, `redditPixelId`, `linkedInPartnerId`, `uetTagId`, `hotjarId`,
113
- and on TanStack Start `openaiPixelId`). On TanStack Start:
158
+ it tracks page views, outbound clicks and web vitals, and renders the script of each of the
159
+ `integrations` you pass — the same array given to `setupAnalytics`, so each id is written once.
160
+ Every integration carries one script (`Integration.script`: an inline snippet that loads the
161
+ vendor's script from its host, as the vendors' official snippets do). Next.js has its own entry
162
+ (`@shware/analytics/next`); any other React router uses `@shware/analytics/react` and passes the
163
+ current location. On TanStack Start:
114
164
 
115
165
  ```tsx
116
- import { Analytics } from '@shware/analytics/tanstack';
166
+ import { Analytics } from '@shware/analytics/react';
167
+ import { useLocation } from '@tanstack/react-router';
168
+ import { integrations } from './integrations';
169
+
170
+ const { pathname, searchStr } = useLocation();
117
171
 
118
172
  <head>
119
173
  <HeadContent />
120
- <Analytics nonce={nonce} gaId="G-XXXXXXXXXX" debugMode={import.meta.env.DEV} />
174
+ <Analytics pathname={pathname} search={searchStr} nonce={nonce} integrations={integrations} />
121
175
  </head>;
122
176
  ```
123
177
 
@@ -206,6 +260,82 @@ The server's conversions API, sending the stored event under the same id, then d
206
260
 
207
261
  Nothing waits for the server: `track` fires the pixels at once and the batch reaches the server within 2 s or by beacon when the page is left, so there is no `trackAsync` (removed in 13.0). A step that must not run before the server has the event does not belong in the client; record it server-side.
208
262
 
263
+ ### Conversions APIs on the server (`setupConversions`)
264
+
265
+ The server's counterpart of `setupAnalytics({ integrations })`, configured on the server alone:
266
+ each ad platform's Conversions API once, sent what its browser integration is sent — the
267
+ platform's standard events and the `customEvents` it lists, nothing else. The options are the
268
+ browser integrations' (`MetaAdsOptions`, …) plus a token; give a platform the same
269
+ `customEvents` on both sides for the tag and the API to report the same events.
270
+
271
+ ```ts
272
+ import {
273
+ linkedinConversions,
274
+ metaConversions,
275
+ redditConversions,
276
+ setupConversions,
277
+ } from '@shware/analytics/server';
278
+
279
+ export const conversions = setupConversions({
280
+ destinations: [
281
+ metaConversions({
282
+ accessToken: env.META_CONVERSIONS_API_ACCESS_TOKEN,
283
+ pixelId: '1234567890',
284
+ customEvents: ['onboarding_completed'],
285
+ }),
286
+ redditConversions({ accessToken: env.REDDIT_CONVERSIONS_API_ACCESS_TOKEN, pixelId: 'a2_xxx' }),
287
+ linkedinConversions({
288
+ accessToken: env.LINKEDIN_CONVERSIONS_API_ACCESS_TOKEN,
289
+ conversions: { sign_up: 7654321, purchase: 7654322 },
290
+ }),
291
+ // a CRM or the host's own workflows: any `{ send(events, data) }`
292
+ { send: (events, data) => sendToCrm(events, data) },
293
+ ],
294
+ // Only for conversions.track(), which is returned only with it; forward needs none of it.
295
+ track: {
296
+ resolveUser: async (userId) => latestSessionOf(userId),
297
+ store: async (event) => (await insertEvents([event])).length > 0,
298
+ },
299
+ });
300
+
301
+ // POST /events, after storing the batch
302
+ ctx.waitUntil(conversions.forward(events, userProvidedData));
303
+
304
+ // a webhook: Stripe's invoice.paid, once the account is credited
305
+ ctx.waitUntil(
306
+ conversions.track({
307
+ id: invoice.id,
308
+ name: 'purchase',
309
+ userId,
310
+ properties: { transaction_id: invoice.id, value: 9.99, currency: 'usd', items: [] },
311
+ createdAt: new Date(invoice.created * 1000).toISOString(),
312
+ })
313
+ );
314
+ ```
315
+
316
+ - `forward(events, data)`: the events a client sent, as stored, to every destination at once.
317
+ - `track(event)`: an event the server reports on its own — a webhook's purchase, renewal or
318
+ refund — with `id` the transaction id. `track.resolveUser(userId)` returns what a client event
319
+ would have carried, from the host's records: the user's latest session's `tags` (cookies, page,
320
+ user agent) with the click ids of the touch the conversion is credited to, that session's
321
+ `visitor_id`, `session_id`, `platform` (which decides website or app) and `environment`, and the
322
+ user's identity as `data`. `track.store` stores the event — in the events table, so the
323
+ server's conversions count wherever the client's do — and says whether it was new: only a new
324
+ one is sent, so a webhook delivered again is not reported twice. That matters: the platforms
325
+ document deduplicating a server event against a browser one, and only Microsoft (on `eventId`)
326
+ and Google Ads (on `transaction_id`) a server event sent twice. A user with no session is
327
+ skipped.
328
+
329
+ Neither throws, so reporting a conversion cannot fail the request it runs in — least of all a
330
+ payment webhook, which its provider would deliver again and again. A failure is logged with the
331
+ ids of the events it lost (`Conversions not sent, events: …`), to be found and sent later: a
332
+ missed conversion costs less than a duplicate one or a failing webhook. The `send…Events`
333
+ functions underneath reject instead (`ConversionsApiError` for an error status, the fetch error
334
+ for a network failure; neither carries a token), for a caller using them directly to handle.
335
+
336
+ List events the server reports itself in `setupAnalytics({ excludeFromIntegrations })` so the
337
+ browser does not send them too.
338
+
209
339
  ### Tracking an occurrence once (`trackOnce`)
210
340
 
211
341
  A payment result page can be reloaded or reopened from history, and a store transaction can be delivered again; each would report the same `purchase` again. `trackOnce` takes the key that identifies the occurrence and tracks it at most once per key:
@@ -842,21 +972,19 @@ Microsoft recommends the UET tag and the Conversions API (CAPI) together. The tw
842
972
  (`tagId`, `eventName`, `eventId`): the browser sends the internal event name as the UET action with
843
973
  the event id as `event_id`, the server sends the same name as `eventName` with the same id.
844
974
 
845
- Browser — pass the tag id and the customer id to the framework `Analytics` component
846
- (`<Analytics uetTagId="97267979" uetCustomerId="255004870" />` from `@shware/analytics/tanstack`,
847
- `/next` or `/react-router`). It inlines Microsoft's snippet with `enableAutoSpaTracking: true` (the
975
+ Browser — the `microsoftAds` integration below carries the tag id and the customer id, and the
976
+ framework `Analytics` component (from `@shware/analytics/react` or `/next`)
977
+ renders its tag from `integrations`. It inlines Microsoft's snippet with `enableAutoSpaTracking: true` (the
848
978
  tag owns page loads, `sendUETEvent` drops `page_view` and forwards everything else) and fires the
849
979
  Conversions API's ID Sync pixel once per visit for the SDK visitor — anonymous visitors included,
850
980
  they are who remarketing audiences are built from. Then:
851
981
 
852
982
  ```ts
853
- import { sendUETEvent, setUETUser, setUETConsent } from '@shware/analytics/third-parties';
983
+ import { microsoftAds, setUETConsent } from '@shware/analytics/third-parties';
854
984
 
855
- setupAnalytics({
856
- thirdPartyTrackers: [sendUETEvent],
857
- // Enhanced conversions: the tag hashes the email/phone itself before they leave the page.
858
- thirdPartyUserSetters: [setUETUser],
859
- });
985
+ // One integration: conversions to UET, enhanced conversions (the tag hashes the email/phone itself
986
+ // before they leave the page), and the tag id and customer id `<Analytics integrations>` renders.
987
+ setupAnalytics({ integrations: [microsoftAds({ tagId: '97267979', customerId: '255004870' })] });
860
988
  // Consent mode (EEA/UK/CH): push `default` before the tag loads, `update` on the visitor's choice.
861
989
  setUETConsent('default', { ad_storage: 'denied', wait_for_update: 2000 });
862
990
  ```
@@ -1,14 +1,57 @@
1
1
  Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
2
+ const require_utils_field = require("../utils/field.cjs");
3
+ const require_third_parties_integration = require("../third-parties/integration.cjs");
2
4
  const require_track_fbq = require("../track/fbq.cjs");
3
5
  let react_native_fbsdk_next = require("react-native-fbsdk-next");
4
6
  // src/native/fbsdk.ts
5
7
  /**
6
8
  * ref: https://developers.facebook.com/docs/app-events/guides/maximize-in-app-ad-revenue/
9
+ *
10
+ * Synchronous, like `logEvent`: a tracker returns `void | boolean`, which an `async` function's
11
+ * promise would not satisfy. Callers that still `await` it keep compiling.
7
12
  */
8
- async function sendFBEvent(name, properties) {
13
+ function sendFBEvent(name, properties) {
9
14
  const [_, fbEventName, fbEventProperties] = require_track_fbq.mapFBEvent(name, properties);
10
15
  react_native_fbsdk_next.AppEventsLogger.logEvent(fbEventName, fbEventProperties);
11
16
  }
17
+ /**
18
+ * Hands the signed-in user to Facebook App Events, as `setFBUser` does the Pixel: the user id
19
+ * (`external_id`) and the advanced matching fields, which the SDK hashes on the device. No user is
20
+ * sign-out (`reset()`): the user id is cleared, but the matching fields may not be.
21
+ *
22
+ * Known gap, kept on purpose: the fields go to the native `setUserData`, which on Android only
23
+ * updates the fields it is given, so the empty ones sent at sign-out leave the previous user's
24
+ * email and phone in place, and later anonymous events (or another user's without an email) can
25
+ * still carry them. `react-native-fbsdk-next` does not expose the native `clearUserData`. Dropping
26
+ * the fields would avoid it, but cost more in ad conversion matching than the gap does.
27
+ */
28
+ function setFBUser({ user_id, user_data }) {
29
+ react_native_fbsdk_next.AppEventsLogger.setUserID(user_id || null);
30
+ const address = require_utils_field.getFirst(user_data?.address);
31
+ react_native_fbsdk_next.AppEventsLogger.setUserData({
32
+ email: require_utils_field.getFirst(user_data?.email),
33
+ phone: require_utils_field.getFirst(user_data?.phone_number),
34
+ firstName: address?.first_name,
35
+ lastName: address?.last_name,
36
+ city: address?.city,
37
+ state: address?.region,
38
+ zip: address?.postal_code,
39
+ country: address?.country
40
+ });
41
+ }
42
+ /**
43
+ * Facebook App Events: the events `mapFBEvent` maps to a Meta standard event, and `customEvents`
44
+ * — the app's counterpart of `metaAds`.
45
+ */
46
+ function metaAppEvents(options = {}) {
47
+ return {
48
+ type: "ads",
49
+ track: require_third_parties_integration.adsTracker(sendFBEvent, require_third_parties_integration.adEvents(require_track_fbq.isStandardFBEvent, options.customEvents)),
50
+ setUser: setFBUser
51
+ };
52
+ }
53
+ exports.metaAppEvents = metaAppEvents;
12
54
  exports.sendFBEvent = sendFBEvent;
55
+ exports.setFBUser = setFBUser;
13
56
 
14
57
  //# sourceMappingURL=fbsdk.cjs.map
@@ -1 +1 @@
1
- {"version":3,"file":"fbsdk.cjs","names":["mapFBEvent"],"sources":["../../src/native/fbsdk.ts"],"sourcesContent":["import { AppEventsLogger, type Params } from 'react-native-fbsdk-next';\nimport { mapFBEvent } from '../track/fbq';\nimport type { EventName, TrackName, TrackProperties } from '../track/types';\n\n/**\n * ref: https://developers.facebook.com/docs/app-events/guides/maximize-in-app-ad-revenue/\n */\nexport async function sendFBEvent<T extends EventName>(\n name: TrackName<T>,\n properties?: TrackProperties<T>\n) {\n const [_, fbEventName, fbEventProperties] = mapFBEvent(name, properties);\n AppEventsLogger.logEvent(fbEventName, fbEventProperties as Params);\n}\n"],"mappings":";;;;;;;AAOA,eAAsB,YACpB,MACA,YACA;CACA,MAAM,CAAC,GAAG,aAAa,qBAAqBA,kBAAAA,WAAW,MAAM,UAAU;CACvE,wBAAA,gBAAgB,SAAS,aAAa,iBAA2B;AACnE"}
1
+ {"version":3,"file":"fbsdk.cjs","names":["mapFBEvent","getFirst","adsTracker","adEvents","isStandardFBEvent"],"sources":["../../src/native/fbsdk.ts"],"sourcesContent":["import { AppEventsLogger, type Params } from 'react-native-fbsdk-next';\nimport type { UpdateVisitorDTO } from '../schema/index';\nimport {\n type AdsOptions,\n type Integration,\n adEvents,\n adsTracker,\n} from '../third-parties/integration';\nimport { isStandardFBEvent, mapFBEvent } from '../track/fbq';\nimport type { EventName, TrackName, TrackProperties } from '../track/types';\nimport { getFirst } from '../utils/field';\n\n/**\n * ref: https://developers.facebook.com/docs/app-events/guides/maximize-in-app-ad-revenue/\n *\n * Synchronous, like `logEvent`: a tracker returns `void | boolean`, which an `async` function's\n * promise would not satisfy. Callers that still `await` it keep compiling.\n */\nexport function sendFBEvent<T extends EventName>(\n name: TrackName<T>,\n properties?: TrackProperties<T>\n) {\n const [_, fbEventName, fbEventProperties] = mapFBEvent(name, properties);\n AppEventsLogger.logEvent(fbEventName, fbEventProperties as Params);\n}\n\n/**\n * Hands the signed-in user to Facebook App Events, as `setFBUser` does the Pixel: the user id\n * (`external_id`) and the advanced matching fields, which the SDK hashes on the device. No user is\n * sign-out (`reset()`): the user id is cleared, but the matching fields may not be.\n *\n * Known gap, kept on purpose: the fields go to the native `setUserData`, which on Android only\n * updates the fields it is given, so the empty ones sent at sign-out leave the previous user's\n * email and phone in place, and later anonymous events (or another user's without an email) can\n * still carry them. `react-native-fbsdk-next` does not expose the native `clearUserData`. Dropping\n * the fields would avoid it, but cost more in ad conversion matching than the gap does.\n */\nexport function setFBUser({ user_id, user_data }: Omit<UpdateVisitorDTO, 'tags'>) {\n AppEventsLogger.setUserID(user_id || null);\n const address = getFirst(user_data?.address);\n AppEventsLogger.setUserData({\n email: getFirst(user_data?.email),\n phone: getFirst(user_data?.phone_number),\n firstName: address?.first_name,\n lastName: address?.last_name,\n city: address?.city,\n state: address?.region,\n zip: address?.postal_code,\n country: address?.country,\n });\n}\n\n/**\n * Facebook App Events: the events `mapFBEvent` maps to a Meta standard event, and `customEvents`\n * — the app's counterpart of `metaAds`.\n */\nexport function metaAppEvents(options: AdsOptions = {}): Integration {\n return {\n type: 'ads',\n track: adsTracker(sendFBEvent, adEvents(isStandardFBEvent, options.customEvents)),\n setUser: setFBUser,\n };\n}\n"],"mappings":";;;;;;;;;;;;AAkBA,SAAgB,YACd,MACA,YACA;CACA,MAAM,CAAC,GAAG,aAAa,qBAAqBA,kBAAAA,WAAW,MAAM,UAAU;CACvE,wBAAA,gBAAgB,SAAS,aAAa,iBAA2B;AACnE;;;;;;;;;;;;AAaA,SAAgB,UAAU,EAAE,SAAS,aAA6C;CAChF,wBAAA,gBAAgB,UAAU,WAAW,IAAI;CACzC,MAAM,UAAUC,oBAAAA,SAAS,WAAW,OAAO;CAC3C,wBAAA,gBAAgB,YAAY;EAC1B,OAAOA,oBAAAA,SAAS,WAAW,KAAK;EAChC,OAAOA,oBAAAA,SAAS,WAAW,YAAY;EACvC,WAAW,SAAS;EACpB,UAAU,SAAS;EACnB,MAAM,SAAS;EACf,OAAO,SAAS;EAChB,KAAK,SAAS;EACd,SAAS,SAAS;CACpB,CAAC;AACH;;;;;AAMA,SAAgB,cAAc,UAAsB,CAAC,GAAgB;CACnE,OAAO;EACL,MAAM;EACN,OAAOC,kCAAAA,WAAW,aAAaC,kCAAAA,SAASC,kBAAAA,mBAAmB,QAAQ,YAAY,CAAC;EAChF,SAAS;CACX;AACF"}
@@ -1,6 +1,28 @@
1
1
  import { EventName, TrackName, TrackProperties } from "../track/types.cjs";
2
+ import { UpdateVisitorDTO } from "../schema/index.cjs";
3
+ import { AdsOptions, Integration } from "../third-parties/integration.cjs";
2
4
  /**
3
5
  * ref: https://developers.facebook.com/docs/app-events/guides/maximize-in-app-ad-revenue/
6
+ *
7
+ * Synchronous, like `logEvent`: a tracker returns `void | boolean`, which an `async` function's
8
+ * promise would not satisfy. Callers that still `await` it keep compiling.
4
9
  */
5
- export declare function sendFBEvent<T extends EventName>(name: TrackName<T>, properties?: TrackProperties<T>): Promise<void>;
10
+ export declare function sendFBEvent<T extends EventName>(name: TrackName<T>, properties?: TrackProperties<T>): void;
11
+ /**
12
+ * Hands the signed-in user to Facebook App Events, as `setFBUser` does the Pixel: the user id
13
+ * (`external_id`) and the advanced matching fields, which the SDK hashes on the device. No user is
14
+ * sign-out (`reset()`): the user id is cleared, but the matching fields may not be.
15
+ *
16
+ * Known gap, kept on purpose: the fields go to the native `setUserData`, which on Android only
17
+ * updates the fields it is given, so the empty ones sent at sign-out leave the previous user's
18
+ * email and phone in place, and later anonymous events (or another user's without an email) can
19
+ * still carry them. `react-native-fbsdk-next` does not expose the native `clearUserData`. Dropping
20
+ * the fields would avoid it, but cost more in ad conversion matching than the gap does.
21
+ */
22
+ export declare function setFBUser({ user_id, user_data }: Omit<UpdateVisitorDTO, 'tags'>): void;
23
+ /**
24
+ * Facebook App Events: the events `mapFBEvent` maps to a Meta standard event, and `customEvents`
25
+ * — the app's counterpart of `metaAds`.
26
+ */
27
+ export declare function metaAppEvents(options?: AdsOptions): Integration;
6
28
  //# sourceMappingURL=fbsdk.d.cts.map
@@ -1 +1 @@
1
- {"version":3,"file":"fbsdk.d.cts","names":[],"sources":["../../src/native/fbsdk.ts"],"mappings":";;;;wBAOsB,YAAY,UAAU,WAC1C,MAAM,UAAU,IAChB,aAAa,gBAAgB,KAAE"}
1
+ {"version":3,"file":"fbsdk.d.cts","names":[],"sources":["../../src/native/fbsdk.ts"],"mappings":";;;;;;;;;wBAkBgB,YAAY,UAAU,WACpC,MAAM,UAAU,IAChB,aAAa,gBAAgB;;;;;;;;;;;;wBAiBf,YAAY,SAAS,aAAa,KAAK;;;;;wBAmBvC,cAAc,UAAS,aAAkB"}
@@ -1,6 +1,28 @@
1
1
  import { EventName, TrackName, TrackProperties } from "../track/types.mjs";
2
+ import { UpdateVisitorDTO } from "../schema/index.mjs";
3
+ import { AdsOptions, Integration } from "../third-parties/integration.mjs";
2
4
  /**
3
5
  * ref: https://developers.facebook.com/docs/app-events/guides/maximize-in-app-ad-revenue/
6
+ *
7
+ * Synchronous, like `logEvent`: a tracker returns `void | boolean`, which an `async` function's
8
+ * promise would not satisfy. Callers that still `await` it keep compiling.
4
9
  */
5
- export declare function sendFBEvent<T extends EventName>(name: TrackName<T>, properties?: TrackProperties<T>): Promise<void>;
10
+ export declare function sendFBEvent<T extends EventName>(name: TrackName<T>, properties?: TrackProperties<T>): void;
11
+ /**
12
+ * Hands the signed-in user to Facebook App Events, as `setFBUser` does the Pixel: the user id
13
+ * (`external_id`) and the advanced matching fields, which the SDK hashes on the device. No user is
14
+ * sign-out (`reset()`): the user id is cleared, but the matching fields may not be.
15
+ *
16
+ * Known gap, kept on purpose: the fields go to the native `setUserData`, which on Android only
17
+ * updates the fields it is given, so the empty ones sent at sign-out leave the previous user's
18
+ * email and phone in place, and later anonymous events (or another user's without an email) can
19
+ * still carry them. `react-native-fbsdk-next` does not expose the native `clearUserData`. Dropping
20
+ * the fields would avoid it, but cost more in ad conversion matching than the gap does.
21
+ */
22
+ export declare function setFBUser({ user_id, user_data }: Omit<UpdateVisitorDTO, 'tags'>): void;
23
+ /**
24
+ * Facebook App Events: the events `mapFBEvent` maps to a Meta standard event, and `customEvents`
25
+ * — the app's counterpart of `metaAds`.
26
+ */
27
+ export declare function metaAppEvents(options?: AdsOptions): Integration;
6
28
  //# sourceMappingURL=fbsdk.d.mts.map
@@ -1 +1 @@
1
- {"version":3,"file":"fbsdk.d.mts","names":[],"sources":["../../src/native/fbsdk.ts"],"mappings":";;;;wBAOsB,YAAY,UAAU,WAC1C,MAAM,UAAU,IAChB,aAAa,gBAAgB,KAAE"}
1
+ {"version":3,"file":"fbsdk.d.mts","names":[],"sources":["../../src/native/fbsdk.ts"],"mappings":";;;;;;;;;wBAkBgB,YAAY,UAAU,WACpC,MAAM,UAAU,IAChB,aAAa,gBAAgB;;;;;;;;;;;;wBAiBf,YAAY,SAAS,aAAa,KAAK;;;;;wBAmBvC,cAAc,UAAS,aAAkB"}
@@ -1,13 +1,54 @@
1
- import { mapFBEvent } from "../track/fbq.mjs";
1
+ import { getFirst } from "../utils/field.mjs";
2
+ import { adEvents, adsTracker } from "../third-parties/integration.mjs";
3
+ import { isStandardFBEvent, mapFBEvent } from "../track/fbq.mjs";
2
4
  import { AppEventsLogger } from "react-native-fbsdk-next";
3
5
  // src/native/fbsdk.ts
4
6
  /**
5
7
  * ref: https://developers.facebook.com/docs/app-events/guides/maximize-in-app-ad-revenue/
8
+ *
9
+ * Synchronous, like `logEvent`: a tracker returns `void | boolean`, which an `async` function's
10
+ * promise would not satisfy. Callers that still `await` it keep compiling.
6
11
  */
7
- async function sendFBEvent(name, properties) {
12
+ function sendFBEvent(name, properties) {
8
13
  const [_, fbEventName, fbEventProperties] = mapFBEvent(name, properties);
9
14
  AppEventsLogger.logEvent(fbEventName, fbEventProperties);
10
15
  }
11
- export { sendFBEvent };
16
+ /**
17
+ * Hands the signed-in user to Facebook App Events, as `setFBUser` does the Pixel: the user id
18
+ * (`external_id`) and the advanced matching fields, which the SDK hashes on the device. No user is
19
+ * sign-out (`reset()`): the user id is cleared, but the matching fields may not be.
20
+ *
21
+ * Known gap, kept on purpose: the fields go to the native `setUserData`, which on Android only
22
+ * updates the fields it is given, so the empty ones sent at sign-out leave the previous user's
23
+ * email and phone in place, and later anonymous events (or another user's without an email) can
24
+ * still carry them. `react-native-fbsdk-next` does not expose the native `clearUserData`. Dropping
25
+ * the fields would avoid it, but cost more in ad conversion matching than the gap does.
26
+ */
27
+ function setFBUser({ user_id, user_data }) {
28
+ AppEventsLogger.setUserID(user_id || null);
29
+ const address = getFirst(user_data?.address);
30
+ AppEventsLogger.setUserData({
31
+ email: getFirst(user_data?.email),
32
+ phone: getFirst(user_data?.phone_number),
33
+ firstName: address?.first_name,
34
+ lastName: address?.last_name,
35
+ city: address?.city,
36
+ state: address?.region,
37
+ zip: address?.postal_code,
38
+ country: address?.country
39
+ });
40
+ }
41
+ /**
42
+ * Facebook App Events: the events `mapFBEvent` maps to a Meta standard event, and `customEvents`
43
+ * — the app's counterpart of `metaAds`.
44
+ */
45
+ function metaAppEvents(options = {}) {
46
+ return {
47
+ type: "ads",
48
+ track: adsTracker(sendFBEvent, adEvents(isStandardFBEvent, options.customEvents)),
49
+ setUser: setFBUser
50
+ };
51
+ }
52
+ export { metaAppEvents, sendFBEvent, setFBUser };
12
53
 
13
54
  //# sourceMappingURL=fbsdk.mjs.map
@@ -1 +1 @@
1
- {"version":3,"file":"fbsdk.mjs","names":[],"sources":["../../src/native/fbsdk.ts"],"sourcesContent":["import { AppEventsLogger, type Params } from 'react-native-fbsdk-next';\nimport { mapFBEvent } from '../track/fbq';\nimport type { EventName, TrackName, TrackProperties } from '../track/types';\n\n/**\n * ref: https://developers.facebook.com/docs/app-events/guides/maximize-in-app-ad-revenue/\n */\nexport async function sendFBEvent<T extends EventName>(\n name: TrackName<T>,\n properties?: TrackProperties<T>\n) {\n const [_, fbEventName, fbEventProperties] = mapFBEvent(name, properties);\n AppEventsLogger.logEvent(fbEventName, fbEventProperties as Params);\n}\n"],"mappings":";;;;;;AAOA,eAAsB,YACpB,MACA,YACA;CACA,MAAM,CAAC,GAAG,aAAa,qBAAqB,WAAW,MAAM,UAAU;CACvE,gBAAgB,SAAS,aAAa,iBAA2B;AACnE"}
1
+ {"version":3,"file":"fbsdk.mjs","names":[],"sources":["../../src/native/fbsdk.ts"],"sourcesContent":["import { AppEventsLogger, type Params } from 'react-native-fbsdk-next';\nimport type { UpdateVisitorDTO } from '../schema/index';\nimport {\n type AdsOptions,\n type Integration,\n adEvents,\n adsTracker,\n} from '../third-parties/integration';\nimport { isStandardFBEvent, mapFBEvent } from '../track/fbq';\nimport type { EventName, TrackName, TrackProperties } from '../track/types';\nimport { getFirst } from '../utils/field';\n\n/**\n * ref: https://developers.facebook.com/docs/app-events/guides/maximize-in-app-ad-revenue/\n *\n * Synchronous, like `logEvent`: a tracker returns `void | boolean`, which an `async` function's\n * promise would not satisfy. Callers that still `await` it keep compiling.\n */\nexport function sendFBEvent<T extends EventName>(\n name: TrackName<T>,\n properties?: TrackProperties<T>\n) {\n const [_, fbEventName, fbEventProperties] = mapFBEvent(name, properties);\n AppEventsLogger.logEvent(fbEventName, fbEventProperties as Params);\n}\n\n/**\n * Hands the signed-in user to Facebook App Events, as `setFBUser` does the Pixel: the user id\n * (`external_id`) and the advanced matching fields, which the SDK hashes on the device. No user is\n * sign-out (`reset()`): the user id is cleared, but the matching fields may not be.\n *\n * Known gap, kept on purpose: the fields go to the native `setUserData`, which on Android only\n * updates the fields it is given, so the empty ones sent at sign-out leave the previous user's\n * email and phone in place, and later anonymous events (or another user's without an email) can\n * still carry them. `react-native-fbsdk-next` does not expose the native `clearUserData`. Dropping\n * the fields would avoid it, but cost more in ad conversion matching than the gap does.\n */\nexport function setFBUser({ user_id, user_data }: Omit<UpdateVisitorDTO, 'tags'>) {\n AppEventsLogger.setUserID(user_id || null);\n const address = getFirst(user_data?.address);\n AppEventsLogger.setUserData({\n email: getFirst(user_data?.email),\n phone: getFirst(user_data?.phone_number),\n firstName: address?.first_name,\n lastName: address?.last_name,\n city: address?.city,\n state: address?.region,\n zip: address?.postal_code,\n country: address?.country,\n });\n}\n\n/**\n * Facebook App Events: the events `mapFBEvent` maps to a Meta standard event, and `customEvents`\n * — the app's counterpart of `metaAds`.\n */\nexport function metaAppEvents(options: AdsOptions = {}): Integration {\n return {\n type: 'ads',\n track: adsTracker(sendFBEvent, adEvents(isStandardFBEvent, options.customEvents)),\n setUser: setFBUser,\n };\n}\n"],"mappings":";;;;;;;;;;;AAkBA,SAAgB,YACd,MACA,YACA;CACA,MAAM,CAAC,GAAG,aAAa,qBAAqB,WAAW,MAAM,UAAU;CACvE,gBAAgB,SAAS,aAAa,iBAA2B;AACnE;;;;;;;;;;;;AAaA,SAAgB,UAAU,EAAE,SAAS,aAA6C;CAChF,gBAAgB,UAAU,WAAW,IAAI;CACzC,MAAM,UAAU,SAAS,WAAW,OAAO;CAC3C,gBAAgB,YAAY;EAC1B,OAAO,SAAS,WAAW,KAAK;EAChC,OAAO,SAAS,WAAW,YAAY;EACvC,WAAW,SAAS;EACpB,UAAU,SAAS;EACnB,MAAM,SAAS;EACf,OAAO,SAAS;EAChB,KAAK,SAAS;EACd,SAAS,SAAS;CACpB,CAAC;AACH;;;;;AAMA,SAAgB,cAAc,UAAsB,CAAC,GAAgB;CACnE,OAAO;EACL,MAAM;EACN,OAAO,WAAW,aAAa,SAAS,mBAAmB,QAAQ,YAAY,CAAC;EAChF,SAAS;CACX;AACF"}
@@ -1,4 +1,5 @@
1
1
  Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
2
+ const require_utils_field = require("../utils/field.cjs");
2
3
  let _react_native_firebase_analytics = require("@react-native-firebase/analytics");
3
4
  // src/native/firebase.ts
4
5
  const analytics = (0, _react_native_firebase_analytics.getAnalytics)();
@@ -15,6 +16,32 @@ function sendFirebaseEvent(name, properties) {
15
16
  });
16
17
  else (0, _react_native_firebase_analytics.logEvent)(analytics, name, properties);
17
18
  }
19
+ function logError(e) {
20
+ if (e instanceof Error) console.log(e.message);
21
+ }
22
+ /**
23
+ * Sets Firebase's user id to the signed-in user, as `setGAUser` does GA's; no user is sign-out
24
+ * (`reset()`), which clears it. The user properties stay free of PII, as Google requires: the
25
+ * email and phone number go to on-device conversion measurement instead, which matches Google
26
+ * Ads app campaign clicks on the device without them leaving it — iOS only, a no-op elsewhere.
27
+ */
28
+ function setFirebaseUser({ user_id, user_data }) {
29
+ (0, _react_native_firebase_analytics.setUserId)(analytics, user_id || null).catch(logError);
30
+ const email = require_utils_field.getFirst(user_data?.email);
31
+ if (email) (0, _react_native_firebase_analytics.initiateOnDeviceConversionMeasurementWithEmailAddress)(analytics, email).catch(logError);
32
+ const phone = require_utils_field.getFirst(user_data?.phone_number);
33
+ if (phone) (0, _react_native_firebase_analytics.initiateOnDeviceConversionMeasurementWithPhoneNumber)(analytics, phone).catch(logError);
34
+ }
35
+ /** Firebase Analytics: every event, for behavior analysis — the app's counterpart of GA4. */
36
+ function firebaseAnalytics() {
37
+ return {
38
+ type: "analytics",
39
+ track: sendFirebaseEvent,
40
+ setUser: setFirebaseUser
41
+ };
42
+ }
43
+ exports.firebaseAnalytics = firebaseAnalytics;
18
44
  exports.sendFirebaseEvent = sendFirebaseEvent;
45
+ exports.setFirebaseUser = setFirebaseUser;
19
46
 
20
47
  //# sourceMappingURL=firebase.cjs.map
@@ -1 +1 @@
1
- {"version":3,"file":"firebase.cjs","names":["getAnalytics"],"sources":["../../src/native/firebase.ts"],"sourcesContent":["import { getAnalytics, logEvent } from '@react-native-firebase/analytics';\nimport type { StandardEvents } from '../track/gtag';\nimport type { EventName, TrackName, TrackProperties } from '../track/types';\n\nconst analytics = getAnalytics();\n\n/**\n * A `ThirdPartyTracker` for Firebase Analytics. Synchronous: @react-native-firebase/analytics 26\n * made the modular `logEvent` fire-and-forget (void), and a tracker's return is `void | boolean`\n * (`false` meaning \"not ready\"), which an `async` function's promise would not satisfy. Callers\n * that still `await` it keep compiling.\n */\nexport function sendFirebaseEvent<T extends EventName>(\n name: TrackName<T>,\n properties?: TrackProperties<T>\n) {\n if (name === 'screen_view') {\n logEvent(analytics, 'screen_view', {\n firebase_screen: (properties as StandardEvents['screen_view'] | undefined)?.screen_name,\n firebase_screen_class: (properties as StandardEvents['screen_view'] | undefined)\n ?.screen_class,\n });\n } else {\n logEvent(analytics, name, properties);\n }\n}\n"],"mappings":";;;AAIA,MAAM,aAAA,GAAYA,iCAAAA,aAAAA,CAAa;;;;;;;AAQ/B,SAAgB,kBACd,MACA,YACA;CACA,IAAI,SAAS,eACX,CAAA,GAAA,iCAAA,SAAA,CAAS,WAAW,eAAe;EACjC,iBAAkB,YAA0D;EAC5E,uBAAwB,YACpB;CACN,CAAC;MAED,CAAA,GAAA,iCAAA,SAAA,CAAS,WAAW,MAAM,UAAU;AAExC"}
1
+ {"version":3,"file":"firebase.cjs","names":["getAnalytics","getFirst"],"sources":["../../src/native/firebase.ts"],"sourcesContent":["import {\n getAnalytics,\n initiateOnDeviceConversionMeasurementWithEmailAddress,\n initiateOnDeviceConversionMeasurementWithPhoneNumber,\n logEvent,\n setUserId,\n} from '@react-native-firebase/analytics';\nimport type { UpdateVisitorDTO } from '../schema/index';\nimport type { Integration } from '../third-parties/integration';\nimport type { StandardEvents } from '../track/gtag';\nimport type { EventName, TrackName, TrackProperties } from '../track/types';\nimport { getFirst } from '../utils/field';\n\nconst analytics = getAnalytics();\n\n/**\n * A `ThirdPartyTracker` for Firebase Analytics. Synchronous: @react-native-firebase/analytics 26\n * made the modular `logEvent` fire-and-forget (void), and a tracker's return is `void | boolean`\n * (`false` meaning \"not ready\"), which an `async` function's promise would not satisfy. Callers\n * that still `await` it keep compiling.\n */\nexport function sendFirebaseEvent<T extends EventName>(\n name: TrackName<T>,\n properties?: TrackProperties<T>\n) {\n if (name === 'screen_view') {\n logEvent(analytics, 'screen_view', {\n firebase_screen: (properties as StandardEvents['screen_view'] | undefined)?.screen_name,\n firebase_screen_class: (properties as StandardEvents['screen_view'] | undefined)\n ?.screen_class,\n });\n } else {\n logEvent(analytics, name, properties);\n }\n}\n\nfunction logError(e: unknown) {\n if (e instanceof Error) console.log(e.message);\n}\n\n/**\n * Sets Firebase's user id to the signed-in user, as `setGAUser` does GA's; no user is sign-out\n * (`reset()`), which clears it. The user properties stay free of PII, as Google requires: the\n * email and phone number go to on-device conversion measurement instead, which matches Google\n * Ads app campaign clicks on the device without them leaving it — iOS only, a no-op elsewhere.\n */\nexport function setFirebaseUser({ user_id, user_data }: Omit<UpdateVisitorDTO, 'tags'>) {\n setUserId(analytics, user_id || null).catch(logError);\n const email = getFirst(user_data?.email);\n if (email)\n initiateOnDeviceConversionMeasurementWithEmailAddress(analytics, email).catch(logError);\n const phone = getFirst(user_data?.phone_number);\n if (phone) initiateOnDeviceConversionMeasurementWithPhoneNumber(analytics, phone).catch(logError);\n}\n\n/** Firebase Analytics: every event, for behavior analysis — the app's counterpart of GA4. */\nexport function firebaseAnalytics(): Integration {\n return { type: 'analytics', track: sendFirebaseEvent, setUser: setFirebaseUser };\n}\n"],"mappings":";;;;AAaA,MAAM,aAAA,GAAYA,iCAAAA,aAAAA,CAAa;;;;;;;AAQ/B,SAAgB,kBACd,MACA,YACA;CACA,IAAI,SAAS,eACX,CAAA,GAAA,iCAAA,SAAA,CAAS,WAAW,eAAe;EACjC,iBAAkB,YAA0D;EAC5E,uBAAwB,YACpB;CACN,CAAC;MAED,CAAA,GAAA,iCAAA,SAAA,CAAS,WAAW,MAAM,UAAU;AAExC;AAEA,SAAS,SAAS,GAAY;CAC5B,IAAI,aAAa,OAAO,QAAQ,IAAI,EAAE,OAAO;AAC/C;;;;;;;AAQA,SAAgB,gBAAgB,EAAE,SAAS,aAA6C;CACtF,CAAA,GAAA,iCAAA,UAAA,CAAU,WAAW,WAAW,IAAI,CAAC,CAAC,MAAM,QAAQ;CACpD,MAAM,QAAQC,oBAAAA,SAAS,WAAW,KAAK;CACvC,IAAI,OACF,CAAA,GAAA,iCAAA,sDAAA,CAAsD,WAAW,KAAK,CAAC,CAAC,MAAM,QAAQ;CACxF,MAAM,QAAQA,oBAAAA,SAAS,WAAW,YAAY;CAC9C,IAAI,OAAO,CAAA,GAAA,iCAAA,qDAAA,CAAqD,WAAW,KAAK,CAAC,CAAC,MAAM,QAAQ;AAClG;;AAGA,SAAgB,oBAAiC;CAC/C,OAAO;EAAE,MAAM;EAAa,OAAO;EAAmB,SAAS;CAAgB;AACjF"}
@@ -1,4 +1,6 @@
1
1
  import { EventName, TrackName, TrackProperties } from "../track/types.cjs";
2
+ import { UpdateVisitorDTO } from "../schema/index.cjs";
3
+ import { Integration } from "../third-parties/integration.cjs";
2
4
  /**
3
5
  * A `ThirdPartyTracker` for Firebase Analytics. Synchronous: @react-native-firebase/analytics 26
4
6
  * made the modular `logEvent` fire-and-forget (void), and a tracker's return is `void | boolean`
@@ -6,4 +8,13 @@ import { EventName, TrackName, TrackProperties } from "../track/types.cjs";
6
8
  * that still `await` it keep compiling.
7
9
  */
8
10
  export declare function sendFirebaseEvent<T extends EventName>(name: TrackName<T>, properties?: TrackProperties<T>): void;
11
+ /**
12
+ * Sets Firebase's user id to the signed-in user, as `setGAUser` does GA's; no user is sign-out
13
+ * (`reset()`), which clears it. The user properties stay free of PII, as Google requires: the
14
+ * email and phone number go to on-device conversion measurement instead, which matches Google
15
+ * Ads app campaign clicks on the device without them leaving it — iOS only, a no-op elsewhere.
16
+ */
17
+ export declare function setFirebaseUser({ user_id, user_data }: Omit<UpdateVisitorDTO, 'tags'>): void;
18
+ /** Firebase Analytics: every event, for behavior analysis — the app's counterpart of GA4. */
19
+ export declare function firebaseAnalytics(): Integration;
9
20
  //# sourceMappingURL=firebase.d.cts.map
@@ -1 +1 @@
1
- {"version":3,"file":"firebase.d.cts","names":[],"sources":["../../src/native/firebase.ts"],"mappings":";;;;;;;wBAYgB,kBAAkB,UAAU,WAC1C,MAAM,UAAU,IAChB,aAAa,gBAAgB"}
1
+ {"version":3,"file":"firebase.d.cts","names":[],"sources":["../../src/native/firebase.ts"],"mappings":";;;;;;;;;wBAqBgB,kBAAkB,UAAU,WAC1C,MAAM,UAAU,IAChB,aAAa,gBAAgB;;;;;;;wBAuBf,kBAAkB,SAAS,aAAa,KAAK;;wBAU7C,qBAAqB"}
@@ -1,4 +1,6 @@
1
1
  import { EventName, TrackName, TrackProperties } from "../track/types.mjs";
2
+ import { UpdateVisitorDTO } from "../schema/index.mjs";
3
+ import { Integration } from "../third-parties/integration.mjs";
2
4
  /**
3
5
  * A `ThirdPartyTracker` for Firebase Analytics. Synchronous: @react-native-firebase/analytics 26
4
6
  * made the modular `logEvent` fire-and-forget (void), and a tracker's return is `void | boolean`
@@ -6,4 +8,13 @@ import { EventName, TrackName, TrackProperties } from "../track/types.mjs";
6
8
  * that still `await` it keep compiling.
7
9
  */
8
10
  export declare function sendFirebaseEvent<T extends EventName>(name: TrackName<T>, properties?: TrackProperties<T>): void;
11
+ /**
12
+ * Sets Firebase's user id to the signed-in user, as `setGAUser` does GA's; no user is sign-out
13
+ * (`reset()`), which clears it. The user properties stay free of PII, as Google requires: the
14
+ * email and phone number go to on-device conversion measurement instead, which matches Google
15
+ * Ads app campaign clicks on the device without them leaving it — iOS only, a no-op elsewhere.
16
+ */
17
+ export declare function setFirebaseUser({ user_id, user_data }: Omit<UpdateVisitorDTO, 'tags'>): void;
18
+ /** Firebase Analytics: every event, for behavior analysis — the app's counterpart of GA4. */
19
+ export declare function firebaseAnalytics(): Integration;
9
20
  //# sourceMappingURL=firebase.d.mts.map
@@ -1 +1 @@
1
- {"version":3,"file":"firebase.d.mts","names":[],"sources":["../../src/native/firebase.ts"],"mappings":";;;;;;;wBAYgB,kBAAkB,UAAU,WAC1C,MAAM,UAAU,IAChB,aAAa,gBAAgB"}
1
+ {"version":3,"file":"firebase.d.mts","names":[],"sources":["../../src/native/firebase.ts"],"mappings":";;;;;;;;;wBAqBgB,kBAAkB,UAAU,WAC1C,MAAM,UAAU,IAChB,aAAa,gBAAgB;;;;;;;wBAuBf,kBAAkB,SAAS,aAAa,KAAK;;wBAU7C,qBAAqB"}
@@ -1,4 +1,5 @@
1
- import { getAnalytics, logEvent } from "@react-native-firebase/analytics";
1
+ import { getFirst } from "../utils/field.mjs";
2
+ import { getAnalytics, initiateOnDeviceConversionMeasurementWithEmailAddress, initiateOnDeviceConversionMeasurementWithPhoneNumber, logEvent, setUserId } from "@react-native-firebase/analytics";
2
3
  // src/native/firebase.ts
3
4
  const analytics = getAnalytics();
4
5
  /**
@@ -14,6 +15,30 @@ function sendFirebaseEvent(name, properties) {
14
15
  });
15
16
  else logEvent(analytics, name, properties);
16
17
  }
17
- export { sendFirebaseEvent };
18
+ function logError(e) {
19
+ if (e instanceof Error) console.log(e.message);
20
+ }
21
+ /**
22
+ * Sets Firebase's user id to the signed-in user, as `setGAUser` does GA's; no user is sign-out
23
+ * (`reset()`), which clears it. The user properties stay free of PII, as Google requires: the
24
+ * email and phone number go to on-device conversion measurement instead, which matches Google
25
+ * Ads app campaign clicks on the device without them leaving it — iOS only, a no-op elsewhere.
26
+ */
27
+ function setFirebaseUser({ user_id, user_data }) {
28
+ setUserId(analytics, user_id || null).catch(logError);
29
+ const email = getFirst(user_data?.email);
30
+ if (email) initiateOnDeviceConversionMeasurementWithEmailAddress(analytics, email).catch(logError);
31
+ const phone = getFirst(user_data?.phone_number);
32
+ if (phone) initiateOnDeviceConversionMeasurementWithPhoneNumber(analytics, phone).catch(logError);
33
+ }
34
+ /** Firebase Analytics: every event, for behavior analysis — the app's counterpart of GA4. */
35
+ function firebaseAnalytics() {
36
+ return {
37
+ type: "analytics",
38
+ track: sendFirebaseEvent,
39
+ setUser: setFirebaseUser
40
+ };
41
+ }
42
+ export { firebaseAnalytics, sendFirebaseEvent, setFirebaseUser };
18
43
 
19
44
  //# sourceMappingURL=firebase.mjs.map