@metarouter/react-native-sdk 1.7.0 → 1.8.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 (31) hide show
  1. package/README.md +164 -56
  2. package/lib/analytics/MetaRouterAnalyticsClient.d.ts +50 -2
  3. package/lib/analytics/MetaRouterAnalyticsClient.d.ts.map +1 -1
  4. package/lib/analytics/MetaRouterAnalyticsClient.js +239 -44
  5. package/lib/analytics/init.d.ts +7 -0
  6. package/lib/analytics/init.d.ts.map +1 -1
  7. package/lib/analytics/init.js +197 -37
  8. package/lib/analytics/lifecycle/lifecycleEvents.d.ts +52 -0
  9. package/lib/analytics/lifecycle/lifecycleEvents.d.ts.map +1 -0
  10. package/lib/analytics/lifecycle/lifecycleEvents.js +66 -0
  11. package/lib/analytics/proxy/proxyClient.d.ts +29 -0
  12. package/lib/analytics/proxy/proxyClient.d.ts.map +1 -1
  13. package/lib/analytics/proxy/proxyClient.js +125 -5
  14. package/lib/analytics/types.d.ts +50 -1
  15. package/lib/analytics/types.d.ts.map +1 -1
  16. package/lib/analytics/utils/appContext.d.ts +20 -0
  17. package/lib/analytics/utils/appContext.d.ts.map +1 -0
  18. package/lib/analytics/utils/appContext.js +22 -0
  19. package/lib/analytics/utils/contextInfo.d.ts +7 -3
  20. package/lib/analytics/utils/contextInfo.d.ts.map +1 -1
  21. package/lib/analytics/utils/contextInfo.js +12 -9
  22. package/lib/analytics/utils/initOptions.d.ts +22 -0
  23. package/lib/analytics/utils/initOptions.d.ts.map +1 -0
  24. package/lib/analytics/utils/initOptions.js +100 -0
  25. package/lib/analytics/utils/lifecycleStorage.d.ts +13 -0
  26. package/lib/analytics/utils/lifecycleStorage.d.ts.map +1 -0
  27. package/lib/analytics/utils/lifecycleStorage.js +35 -0
  28. package/lib/index.d.ts +4 -4
  29. package/lib/index.d.ts.map +1 -1
  30. package/lib/index.js +3 -3
  31. package/package.json +1 -1
