@tolinku/react-native-sdk 0.7.1 → 0.8.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.mts CHANGED
@@ -10,6 +10,20 @@ interface TolinkuConfig {
10
10
  debug?: boolean;
11
11
  /** Request timeout in milliseconds. Defaults to 30000 (30 seconds). */
12
12
  timeout?: number;
13
+ /**
14
+ * Report incoming links automatically, instead of calling trackLinkOpen by
15
+ * hand. Defaults to false.
16
+ *
17
+ * Off by default because a reported open is billed as a click. Turning this
18
+ * on by upgrading would raise somebody's bill without them asking, so it is
19
+ * a decision the app makes rather than one a release makes for it.
20
+ *
21
+ * Covers both ways a link arrives on React Native, the cold start and the
22
+ * listener, which is the pair that is easy to get half right by hand. It does
23
+ * not cover the open after a deferred install: only your app knows that it
24
+ * just claimed a link, so that one is still reported explicitly.
25
+ */
26
+ autoTrackLinkOpens?: boolean;
13
27
  }
14
28
  /** Resolved configuration with all defaults applied */
15
29
  interface ResolvedTolinkuConfig {
@@ -101,6 +115,15 @@ interface LeaderboardEntry {
101
115
  interface DeferredLink {
102
116
  deep_link_path: string;
103
117
  appspace_id: string;
118
+ /**
119
+ * The absolute URL for this link, for reporting the open that follows.
120
+ *
121
+ * Reporting an open needs the whole URL, not the path: the host is how the
122
+ * server finds the Appspace and the only thing proving the link belongs to
123
+ * it, and the device has no way to know it. Absent from servers older than
124
+ * this field, so treat it as optional.
125
+ */
126
+ url?: string;
104
127
  referrer_id?: string;
105
128
  referral_code?: string;
106
129
  }
@@ -450,7 +473,7 @@ declare class Links {
450
473
  * await Tolinku.track('signup', { source: 'onboarding' });
451
474
  */
452
475
  declare class Tolinku {
453
- static readonly VERSION = "0.7.1";
476
+ static readonly VERSION = "0.8.1";
454
477
  private static client;
455
478
  private static analyticsInstance;
456
479
  private static ecommerceInstance;
@@ -474,7 +497,28 @@ declare class Tolinku {
474
497
  * moving off it is a one-line change rather than a surprise.
475
498
  */
476
499
  static configure(config: TolinkuConfig): void;
500
+ /**
501
+ * Removes the automatic link listener, when one was installed.
502
+ *
503
+ * Held here rather than inside Analytics because it is a property of this
504
+ * configuration: destroy() has to take it back down or a reconfigured SDK
505
+ * reports every link twice.
506
+ */
507
+ private static linkSubscription;
477
508
  static init(config: TolinkuConfig): void;
509
+ /**
510
+ * Report incoming links without the app wiring anything.
511
+ *
512
+ * A link arrives in two places and both need reporting: one that launches the
513
+ * app cold arrives at getInitialURL, one tapped while it is already running
514
+ * arrives at the listener. Instrumenting only the second is the common
515
+ * mistake, because it works in every test done by hand with the app open.
516
+ *
517
+ * Both are wired, and the same link arriving at both inside a few seconds is
518
+ * reported once: trackLinkOpen drops a repeat of the same URL, which is why
519
+ * covering both here is safe rather than double counting.
520
+ */
521
+ private static startAutoLinkTracking;
478
522
  /** Check whether the SDK has been initialized. */
479
523
  static isConfigured(): boolean;
480
524
  /**
@@ -523,7 +567,7 @@ declare class Tolinku {
523
567
  *
524
568
  * Never throws.
525
569
  */
526
- static trackLinkOpen(url: string): Promise<void>;
570
+ static trackLinkOpen(url: string, deferred?: boolean): Promise<void>;
527
571
  /**
528
572
  * Immediately flush all queued analytics and ecommerce events to the server.
529
573
  */
package/dist/index.d.ts CHANGED
@@ -10,6 +10,20 @@ interface TolinkuConfig {
10
10
  debug?: boolean;
11
11
  /** Request timeout in milliseconds. Defaults to 30000 (30 seconds). */
12
12
  timeout?: number;
13
+ /**
14
+ * Report incoming links automatically, instead of calling trackLinkOpen by
15
+ * hand. Defaults to false.
16
+ *
17
+ * Off by default because a reported open is billed as a click. Turning this
18
+ * on by upgrading would raise somebody's bill without them asking, so it is
19
+ * a decision the app makes rather than one a release makes for it.
20
+ *
21
+ * Covers both ways a link arrives on React Native, the cold start and the
22
+ * listener, which is the pair that is easy to get half right by hand. It does
23
+ * not cover the open after a deferred install: only your app knows that it
24
+ * just claimed a link, so that one is still reported explicitly.
25
+ */
26
+ autoTrackLinkOpens?: boolean;
13
27
  }
14
28
  /** Resolved configuration with all defaults applied */
15
29
  interface ResolvedTolinkuConfig {
@@ -101,6 +115,15 @@ interface LeaderboardEntry {
101
115
  interface DeferredLink {
102
116
  deep_link_path: string;
103
117
  appspace_id: string;
118
+ /**
119
+ * The absolute URL for this link, for reporting the open that follows.
120
+ *
121
+ * Reporting an open needs the whole URL, not the path: the host is how the
122
+ * server finds the Appspace and the only thing proving the link belongs to
123
+ * it, and the device has no way to know it. Absent from servers older than
124
+ * this field, so treat it as optional.
125
+ */
126
+ url?: string;
104
127
  referrer_id?: string;
105
128
  referral_code?: string;
106
129
  }
@@ -450,7 +473,7 @@ declare class Links {
450
473
  * await Tolinku.track('signup', { source: 'onboarding' });
451
474
  */
452
475
  declare class Tolinku {
453
- static readonly VERSION = "0.7.1";
476
+ static readonly VERSION = "0.8.1";
454
477
  private static client;
455
478
  private static analyticsInstance;
456
479
  private static ecommerceInstance;
@@ -474,7 +497,28 @@ declare class Tolinku {
474
497
  * moving off it is a one-line change rather than a surprise.
475
498
  */
476
499
  static configure(config: TolinkuConfig): void;
500
+ /**
501
+ * Removes the automatic link listener, when one was installed.
502
+ *
503
+ * Held here rather than inside Analytics because it is a property of this
504
+ * configuration: destroy() has to take it back down or a reconfigured SDK
505
+ * reports every link twice.
506
+ */
507
+ private static linkSubscription;
477
508
  static init(config: TolinkuConfig): void;
509
+ /**
510
+ * Report incoming links without the app wiring anything.
511
+ *
512
+ * A link arrives in two places and both need reporting: one that launches the
513
+ * app cold arrives at getInitialURL, one tapped while it is already running
514
+ * arrives at the listener. Instrumenting only the second is the common
515
+ * mistake, because it works in every test done by hand with the app open.
516
+ *
517
+ * Both are wired, and the same link arriving at both inside a few seconds is
518
+ * reported once: trackLinkOpen drops a repeat of the same URL, which is why
519
+ * covering both here is safe rather than double counting.
520
+ */
521
+ private static startAutoLinkTracking;
478
522
  /** Check whether the SDK has been initialized. */
479
523
  static isConfigured(): boolean;
480
524
  /**
@@ -523,7 +567,7 @@ declare class Tolinku {
523
567
  *
524
568
  * Never throws.
525
569
  */
526
- static trackLinkOpen(url: string): Promise<void>;
570
+ static trackLinkOpen(url: string, deferred?: boolean): Promise<void>;
527
571
  /**
528
572
  * Immediately flush all queued analytics and ecommerce events to the server.
529
573
  */
package/dist/index.js CHANGED
@@ -10,8 +10,10 @@ function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
10
10
  var AsyncStorage__default = /*#__PURE__*/_interopDefault(AsyncStorage);
11
11
  var React__default = /*#__PURE__*/_interopDefault(React);
12
12
 
13
+ // src/Tolinku.ts
14
+
13
15
  // src/types.ts
14
- var SDK_VERSION = "0.7.1";
16
+ var SDK_VERSION = "0.8.1";
15
17
 
16
18
  // src/debug.ts
17
19
  var _debugEnabled = false;
@@ -331,6 +333,16 @@ var _Analytics = class _Analytics {
331
333
  */
332
334
  this.lastOpenUrl = null;
333
335
  this.lastOpenAt = 0;
336
+ /**
337
+ * Part of the key, not carried alongside it. An ordinary open and a deferred
338
+ * one are different events on the server and only the app can tell them
339
+ * apart, so a deferred report just after an ordinary one for the same link is
340
+ * new information rather than a repeat. Keyed on the URL alone, somebody who
341
+ * tapped a link, installed, then tapped it again would have the deferred
342
+ * report swallowed, losing the last stage of the install funnel in the one
343
+ * case it exists to show.
344
+ */
345
+ this.lastOpenDeferred = false;
334
346
  this.handleAppStateChange = (state) => {
335
347
  if (state === "background" || state === "inactive") {
336
348
  this.flush().catch(() => {
@@ -358,15 +370,16 @@ var _Analytics = class _Analytics {
358
370
  * Never throws. This runs on the path that routes the user somewhere, and a
359
371
  * tap that goes unrecorded is not worth interrupting that.
360
372
  */
361
- async trackLinkOpen(url, userId) {
373
+ async trackLinkOpen(url, userId, deferred = false) {
362
374
  if (this.appOpensDisabled) return;
363
375
  const trimmed = typeof url === "string" ? url.trim() : "";
364
376
  if (!trimmed) return;
365
377
  if (!isSafeUrl(trimmed)) return;
366
378
  const now = Date.now();
367
- if (this.lastOpenUrl === trimmed && now - this.lastOpenAt < _Analytics.OPEN_DEDUPE_MS) return;
379
+ if (this.lastOpenUrl === trimmed && this.lastOpenDeferred === deferred && now - this.lastOpenAt < _Analytics.OPEN_DEDUPE_MS) return;
368
380
  this.lastOpenUrl = trimmed;
369
381
  this.lastOpenAt = now;
382
+ this.lastOpenDeferred = deferred;
370
383
  try {
371
384
  const result = await this.client.postPublic(
372
385
  "/v1/api/opens",
@@ -376,6 +389,12 @@ var _Analytics = class _Analytics {
376
389
  // identifies itself the same way on both. Without it an app open has
377
390
  // no platform and lands in a blank bucket on every breakdown.
378
391
  platform: reactNative.Platform.OS === "ios" || reactNative.Platform.OS === "android" ? reactNative.Platform.OS : void 0,
392
+ // Whether this open followed a deferred install. Only the app knows.
393
+ // An ordinary open is somebody who already had the app and can never
394
+ // convert to an install; an open after a deferred claim is the last
395
+ // stage of the install funnel. The server records them as different
396
+ // events and must not pool them.
397
+ ...deferred ? { deferred: true } : {},
379
398
  ...userId ? { user_id: userId } : {}
380
399
  }
381
400
  );
@@ -1062,8 +1081,30 @@ var _Tolinku = class _Tolinku {
1062
1081
  _Tolinku.deferredInstance = new Deferred(_Tolinku.client);
1063
1082
  _Tolinku.linksInstance = new Links(_Tolinku.client);
1064
1083
  _Tolinku._initialized = true;
1084
+ if (config.autoTrackLinkOpens === true) _Tolinku.startAutoLinkTracking();
1065
1085
  debugLog(`Tolinku SDK v${SDK_VERSION} initialized (baseUrl=${baseUrl})`);
1066
1086
  }
1087
+ /**
1088
+ * Report incoming links without the app wiring anything.
1089
+ *
1090
+ * A link arrives in two places and both need reporting: one that launches the
1091
+ * app cold arrives at getInitialURL, one tapped while it is already running
1092
+ * arrives at the listener. Instrumenting only the second is the common
1093
+ * mistake, because it works in every test done by hand with the app open.
1094
+ *
1095
+ * Both are wired, and the same link arriving at both inside a few seconds is
1096
+ * reported once: trackLinkOpen drops a repeat of the same URL, which is why
1097
+ * covering both here is safe rather than double counting.
1098
+ */
1099
+ static startAutoLinkTracking() {
1100
+ reactNative.Linking.getInitialURL().then((url) => {
1101
+ if (url) void _Tolinku.trackLinkOpen(url);
1102
+ }).catch(() => {
1103
+ });
1104
+ _Tolinku.linkSubscription = reactNative.Linking.addEventListener("url", ({ url }) => {
1105
+ if (url) void _Tolinku.trackLinkOpen(url);
1106
+ });
1107
+ }
1067
1108
  /** Check whether the SDK has been initialized. */
1068
1109
  static isConfigured() {
1069
1110
  return _Tolinku._initialized;
@@ -1129,9 +1170,9 @@ var _Tolinku = class _Tolinku {
1129
1170
  *
1130
1171
  * Never throws.
1131
1172
  */
1132
- static async trackLinkOpen(url) {
1173
+ static async trackLinkOpen(url, deferred = false) {
1133
1174
  if (!_Tolinku.analyticsInstance) return;
1134
- return _Tolinku.analyticsInstance.trackLinkOpen(url, _Tolinku._userId ?? void 0);
1175
+ return _Tolinku.analyticsInstance.trackLinkOpen(url, _Tolinku._userId ?? void 0, deferred);
1135
1176
  }
1136
1177
  /**
1137
1178
  * Immediately flush all queued analytics and ecommerce events to the server.
@@ -1196,6 +1237,10 @@ var _Tolinku = class _Tolinku {
1196
1237
  _Tolinku.client.abort();
1197
1238
  }
1198
1239
  resetStorageNamespace();
1240
+ if (_Tolinku.linkSubscription) {
1241
+ _Tolinku.linkSubscription.remove();
1242
+ _Tolinku.linkSubscription = null;
1243
+ }
1199
1244
  _Tolinku.client = null;
1200
1245
  _Tolinku.analyticsInstance = null;
1201
1246
  _Tolinku.ecommerceInstance = null;
@@ -1216,6 +1261,14 @@ _Tolinku.deferredInstance = null;
1216
1261
  _Tolinku.linksInstance = null;
1217
1262
  _Tolinku._initialized = false;
1218
1263
  _Tolinku._userId = null;
1264
+ /**
1265
+ * Removes the automatic link listener, when one was installed.
1266
+ *
1267
+ * Held here rather than inside Analytics because it is a property of this
1268
+ * configuration: destroy() has to take it back down or a reconfigured SDK
1269
+ * reports every link twice.
1270
+ */
1271
+ _Tolinku.linkSubscription = null;
1219
1272
  var Tolinku = _Tolinku;
1220
1273
  var DEFAULT_IMAGE_HEIGHT = 200;
1221
1274
  function dimension(raw) {