@metarouter/react-native-sdk 1.3.0 → 1.5.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.
package/README.md CHANGED
@@ -5,6 +5,22 @@
5
5
 
6
6
  A lightweight React Native analytics SDK that transmits events to your MetaRouter cluster.
7
7
 
8
+ ## Table of Contents
9
+
10
+ - [Installation](#installation)
11
+ - [Usage](#usage)
12
+ - [Basic Setup](#basic-setup)
13
+ - [React Context Usage](#react-context-usage)
14
+ - [Direct Usage](#direct-usage)
15
+ - [API Reference](#api-reference)
16
+ - [Features](#features)
17
+ - [Compatibility](#-compatibility)
18
+ - [Debugging](#debugging)
19
+ - [Identity Persistence](#identity-persistence)
20
+ - [Advertising ID (IDFA/GAID)](#advertising-id-idfagaid)
21
+ - [Using the alias() Method](#using-the-alias-method)
22
+ - [License](#license)
23
+
8
24
  ## Installation
9
25
 
10
26
  ```sh
@@ -88,7 +104,8 @@ const MyComponent = () => {
88
104
  ```js
89
105
  import { createAnalyticsClient } from "@metarouter/react-native-sdk";
90
106
 
91
- // Initialize optionally await it but can use at anytime with events transmitted when client is available.
107
+ // Initialize the client (optionally await it), but you can use it at any time
108
+ // with events transmitted when the client is ready.
92
109
  const analytics = await createAnalyticsClient({
93
110
  writeKey: "your-write-key",
94
111
  ingestionHost: "https://your-ingestion-endpoint.com",
@@ -111,6 +128,12 @@ analytics.screen("Home Screen", {
111
128
  category: "navigation",
112
129
  });
113
130
 
131
+ // Track page views
132
+ analytics.page("Home Page", {
133
+ url: "/home",
134
+ referrer: "/landing",
135
+ });
136
+
114
137
  // Group users
115
138
  analytics.group("company123", {
116
139
  name: "Acme Corp",
@@ -157,9 +180,13 @@ The analytics client provides the following methods:
157
180
  - `identify(userId: string, traits?: Record<string, any>)`: Identify users
158
181
  - `group(groupId: string, traits?: Record<string, any>)`: Group users
159
182
  - `screen(name: string, properties?: Record<string, any>)`: Track screen views
160
- - `alias(newUserId: string)`: Alias user IDs
183
+ - `page(name: string, properties?: Record<string, any>)`: Track page views
184
+ - `alias(newUserId: string)`: Connect anonymous users to known user IDs. See [Using the alias() Method](#using-the-alias-method) for details
185
+ - `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
186
+ - `clearAdvertisingId()`: Clear the advertising identifier from storage and context. Useful for GDPR/CCPA compliance when users opt out of ad tracking
187
+ - `setTracing(enabled: boolean)`: Enable or disable tracing headers on API requests. When enabled, includes a `Trace: true` header for debugging request flows
161
188
  - `flush()`: Flush events immediately
162
- - `reset()`: Reset analytics state and clear all stored data
189
+ - `reset()`: Reset analytics state and clear all stored data (includes clearing advertising ID)
163
190
  - `enableDebugLogging()`: Enable debug logging
164
191
  - `getDebugInfo()`: Get current debug information
165
192
 
@@ -227,7 +254,7 @@ await analytics.flush();
227
254
  ### 4. Common Issues
228
255
 
229
256
  - **Network Permissions**: Ensure your app has network permissions
230
- - **AsyncStorage**: The SDK uses AsyncStorage for anonymous ID persistence
257
+ - **AsyncStorage**: The SDK uses AsyncStorage for identity persistence (anonymousId, userId, groupId, advertisingId)
231
258
  - **Endpoint URL**: Verify your ingestion endpoint is correct and accessible
232
259
  - **Write Key**: Ensure your write key is valid
233
260
 
@@ -266,6 +293,410 @@ sentAt semantics: sentAt is stamped when the event is enqueued. If the client is
266
293
  - `anonymousId` is a stable, persisted UUID for the device/user before identify; it does **not** include timestamps.
267
294
  - `messageId` is generated as `<epochMillis>-<uuid>` (e.g., `1734691572843-6f0c7e85-...`) to aid debugging.
268
295
 
296
+ ## Identity Persistence
297
+
298
+ The MetaRouter React Native SDK automatically manages and persists user identifiers across app sessions using React Native's AsyncStorage. This ensures consistent user tracking even after app restarts.
299
+
300
+ ### The Four Identity Fields
301
+
302
+ #### 1. userId (Common User ID)
303
+
304
+ The `userId` is set when you identify a user and represents their unique identifier in your system (e.g., database ID, email, employee ID).
305
+
306
+ **How to set:**
307
+
308
+ ```js
309
+ analytics.identify("user123", {
310
+ name: "John Doe",
311
+ email: "john@example.com",
312
+ role: "Sales Associate",
313
+ });
314
+ ```
315
+
316
+ **Behavior:**
317
+
318
+ - Persisted to device storage (`AsyncStorage` key: `metarouter:user_id`)
319
+ - Automatically loaded on app restart
320
+ - Automatically included in **all** subsequent events (`track`, `page`, `screen`, `group`)
321
+ - Remains set until `reset()` is called or app is uninstalled
322
+
323
+ **Example flow:**
324
+
325
+ ```js
326
+ // Day 1: User logs in
327
+ analytics.identify("employeeID", { name: "Jane" });
328
+ analytics.track("Product Viewed", { sku: "ABC123" });
329
+ // Event includes: userId: "employeeID"
330
+
331
+ // App restarts...
332
+
333
+ // Day 2: User opens app
334
+ analytics.track("App Opened");
335
+ // Event STILL includes: userId: "employeeID" (auto-loaded from storage)
336
+ ```
337
+
338
+ #### 2. anonymousId
339
+
340
+ The `anonymousId` is a unique identifier automatically generated for each device/installation before a user is identified.
341
+
342
+ **How it's set:**
343
+
344
+ - **Automatically** generated as a UUID v4 on first SDK initialization
345
+ - No manual action required
346
+
347
+ **Behavior:**
348
+
349
+ - Persisted to device storage (`AsyncStorage` key: `metarouter:anonymous_id`)
350
+ - Automatically loaded on app restart
351
+ - Automatically included in **all** events
352
+ - Remains stable across app sessions until `reset()` is called
353
+ - Cleared on `reset()` and a **new** UUID is generated on next `init()`
354
+
355
+ **Use case:**
356
+ Track user behavior before they log in or create an account, then connect pre-login and post-login activity using the `alias()` method.
357
+
358
+ #### 3. groupId
359
+
360
+ The `groupId` associates a user with an organization, team, account, or other group entity.
361
+
362
+ **How to set:**
363
+
364
+ ```js
365
+ analytics.group("company123", {
366
+ name: "Acme Corp",
367
+ plan: "Enterprise",
368
+ industry: "Technology",
369
+ });
370
+ ```
371
+
372
+ **Behavior:**
373
+
374
+ - Persisted to device storage (`AsyncStorage` key: `metarouter:group_id`)
375
+ - Automatically loaded on app restart
376
+ - Automatically included in **all** subsequent events after being set
377
+ - Remains set until `reset()` is called
378
+
379
+ **Example use case:**
380
+
381
+ ```js
382
+ // User logs into their company account
383
+ analytics.identify("user123", { name: "Jane" });
384
+ analytics.group("acme-corp", { name: "Acme Corp" });
385
+
386
+ // All future events include both userId and groupId
387
+ analytics.track("Report Generated");
388
+ // Event includes: userId: "user123", groupId: "acme-corp"
389
+ ```
390
+
391
+ #### 4. advertisingId (Optional)
392
+
393
+ The `advertisingId` is used for ad tracking and attribution (IDFA on iOS, GAID on Android). See the [Advertising ID](#advertising-id-idfagaid) section below for detailed usage and compliance requirements.
394
+
395
+ ### Persistence Summary
396
+
397
+ | Field | Set By | Storage Key | Auto-Attached | Cleared By |
398
+ | ----------------- | ------------------------ | --------------------------- | -------------------- | ----------------------------------------- |
399
+ | **userId** | `identify(userId)` | `metarouter:user_id` | All events | `reset()` |
400
+ | **anonymousId** | Auto-generated (UUID v4) | `metarouter:anonymous_id` | All events | `reset()` (new ID generated on next init) |
401
+ | **groupId** | `group(groupId)` | `metarouter:group_id` | All events after set | `reset()` |
402
+ | **advertisingId** | `setAdvertisingId(id)` | `metarouter:advertising_id` | Event context | `clearAdvertisingId()`, `reset()` |
403
+
404
+ ### Event Enrichment Flow
405
+
406
+ Every event you send (track, page, screen, group) is automatically enriched with persisted identity information:
407
+
408
+ ```js
409
+ // You call:
410
+ analytics.track("Button Clicked", { buttonName: "Submit" });
411
+
412
+ // SDK automatically adds:
413
+ {
414
+ "type": "track",
415
+ "event": "Button Clicked",
416
+ "properties": { "buttonName": "Submit" },
417
+ "userId": "employeeID", // ← Auto-added from storage
418
+ "anonymousId": "a1b2c3d4-...", // ← Auto-added from storage
419
+ "groupId": "company123", // ← Auto-added from storage (if set)
420
+ "timestamp": "2025-10-23T...",
421
+ "context": {
422
+ "device": {
423
+ "advertisingId": "..." // ← Auto-added from storage (if set)
424
+ }
425
+ }
426
+ }
427
+ ```
428
+
429
+ ### Resetting Identity
430
+
431
+ Call `reset()` to clear **all** identity data, typically when a user logs out:
432
+
433
+ ```js
434
+ await analytics.reset();
435
+ ```
436
+
437
+ **What `reset()` does:**
438
+
439
+ - Clears `userId`, `anonymousId`, `groupId`, and `advertisingId` from memory
440
+ - Removes all identity fields from AsyncStorage
441
+ - Stops background flush loops
442
+ - Clears event queue
443
+ - Next `init()` will generate a **new** `anonymousId`
444
+
445
+ **Common logout flow:**
446
+
447
+ ```js
448
+ // User logs out
449
+ await analytics.reset();
450
+
451
+ // User is now tracked with a new anonymousId (auto-generated on next event)
452
+ // No userId or groupId until they log in again
453
+ ```
454
+
455
+ ### Best Practices
456
+
457
+ 1. **On Login:** Call `identify()` immediately after successful authentication
458
+ 2. **On Logout:** Call `reset()` to clear user identity
459
+ 3. **Cross-Session Tracking:** The SDK handles this automatically - no action needed
460
+ 4. **Group Associations:** Set `groupId` after determining the user's organization/team
461
+ 5. **Pre-Login Tracking:** Events are tracked with `anonymousId` before login
462
+ 6. **Connecting Sessions:** Use `alias()` to connect pre-login and post-login activity
463
+
464
+ ### Example: Complete User Journey
465
+
466
+ ```js
467
+ // App starts - SDK initializes
468
+ const analytics = await createAnalyticsClient({...});
469
+ // anonymousId: "abc-123" (auto-generated and persisted)
470
+
471
+ // User browses before login
472
+ analytics.track("Product Viewed", { sku: "XYZ" });
473
+ // Includes: anonymousId: "abc-123"
474
+
475
+ // User logs in
476
+ analytics.identify("user456", { name: "John", email: "john@example.com" });
477
+ // userId: "user456" is now persisted
478
+
479
+ // User performs actions
480
+ analytics.track("Added to Cart", { sku: "XYZ" });
481
+ // Includes: userId: "user456", anonymousId: "abc-123"
482
+
483
+ // App closes and reopens...
484
+
485
+ // SDK auto-loads userId from storage
486
+ analytics.track("App Reopened");
487
+ // STILL includes: userId: "user456", anonymousId: "abc-123"
488
+
489
+ // User logs out
490
+ await analytics.reset();
491
+ // All IDs cleared, new anonymousId will be generated on next init
492
+ ```
493
+
494
+ ### Storage Location
495
+
496
+ All identity data is stored in **React Native AsyncStorage**, which provides:
497
+
498
+ - Persistent storage across app sessions
499
+ - Automatic data encryption on iOS (Keychain-backed)
500
+ - Secure local storage on Android
501
+ - Cleared only on app uninstall or explicit `reset()` call
502
+
503
+ ## Using the alias() Method
504
+
505
+ The `alias()` method connects an **anonymous user** (tracked by `anonymousId`) to a **known user ID**. It's used to link pre-login activity to post-login identity.
506
+
507
+ ### When to Use alias()
508
+
509
+ Use `alias()` when a user **signs up** or **logs in for the first time**, and you want to connect their pre-login browsing activity to their new account.
510
+
511
+ **Primary use case:** Connecting anonymous browsing sessions to newly created user accounts.
512
+
513
+ ### How It Works
514
+
515
+ ```js
516
+ analytics.alias(newUserId);
517
+ ```
518
+
519
+ This does two things:
520
+
521
+ 1. Sets the new `userId` (same as `identify()`)
522
+ 2. Sends an `alias` event to your analytics backend, telling it: "This anonymousId and this userId are the same person"
523
+
524
+ ### Example: User Sign-Up Flow
525
+
526
+ ```js
527
+ // App starts - user is anonymous
528
+ const analytics = await createAnalyticsClient({...});
529
+ // anonymousId: "abc-123" (auto-generated)
530
+
531
+ // User browses anonymously
532
+ analytics.track("Product Viewed", { productId: "XYZ" });
533
+ analytics.track("Add to Cart", { productId: "XYZ" });
534
+ // Both events tracked with anonymousId: "abc-123"
535
+
536
+ // User creates an account / signs up
537
+ analytics.alias("user-456");
538
+ // Sends alias event connecting: anonymousId "abc-123" → userId "user-456"
539
+
540
+ // Optionally add user traits
541
+ analytics.identify("user-456", {
542
+ name: "John Doe",
543
+ email: "john@example.com"
544
+ });
545
+
546
+ // Future events now tracked as authenticated user
547
+ analytics.track("Purchase Complete", { orderId: "789" });
548
+ // Event includes: userId: "user-456", anonymousId: "abc-123"
549
+ ```
550
+
551
+ ### alias() vs identify()
552
+
553
+ | Method | When to Use | What It Does |
554
+ | ---------------- | --------------------------------------------------------------- | -------------------------------------------------------------- |
555
+ | **`alias()`** | **First-time sign-up/login** when connecting anonymous activity | Sets userId + sends `alias` event to link anonymousId → userId |
556
+ | **`identify()`** | Subsequent logins or updating user traits | Sets userId + sends `identify` event with user traits |
557
+
558
+ ### Best Practices
559
+
560
+ 1. **First-time sign-up:** Call `alias()` to connect anonymous activity to the new account
561
+ 2. **Subsequent logins:** Use `identify()` - no need to alias again
562
+ 3. **Backend support:** Ensure your analytics backend supports alias events for merging user profiles
563
+ 4. **One-time operation:** You typically only need `alias()` once per user - when they first create an account
564
+
565
+ ### Real-World Example: E-Commerce App
566
+
567
+ ```js
568
+ // Day 1: Anonymous browsing
569
+ analytics.track("App Opened");
570
+ analytics.track("Product Viewed", { sku: "SHOE-123" });
571
+ analytics.track("Product Viewed", { sku: "SHIRT-456" });
572
+ // All tracked with anonymousId: "anon-xyz"
573
+
574
+ // User signs up
575
+ analytics.alias("user-789");
576
+ analytics.identify("user-789", {
577
+ name: "Jane Doe",
578
+ email: "jane@example.com",
579
+ });
580
+
581
+ // User continues shopping (now authenticated)
582
+ analytics.track("Added to Cart", { sku: "SHIRT-456" });
583
+ analytics.track("Purchase", { total: 49.99 });
584
+
585
+ // Your analytics platform can now show the complete customer journey:
586
+ // - Pre-signup activity (anonymous product views)
587
+ // - Post-signup activity (cart additions, purchase)
588
+ // - Full conversion funnel from anonymous → identified → converted
589
+ ```
590
+
591
+ ## Advertising ID (IDFA/GAID)
592
+
593
+ The SDK supports including advertising identifiers (IDFA on iOS, GAID on Android) in event context for ad tracking and attribution purposes.
594
+
595
+ ### Usage
596
+
597
+ Use the `setAdvertisingId()` method to set the advertising identifier after initializing the analytics client:
598
+
599
+ ```js
600
+ const analytics = await createAnalyticsClient({
601
+ writeKey: "your-write-key",
602
+ ingestionHost: "https://your-ingestion-endpoint.com",
603
+ });
604
+
605
+ // Set advertising ID after initialization
606
+ await analytics.setAdvertisingId("your-advertising-id"); // IDFA on iOS, GAID on Android
607
+ ```
608
+
609
+ Once set, the `advertisingId` will be automatically included in the device context of all subsequent events:
610
+
611
+ ```json
612
+ {
613
+ "context": {
614
+ "device": {
615
+ "advertisingId": "your-advertising-id",
616
+ "manufacturer": "Apple",
617
+ "model": "iPhone 14",
618
+ ...
619
+ }
620
+ }
621
+ }
622
+ ```
623
+
624
+ ### Privacy & Compliance
625
+
626
+ ⚠️ **Important**: Advertising identifiers are Personally Identifiable Information (PII). Before collecting advertising IDs, you must:
627
+
628
+ 1. **Obtain User Consent**: Request explicit permission from users before tracking
629
+ 2. **Comply with Regulations**: Follow GDPR, CCPA, and other applicable privacy laws
630
+ 3. **App Store Requirements**:
631
+ - iOS: Follow Apple's [App Tracking Transparency (ATT)](https://developer.apple.com/documentation/apptrackingtransparency) framework
632
+ - Android: Follow Google Play's [advertising ID policies](https://support.google.com/googleplay/android-developer/answer/6048248)
633
+
634
+ ### iOS Example (with ATT)
635
+
636
+ > **Note:** The examples below use third-party libraries for demonstration purposes. You should choose appropriate packages that fit your project's needs and are actively maintained.
637
+
638
+ ```js
639
+ import { AppTrackingTransparency } from "react-native-tracking-transparency";
640
+ import { getAdvertisingId } from "@react-native-community/google-advertiser-id"; // or similar library
641
+
642
+ // Initialize analytics first
643
+ const analytics = await createAnalyticsClient({
644
+ writeKey: "your-write-key",
645
+ ingestionHost: "https://your-ingestion-endpoint.com",
646
+ });
647
+
648
+ // Request tracking permission
649
+ const trackingStatus =
650
+ await AppTrackingTransparency.requestTrackingAuthorization();
651
+
652
+ if (trackingStatus === "authorized") {
653
+ // Get and set IDFA only if authorized
654
+ const advertisingId = await getAdvertisingId();
655
+ await analytics.setAdvertisingId(advertisingId);
656
+ }
657
+ ```
658
+
659
+ ### Android Example
660
+
661
+ ```js
662
+ import { getAdvertisingId } from "@react-native-community/google-advertiser-id"; // or similar library
663
+
664
+ // Initialize analytics first
665
+ const analytics = await createAnalyticsClient({
666
+ writeKey: "your-write-key",
667
+ ingestionHost: "https://your-ingestion-endpoint.com",
668
+ });
669
+
670
+ // Check if user has opted out of personalized ads
671
+ const { advertisingId, isLimitAdTrackingEnabled } = await getAdvertisingId();
672
+
673
+ if (!isLimitAdTrackingEnabled && advertisingId) {
674
+ await analytics.setAdvertisingId(advertisingId);
675
+ }
676
+ ```
677
+
678
+ ### Clearing Advertising ID
679
+
680
+ When users opt out of ad tracking or revoke consent, use `clearAdvertisingId()` to remove the advertising ID from storage and context:
681
+
682
+ ```js
683
+ // User opts out of ad tracking
684
+ await analytics.clearAdvertisingId();
685
+
686
+ // All subsequent events will not include advertisingId in context
687
+ analytics.track("Event After Opt Out");
688
+ ```
689
+
690
+ **Note:** The `reset()` method also clears the advertising ID along with all other analytics data.
691
+
692
+ ### Validation
693
+
694
+ The SDK validates advertising IDs before setting them:
695
+
696
+ - Must be a non-empty string
697
+ - Cannot be only whitespace
698
+ - Invalid values are rejected and logged as warnings
699
+
269
700
  ## License
270
701
 
271
702
  MIT
@@ -20,6 +20,7 @@ export declare class MetaRouterAnalyticsClient {
20
20
  private static readonly MAX_QUEUE_SIZE;
21
21
  private maxQueueEvents;
22
22
  private dispatcher;
23
+ private tracingEnabled;
23
24
  /**
24
25
  * Initializes the analytics client with the provided options.
25
26
  * @param options - The initialization options.
@@ -102,6 +103,38 @@ export declare class MetaRouterAnalyticsClient {
102
103
  * @param newUserId - The new user ID to alias to.
103
104
  */
104
105
  alias(newUserId: string): void;
106
+ /**
107
+ * Sets the advertising identifier for ad tracking and attribution.
108
+ * This will update the context for all subsequent events and persist it to storage.
109
+ *
110
+ * ⚠️ Important: Advertising identifiers are Personally Identifiable Information (PII).
111
+ * You must obtain user consent before collecting advertising IDs and comply with
112
+ * GDPR, CCPA, and App Store privacy requirements.
113
+ *
114
+ * @param advertisingId - The advertising identifier (IDFA on iOS, GAID on Android)
115
+ */
116
+ setAdvertisingId(advertisingId: string): Promise<void>;
117
+ /**
118
+ * Clears the advertising identifier from storage and context.
119
+ * Use this method when users opt out of ad tracking or revoke consent.
120
+ *
121
+ * This is useful for GDPR/CCPA compliance when users want to stop sharing
122
+ * their advertising ID without performing a full analytics reset.
123
+ */
124
+ clearAdvertisingId(): Promise<void>;
125
+ /**
126
+ * Enable or disable tracing headers on outgoing requests.
127
+ * When enabled, a "Trace: true" header is included in all API calls to the cluster.
128
+ * This is useful for debugging and troubleshooting request flows.
129
+ *
130
+ * @param enabled - Whether to enable tracing headers
131
+ */
132
+ setTracing(enabled: boolean): void;
133
+ /**
134
+ * Returns whether tracing is currently enabled.
135
+ * @returns True if tracing is enabled
136
+ */
137
+ isTracingEnabled(): boolean;
105
138
  /**
106
139
  * Enable debug logging for troubleshooting
107
140
  */
@@ -123,6 +156,7 @@ export declare class MetaRouterAnalyticsClient {
123
156
  circuitState: import("./utils/circuitBreaker").CircuitState;
124
157
  circuitRemainingMs: number;
125
158
  maxQueueEvents: number;
159
+ tracingEnabled: boolean;
126
160
  }>;
127
161
  /**
128
162
  * Flushes the event queue to the ingestion endpoint in chunks.
@@ -1 +1 @@
1
- {"version":3,"file":"MetaRouterAnalyticsClient.d.ts","sourceRoot":"","sources":["../../src/analytics/MetaRouterAnalyticsClient.ts"],"names":[],"mappings":"AAAA,OAAO,EAA8B,WAAW,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAS7E;;;;;;GAMG;AACH,qBAAa,yBAAyB;IACpC,OAAO,CAAC,SAAS,CAAqB;IACtC,OAAO,CAAC,WAAW,CAA8B;IACjD,OAAO,CAAC,KAAK,CAAsB;IACnC,OAAO,CAAC,oBAAoB,CAAM;IAClC,OAAO,CAAC,aAAa,CAAS;IAC9B,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,OAAO,CAAgB;IAC/B,OAAO,CAAC,QAAQ,CAAyC;IACzD,OAAO,CAAC,oBAAoB,CAAwC;IACpE,OAAO,CAAC,eAAe,CAAkB;IACzC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,cAAc,CAAM;IAC5C,OAAO,CAAC,cAAc,CAAgB;IACtC,OAAO,CAAC,UAAU,CAAc;IAEhC;;;OAGG;gBACS,OAAO,EAAE,WAAW;IA+EhC;;;OAGG;IACU,IAAI;IA+CjB,OAAO,CAAC,QAAQ;IAIhB;;OAEG;IACH,OAAO,CAAC,cAAc;IAItB,OAAO,CAAC,OAAO;IAIf;;;;;;OAMG;YACW,gBAAgB;IAe9B;;;OAGG;IACH,OAAO,CAAC,GAAG;IAIX;;;OAGG;IACH,OAAO,CAAC,OAAO;IAgBf,OAAO,CAAC,eAAe;IAKvB,OAAO,CAAC,aAAa;IAIrB,OAAO,CAAC,cAAc;IAItB;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAO7B;;;OAGG;IACH,OAAO,CAAC,oBAAoB,CAW1B;IAEF;;;;OAIG;IACH,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;IAMrD;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;IAOrD;;;;OAIG;IACH,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;IAWnD;;;;OAIG;IACH,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;IAOnD;;;;OAIG;IACH,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;IAWrD;;;;OAIG;IACH,KAAK,CAAC,SAAS,EAAE,MAAM;IAOvB;;OAEG;IACH,kBAAkB;IAKlB;;OAEG;IACG,YAAY;;;;;;;;;;;;;;;IAmBlB;;;OAGG;IACG,KAAK;IAIX;;OAEG;IACU,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAyBpC"}
1
+ {"version":3,"file":"MetaRouterAnalyticsClient.d.ts","sourceRoot":"","sources":["../../src/analytics/MetaRouterAnalyticsClient.ts"],"names":[],"mappings":"AAAA,OAAO,EAA8B,WAAW,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAU7E;;;;;;GAMG;AACH,qBAAa,yBAAyB;IACpC,OAAO,CAAC,SAAS,CAAqB;IACtC,OAAO,CAAC,WAAW,CAA8B;IACjD,OAAO,CAAC,KAAK,CAAsB;IACnC,OAAO,CAAC,oBAAoB,CAAM;IAClC,OAAO,CAAC,aAAa,CAAS;IAC9B,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,OAAO,CAAgB;IAC/B,OAAO,CAAC,QAAQ,CAAyC;IACzD,OAAO,CAAC,oBAAoB,CAAwC;IACpE,OAAO,CAAC,eAAe,CAAkB;IACzC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,cAAc,CAAM;IAC5C,OAAO,CAAC,cAAc,CAAgB;IACtC,OAAO,CAAC,UAAU,CAAc;IAChC,OAAO,CAAC,cAAc,CAAkB;IAExC;;;OAGG;gBACS,OAAO,EAAE,WAAW;IAgFhC;;;OAGG;IACU,IAAI;IAsDjB,OAAO,CAAC,QAAQ;IAIhB;;OAEG;IACH,OAAO,CAAC,cAAc;IAItB,OAAO,CAAC,OAAO;IAIf;;;;;;OAMG;YACW,gBAAgB;IAe9B;;;OAGG;IACH,OAAO,CAAC,GAAG;IAIX;;;OAGG;IACH,OAAO,CAAC,OAAO;IAgBf,OAAO,CAAC,eAAe;IAKvB,OAAO,CAAC,aAAa;IAIrB,OAAO,CAAC,cAAc;IAItB;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAO7B;;;OAGG;IACH,OAAO,CAAC,oBAAoB,CAW1B;IAEF;;;;OAIG;IACH,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;IAMrD;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;IAOrD;;;;OAIG;IACH,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;IAWnD;;;;OAIG;IACH,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;IAOnD;;;;OAIG;IACH,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;IAWrD;;;;OAIG;IACH,KAAK,CAAC,SAAS,EAAE,MAAM;IAOvB;;;;;;;;;OASG;IACG,gBAAgB,CAAC,aAAa,EAAE,MAAM;IAkB5C;;;;;;OAMG;IACG,kBAAkB;IAaxB;;;;;;OAMG;IACH,UAAU,CAAC,OAAO,EAAE,OAAO;IAK3B;;;OAGG;IACH,gBAAgB,IAAI,OAAO;IAI3B;;OAEG;IACH,kBAAkB;IAKlB;;OAEG;IACG,YAAY;;;;;;;;;;;;;;;;IAoBlB;;;OAGG;IACG,KAAK;IAIX;;OAEG;IACU,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CA4BpC"}
@@ -2,7 +2,8 @@ import { AppState } from "react-native";
2
2
  import { log, setDebugLogging, warn, error } from "./utils/logger";
3
3
  import { IdentityManager } from "./IdentityManager";
4
4
  import { enrichEvent } from "./utils/enrichEvent";
5
- import { getContextInfo } from "./utils/contextInfo";
5
+ import { getContextInfo, clearContextCache } from "./utils/contextInfo";
6
+ import { getIdentityField, setIdentityField, removeIdentityField, ADVERTISING_ID_KEY } from "./utils/identityStorage";
6
7
  import CircuitBreaker from "./utils/circuitBreaker";
7
8
  import Dispatcher from "./dispatcher";
8
9
  /**
@@ -26,6 +27,7 @@ export class MetaRouterAnalyticsClient {
26
27
  this.appState = AppState.currentState;
27
28
  this.appStateSubscription = null;
28
29
  this.maxQueueEvents = 2000;
30
+ this.tracingEnabled = false;
29
31
  /**
30
32
  * Handles the app state change event.
31
33
  * @param nextState - The new app state.
@@ -76,6 +78,7 @@ export class MetaRouterAnalyticsClient {
76
78
  fetchWithTimeout: (url, init, timeoutMs) => this.fetchWithTimeout(url, init, timeoutMs),
77
79
  canSend: () => this.lifecycle === "ready" && !!this.identityManager.getAnonymousId(),
78
80
  isOperational: () => this.lifecycle === "ready",
81
+ isTracingEnabled: () => this.tracingEnabled,
79
82
  createBreaker: () => new CircuitBreaker({
80
83
  failureThreshold: 3,
81
84
  cooldownMs: 10000,
@@ -129,7 +132,12 @@ export class MetaRouterAnalyticsClient {
129
132
  log("Flush loop started with interval:", this.flushIntervalSeconds, "seconds");
130
133
  this.setupAppStateListener();
131
134
  log("App state listener setup completed");
132
- this.context = await getContextInfo();
135
+ // Load persisted advertising ID if available
136
+ const persistedAdvertisingId = await getIdentityField(ADVERTISING_ID_KEY);
137
+ this.context = await getContextInfo(persistedAdvertisingId || undefined);
138
+ if (persistedAdvertisingId) {
139
+ log("Restored advertising ID from storage");
140
+ }
133
141
  this.lifecycle = "ready";
134
142
  log("Analytics client initialization completed successfully");
135
143
  }
@@ -281,6 +289,67 @@ export class MetaRouterAnalyticsClient {
281
289
  this.enqueue({ type: "alias", userId: newUserId, timestamp: this.now() });
282
290
  log("Alias event enqueued, queue length:", this.queue.length);
283
291
  }
292
+ /**
293
+ * Sets the advertising identifier for ad tracking and attribution.
294
+ * This will update the context for all subsequent events and persist it to storage.
295
+ *
296
+ * ⚠️ Important: Advertising identifiers are Personally Identifiable Information (PII).
297
+ * You must obtain user consent before collecting advertising IDs and comply with
298
+ * GDPR, CCPA, and App Store privacy requirements.
299
+ *
300
+ * @param advertisingId - The advertising identifier (IDFA on iOS, GAID on Android)
301
+ */
302
+ async setAdvertisingId(advertisingId) {
303
+ if (!this.isReady()) {
304
+ warn("Analytics client is not ready. Call init() before setAdvertisingId()");
305
+ return;
306
+ }
307
+ if (!advertisingId || typeof advertisingId !== 'string' || advertisingId.trim() === '') {
308
+ warn("Invalid advertising ID provided. Must be a non-empty string.");
309
+ return;
310
+ }
311
+ log("Setting advertising ID");
312
+ await setIdentityField(ADVERTISING_ID_KEY, advertisingId);
313
+ clearContextCache();
314
+ this.context = await getContextInfo(advertisingId);
315
+ log("Advertising ID updated, persisted, and context refreshed");
316
+ }
317
+ /**
318
+ * Clears the advertising identifier from storage and context.
319
+ * Use this method when users opt out of ad tracking or revoke consent.
320
+ *
321
+ * This is useful for GDPR/CCPA compliance when users want to stop sharing
322
+ * their advertising ID without performing a full analytics reset.
323
+ */
324
+ async clearAdvertisingId() {
325
+ if (!this.isReady()) {
326
+ warn("Analytics client is not ready. Call init() before clearAdvertisingId()");
327
+ return;
328
+ }
329
+ log("Clearing advertising ID");
330
+ await removeIdentityField(ADVERTISING_ID_KEY);
331
+ clearContextCache();
332
+ this.context = await getContextInfo();
333
+ log("Advertising ID cleared from storage and context");
334
+ }
335
+ /**
336
+ * Enable or disable tracing headers on outgoing requests.
337
+ * When enabled, a "Trace: true" header is included in all API calls to the cluster.
338
+ * This is useful for debugging and troubleshooting request flows.
339
+ *
340
+ * @param enabled - Whether to enable tracing headers
341
+ */
342
+ setTracing(enabled) {
343
+ log(`Tracing ${enabled ? 'enabled' : 'disabled'}`);
344
+ this.tracingEnabled = enabled;
345
+ }
346
+ /**
347
+ * Returns whether tracing is currently enabled.
348
+ * @returns True if tracing is enabled
349
+ */
350
+ isTracingEnabled() {
351
+ return this.tracingEnabled;
352
+ }
284
353
  /**
285
354
  * Enable debug logging for troubleshooting
286
355
  */
@@ -307,6 +376,7 @@ export class MetaRouterAnalyticsClient {
307
376
  circuitState: d.circuitState,
308
377
  circuitRemainingMs: d.circuitRemainingMs,
309
378
  maxQueueEvents: d.maxQueueEvents,
379
+ tracingEnabled: this.tracingEnabled,
310
380
  };
311
381
  }
312
382
  /**
@@ -331,6 +401,8 @@ export class MetaRouterAnalyticsClient {
331
401
  this.dispatcher.reset();
332
402
  // Clear identity (must remove persisted IDs)
333
403
  await this.identityManager.reset();
404
+ // Clear advertising ID from storage
405
+ await removeIdentityField(ADVERTISING_ID_KEY);
334
406
  // Allow a clean future init
335
407
  this.initPromise = null;
336
408
  // Back to idle: explicit init required
@@ -10,6 +10,7 @@ export interface DispatcherOptions {
10
10
  fetchWithTimeout: (url: string, init: RequestInit, timeoutMs: number) => Promise<Response>;
11
11
  canSend: () => boolean;
12
12
  isOperational: () => boolean;
13
+ isTracingEnabled: () => boolean;
13
14
  createBreaker: () => CircuitBreaker;
14
15
  log: (...args: any[]) => void;
15
16
  warn: (...args: any[]) => void;
@@ -1 +1 @@
1
- {"version":3,"file":"dispatcher.d.ts","sourceRoot":"","sources":["../../src/analytics/dispatcher.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAC5C,OAAO,KAAK,cAAc,MAAM,wBAAwB,CAAC;AAEzD,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,MAAM,GAAG,WAAW,CAAC;AAE3D,MAAM,WAAW,iBAAiB;IAChC,cAAc,EAAE,MAAM,CAAC;IACvB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,YAAY,EAAE,MAAM,CAAC;IACrB,oBAAoB,EAAE,MAAM,CAAC;IAE7B,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;IACnC,gBAAgB,EAAE,CAChB,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,WAAW,EACjB,SAAS,EAAE,MAAM,KACd,OAAO,CAAC,QAAQ,CAAC,CAAC;IACvB,OAAO,EAAE,MAAM,OAAO,CAAC;IACvB,aAAa,EAAE,MAAM,OAAO,CAAC;IAC7B,aAAa,EAAE,MAAM,cAAc,CAAC;IAEpC,GAAG,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,CAAC;IAC9B,IAAI,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,CAAC;IAC/B,KAAK,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,CAAC;IAEhC,iBAAiB,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;IACzC,aAAa,CAAC,EAAE,MAAM,IAAI,CAAC;CAC5B;AAED,MAAM,CAAC,OAAO,OAAO,UAAU;IAC7B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAoB;IACzC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAsB;IAC5C,OAAO,CAAC,UAAU,CAA+B;IACjD,OAAO,CAAC,SAAS,CAA+B;IAChD,OAAO,CAAC,eAAe,CAAuB;IAC9C,OAAO,CAAC,aAAa,CAA8B;IACnD,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,OAAO,CAAiB;gBAEpB,IAAI,EAAE,iBAAiB;IAMnC,WAAW,IAAI,YAAY,EAAE;IAI7B,KAAK,IAAI,IAAI;IAQb,IAAI,IAAI,IAAI;IAQZ,KAAK,IAAI,IAAI;IAOb,OAAO,CAAC,cAAc;IAQtB,eAAe,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAejC,OAAO,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI;IAuBlC,OAAO,CAAC,UAAU;IAUlB,OAAO,CAAC,eAAe;IAQjB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAkJ5B,YAAY;;;;;;;;;;CAYb"}
1
+ {"version":3,"file":"dispatcher.d.ts","sourceRoot":"","sources":["../../src/analytics/dispatcher.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAC5C,OAAO,KAAK,cAAc,MAAM,wBAAwB,CAAC;AAEzD,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,MAAM,GAAG,WAAW,CAAC;AAE3D,MAAM,WAAW,iBAAiB;IAChC,cAAc,EAAE,MAAM,CAAC;IACvB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,YAAY,EAAE,MAAM,CAAC;IACrB,oBAAoB,EAAE,MAAM,CAAC;IAE7B,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;IACnC,gBAAgB,EAAE,CAChB,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,WAAW,EACjB,SAAS,EAAE,MAAM,KACd,OAAO,CAAC,QAAQ,CAAC,CAAC;IACvB,OAAO,EAAE,MAAM,OAAO,CAAC;IACvB,aAAa,EAAE,MAAM,OAAO,CAAC;IAC7B,gBAAgB,EAAE,MAAM,OAAO,CAAC;IAChC,aAAa,EAAE,MAAM,cAAc,CAAC;IAEpC,GAAG,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,CAAC;IAC9B,IAAI,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,CAAC;IAC/B,KAAK,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,CAAC;IAEhC,iBAAiB,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;IACzC,aAAa,CAAC,EAAE,MAAM,IAAI,CAAC;CAC5B;AAED,MAAM,CAAC,OAAO,OAAO,UAAU;IAC7B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAoB;IACzC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAsB;IAC5C,OAAO,CAAC,UAAU,CAA+B;IACjD,OAAO,CAAC,SAAS,CAA+B;IAChD,OAAO,CAAC,eAAe,CAAuB;IAC9C,OAAO,CAAC,aAAa,CAA8B;IACnD,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,OAAO,CAAiB;gBAEpB,IAAI,EAAE,iBAAiB;IAMnC,WAAW,IAAI,YAAY,EAAE;IAI7B,KAAK,IAAI,IAAI;IAQb,IAAI,IAAI,IAAI;IAQZ,KAAK,IAAI,IAAI;IAOb,OAAO,CAAC,cAAc;IAQtB,eAAe,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAejC,OAAO,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI;IAuBlC,OAAO,CAAC,UAAU;IAUlB,OAAO,CAAC,eAAe;IAQjB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IA2J5B,YAAY;;;;;;;;;;CAYb"}
@@ -106,9 +106,15 @@ export default class Dispatcher {
106
106
  const chunk = this.drainBatch();
107
107
  try {
108
108
  this.opts.log("Making API call to:", this.opts.endpoint("/v1/batch"));
109
+ const headers = {
110
+ "Content-Type": "application/json"
111
+ };
112
+ if (this.opts.isTracingEnabled()) {
113
+ headers["Trace"] = "true";
114
+ }
109
115
  const res = await this.opts.fetchWithTimeout(this.opts.endpoint("/v1/batch"), {
110
116
  method: "POST",
111
- headers: { "Content-Type": "application/json" },
117
+ headers,
112
118
  body: JSON.stringify({ batch: chunk }),
113
119
  }, 8000);
114
120
  if (!res.ok) {
@@ -1 +1 @@
1
- {"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../src/analytics/init.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAK/D,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,WAAW,GACnB,kBAAkB,CAyBpB"}
1
+ {"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../src/analytics/init.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAK/D,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,WAAW,GACnB,kBAAkB,CA4BpB"}
@@ -14,6 +14,9 @@ export function createAnalyticsClient(options) {
14
14
  screen: (name, props) => instance.screen(name, props),
15
15
  page: (name, props) => instance.page(name, props),
16
16
  alias: (newUserId) => instance.alias(newUserId),
17
+ setAdvertisingId: (advertisingId) => instance.setAdvertisingId(advertisingId),
18
+ clearAdvertisingId: () => instance.clearAdvertisingId(),
19
+ setTracing: (enabled) => instance.setTracing(enabled),
17
20
  enableDebugLogging: () => instance.enableDebugLogging(),
18
21
  getDebugInfo: () => instance.getDebugInfo(),
19
22
  flush: () => instance.flush(),
@@ -1 +1 @@
1
- {"version":3,"file":"proxyClient.d.ts","sourceRoot":"","sources":["../../../src/analytics/proxy/proxyClient.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AA4InD,eAAO,MAAM,WAAW,EAAE,kBAYzB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,kBAAkB,GAAG,IAAI,EACjC,IAAI,CAAC,EAAE;IAAE,WAAW,CAAC,EAAE,OAAO,CAAA;CAAE,QAqBjC"}
1
+ {"version":3,"file":"proxyClient.d.ts","sourceRoot":"","sources":["../../../src/analytics/proxy/proxyClient.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AA8InD,eAAO,MAAM,WAAW,EAAE,kBAezB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,kBAAkB,GAAG,IAAI,EACjC,IAAI,CAAC,EAAE;IAAE,WAAW,CAAC,EAAE,OAAO,CAAA;CAAE,QAqBjC"}
@@ -4,6 +4,8 @@ let realClient = null;
4
4
  const ASYNC_METHODS = {
5
5
  flush: true,
6
6
  getDebugInfo: true,
7
+ setAdvertisingId: true,
8
+ clearAdvertisingId: true,
7
9
  };
8
10
  const isAsyncMethod = (m) => ASYNC_METHODS[m] === true;
9
11
  // One in-flight flush at a time
@@ -111,6 +113,9 @@ export const proxyClient = {
111
113
  screen: (name, props) => handleMethodCall("screen", name, props),
112
114
  page: (name, props) => handleMethodCall("page", name, props),
113
115
  alias: (newUserId) => handleMethodCall("alias", newUserId),
116
+ setAdvertisingId: (advertisingId) => handleMethodCall("setAdvertisingId", advertisingId),
117
+ clearAdvertisingId: () => handleMethodCall("clearAdvertisingId"),
118
+ setTracing: (enabled) => handleMethodCall("setTracing", enabled),
114
119
  flush: () => handleMethodCall("flush"),
115
120
  reset: () => handleMethodCall("reset"),
116
121
  enableDebugLogging: () => handleMethodCall("enableDebugLogging"),
@@ -31,6 +31,9 @@ export interface AnalyticsInterface {
31
31
  screen: (name: string, props?: Record<string, any>) => void;
32
32
  page: (name: string, props?: Record<string, any>) => void;
33
33
  alias: (newUserId: string) => void;
34
+ setAdvertisingId: (advertisingId: string) => Promise<void>;
35
+ clearAdvertisingId: () => Promise<void>;
36
+ setTracing: (enabled: boolean) => void;
34
37
  flush: () => Promise<void>;
35
38
  reset: () => Promise<void>;
36
39
  enableDebugLogging: () => void;
@@ -48,6 +51,7 @@ export interface EventContext {
48
51
  model: string;
49
52
  name: string;
50
53
  type: string;
54
+ advertisingId?: string;
51
55
  };
52
56
  library: {
53
57
  name: string;
@@ -1 +1 @@
1
- {"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/analytics/types.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/analytics/types.ts"],"names":[],"mappings":"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"}
@@ -1,4 +1,8 @@
1
1
  import { EventContext } from "../types";
2
+ /**
3
+ * Clears the cached context information, forcing a refresh on the next getContextInfo call.
4
+ */
5
+ export declare function clearContextCache(): void;
2
6
  /**
3
7
  * Gathers and caches device, app, and environment context information for analytics events.
4
8
  *
@@ -7,7 +11,8 @@ import { EventContext } from "../types";
7
11
  * - Caches the result for the lifetime of the app to avoid redundant async calls.
8
12
  * - Returns a context object suitable for event enrichment.
9
13
  *
14
+ * @param advertisingId - Optional advertising identifier (IDFA on iOS, GAID on Android) for ad tracking and attribution.
10
15
  * @returns {Promise<EventContext>} A promise that resolves to the context information object.
11
16
  */
12
- export declare function getContextInfo(): Promise<EventContext>;
17
+ export declare function getContextInfo(advertisingId?: string): Promise<EventContext>;
13
18
  //# sourceMappingURL=contextInfo.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"contextInfo.d.ts","sourceRoot":"","sources":["../../../src/analytics/utils/contextInfo.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAWxC;;;;;;;;;GASG;AACH,wBAAsB,cAAc,IAAI,OAAO,CAAC,YAAY,CAAC,CAqD5D"}
1
+ {"version":3,"file":"contextInfo.d.ts","sourceRoot":"","sources":["../../../src/analytics/utils/contextInfo.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAYxC;;GAEG;AACH,wBAAgB,iBAAiB,IAAI,IAAI,CAGxC;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,cAAc,CAAC,aAAa,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAyDlF"}
@@ -2,6 +2,7 @@ import { Dimensions, PixelRatio, Platform } from "react-native";
2
2
  import { getTimeZone } from "./timezone";
3
3
  import pkg from "../../../package.json";
4
4
  let cachedContext = null;
5
+ let cachedAdvertisingId = undefined;
5
6
  let DeviceInfo = null;
6
7
  try {
7
8
  DeviceInfo = require("react-native-device-info");
@@ -9,6 +10,13 @@ try {
9
10
  catch {
10
11
  DeviceInfo = null;
11
12
  }
13
+ /**
14
+ * Clears the cached context information, forcing a refresh on the next getContextInfo call.
15
+ */
16
+ export function clearContextCache() {
17
+ cachedContext = null;
18
+ cachedAdvertisingId = undefined;
19
+ }
12
20
  /**
13
21
  * Gathers and caches device, app, and environment context information for analytics events.
14
22
  *
@@ -17,11 +25,13 @@ catch {
17
25
  * - Caches the result for the lifetime of the app to avoid redundant async calls.
18
26
  * - Returns a context object suitable for event enrichment.
19
27
  *
28
+ * @param advertisingId - Optional advertising identifier (IDFA on iOS, GAID on Android) for ad tracking and attribution.
20
29
  * @returns {Promise<EventContext>} A promise that resolves to the context information object.
21
30
  */
22
- export async function getContextInfo() {
31
+ export async function getContextInfo(advertisingId) {
23
32
  var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q, _r, _s, _t, _u, _v, _w, _x, _y, _z;
24
- if (cachedContext)
33
+ // Return cached context only if it exists AND the advertising ID hasn't changed
34
+ if (cachedContext && cachedAdvertisingId === advertisingId)
25
35
  return cachedContext;
26
36
  let locale = "en-US";
27
37
  if (typeof Intl !== "undefined" &&
@@ -43,6 +53,7 @@ export async function getContextInfo() {
43
53
  model: (_f = (_e = DeviceInfo === null || DeviceInfo === void 0 ? void 0 : DeviceInfo.getModel) === null || _e === void 0 ? void 0 : _e.call(DeviceInfo)) !== null && _f !== void 0 ? _f : "unknown",
44
54
  name: (_h = (await ((_g = DeviceInfo === null || DeviceInfo === void 0 ? void 0 : DeviceInfo.getDeviceName) === null || _g === void 0 ? void 0 : _g.call(DeviceInfo)))) !== null && _h !== void 0 ? _h : "unknown",
45
55
  type: ((_j = DeviceInfo === null || DeviceInfo === void 0 ? void 0 : DeviceInfo.getSystemName) === null || _j === void 0 ? void 0 : _j.call(DeviceInfo)) === "Android" ? "android" : "ios",
56
+ ...(advertisingId ? { advertisingId } : {}),
46
57
  },
47
58
  os: {
48
59
  name: (_l = (_k = DeviceInfo === null || DeviceInfo === void 0 ? void 0 : DeviceInfo.getSystemName) === null || _k === void 0 ? void 0 : _k.call(DeviceInfo)) !== null && _l !== void 0 ? _l : "unknown",
@@ -67,5 +78,6 @@ export async function getContextInfo() {
67
78
  }
68
79
  : {}),
69
80
  };
81
+ cachedAdvertisingId = advertisingId;
70
82
  return cachedContext;
71
83
  }
@@ -1,6 +1,7 @@
1
1
  export declare const ANONYMOUS_ID_KEY = "metarouter:anonymous_id";
2
2
  export declare const USER_ID_KEY = "metarouter:user_id";
3
3
  export declare const GROUP_ID_KEY = "metarouter:group_id";
4
+ export declare const ADVERTISING_ID_KEY = "metarouter:advertising_id";
4
5
  export declare function getIdentityField(key: string): Promise<string | null>;
5
6
  export declare function setIdentityField(key: string, value: string): Promise<void>;
6
7
  export declare function removeIdentityField(key: string): Promise<void>;
@@ -1 +1 @@
1
- {"version":3,"file":"identityStorage.d.ts","sourceRoot":"","sources":["../../../src/analytics/utils/identityStorage.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,gBAAgB,4BAA4B,CAAC;AAC1D,eAAO,MAAM,WAAW,uBAAuB,CAAC;AAChD,eAAO,MAAM,YAAY,wBAAwB,CAAC;AAElD,wBAAsB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAM1E;AAED,wBAAsB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAMhF;AAED,wBAAsB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAMpE"}
1
+ {"version":3,"file":"identityStorage.d.ts","sourceRoot":"","sources":["../../../src/analytics/utils/identityStorage.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,gBAAgB,4BAA4B,CAAC;AAC1D,eAAO,MAAM,WAAW,uBAAuB,CAAC;AAChD,eAAO,MAAM,YAAY,wBAAwB,CAAC;AAClD,eAAO,MAAM,kBAAkB,8BAA8B,CAAC;AAE9D,wBAAsB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAM1E;AAED,wBAAsB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAMhF;AAED,wBAAsB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAMpE"}
@@ -2,6 +2,7 @@ import AsyncStorage from '@react-native-async-storage/async-storage';
2
2
  export const ANONYMOUS_ID_KEY = 'metarouter:anonymous_id';
3
3
  export const USER_ID_KEY = 'metarouter:user_id';
4
4
  export const GROUP_ID_KEY = 'metarouter:group_id';
5
+ export const ADVERTISING_ID_KEY = 'metarouter:advertising_id';
5
6
  export async function getIdentityField(key) {
6
7
  try {
7
8
  return await AsyncStorage.getItem(key);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@metarouter/react-native-sdk",
3
- "version": "1.3.0",
3
+ "version": "1.5.0",
4
4
  "main": "./lib/index.js",
5
5
  "types": "./lib/index.d.ts",
6
6
  "exports": {