package/README.md CHANGED
@@ -15,6 +15,7 @@ A lightweight React Native analytics SDK that transmits events to your MetaRoute
15
15
  - [API Reference](#api-reference)
16
16
  - [Features](#features)
17
17
  - [Disk-Backed Queue Persistence](#disk-backed-queue-persistence)
18
+ - [Application Lifecycle Events](#application-lifecycle-events)
18
19
  - [Compatibility](#-compatibility)
19
20
  - [Debugging](#debugging)
20
21
  - [Identity Persistence](#identity-persistence)
@@ -37,11 +38,11 @@ After installing or upgrading, run `cd ios && pod install` and rebuild the nativ
37
38
  ```js
38
39
  import { createAnalyticsClient } from "@metarouter/react-native-sdk";
39
40
 
40
- // Initialize the analytics client
41
- const analytics = await createAnalyticsClient({
41
+ // Returns the client right away; initialization finishes in the background
42
+ const analytics = createAnalyticsClient({
42
43
  writeKey: "your-write-key",
43
44
  ingestionHost: "https://your-ingestion-endpoint.com",
44
- debug: true, // Optional: enable debug mode
45
+ debug: __DEV__, // Optional: verbose logs, never in a store release
45
46
  flushIntervalSeconds: 30, // Optional: flush events every 30 seconds
46
47
  });
47
48
  ```
@@ -49,43 +50,25 @@ const analytics = await createAnalyticsClient({
49
50
  ### React Context Usage
50
51
 
51
52
  ```jsx
52
- import React, { useEffect, useState } from "react";
53
+ import React from "react";
53
54
  import {
54
55
  createAnalyticsClient,
55
56
  MetaRouterProvider,
56
57
  useMetaRouter,
57
58
  } from "@metarouter/react-native-sdk";
58
59
 
59
- const App = () => {
60
- const [analyticsClient, setAnalyticsClient] = useState(null);
61
- const [isLoading, setIsLoading] = useState(true);
62
-
63
- useEffect(() => {
64
- const initializeAnalytics = async () => {
65
- try {
66
- // Initialize the analytics client
67
- const client = await createAnalyticsClient({
68
- writeKey: "your-write-key",
69
- ingestionHost: "https://your-ingestion-endpoint.com",
70
- });
71
- setAnalyticsClient(client);
72
- } catch (error) {
73
- console.error("Failed to initialize analytics:", error);
74
- } finally {
75
- setIsLoading(false);
76
- }
77
- };
78
- initializeAnalytics();
79
- }, []);
80
-
81
- if (isLoading) return null; // or a loading spinner
82
-
83
- return (
84
- <MetaRouterProvider analyticsClient={analyticsClient}>
85
- <YourApp />
86
- </MetaRouterProvider>
87
- );
88
- };
60
+ // Create the client once, outside any component. It is usable immediately:
61
+ // there is no promise to await, and nothing to catch in a release build.
62
+ const analytics = createAnalyticsClient({
63
+ writeKey: "your-write-key",
64
+ ingestionHost: "https://your-ingestion-endpoint.com",
65
+ });
66
+
67
+ const App = () => (
68
+ <MetaRouterProvider analyticsClient={analytics}>
69
+ <YourApp />
70
+ </MetaRouterProvider>
71
+ );
89
72
 
90
73
  // Use analytics in any component
91
74
  const MyComponent = () => {
@@ -107,9 +90,9 @@ const MyComponent = () => {
107
90
  ```js
108
91
  import { createAnalyticsClient } from "@metarouter/react-native-sdk";
109
92
 
110
- // Initialize the client (optionally await it), but you can use it at any time
111
- // with events transmitted when the client is ready.
112
- const analytics = await createAnalyticsClient({
93
+ // Usable immediately: calls made before initialization finishes are
94
+ // buffered and sent once the client is ready.
95
+ const analytics = createAnalyticsClient({
113
96
  writeKey: "your-write-key",
114
97
  ingestionHost: "https://your-ingestion-endpoint.com",
115
98
  });
@@ -156,7 +139,7 @@ await analytics.reset();
156
139
 
157
140
  ```js
158
141
  // Initial configuration
159
- const analytics = await createAnalyticsClient({
142
+ const analytics = createAnalyticsClient({
160
143
  writeKey: "key-1",
161
144
  ingestionHost: "https://endpoint-1.com",
162
145
  });
@@ -164,8 +147,9 @@ const analytics = await createAnalyticsClient({
164
147
  // Later, if you need to change configuration:
165
148
  await analytics.reset(); // Must reset first!
166
149
 
167
- // Now reconfigure with new options
168
- const analytics = await createAnalyticsClient({
150
+ // Now reconfigure with new options. The same client object is returned, so
151
+ // existing references (and MetaRouterProvider) keep working.
152
+ createAnalyticsClient({
169
153
  writeKey: "key-2",
170
154
  ingestionHost: "https://endpoint-2.com",
171
155
  });
@@ -181,27 +165,61 @@ If you call `createAnalyticsClient()` with different options without resetting f
181
165
 
182
166
  ### createAnalyticsClient(options)
183
167
 
184
- Initializes the analytics client and returns a **live proxy** to the client instance.
185
-
186
- ⚠️ `createAnalyticsClient()` is asynchronous, but you **do not** need to `await` it before using analytics methods.
168
+ Starts initialization and returns a **live proxy** to the client instance, synchronously. It does not return a Promise, so there is nothing to `await`, and in a release build nothing to `catch`: invalid options never throw there (development builds throw so the mistake surfaces at the call site). See [Invalid configuration](#invalid-configuration).
187
169
 
188
170
  Calls to `track`, `identify`, etc. are **buffered in-memory** by the proxy and replayed **in order** once the client is fully initialized.
189
171
 
190
172
  **Options:**
191
173
 
192
- - `writeKey` (string, required): Your write key
193
- - `ingestionHost` (string, required): Your MetaRouter ingestor host
194
- - `debug` (boolean, optional): Enable debug mode
195
- - `flushIntervalSeconds` (number, optional): Interval in seconds to flush events
196
- - `maxQueueBytes` (number, optional): max bytes (UTF-8) held in memory queue (default: 5MB)
174
+ - `writeKey` (string, required): Your MetaRouter write key. Trimmed; empty or whitespace-only is a config error.
175
+ - `ingestionHost` (string, required): Your MetaRouter ingestion endpoint: an `http`/`https` URL with a host. Trimmed, and trailing slashes are removed. Cleartext `http` logs a warning unless the host is `localhost`, `127.0.0.1` or `::1`.
176
+ - `flushIntervalSeconds` (number, optional, default: `10`): How often the SDK attempts to send queued events. Values below 1 are clamped to 1.
177
+ - `debug` (boolean, optional, default: `false`): Enables verbose SDK logging. Can also be toggled at runtime via `analytics.enableDebugLogging()`.
178
+ - `maxQueueEvents` (number, optional, default: `2000`): Maximum events held in the in-memory queue. Values below 1 are clamped to 1. The queue is also bounded by a 5 MB byte cap — whichever limit is reached first triggers drop-oldest eviction.
179
+ - `maxDiskEvents` (number, optional, default: `10000`): Maximum unsent events retained on disk for crash safety and offline recovery. Negative values are clamped to `0` with a warning. Set to `0` to disable disk persistence (events are lost on app kill).
180
+ - `trackLifecycleEvents` (boolean, optional, default: `false`): Opt-in. Set to `true` to emit `Application Installed`, `Application Updated`, `Application Opened`, and `Application Backgrounded` events automatically. See [Application Lifecycle Events](#application-lifecycle-events).
181
+ - `onConfigError` (function, optional): Called with a `ConfigError` (`type`, `description`, and `raw` for a bad host) when the options are invalid in a release build. See [Invalid configuration](#invalid-configuration).
182
+
183
+ Out-of-range numbers are clamped and logged as a warning; they never fail initialization.
197
184
 
198
185
  **Proxy behavior (quick notes):**
199
186
 
200
187
  - Buffer is **in-memory only** (not persisted). Calls made before ready are lost if the process exits.
201
188
  - Ordering is preserved relative to other buffered calls; normal FIFO + batching applies after ready.
202
- - On fatal config errors (`401/403/404`), the client enters **disabled** state and drops subsequent calls.
189
+ - On fatal config errors from the ingestion host (`401/403/404`), the client enters **disabled** state and drops subsequent calls. This is separate from [invalid options](#invalid-configuration) and does not call `onConfigError`.
203
190
  - `sentAt` is stamped when the batch is prepared for transmission (just before network send). If you need the original occurrence time, pass your own `timestamp` on each event.
204
191
 
192
+ ### Invalid configuration
193
+
194
+ Invalid options (an empty `writeKey`, or an `ingestionHost` that is not an `http`/`https` URL with a host) never crash a release build. The same rules apply on iOS and Android.
195
+
196
+ | Build | What happens |
197
+ | ----- | ------------ |
198
+ | Development (`__DEV__`) | `createAnalyticsClient` throws `Invalid InitOptions: <reason>`, so the mistake shows up immediately at the call site. |
199
+ | Release | An always-on error is logged (`[MetaRouter] MetaRouter disabled for this session — <reason>`), `onConfigError` is called once, synchronously, and the SDK stays inert for the session: calls are accepted and nothing is sent. |
200
+
201
+ While the session is disabled:
202
+
203
+ - `getAnonymousId()` resolves `""` instead of waiting, and `flush()` resolves immediately.
204
+ - `getDebugInfo()` returns `lifecycle: "disabled"` and the reason as `configError`.
205
+ - Calls made while disabled are kept (up to the usual 20) and sent if the session recovers.
206
+
207
+ A later `createAnalyticsClient` with valid options recovers the session, and so does `reset()`. An invalid call made while a valid session is running disables that session too, rather than leaving the old configuration running unnoticed.
208
+
209
+ Disabling a running session resets its client, which clears the stored identity (anonymous ID, user ID, group ID, advertising ID), the same as the Android SDK. A single invalid call between two valid ones therefore starts the recovered session as a new anonymous user.
210
+
211
+ ```js
212
+ const analytics = createAnalyticsClient({
213
+ writeKey: remoteConfig.writeKey,
214
+ ingestionHost: remoteConfig.ingestionHost,
215
+ onConfigError: (error) => {
216
+ // error.type is "emptyWriteKey" or "invalidIngestionHost" (with error.raw);
217
+ // error.description is the same text the iOS and Android SDKs report.
218
+ reportToYourDiagnostics("MetaRouter config", error.description);
219
+ },
220
+ });
221
+ ```
222
+
205
223
  ### Analytics Interface
206
224
 
207
225
  The analytics client provides the following methods:
@@ -212,6 +230,7 @@ The analytics client provides the following methods:
212
230
  - `screen(name: string, properties?: Record<string, any>)`: Track screen views
213
231
  - `page(name: string, properties?: Record<string, any>)`: Track page views
214
232
  - `alias(newUserId: string)`: Connect anonymous users to known user IDs. See [Using the alias() Method](#using-the-alias-method) for details
233
+ - `recordOpenedURL(url: string, sourceApplication?: string)`: Forward a URL the host received (from `Linking.getInitialURL`, `Linking.addEventListener('url', ...)`, a UIScene URL handler, or an Android Intent) so it is attached to the next `Application Opened` event. The SDK does not read `Linking` itself, so only URLs passed here are recorded. One-shot — the buffer is cleared after the next Opened emit; last-write-wins if called multiple times. No-op (with a warning, always logged) when `trackLifecycleEvents` is disabled. See [Application Lifecycle Events](#application-lifecycle-events) for deep-link wiring details.
215
234
  - `setAdvertisingId(advertisingId: string)`: Set the advertising identifier (IDFA on iOS, GAID on Android) for ad tracking. See [Advertising ID](#advertising-id-idfagaid) section for usage and compliance requirements
216
235
  - `clearAdvertisingId()`: Clear the advertising identifier from storage and context. Useful for GDPR/CCPA compliance when users opt out of ad tracking
217
236
  - `getAnonymousId(): Promise<string>`: Returns the current anonymous ID. Async, never returns null — guaranteed to resolve a string after `init()`
@@ -237,6 +256,7 @@ The analytics client provides the following methods:
237
256
  - 🔧 **TypeScript Support**: Full TypeScript support included
238
257
  - 🚀 **Lightweight**: Minimal overhead and dependencies
239
258
  - 💾 **Best-Effort Queue Persistence**: Can persist queued events to native disk storage and rehydrate them on next launch
259
+ - 📲 **Lifecycle Events (opt-in)**: Emit `Application Installed/Updated/Opened/Backgrounded` automatically when enabled — see [Application Lifecycle Events](#application-lifecycle-events)
240
260
  - 🔄 **Reset Capability**: Easily reset analytics state for testing or logout scenarios
241
261
  - 🐛 **Debug Support**: Built-in debugging tools for troubleshooting
242
262
 
@@ -249,6 +269,94 @@ This release adds native iOS and Android storage for best-effort queue durabilit
249
269
  - Persisted events are rehydrated during the next `init()`.
250
270
  - This is a durability baseline, not a full offline mode. The SDK still primarily uses in-memory batching and normal network delivery, and it does not guarantee zero-loss across every crash or termination window.
251
271
 
272
+ ## Application Lifecycle Events
273
+
274
+ Opt-in. When enabled, the SDK emits four lifecycle events that mirror the iOS and Android native SDKs. They are sent through the same enrichment + batching pipeline as user-emitted events.
275
+
276
+ | Event | When it fires | Properties |
277
+ | --------------------------- | ---------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
278
+ | `Application Installed` | First launch with no prior version stored and no prior identity state. | `version`, `build` |
279
+ | `Application Updated` | First launch where the stored version/build differs from the current. | `version`, `build`, `previous_version`, `previous_build` |
280
+ | `Application Opened` | Cold launch (foreground) and every return to the foreground after a background entry. | `from_background` (false on cold launch, true on resume), `version`, `build`, optional `url`, optional `referring_application` |
281
+ | `Application Backgrounded` | App enters background from the foreground. | _(none)_ |
282
+
283
+ ### Enabling lifecycle events
284
+
285
+ Lifecycle events are **opt-in** — existing customers upgrading the SDK do not begin emitting these events without explicitly setting the flag. To enable:
286
+
287
+ ```js
288
+ const analytics = createAnalyticsClient({
289
+ writeKey: "your-write-key",
290
+ ingestionHost: "https://your-ingestion-endpoint.com",
291
+ trackLifecycleEvents: true, // default: false
292
+ });
293
+ ```
294
+
295
+ ### Notes
296
+
297
+ - `active → inactive → active` blips (Control Center, a FaceID prompt, system alerts) are **suppressed**. `Application Opened` with `from_background: true` needs a real background entry first; a return that passes through `inactive` (e.g. a passcode prompt on resume) still counts.
298
+ - On iOS, React Native reports `active → inactive → background` when the app is left; `Application Backgrounded` fires on the `background` step. A process that settles straight into the background from `unknown` (headless task, push wake) does not emit `Application Backgrounded`. On iOS the launch state is `inactive`, so locking the device before the app first becomes active does emit one, the same as the native iOS SDK.
299
+ - Cold launches in a background process state (silent push, headless task) suppress the cold-launch `Application Opened`; the next `background → active` transition emits with `from_background: false` as the cold-launch bridge.
300
+ - Existing users upgrading from a pre-lifecycle SDK build receive `Application Updated` with `previous_version="unknown"` and `previous_build="unknown"` (instead of a spurious `Application Installed`).
301
+ - Lifecycle storage (`metarouter:lifecycle:version`, `metarouter:lifecycle:build`) is **not** cleared by `reset()` — install/update history survives logout.
302
+ - `Application Backgrounded` is emitted **before** the SDK's flush-to-disk pass on background entry, so the event is captured by the same drain that ships pending events.
303
+
304
+ ### Deep-link wiring
305
+
306
+ The SDK does **not** read `Linking` itself, the same as the iOS and Android SDKs: only URLs your app forwards through `recordOpenedURL` are attached to `Application Opened` (as `url`, plus `referring_application` when you pass one). Forward the cold-launch URL and runtime URL events:
307
+
308
+ ```js
309
+ import { Linking } from "react-native";
310
+
311
+ const analytics = createAnalyticsClient({ /* ... */ trackLifecycleEvents: true });
312
+
313
+ // Cold launch: safe to call right after createAnalyticsClient(). A URL
314
+ // forwarded while initialization is still running reaches the cold-launch
315
+ // Application Opened.
316
+ Linking.getInitialURL().then((url) => {
317
+ if (url) analytics.recordOpenedURL(url);
318
+ });
319
+
320
+ // Resume: attached to the next Application Opened.
321
+ Linking.addEventListener("url", ({ url }) => {
322
+ analytics.recordOpenedURL(url);
323
+ });
324
+
325
+ // With a referring application (typically forwarded from native):
326
+ analytics.recordOpenedURL("myapp://product/123", "com.example.referrer");
327
+ ```
328
+
329
+ URLs from outside `Linking` (a UIScene URL handler on iOS, an Android `Intent.ACTION_VIEW`, a deep-link library such as Branch) are forwarded the same way.
330
+
331
+ **Buffer semantics:**
332
+
333
+ - One-shot — the buffer is cleared after the next `Application Opened` emits.
334
+ - Last-write-wins — multiple `recordOpenedURL` calls before the next Opened keep only the most recent URL.
335
+ - No-op with an always-on warning when `trackLifecycleEvents` is disabled, so misconfigurations surface in logs instead of failing silently.
336
+
337
+ ### Privacy & sanitization
338
+
339
+ URLs can contain sensitive material (auth tokens, OTPs, magic-link secrets, PII in query strings). The SDK records the URL verbatim, and because it only records what you forward, sanitizing before the call is enough:
340
+
341
+ ```js
342
+ function sanitize(url) {
343
+ const u = new URL(url);
344
+ // Strip known sensitive query params before forwarding.
345
+ ["token", "otp", "auth"].forEach((k) => u.searchParams.delete(k));
346
+ return u.toString();
347
+ }
348
+
349
+ Linking.addEventListener("url", ({ url }) => {
350
+ analytics.recordOpenedURL(sanitize(url));
351
+ });
352
+ ```
353
+
354
+ ### Why the SDK does not auto-instrument deep links
355
+
356
+ - **Privacy.** Hosts often receive URLs that contain credentials. Capturing them automatically would record secrets before the app has a chance to strip them.
357
+ - **Host control.** Apps with custom URL routers or deep-link libraries (react-navigation linking, react-native-firebase dynamic links, Branch) need to decide *if* and *which* URLs reach analytics — `recordOpenedURL` is the explicit hand-off point.
358
+ - **Parity.** The iOS (`recordOpenedURL`) and Android (`recordOpenedUrl`) SDKs work the same way, so the same app behaves the same on every platform.
359
+
252
360
  ## ✅ Compatibility
253
361
 
254
362
  | Component | Supported Versions |
@@ -268,7 +376,7 @@ If you're not seeing API calls being made, here are some steps to troubleshoot:
268
376
 
269
377
  ```js
270
378
  // Initialize with debug enabled
271
- const analytics = await createAnalyticsClient({
379
+ const analytics = createAnalyticsClient({
272
380
  writeKey: "your-write-key",
273
381
  ingestionHost: "https://your-ingestion-endpoint.com",
274
382
  debug: true, // This enables detailed logging
@@ -302,7 +410,7 @@ await analytics.flush();
302
410
 
303
411
  ### Delivery & Backoff (How events flow under failures)
304
412
 
305
- Queue capacity: The SDK caps the in-memory queue at 5MB by default. When the cap is reached, the oldest events are dropped first (drop-oldest). You can change this via maxQueueBytes in createAnalyticsClient(options)
413
+ Queue capacity: The SDK caps the in-memory queue at 5 MB (hardcoded). When either the 5 MB byte cap or the `maxQueueEvents` count cap is reached, the oldest events are dropped first (drop-oldest). Tune the event count via `maxQueueEvents` in `createAnalyticsClient(options)`.
306
414
 
307
415
  This SDK uses a circuit breaker around network I/O. It keeps ordering stable, avoids tight retry loops, and backs off cleanly when your cluster is unhealthy or throttling.
308
416
 
@@ -514,7 +622,7 @@ await analytics.reset();
514
622
 
515
623
  ```js
516
624
  // App starts - SDK initializes
517
- const analytics = await createAnalyticsClient({...});
625
+ const analytics = createAnalyticsClient({...});
518
626
  // anonymousId: "abc-123" (auto-generated and persisted)
519
627
 
520
628
  // User browses before login
@@ -574,7 +682,7 @@ This does two things:
574
682
 
575
683
  ```js
576
684
  // App starts - user is anonymous
577
- const analytics = await createAnalyticsClient({...});
685
+ const analytics = createAnalyticsClient({...});
578
686
  // anonymousId: "abc-123" (auto-generated)
579
687
 
580
688
  // User browses anonymously
@@ -646,7 +754,7 @@ The SDK supports including advertising identifiers (IDFA on iOS, GAID on Android
646
754
  Use the `setAdvertisingId()` method to set the advertising identifier after initializing the analytics client:
647
755
 
648
756
  ```js
649
- const analytics = await createAnalyticsClient({
757
+ const analytics = createAnalyticsClient({
650
758
  writeKey: "your-write-key",
651
759
  ingestionHost: "https://your-ingestion-endpoint.com",
652
760
  });
@@ -689,7 +797,7 @@ import { AppTrackingTransparency } from "react-native-tracking-transparency";
689
797
  import { getAdvertisingId } from "@react-native-community/google-advertiser-id"; // or similar library
690
798
 
691
799
  // Initialize analytics first
692
- const analytics = await createAnalyticsClient({
800
+ const analytics = createAnalyticsClient({
693
801
  writeKey: "your-write-key",
694
802
  ingestionHost: "https://your-ingestion-endpoint.com",
695
803
  });
@@ -711,7 +819,7 @@ if (trackingStatus === "authorized") {
711
819
  import { getAdvertisingId } from "@react-native-community/google-advertiser-id"; // or similar library
712
820
 
713
821
  // Initialize analytics first
714
- const analytics = await createAnalyticsClient({
822
+ const analytics = createAnalyticsClient({
715
823
  writeKey: "your-write-key",
716
824
  ingestionHost: "https://your-ingestion-endpoint.com",
717
825
  });
@@ -15,12 +15,11 @@ export declare class MetaRouterAnalyticsClient {
15
15
  private ingestionHost;
16
16
  private writeKey;
17
17
  private context;
18
+ private appContext;
18
19
  private appState;
19
20
  private appStateSubscription;
20
21
  private identityManager;
21
22
  private static readonly AUTO_FLUSH_THRESHOLD;
22
- private static readonly DEFAULT_MAX_QUEUE_EVENTS;
23
- private static readonly DEFAULT_MAX_DISK_EVENTS;
24
23
  private static readonly MAX_QUEUE_BYTES;
25
24
  private maxDiskEvents;
26
25
  private dispatcher;
@@ -29,6 +28,11 @@ export declare class MetaRouterAnalyticsClient {
29
28
  private networkMonitor;
30
29
  private networkStatus;
31
30
  private unsubscribeNetwork;
31
+ private lifecycleEmitter;
32
+ private trackLifecycleEvents;
33
+ private pendingDeepLink;
34
+ private coldLaunchOpenDeferred;
35
+ private wasBackgrounded;
32
36
  /**
33
37
  * Initializes the analytics client with the provided options.
34
38
  * @param options - The initialization options.
@@ -60,6 +64,12 @@ export declare class MetaRouterAnalyticsClient {
60
64
  * @returns The current timestamp in ISO format.
61
65
  */
62
66
  private now;
67
+ /**
68
+ * Adds identity, writeKey, context and messageId to a raw event. Shared by
69
+ * enqueue() and the lifecycle emitter so both paths produce identical
70
+ * payloads.
71
+ */
72
+ private buildEnrichedEvent;
63
73
  /**
64
74
  * Enqueues an event for processing.
65
75
  * @param event - The event to enqueue.
@@ -72,11 +82,49 @@ export declare class MetaRouterAnalyticsClient {
72
82
  * Sets up the app state listener.
73
83
  */
74
84
  private setupAppStateListener;
85
+ /**
86
+ * Runs the cold-launch lifecycle sequence: detect install vs update vs
87
+ * neither, persist the current version/build, capture any cold-launch
88
+ * deep link, and (when the process is foregrounded) emit Application
89
+ * Opened with from_background=false.
90
+ *
91
+ * No-ops when trackLifecycleEvents is false.
92
+ *
93
+ * @param hadIdentityBeforeInit - Whether identity existed in storage before
94
+ * IdentityManager.init() ran on this launch (see init()).
95
+ */
96
+ private runColdLaunchLifecycle;
97
+ /**
98
+ * True if any identity field is present in storage. Used to distinguish a
99
+ * fresh install from an existing user upgrading from a pre-lifecycle SDK
100
+ * build. Best-effort: failures are treated as "no identity state".
101
+ */
102
+ private hasIdentityState;
103
+ private consumePendingDeepLink;
75
104
  /**
76
105
  * Handles the app state change event.
77
106
  * @param nextState - The new app state.
78
107
  */
79
108
  private handleAppStateChange;
109
+ /**
110
+ * Forward a URL the host received (e.g. from `Linking.getInitialURL`,
111
+ * `Linking.addEventListener('url', ...)`, a UIScene URL handler, or an
112
+ * Android Intent) so it is attached to the next `Application Opened`
113
+ * event as `url` (and `referring_application` if `sourceApplication`
114
+ * is provided). One-shot — the buffer is cleared on the next Opened
115
+ * emit. Last-write-wins if called multiple times before the next Opened.
116
+ *
117
+ * The SDK never reads `Linking` itself: deep links routinely carry auth
118
+ * tokens and OTPs, and an automatic capture would race the host's own
119
+ * sanitized forward for the same one-slot buffer. Only what the host
120
+ * passes here reaches the event (parity with iOS recordOpenedURL and
121
+ * Android recordOpenedUrl).
122
+ *
123
+ * No-op with an always-on warning when `trackLifecycleEvents` is
124
+ * disabled — silent no-ops are bad DX, hosts wiring this up should know
125
+ * they have the feature flag off.
126
+ */
127
+ recordOpenedURL(url: string, sourceApplication?: string): void;
80
128
  /**
81
129
  * Tracks an event.
82
130
  * @param event - The event to track.
@@ -1 +1 @@
1
- {"version":3,"file":"MetaRouterAnalyticsClient.d.ts","sourceRoot":"","sources":["../../src/analytics/MetaRouterAnalyticsClient.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"MetaRouterAnalyticsClient.d.ts","sourceRoot":"","sources":["../../src/analytics/MetaRouterAnalyticsClient.ts"],"names":[],"mappings":"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"}