@tolinku/react-native-sdk 0.3.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/dist/index.mjs CHANGED
@@ -1,10 +1,10 @@
1
- import { StyleSheet, AppState, Dimensions, Platform, PixelRatio, Modal, Pressable, TouchableOpacity, Text, ScrollView, View, ImageBackground, Image, Linking } from 'react-native';
1
+ import { StyleSheet, Platform, NativeModules, AppState, Dimensions, PixelRatio, Modal, Pressable, TouchableOpacity, Text, ScrollView, View, ImageBackground, Image, Linking } from 'react-native';
2
2
  import AsyncStorage from '@react-native-async-storage/async-storage';
3
3
  import { useState, useRef, useMemo, useEffect, useCallback } from 'react';
4
4
  import { jsx, Fragment, jsxs } from 'react/jsx-runtime';
5
5
 
6
6
  // src/types.ts
7
- var SDK_VERSION = "0.1.0";
7
+ var SDK_VERSION = "0.5.0";
8
8
 
9
9
  // src/debug.ts
10
10
  var _debugEnabled = false;
@@ -247,12 +247,33 @@ function validateEventType(eventType) {
247
247
  var BATCH_SIZE = 10;
248
248
  var FLUSH_INTERVAL_MS = 5e3;
249
249
  var MAX_QUEUE_SIZE = 1e3;
250
- var Analytics = class {
250
+ var _Analytics = class _Analytics {
251
251
  constructor(client) {
252
252
  this.queue = [];
253
253
  this.flushTimer = null;
254
254
  this.appStateSubscription = null;
255
255
  this.isFlushing = false;
256
+ /**
257
+ * Track a custom event. The event is added to the internal queue
258
+ * and will be flushed automatically or when flush() is called.
259
+ *
260
+ * Event type must match /^custom\.[a-z0-9_]+$/.
261
+ * Auto-prefixes with "custom." if missing.
262
+ */
263
+ /**
264
+ * Set once the server says this Appspace does not attribute app opens, so the
265
+ * setting costs one request a launch rather than one per link.
266
+ */
267
+ this.appOpensDisabled = false;
268
+ /**
269
+ * The last link reported, and when. Cold start and the link stream can both
270
+ * deliver the same tap, depending on the plugin, so an app instrumenting both
271
+ * paths would otherwise report it twice and be billed twice. A genuine second
272
+ * tap of the same link inside this window is implausible; a duplicate delivery
273
+ * of one tap is not.
274
+ */
275
+ this.lastOpenUrl = null;
276
+ this.lastOpenAt = 0;
256
277
  this.handleAppStateChange = (state) => {
257
278
  if (state === "background" || state === "inactive") {
258
279
  this.flush().catch(() => {
@@ -266,12 +287,51 @@ var Analytics = class {
266
287
  );
267
288
  }
268
289
  /**
269
- * Track a custom event. The event is added to the internal queue
270
- * and will be flushed automatically or when flush() is called.
290
+ * Report that a link opened the app without the browser being involved.
271
291
  *
272
- * Event type must match /^custom\.[a-z0-9_]+$/.
273
- * Auto-prefixes with "custom." if missing.
292
+ * A Universal Link or App Link hands the app the URL directly, so Tolinku is
293
+ * never contacted and the tap goes unrecorded. Those taps come from people who
294
+ * already have the app, so leaving them out makes a re-engagement campaign
295
+ * look like a failure exactly when it worked.
296
+ *
297
+ * Only http and https links are reported. A custom scheme means Tolinku's own
298
+ * hand-off page opened the app, and that tap was counted when the page was
299
+ * served, so passing one does nothing rather than counting it twice.
300
+ *
301
+ * Never throws. This runs on the path that routes the user somewhere, and a
302
+ * tap that goes unrecorded is not worth interrupting that.
274
303
  */
304
+ async trackLinkOpen(url, userId) {
305
+ if (this.appOpensDisabled) return;
306
+ const trimmed = typeof url === "string" ? url.trim() : "";
307
+ if (!trimmed) return;
308
+ let parsed;
309
+ try {
310
+ parsed = new URL(trimmed);
311
+ } catch {
312
+ return;
313
+ }
314
+ if (parsed.protocol !== "http:" && parsed.protocol !== "https:") return;
315
+ const now = Date.now();
316
+ if (this.lastOpenUrl === trimmed && now - this.lastOpenAt < _Analytics.OPEN_DEDUPE_MS) return;
317
+ this.lastOpenUrl = trimmed;
318
+ this.lastOpenAt = now;
319
+ try {
320
+ const result = await this.client.postPublic(
321
+ "/v1/api/opens",
322
+ {
323
+ url: trimmed,
324
+ // The User-Agent cannot say which platform this is: this SDK
325
+ // identifies itself the same way on both. Without it an app open has
326
+ // no platform and lands in a blank bucket on every breakdown.
327
+ platform: Platform.OS === "ios" || Platform.OS === "android" ? Platform.OS : void 0,
328
+ ...userId ? { user_id: userId } : {}
329
+ }
330
+ );
331
+ if (result?.attribute === false) this.appOpensDisabled = true;
332
+ } catch {
333
+ }
334
+ }
275
335
  async track(eventType, properties) {
276
336
  const normalizedType = validateEventType(eventType);
277
337
  const event = {
@@ -347,6 +407,8 @@ var Analytics = class {
347
407
  }
348
408
  }
349
409
  };
410
+ _Analytics.OPEN_DEDUPE_MS = 5e3;
411
+ var Analytics = _Analytics;
350
412
  var BATCH_SIZE2 = 10;
351
413
  var FLUSH_INTERVAL_MS2 = 5e3;
352
414
  var MAX_QUEUE_SIZE2 = 500;
@@ -624,58 +686,163 @@ var Referrals = class {
624
686
  });
625
687
  }
626
688
  };
689
+ var TOKEN_KEY = "tolk_token";
690
+ function parseInstallReferrer(referrer) {
691
+ if (!referrer || !referrer.trim()) return null;
692
+ let decoded = referrer;
693
+ try {
694
+ decoded = decodeURIComponent(referrer);
695
+ } catch {
696
+ }
697
+ const pair = decoded.split("&").map((p) => p.trim()).find((p) => p.startsWith(`${TOKEN_KEY}=`));
698
+ if (!pair) return null;
699
+ const token = pair.slice(TOKEN_KEY.length + 1);
700
+ return token.trim() ? token : null;
701
+ }
702
+ function nativeProvider() {
703
+ const native = NativeModules?.TolinkuInstallReferrer;
704
+ if (!native || typeof native.getInstallReferrer !== "function") return null;
705
+ return () => native.getInstallReferrer();
706
+ }
707
+ async function getInstallReferrerToken(provider) {
708
+ if (Platform.OS !== "android") return null;
709
+ const source = provider ?? nativeProvider();
710
+ if (!source) return null;
711
+ try {
712
+ const referrer = await source();
713
+ return parseInstallReferrer(referrer);
714
+ } catch (err) {
715
+ debugWarn(`Install referrer lookup failed: ${err.message}`);
716
+ return null;
717
+ }
718
+ }
719
+
720
+ // src/deferred.ts
721
+ var CLAIMED_KEY = "tolinku_deferred_claimed";
627
722
  var Deferred = class {
628
723
  constructor(client) {
629
724
  this.client = client;
630
725
  }
631
726
  /** Claim a deferred deep link by referrer token (from Play Store referrer or clipboard) */
632
- async claimByToken(token) {
727
+ async claimByToken(token, appspaceId) {
633
728
  if (!token || !token.trim()) {
634
729
  throw new Error("Tolinku: token is required and must not be blank for claimByToken.");
635
730
  }
636
731
  try {
637
- return await this.client.getPublic("/v1/api/deferred/claim", { token });
732
+ return await this.client.getPublic("/v1/api/deferred/claim", {
733
+ token,
734
+ ...appspaceId ? { appspace_id: appspaceId } : {}
735
+ });
638
736
  } catch (err) {
639
737
  debugWarn(`Deferred claimByToken failed: ${err.message}`);
640
738
  return null;
641
739
  }
642
740
  }
741
+ /**
742
+ * Recover the link that led to this install, trying both mechanisms.
743
+ *
744
+ * The Play Install Referrer is asked first on Android: it names the exact
745
+ * click, survives for days, and does not care which network the device was
746
+ * on. Device signals are the fallback, and the only option on iOS, where no
747
+ * equivalent exists.
748
+ *
749
+ * Call once on first launch. Safe to call again, but a claim is consumed the
750
+ * first time it succeeds, so a second call returns null.
751
+ *
752
+ * Reading the referrer needs a native Play Services binding, which this
753
+ * package deliberately does not bundle. Pass `referrerProvider`, or install a
754
+ * supported referrer package and it is used automatically. Without either,
755
+ * Android falls back to signal matching.
756
+ */
757
+ async claimDeferredLink(options) {
758
+ if (!options.appspaceId || !options.appspaceId.trim()) {
759
+ throw new Error("Tolinku: appspaceId is required and must not be blank for claimDeferredLink.");
760
+ }
761
+ if (!options.force && await this.alreadyAttempted()) return null;
762
+ const token = await getInstallReferrerToken(options.referrerProvider);
763
+ if (token) {
764
+ const byToken = await this.claimByToken(token, options.appspaceId).catch(() => null);
765
+ if (byToken) {
766
+ await this.rememberAttempt();
767
+ return byToken;
768
+ }
769
+ }
770
+ const { link, settled } = await this.attemptSignals({ appspaceId: options.appspaceId });
771
+ if (settled) await this.rememberAttempt();
772
+ return link;
773
+ }
774
+ async alreadyAttempted() {
775
+ try {
776
+ return await AsyncStorage.getItem(CLAIMED_KEY) !== null;
777
+ } catch {
778
+ return false;
779
+ }
780
+ }
781
+ async rememberAttempt() {
782
+ try {
783
+ await AsyncStorage.setItem(CLAIMED_KEY, (/* @__PURE__ */ new Date()).toISOString());
784
+ } catch {
785
+ }
786
+ }
643
787
  /** Claim a deferred deep link by device signal matching */
644
788
  async claimBySignals(options) {
645
789
  if (!options.appspaceId || !options.appspaceId.trim()) {
646
790
  throw new Error("Tolinku: appspaceId is required and must not be blank for claimBySignals.");
647
791
  }
792
+ return (await this.attemptSignals(options)).link;
793
+ }
794
+ /**
795
+ * The signal claim, with whether the server actually answered.
796
+ *
797
+ * `settled` separates "nothing is waiting for this device", which no amount
798
+ * of asking will change, from "the request never got there". Both surface as
799
+ * null to callers of claimBySignals, but claimDeferredLink has to tell them
800
+ * apart: recording an attempt that never reached the server would spend an
801
+ * install's one chance at attribution on a dropped connection.
802
+ */
803
+ async attemptSignals(options) {
648
804
  try {
649
805
  const { width, height } = Dimensions.get("screen");
650
- const resolvedTimezone = options.timezone || Intl.DateTimeFormat().resolvedOptions().timeZone;
651
- const resolvedLanguage = options.language || (typeof Intl !== "undefined" && typeof Intl.DateTimeFormat === "function" ? Intl.DateTimeFormat().resolvedOptions().locale : void 0) || "en";
652
- return await this.client.postPublic("/v1/api/deferred/claim-by-signals", {
806
+ const resolvedTimezone = override(options.timezone) || Intl.DateTimeFormat().resolvedOptions().timeZone;
807
+ const resolvedLanguage = override(options.language) || (typeof Intl !== "undefined" && typeof Intl.DateTimeFormat === "function" ? Intl.DateTimeFormat().resolvedOptions().locale : void 0) || "en";
808
+ const link = await this.client.postPublic("/v1/api/deferred/claim-by-signals", {
653
809
  appspace_id: options.appspaceId,
654
810
  timezone: resolvedTimezone,
655
811
  language: resolvedLanguage,
656
- screen_width: options.screenWidth || width,
657
- screen_height: options.screenHeight || height,
812
+ screen_width: override(options.screenWidth) || width,
813
+ screen_height: override(options.screenHeight) || height,
658
814
  // Separates devices reporting identical dp dimensions.
659
- device_pixel_ratio: options.devicePixelRatio || PixelRatio.get(),
660
- os_version: options.osVersion || String(Platform.Version)
815
+ device_pixel_ratio: override(options.devicePixelRatio) || PixelRatio.get(),
816
+ os_version: override(options.osVersion) || String(Platform.Version)
661
817
  });
818
+ return { link, settled: true };
662
819
  } catch (err) {
663
820
  const status = err?.statusCode ?? err?.status;
664
821
  if (status === 404) {
665
822
  debugWarn("Deferred claimBySignals: no match for this device.");
666
- return null;
823
+ return { link: null, settled: true };
667
824
  }
668
825
  if (status === 403) {
669
826
  console.warn(
670
827
  `[Tolinku] claimBySignals failed with HTTP 403. Check that appspaceId is your Appspace ID (copy it from the dashboard under Settings), not your subdomain or slug. ${err.message}`
671
828
  );
672
- return null;
829
+ return { link: null, settled: false };
673
830
  }
674
831
  debugWarn(`Deferred claimBySignals failed: ${err.message}`);
675
- return null;
832
+ return { link: null, settled: false };
676
833
  }
677
834
  }
678
835
  };
836
+ function override(value) {
837
+ if (typeof value === "string") {
838
+ const trimmed = value.trim();
839
+ return trimmed === "" ? void 0 : trimmed;
840
+ }
841
+ if (typeof value === "number") {
842
+ return Number.isFinite(value) && value > 0 ? value : void 0;
843
+ }
844
+ return void 0;
845
+ }
679
846
  var BASE_KEY = "tolinku_message_dismissed";
680
847
  var IMPRESSIONS_BASE_KEY = "tolinku_message_impressions";
681
848
  var LAST_SHOWN_BASE_KEY = "tolinku_message_last_shown";
@@ -762,6 +929,17 @@ var _Tolinku = class _Tolinku {
762
929
  * If init() is called a second time without calling destroy() first,
763
930
  * a warning is logged and the existing instance is returned.
764
931
  */
932
+ /**
933
+ * Configure the SDK.
934
+ *
935
+ * The name the Android, iOS and Flutter SDKs use for this. {@link init} does
936
+ * the same thing and still works; it is what this package shipped and
937
+ * breaking it would serve nobody. It is meant for deprecation later, once
938
+ * moving off it is a one-line change rather than a surprise.
939
+ */
940
+ static configure(config) {
941
+ _Tolinku.init(config);
942
+ }
765
943
  static init(config) {
766
944
  if (!config.apiKey) throw new Error("Tolinku: apiKey is required");
767
945
  if (_Tolinku._initialized) {
@@ -825,6 +1003,41 @@ var _Tolinku = class _Tolinku {
825
1003
  const mergedProps = _Tolinku._userId ? { user_id: _Tolinku._userId, ...properties } : properties;
826
1004
  return _Tolinku.analyticsInstance.track(eventType, mergedProps);
827
1005
  }
1006
+ /**
1007
+ * Report that a link opened the app, when it opened without the browser.
1008
+ *
1009
+ * A Universal Link or App Link hands the app the URL directly, so Tolinku is
1010
+ * never contacted and the tap goes unrecorded. Those taps come from people who
1011
+ * already have your app, so leaving them out makes a re-engagement campaign
1012
+ * look like a failure exactly when it worked.
1013
+ *
1014
+ * Both ways a link arrives need it. The listener fires only while the app is
1015
+ * already running, so a link that launched the app cold arrives separately:
1016
+ *
1017
+ * ```ts
1018
+ * // Launched by a link, app was not running.
1019
+ * const initial = await Linking.getInitialURL();
1020
+ * if (initial) Tolinku.trackLinkOpen(initial);
1021
+ *
1022
+ * // Tapped while the app was already open.
1023
+ * Linking.addEventListener('url', ({ url }) => {
1024
+ * Tolinku.trackLinkOpen(url);
1025
+ * // your own routing
1026
+ * });
1027
+ * ```
1028
+ *
1029
+ * Wiring both is safe: the same link arriving twice in quick succession is
1030
+ * reported once.
1031
+ *
1032
+ * Only http and https links are reported. A custom scheme means Tolinku's own
1033
+ * hand-off page opened the app, and that tap is already counted.
1034
+ *
1035
+ * Never throws.
1036
+ */
1037
+ static async trackLinkOpen(url) {
1038
+ if (!_Tolinku.analyticsInstance) return;
1039
+ return _Tolinku.analyticsInstance.trackLinkOpen(url, _Tolinku._userId ?? void 0);
1040
+ }
828
1041
  /**
829
1042
  * Immediately flush all queued analytics and ecommerce events to the server.
830
1043
  */
@@ -959,13 +1172,14 @@ function PuckComponentRenderer({ component, messageId, options }) {
959
1172
  case "Button": {
960
1173
  const handlePress = () => {
961
1174
  const action = props.action || "";
1175
+ if (!action) return;
1176
+ if (!isSafeUrl(action)) {
1177
+ debugWarn(`Button action URL blocked (unsafe protocol): ${action}`);
1178
+ return;
1179
+ }
962
1180
  if (options.onButtonPress) {
963
1181
  options.onButtonPress(action, messageId);
964
- } else if (action) {
965
- if (!isSafeUrl(action)) {
966
- debugWarn(`Button action URL blocked (unsafe protocol): ${action}`);
967
- return;
968
- }
1182
+ } else {
969
1183
  Linking.openURL(action).catch(() => {
970
1184
  });
971
1185
  }
@@ -1196,6 +1410,6 @@ function TolinkuMessages({
1196
1410
  );
1197
1411
  }
1198
1412
 
1199
- export { Tolinku, TolinkuError, TolinkuMessages, isSafeUrl };
1413
+ export { Tolinku, TolinkuError, TolinkuMessages, getInstallReferrerToken, isSafeUrl, parseInstallReferrer };
1200
1414
  //# sourceMappingURL=index.mjs.map
1201
1415
  //# sourceMappingURL=index.mjs.map