@tolinku/react-native-sdk 0.4.0 → 0.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
@@ -211,7 +211,7 @@ The component automatically filters dismissed and suppressed messages, and shows
211
211
  |------|------|-------------|
212
212
  | `trigger` | `string?` | Filter messages by trigger type |
213
213
  | `triggerValue` | `string?` | Match a specific trigger value |
214
- | `onButtonPress` | `(action, messageId) => void` | Called when a message button is pressed |
214
+ | `onButtonPress` | `(action, messageId) => void` | Called when a message button is pressed. Only for `http` and `https` actions; anything else is blocked before this runs |
215
215
  | `onDismiss` | `(messageId) => void` | Called when a message is dismissed |
216
216
 
217
217
  ## Configuration Options
@@ -288,7 +288,7 @@ await Tolinku.destroy();
288
288
  |------|-------------|
289
289
  | `trigger` | Filter messages by trigger type |
290
290
  | `triggerValue` | Match a specific trigger value |
291
- | `onButtonPress` | Callback for button presses |
291
+ | `onButtonPress` | Callback for button presses, for `http` and `https` actions only |
292
292
  | `onDismiss` | Callback for message dismissal |
293
293
 
294
294
  ## Documentation
package/dist/index.d.mts CHANGED
@@ -393,7 +393,7 @@ declare class Deferred {
393
393
  * await Tolinku.track('signup', { source: 'onboarding' });
394
394
  */
395
395
  declare class Tolinku {
396
- static readonly VERSION = "0.4.0";
396
+ static readonly VERSION = "0.5.0";
397
397
  private static client;
398
398
  private static analyticsInstance;
399
399
  private static ecommerceInstance;
@@ -434,6 +434,38 @@ declare class Tolinku {
434
434
  * Events are batched and flushed automatically.
435
435
  */
436
436
  static track(eventType: string, properties?: TrackProperties): Promise<void>;
437
+ /**
438
+ * Report that a link opened the app, when it opened without the browser.
439
+ *
440
+ * A Universal Link or App Link hands the app the URL directly, so Tolinku is
441
+ * never contacted and the tap goes unrecorded. Those taps come from people who
442
+ * already have your app, so leaving them out makes a re-engagement campaign
443
+ * look like a failure exactly when it worked.
444
+ *
445
+ * Both ways a link arrives need it. The listener fires only while the app is
446
+ * already running, so a link that launched the app cold arrives separately:
447
+ *
448
+ * ```ts
449
+ * // Launched by a link, app was not running.
450
+ * const initial = await Linking.getInitialURL();
451
+ * if (initial) Tolinku.trackLinkOpen(initial);
452
+ *
453
+ * // Tapped while the app was already open.
454
+ * Linking.addEventListener('url', ({ url }) => {
455
+ * Tolinku.trackLinkOpen(url);
456
+ * // your own routing
457
+ * });
458
+ * ```
459
+ *
460
+ * Wiring both is safe: the same link arriving twice in quick succession is
461
+ * reported once.
462
+ *
463
+ * Only http and https links are reported. A custom scheme means Tolinku's own
464
+ * hand-off page opened the app, and that tap is already counted.
465
+ *
466
+ * Never throws.
467
+ */
468
+ static trackLinkOpen(url: string): Promise<void>;
437
469
  /**
438
470
  * Immediately flush all queued analytics and ecommerce events to the server.
439
471
  */
package/dist/index.d.ts CHANGED
@@ -393,7 +393,7 @@ declare class Deferred {
393
393
  * await Tolinku.track('signup', { source: 'onboarding' });
394
394
  */
395
395
  declare class Tolinku {
396
- static readonly VERSION = "0.4.0";
396
+ static readonly VERSION = "0.5.0";
397
397
  private static client;
398
398
  private static analyticsInstance;
399
399
  private static ecommerceInstance;
@@ -434,6 +434,38 @@ declare class Tolinku {
434
434
  * Events are batched and flushed automatically.
435
435
  */
436
436
  static track(eventType: string, properties?: TrackProperties): Promise<void>;
437
+ /**
438
+ * Report that a link opened the app, when it opened without the browser.
439
+ *
440
+ * A Universal Link or App Link hands the app the URL directly, so Tolinku is
441
+ * never contacted and the tap goes unrecorded. Those taps come from people who
442
+ * already have your app, so leaving them out makes a re-engagement campaign
443
+ * look like a failure exactly when it worked.
444
+ *
445
+ * Both ways a link arrives need it. The listener fires only while the app is
446
+ * already running, so a link that launched the app cold arrives separately:
447
+ *
448
+ * ```ts
449
+ * // Launched by a link, app was not running.
450
+ * const initial = await Linking.getInitialURL();
451
+ * if (initial) Tolinku.trackLinkOpen(initial);
452
+ *
453
+ * // Tapped while the app was already open.
454
+ * Linking.addEventListener('url', ({ url }) => {
455
+ * Tolinku.trackLinkOpen(url);
456
+ * // your own routing
457
+ * });
458
+ * ```
459
+ *
460
+ * Wiring both is safe: the same link arriving twice in quick succession is
461
+ * reported once.
462
+ *
463
+ * Only http and https links are reported. A custom scheme means Tolinku's own
464
+ * hand-off page opened the app, and that tap is already counted.
465
+ *
466
+ * Never throws.
467
+ */
468
+ static trackLinkOpen(url: string): Promise<void>;
437
469
  /**
438
470
  * Immediately flush all queued analytics and ecommerce events to the server.
439
471
  */
package/dist/index.js CHANGED
@@ -10,7 +10,7 @@ function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
10
10
  var AsyncStorage__default = /*#__PURE__*/_interopDefault(AsyncStorage);
11
11
 
12
12
  // src/types.ts
13
- var SDK_VERSION = "0.4.0";
13
+ var SDK_VERSION = "0.5.0";
14
14
 
15
15
  // src/debug.ts
16
16
  var _debugEnabled = false;
@@ -253,12 +253,33 @@ function validateEventType(eventType) {
253
253
  var BATCH_SIZE = 10;
254
254
  var FLUSH_INTERVAL_MS = 5e3;
255
255
  var MAX_QUEUE_SIZE = 1e3;
256
- var Analytics = class {
256
+ var _Analytics = class _Analytics {
257
257
  constructor(client) {
258
258
  this.queue = [];
259
259
  this.flushTimer = null;
260
260
  this.appStateSubscription = null;
261
261
  this.isFlushing = false;
262
+ /**
263
+ * Track a custom event. The event is added to the internal queue
264
+ * and will be flushed automatically or when flush() is called.
265
+ *
266
+ * Event type must match /^custom\.[a-z0-9_]+$/.
267
+ * Auto-prefixes with "custom." if missing.
268
+ */
269
+ /**
270
+ * Set once the server says this Appspace does not attribute app opens, so the
271
+ * setting costs one request a launch rather than one per link.
272
+ */
273
+ this.appOpensDisabled = false;
274
+ /**
275
+ * The last link reported, and when. Cold start and the link stream can both
276
+ * deliver the same tap, depending on the plugin, so an app instrumenting both
277
+ * paths would otherwise report it twice and be billed twice. A genuine second
278
+ * tap of the same link inside this window is implausible; a duplicate delivery
279
+ * of one tap is not.
280
+ */
281
+ this.lastOpenUrl = null;
282
+ this.lastOpenAt = 0;
262
283
  this.handleAppStateChange = (state) => {
263
284
  if (state === "background" || state === "inactive") {
264
285
  this.flush().catch(() => {
@@ -272,12 +293,51 @@ var Analytics = class {
272
293
  );
273
294
  }
274
295
  /**
275
- * Track a custom event. The event is added to the internal queue
276
- * and will be flushed automatically or when flush() is called.
296
+ * Report that a link opened the app without the browser being involved.
277
297
  *
278
- * Event type must match /^custom\.[a-z0-9_]+$/.
279
- * Auto-prefixes with "custom." if missing.
298
+ * A Universal Link or App Link hands the app the URL directly, so Tolinku is
299
+ * never contacted and the tap goes unrecorded. Those taps come from people who
300
+ * already have the app, so leaving them out makes a re-engagement campaign
301
+ * look like a failure exactly when it worked.
302
+ *
303
+ * Only http and https links are reported. A custom scheme means Tolinku's own
304
+ * hand-off page opened the app, and that tap was counted when the page was
305
+ * served, so passing one does nothing rather than counting it twice.
306
+ *
307
+ * Never throws. This runs on the path that routes the user somewhere, and a
308
+ * tap that goes unrecorded is not worth interrupting that.
280
309
  */
310
+ async trackLinkOpen(url, userId) {
311
+ if (this.appOpensDisabled) return;
312
+ const trimmed = typeof url === "string" ? url.trim() : "";
313
+ if (!trimmed) return;
314
+ let parsed;
315
+ try {
316
+ parsed = new URL(trimmed);
317
+ } catch {
318
+ return;
319
+ }
320
+ if (parsed.protocol !== "http:" && parsed.protocol !== "https:") return;
321
+ const now = Date.now();
322
+ if (this.lastOpenUrl === trimmed && now - this.lastOpenAt < _Analytics.OPEN_DEDUPE_MS) return;
323
+ this.lastOpenUrl = trimmed;
324
+ this.lastOpenAt = now;
325
+ try {
326
+ const result = await this.client.postPublic(
327
+ "/v1/api/opens",
328
+ {
329
+ url: trimmed,
330
+ // The User-Agent cannot say which platform this is: this SDK
331
+ // identifies itself the same way on both. Without it an app open has
332
+ // no platform and lands in a blank bucket on every breakdown.
333
+ platform: reactNative.Platform.OS === "ios" || reactNative.Platform.OS === "android" ? reactNative.Platform.OS : void 0,
334
+ ...userId ? { user_id: userId } : {}
335
+ }
336
+ );
337
+ if (result?.attribute === false) this.appOpensDisabled = true;
338
+ } catch {
339
+ }
340
+ }
281
341
  async track(eventType, properties) {
282
342
  const normalizedType = validateEventType(eventType);
283
343
  const event = {
@@ -353,6 +413,8 @@ var Analytics = class {
353
413
  }
354
414
  }
355
415
  };
416
+ _Analytics.OPEN_DEDUPE_MS = 5e3;
417
+ var Analytics = _Analytics;
356
418
  var BATCH_SIZE2 = 10;
357
419
  var FLUSH_INTERVAL_MS2 = 5e3;
358
420
  var MAX_QUEUE_SIZE2 = 500;
@@ -747,17 +809,17 @@ var Deferred = class {
747
809
  async attemptSignals(options) {
748
810
  try {
749
811
  const { width, height } = reactNative.Dimensions.get("screen");
750
- const resolvedTimezone = options.timezone || Intl.DateTimeFormat().resolvedOptions().timeZone;
751
- const resolvedLanguage = options.language || (typeof Intl !== "undefined" && typeof Intl.DateTimeFormat === "function" ? Intl.DateTimeFormat().resolvedOptions().locale : void 0) || "en";
812
+ const resolvedTimezone = override(options.timezone) || Intl.DateTimeFormat().resolvedOptions().timeZone;
813
+ const resolvedLanguage = override(options.language) || (typeof Intl !== "undefined" && typeof Intl.DateTimeFormat === "function" ? Intl.DateTimeFormat().resolvedOptions().locale : void 0) || "en";
752
814
  const link = await this.client.postPublic("/v1/api/deferred/claim-by-signals", {
753
815
  appspace_id: options.appspaceId,
754
816
  timezone: resolvedTimezone,
755
817
  language: resolvedLanguage,
756
- screen_width: options.screenWidth || width,
757
- screen_height: options.screenHeight || height,
818
+ screen_width: override(options.screenWidth) || width,
819
+ screen_height: override(options.screenHeight) || height,
758
820
  // Separates devices reporting identical dp dimensions.
759
- device_pixel_ratio: options.devicePixelRatio || reactNative.PixelRatio.get(),
760
- os_version: options.osVersion || String(reactNative.Platform.Version)
821
+ device_pixel_ratio: override(options.devicePixelRatio) || reactNative.PixelRatio.get(),
822
+ os_version: override(options.osVersion) || String(reactNative.Platform.Version)
761
823
  });
762
824
  return { link, settled: true };
763
825
  } catch (err) {
@@ -777,6 +839,16 @@ var Deferred = class {
777
839
  }
778
840
  }
779
841
  };
842
+ function override(value) {
843
+ if (typeof value === "string") {
844
+ const trimmed = value.trim();
845
+ return trimmed === "" ? void 0 : trimmed;
846
+ }
847
+ if (typeof value === "number") {
848
+ return Number.isFinite(value) && value > 0 ? value : void 0;
849
+ }
850
+ return void 0;
851
+ }
780
852
  var BASE_KEY = "tolinku_message_dismissed";
781
853
  var IMPRESSIONS_BASE_KEY = "tolinku_message_impressions";
782
854
  var LAST_SHOWN_BASE_KEY = "tolinku_message_last_shown";
@@ -937,6 +1009,41 @@ var _Tolinku = class _Tolinku {
937
1009
  const mergedProps = _Tolinku._userId ? { user_id: _Tolinku._userId, ...properties } : properties;
938
1010
  return _Tolinku.analyticsInstance.track(eventType, mergedProps);
939
1011
  }
1012
+ /**
1013
+ * Report that a link opened the app, when it opened without the browser.
1014
+ *
1015
+ * A Universal Link or App Link hands the app the URL directly, so Tolinku is
1016
+ * never contacted and the tap goes unrecorded. Those taps come from people who
1017
+ * already have your app, so leaving them out makes a re-engagement campaign
1018
+ * look like a failure exactly when it worked.
1019
+ *
1020
+ * Both ways a link arrives need it. The listener fires only while the app is
1021
+ * already running, so a link that launched the app cold arrives separately:
1022
+ *
1023
+ * ```ts
1024
+ * // Launched by a link, app was not running.
1025
+ * const initial = await Linking.getInitialURL();
1026
+ * if (initial) Tolinku.trackLinkOpen(initial);
1027
+ *
1028
+ * // Tapped while the app was already open.
1029
+ * Linking.addEventListener('url', ({ url }) => {
1030
+ * Tolinku.trackLinkOpen(url);
1031
+ * // your own routing
1032
+ * });
1033
+ * ```
1034
+ *
1035
+ * Wiring both is safe: the same link arriving twice in quick succession is
1036
+ * reported once.
1037
+ *
1038
+ * Only http and https links are reported. A custom scheme means Tolinku's own
1039
+ * hand-off page opened the app, and that tap is already counted.
1040
+ *
1041
+ * Never throws.
1042
+ */
1043
+ static async trackLinkOpen(url) {
1044
+ if (!_Tolinku.analyticsInstance) return;
1045
+ return _Tolinku.analyticsInstance.trackLinkOpen(url, _Tolinku._userId ?? void 0);
1046
+ }
940
1047
  /**
941
1048
  * Immediately flush all queued analytics and ecommerce events to the server.
942
1049
  */
@@ -1071,13 +1178,14 @@ function PuckComponentRenderer({ component, messageId, options }) {
1071
1178
  case "Button": {
1072
1179
  const handlePress = () => {
1073
1180
  const action = props.action || "";
1181
+ if (!action) return;
1182
+ if (!isSafeUrl(action)) {
1183
+ debugWarn(`Button action URL blocked (unsafe protocol): ${action}`);
1184
+ return;
1185
+ }
1074
1186
  if (options.onButtonPress) {
1075
1187
  options.onButtonPress(action, messageId);
1076
- } else if (action) {
1077
- if (!isSafeUrl(action)) {
1078
- debugWarn(`Button action URL blocked (unsafe protocol): ${action}`);
1079
- return;
1080
- }
1188
+ } else {
1081
1189
  reactNative.Linking.openURL(action).catch(() => {
1082
1190
  });
1083
1191
  }