@metarouter/react-native-sdk 1.3.0 → 1.4.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
@@ -158,8 +158,10 @@ The analytics client provides the following methods:
158
158
  - `group(groupId: string, traits?: Record<string, any>)`: Group users
159
159
  - `screen(name: string, properties?: Record<string, any>)`: Track screen views
160
160
  - `alias(newUserId: string)`: Alias user IDs
161
+ - `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
162
+ - `clearAdvertisingId()`: Clear the advertising identifier from storage and context. Useful for GDPR/CCPA compliance when users opt out of ad tracking
161
163
  - `flush()`: Flush events immediately
162
- - `reset()`: Reset analytics state and clear all stored data
164
+ - `reset()`: Reset analytics state and clear all stored data (includes clearing advertising ID)
163
165
  - `enableDebugLogging()`: Enable debug logging
164
166
  - `getDebugInfo()`: Get current debug information
165
167
 
@@ -266,6 +268,113 @@ sentAt semantics: sentAt is stamped when the event is enqueued. If the client is
266
268
  - `anonymousId` is a stable, persisted UUID for the device/user before identify; it does **not** include timestamps.
267
269
  - `messageId` is generated as `<epochMillis>-<uuid>` (e.g., `1734691572843-6f0c7e85-...`) to aid debugging.
268
270
 
271
+ ## Advertising ID (IDFA/GAID)
272
+
273
+ The SDK supports including advertising identifiers (IDFA on iOS, GAID on Android) in event context for ad tracking and attribution purposes.
274
+
275
+ ### Usage
276
+
277
+ Use the `setAdvertisingId()` method to set the advertising identifier after initializing the analytics client:
278
+
279
+ ```js
280
+ const analytics = await createAnalyticsClient({
281
+ writeKey: "your-write-key",
282
+ ingestionHost: "https://your-ingestion-endpoint.com",
283
+ });
284
+
285
+ // Set advertising ID after initialization
286
+ await analytics.setAdvertisingId("your-advertising-id"); // IDFA on iOS, GAID on Android
287
+ ```
288
+
289
+ Once set, the `advertisingId` will be automatically included in the device context of all subsequent events:
290
+
291
+ ```json
292
+ {
293
+ "context": {
294
+ "device": {
295
+ "advertisingId": "your-advertising-id",
296
+ "manufacturer": "Apple",
297
+ "model": "iPhone 14",
298
+ ...
299
+ }
300
+ }
301
+ }
302
+ ```
303
+
304
+ ### Privacy & Compliance
305
+
306
+ ⚠️ **Important**: Advertising identifiers are Personally Identifiable Information (PII). Before collecting advertising IDs, you must:
307
+
308
+ 1. **Obtain User Consent**: Request explicit permission from users before tracking
309
+ 2. **Comply with Regulations**: Follow GDPR, CCPA, and other applicable privacy laws
310
+ 3. **App Store Requirements**:
311
+ - iOS: Follow Apple's [App Tracking Transparency (ATT)](https://developer.apple.com/documentation/apptrackingtransparency) framework
312
+ - Android: Follow Google Play's [advertising ID policies](https://support.google.com/googleplay/android-developer/answer/6048248)
313
+
314
+ ### iOS Example (with ATT)
315
+
316
+ > **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.
317
+
318
+ ```js
319
+ import { AppTrackingTransparency } from 'react-native-tracking-transparency';
320
+ import { getAdvertisingId } from '@react-native-community/google-advertiser-id'; // or similar library
321
+
322
+ // Initialize analytics first
323
+ const analytics = await createAnalyticsClient({
324
+ writeKey: "your-write-key",
325
+ ingestionHost: "https://your-ingestion-endpoint.com",
326
+ });
327
+
328
+ // Request tracking permission
329
+ const trackingStatus = await AppTrackingTransparency.requestTrackingAuthorization();
330
+
331
+ if (trackingStatus === 'authorized') {
332
+ // Get and set IDFA only if authorized
333
+ const advertisingId = await getAdvertisingId();
334
+ await analytics.setAdvertisingId(advertisingId);
335
+ }
336
+ ```
337
+
338
+ ### Android Example
339
+
340
+ ```js
341
+ import { getAdvertisingId } from '@react-native-community/google-advertiser-id'; // or similar library
342
+
343
+ // Initialize analytics first
344
+ const analytics = await createAnalyticsClient({
345
+ writeKey: "your-write-key",
346
+ ingestionHost: "https://your-ingestion-endpoint.com",
347
+ });
348
+
349
+ // Check if user has opted out of personalized ads
350
+ const { advertisingId, isLimitAdTrackingEnabled } = await getAdvertisingId();
351
+
352
+ if (!isLimitAdTrackingEnabled && advertisingId) {
353
+ await analytics.setAdvertisingId(advertisingId);
354
+ }
355
+ ```
356
+
357
+ ### Clearing Advertising ID
358
+
359
+ When users opt out of ad tracking or revoke consent, use `clearAdvertisingId()` to remove the advertising ID from storage and context:
360
+
361
+ ```js
362
+ // User opts out of ad tracking
363
+ await analytics.clearAdvertisingId();
364
+
365
+ // All subsequent events will not include advertisingId in context
366
+ analytics.track("Event After Opt Out");
367
+ ```
368
+
369
+ **Note:** The `reset()` method also clears the advertising ID along with all other analytics data.
370
+
371
+ ### Validation
372
+
373
+ The SDK validates advertising IDs before setting them:
374
+ - Must be a non-empty string
375
+ - Cannot be only whitespace
376
+ - Invalid values are rejected and logged as warnings
377
+
269
378
  ## License
270
379
 
271
380
  MIT
@@ -102,6 +102,25 @@ export declare class MetaRouterAnalyticsClient {
102
102
  * @param newUserId - The new user ID to alias to.
103
103
  */
104
104
  alias(newUserId: string): void;
105
+ /**
106
+ * Sets the advertising identifier for ad tracking and attribution.
107
+ * This will update the context for all subsequent events and persist it to storage.
108
+ *
109
+ * ⚠️ Important: Advertising identifiers are Personally Identifiable Information (PII).
110
+ * You must obtain user consent before collecting advertising IDs and comply with
111
+ * GDPR, CCPA, and App Store privacy requirements.
112
+ *
113
+ * @param advertisingId - The advertising identifier (IDFA on iOS, GAID on Android)
114
+ */
115
+ setAdvertisingId(advertisingId: string): Promise<void>;
116
+ /**
117
+ * Clears the advertising identifier from storage and context.
118
+ * Use this method when users opt out of ad tracking or revoke consent.
119
+ *
120
+ * This is useful for GDPR/CCPA compliance when users want to stop sharing
121
+ * their advertising ID without performing a full analytics reset.
122
+ */
123
+ clearAdvertisingId(): Promise<void>;
105
124
  /**
106
125
  * Enable debug logging for troubleshooting
107
126
  */
@@ -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;IAEhC;;;OAGG;gBACS,OAAO,EAAE,WAAW;IA+EhC;;;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;;OAEG;IACH,kBAAkB;IAKlB;;OAEG;IACG,YAAY;;;;;;;;;;;;;;;IAmBlB;;;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
  /**
@@ -129,7 +130,12 @@ export class MetaRouterAnalyticsClient {
129
130
  log("Flush loop started with interval:", this.flushIntervalSeconds, "seconds");
130
131
  this.setupAppStateListener();
131
132
  log("App state listener setup completed");
132
- this.context = await getContextInfo();
133
+ // Load persisted advertising ID if available
134
+ const persistedAdvertisingId = await getIdentityField(ADVERTISING_ID_KEY);
135
+ this.context = await getContextInfo(persistedAdvertisingId || undefined);
136
+ if (persistedAdvertisingId) {
137
+ log("Restored advertising ID from storage");
138
+ }
133
139
  this.lifecycle = "ready";
134
140
  log("Analytics client initialization completed successfully");
135
141
  }
@@ -281,6 +287,49 @@ export class MetaRouterAnalyticsClient {
281
287
  this.enqueue({ type: "alias", userId: newUserId, timestamp: this.now() });
282
288
  log("Alias event enqueued, queue length:", this.queue.length);
283
289
  }
290
+ /**
291
+ * Sets the advertising identifier for ad tracking and attribution.
292
+ * This will update the context for all subsequent events and persist it to storage.
293
+ *
294
+ * ⚠️ Important: Advertising identifiers are Personally Identifiable Information (PII).
295
+ * You must obtain user consent before collecting advertising IDs and comply with
296
+ * GDPR, CCPA, and App Store privacy requirements.
297
+ *
298
+ * @param advertisingId - The advertising identifier (IDFA on iOS, GAID on Android)
299
+ */
300
+ async setAdvertisingId(advertisingId) {
301
+ if (!this.isReady()) {
302
+ warn("Analytics client is not ready. Call init() before setAdvertisingId()");
303
+ return;
304
+ }
305
+ if (!advertisingId || typeof advertisingId !== 'string' || advertisingId.trim() === '') {
306
+ warn("Invalid advertising ID provided. Must be a non-empty string.");
307
+ return;
308
+ }
309
+ log("Setting advertising ID");
310
+ await setIdentityField(ADVERTISING_ID_KEY, advertisingId);
311
+ clearContextCache();
312
+ this.context = await getContextInfo(advertisingId);
313
+ log("Advertising ID updated, persisted, and context refreshed");
314
+ }
315
+ /**
316
+ * Clears the advertising identifier from storage and context.
317
+ * Use this method when users opt out of ad tracking or revoke consent.
318
+ *
319
+ * This is useful for GDPR/CCPA compliance when users want to stop sharing
320
+ * their advertising ID without performing a full analytics reset.
321
+ */
322
+ async clearAdvertisingId() {
323
+ if (!this.isReady()) {
324
+ warn("Analytics client is not ready. Call init() before clearAdvertisingId()");
325
+ return;
326
+ }
327
+ log("Clearing advertising ID");
328
+ await removeIdentityField(ADVERTISING_ID_KEY);
329
+ clearContextCache();
330
+ this.context = await getContextInfo();
331
+ log("Advertising ID cleared from storage and context");
332
+ }
284
333
  /**
285
334
  * Enable debug logging for troubleshooting
286
335
  */
@@ -331,6 +380,8 @@ export class MetaRouterAnalyticsClient {
331
380
  this.dispatcher.reset();
332
381
  // Clear identity (must remove persisted IDs)
333
382
  await this.identityManager.reset();
383
+ // Clear advertising ID from storage
384
+ await removeIdentityField(ADVERTISING_ID_KEY);
334
385
  // Allow a clean future init
335
386
  this.initPromise = null;
336
387
  // Back to idle: explicit init required
@@ -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,CA2BpB"}
@@ -14,6 +14,8 @@ 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(),
17
19
  enableDebugLogging: () => instance.enableDebugLogging(),
18
20
  getDebugInfo: () => instance.getDebugInfo(),
19
21
  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,kBAczB,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,8 @@ 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"),
114
118
  flush: () => handleMethodCall("flush"),
115
119
  reset: () => handleMethodCall("reset"),
116
120
  enableDebugLogging: () => handleMethodCall("enableDebugLogging"),
@@ -31,6 +31,8 @@ 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>;
34
36
  flush: () => Promise<void>;
35
37
  reset: () => Promise<void>;
36
38
  enableDebugLogging: () => void;
@@ -48,6 +50,7 @@ export interface EventContext {
48
50
  model: string;
49
51
  name: string;
50
52
  type: string;
53
+ advertisingId?: string;
51
54
  };
52
55
  library: {
53
56
  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.4.0",
4
4
  "main": "./lib/index.js",
5
5
  "types": "./lib/index.d.ts",
6
6
  "exports": {