@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/README.md +26 -2
- package/android/build.gradle +74 -0
- package/android/src/main/AndroidManifest.xml +1 -0
- package/android/src/main/java/com/tolinku/rnsdk/TolinkuInstallReferrerModule.java +107 -0
- package/android/src/main/java/com/tolinku/rnsdk/TolinkuInstallReferrerPackage.java +30 -0
- package/dist/index.d.mts +99 -3
- package/dist/index.d.ts +99 -3
- package/dist/index.js +239 -23
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +239 -25
- package/dist/index.mjs.map +1 -1
- package/package.json +4 -2
package/README.md
CHANGED
|
@@ -149,6 +149,30 @@ const link = await Tolinku.deferred.claimBySignals({
|
|
|
149
149
|
});
|
|
150
150
|
```
|
|
151
151
|
|
|
152
|
+
On Android the Play Install Referrer is the deterministic mechanism: a Tolinku
|
|
153
|
+
link attaches a token to the store URL, Play keeps it through the install, and
|
|
154
|
+
this SDK reads it back on first launch. It names the exact click, survives for
|
|
155
|
+
days, and does not depend on the network the device was on. Device signals are
|
|
156
|
+
the fallback, and the only option on iOS, where no equivalent exists.
|
|
157
|
+
|
|
158
|
+
Prefer `claimDeferredLink()` over choosing a mechanism yourself:
|
|
159
|
+
|
|
160
|
+
```ts
|
|
161
|
+
// Referrer first, device signals as the fallback.
|
|
162
|
+
const link = await Tolinku.deferred.claimDeferredLink({
|
|
163
|
+
appspaceId: '64f0a1b2c3d4e5f60718',
|
|
164
|
+
});
|
|
165
|
+
if (link) routeTo(link.deep_link_path);
|
|
166
|
+
```
|
|
167
|
+
|
|
168
|
+
Call it once on first launch. Calling again is safe, but a claim is consumed the
|
|
169
|
+
first time it succeeds, so a second call returns nothing.
|
|
170
|
+
|
|
171
|
+
The Android side is bundled with this package, so there is nothing else to
|
|
172
|
+
install. Autolinking is per-platform, so an iOS-only app never builds it. In
|
|
173
|
+
Expo Go the native module is absent and Android falls back to signal matching;
|
|
174
|
+
a development build gets the referrer.
|
|
175
|
+
|
|
152
176
|
`appspaceId` is your Appspace ID, not your subdomain or slug. Copy it from the dashboard
|
|
153
177
|
under **Integrate** or **Settings**. It looks like `64f0a1b2c3d4e5f60718`.
|
|
154
178
|
|
|
@@ -187,7 +211,7 @@ The component automatically filters dismissed and suppressed messages, and shows
|
|
|
187
211
|
|------|------|-------------|
|
|
188
212
|
| `trigger` | `string?` | Filter messages by trigger type |
|
|
189
213
|
| `triggerValue` | `string?` | Match a specific trigger value |
|
|
190
|
-
| `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 |
|
|
191
215
|
| `onDismiss` | `(messageId) => void` | Called when a message is dismissed |
|
|
192
216
|
|
|
193
217
|
## Configuration Options
|
|
@@ -264,7 +288,7 @@ await Tolinku.destroy();
|
|
|
264
288
|
|------|-------------|
|
|
265
289
|
| `trigger` | Filter messages by trigger type |
|
|
266
290
|
| `triggerValue` | Match a specific trigger value |
|
|
267
|
-
| `onButtonPress` | Callback for button presses |
|
|
291
|
+
| `onButtonPress` | Callback for button presses, for `http` and `https` actions only |
|
|
268
292
|
| `onDismiss` | Callback for message dismissal |
|
|
269
293
|
|
|
270
294
|
## Documentation
|
|
@@ -0,0 +1,74 @@
|
|
|
1
|
+
// Android side of @tolinku/react-native-sdk.
|
|
2
|
+
//
|
|
3
|
+
// Exists only to read the Play Install Referrer, which is the deterministic way
|
|
4
|
+
// a deferred link survives an install on Android. It is bundled rather than
|
|
5
|
+
// delegated to a third-party package because the referrer token is Tolinku's
|
|
6
|
+
// own mechanism: we mint it on the link and read it back here.
|
|
7
|
+
//
|
|
8
|
+
// Autolinking is per-platform, so this is not built when compiling for iOS. An
|
|
9
|
+
// iOS-only app pays nothing for its presence.
|
|
10
|
+
//
|
|
11
|
+
// To verify compilation outside a host app:
|
|
12
|
+
// printf 'rootProject.name = "t"\n' > android/settings.gradle
|
|
13
|
+
// ../../android-sdk/gradlew -p android assembleRelease \
|
|
14
|
+
// -PtolinkuReactAndroidVersion=0.73.11 -Pandroid.useAndroidX=true
|
|
15
|
+
// rm android/settings.gradle
|
|
16
|
+
|
|
17
|
+
buildscript {
|
|
18
|
+
repositories {
|
|
19
|
+
google()
|
|
20
|
+
mavenCentral()
|
|
21
|
+
}
|
|
22
|
+
dependencies {
|
|
23
|
+
classpath("com.android.tools.build:gradle:8.1.4")
|
|
24
|
+
}
|
|
25
|
+
}
|
|
26
|
+
|
|
27
|
+
apply plugin: "com.android.library"
|
|
28
|
+
|
|
29
|
+
def safeExtGet(prop, fallback) {
|
|
30
|
+
rootProject.ext.has(prop) ? rootProject.ext.get(prop) : fallback
|
|
31
|
+
}
|
|
32
|
+
|
|
33
|
+
android {
|
|
34
|
+
// The peer range starts at React Native 0.72, whose AGP 7.4 supports
|
|
35
|
+
// namespace, so the old manifest package attribute is not needed.
|
|
36
|
+
namespace "com.tolinku.rnsdk"
|
|
37
|
+
|
|
38
|
+
compileSdkVersion safeExtGet("compileSdkVersion", 34)
|
|
39
|
+
|
|
40
|
+
defaultConfig {
|
|
41
|
+
// The Install Referrer library needs 21; the host app decides above that.
|
|
42
|
+
minSdkVersion safeExtGet("minSdkVersion", 21)
|
|
43
|
+
targetSdkVersion safeExtGet("targetSdkVersion", 34)
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
compileOptions {
|
|
47
|
+
sourceCompatibility JavaVersion.VERSION_1_8
|
|
48
|
+
targetCompatibility JavaVersion.VERSION_1_8
|
|
49
|
+
}
|
|
50
|
+
|
|
51
|
+
lintOptions {
|
|
52
|
+
abortOnError false
|
|
53
|
+
}
|
|
54
|
+
}
|
|
55
|
+
|
|
56
|
+
repositories {
|
|
57
|
+
google()
|
|
58
|
+
mavenCentral()
|
|
59
|
+
}
|
|
60
|
+
|
|
61
|
+
dependencies {
|
|
62
|
+
// Unversioned on purpose: the React Native Gradle plugin in the host app
|
|
63
|
+
// pins this to whatever version the app is on, so the library follows the
|
|
64
|
+
// app rather than forcing one. A version is supplied only for the standalone
|
|
65
|
+
// build used to verify compilation outside an app.
|
|
66
|
+
def rnVersion = project.findProperty("tolinkuReactAndroidVersion")
|
|
67
|
+
if (rnVersion) {
|
|
68
|
+
implementation "com.facebook.react:react-android:${rnVersion}"
|
|
69
|
+
} else {
|
|
70
|
+
implementation "com.facebook.react:react-android"
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
implementation "com.android.installreferrer:installreferrer:2.2"
|
|
74
|
+
}
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
<manifest xmlns:android="http://schemas.android.com/apk/res/android" />
|
|
@@ -0,0 +1,107 @@
|
|
|
1
|
+
package com.tolinku.rnsdk;
|
|
2
|
+
|
|
3
|
+
import androidx.annotation.NonNull;
|
|
4
|
+
|
|
5
|
+
import com.android.installreferrer.api.InstallReferrerClient;
|
|
6
|
+
import com.android.installreferrer.api.InstallReferrerStateListener;
|
|
7
|
+
import com.facebook.react.bridge.Promise;
|
|
8
|
+
import com.facebook.react.bridge.ReactApplicationContext;
|
|
9
|
+
import com.facebook.react.bridge.ReactContextBaseJavaModule;
|
|
10
|
+
import com.facebook.react.bridge.ReactMethod;
|
|
11
|
+
|
|
12
|
+
import java.util.concurrent.atomic.AtomicBoolean;
|
|
13
|
+
|
|
14
|
+
/**
|
|
15
|
+
* Reads the Play Install Referrer.
|
|
16
|
+
*
|
|
17
|
+
* A Tolinku link sends an Android visitor to the store with
|
|
18
|
+
* {@code referrer=tolk_token=<token>} attached. Play keeps that string through
|
|
19
|
+
* the install and hands it back on first launch, which names the exact click
|
|
20
|
+
* instead of inferring it from device signals.
|
|
21
|
+
*
|
|
22
|
+
* Only the raw referrer string is returned. Finding our token inside it is done
|
|
23
|
+
* in JavaScript, where it is covered by tests that run on every platform rather
|
|
24
|
+
* than only where an Android toolchain exists.
|
|
25
|
+
*/
|
|
26
|
+
public class TolinkuInstallReferrerModule extends ReactContextBaseJavaModule {
|
|
27
|
+
|
|
28
|
+
public static final String NAME = "TolinkuInstallReferrer";
|
|
29
|
+
|
|
30
|
+
public TolinkuInstallReferrerModule(ReactApplicationContext reactContext) {
|
|
31
|
+
super(reactContext);
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
@Override
|
|
35
|
+
@NonNull
|
|
36
|
+
public String getName() {
|
|
37
|
+
return NAME;
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
/**
|
|
41
|
+
* Resolves with the raw referrer string, or null when there is nothing to
|
|
42
|
+
* report.
|
|
43
|
+
*
|
|
44
|
+
* Never rejects. An organic install, a device without Play Services, and a
|
|
45
|
+
* store other than Play are all ordinary outcomes rather than errors, and
|
|
46
|
+
* the caller falls back to signal matching for every one of them. Rejecting
|
|
47
|
+
* would turn a routine absence into an unhandled promise on first launch.
|
|
48
|
+
*/
|
|
49
|
+
@ReactMethod
|
|
50
|
+
public void getInstallReferrer(final Promise promise) {
|
|
51
|
+
final InstallReferrerClient client;
|
|
52
|
+
try {
|
|
53
|
+
client = InstallReferrerClient.newBuilder(getReactApplicationContext()).build();
|
|
54
|
+
} catch (Throwable t) {
|
|
55
|
+
promise.resolve(null);
|
|
56
|
+
return;
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
// The Play listener can fire more than once on some devices, and
|
|
60
|
+
// resolving a promise twice is an error in React Native.
|
|
61
|
+
final AtomicBoolean settled = new AtomicBoolean(false);
|
|
62
|
+
|
|
63
|
+
try {
|
|
64
|
+
client.startConnection(new InstallReferrerStateListener() {
|
|
65
|
+
@Override
|
|
66
|
+
public void onInstallReferrerSetupFinished(int responseCode) {
|
|
67
|
+
if (!settled.compareAndSet(false, true)) {
|
|
68
|
+
return;
|
|
69
|
+
}
|
|
70
|
+
String referrer = null;
|
|
71
|
+
try {
|
|
72
|
+
if (responseCode == InstallReferrerClient.InstallReferrerResponse.OK) {
|
|
73
|
+
referrer = client.getInstallReferrer().getInstallReferrer();
|
|
74
|
+
}
|
|
75
|
+
} catch (Throwable t) {
|
|
76
|
+
referrer = null;
|
|
77
|
+
} finally {
|
|
78
|
+
endQuietly(client);
|
|
79
|
+
}
|
|
80
|
+
promise.resolve(referrer);
|
|
81
|
+
}
|
|
82
|
+
|
|
83
|
+
@Override
|
|
84
|
+
public void onInstallReferrerServiceDisconnected() {
|
|
85
|
+
if (!settled.compareAndSet(false, true)) {
|
|
86
|
+
return;
|
|
87
|
+
}
|
|
88
|
+
endQuietly(client);
|
|
89
|
+
promise.resolve(null);
|
|
90
|
+
}
|
|
91
|
+
});
|
|
92
|
+
} catch (Throwable t) {
|
|
93
|
+
if (settled.compareAndSet(false, true)) {
|
|
94
|
+
endQuietly(client);
|
|
95
|
+
promise.resolve(null);
|
|
96
|
+
}
|
|
97
|
+
}
|
|
98
|
+
}
|
|
99
|
+
|
|
100
|
+
private static void endQuietly(InstallReferrerClient client) {
|
|
101
|
+
try {
|
|
102
|
+
client.endConnection();
|
|
103
|
+
} catch (Throwable ignored) {
|
|
104
|
+
// Already gone.
|
|
105
|
+
}
|
|
106
|
+
}
|
|
107
|
+
}
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
package com.tolinku.rnsdk;
|
|
2
|
+
|
|
3
|
+
import androidx.annotation.NonNull;
|
|
4
|
+
|
|
5
|
+
import com.facebook.react.ReactPackage;
|
|
6
|
+
import com.facebook.react.bridge.NativeModule;
|
|
7
|
+
import com.facebook.react.bridge.ReactApplicationContext;
|
|
8
|
+
import com.facebook.react.uimanager.ViewManager;
|
|
9
|
+
|
|
10
|
+
import java.util.ArrayList;
|
|
11
|
+
import java.util.Collections;
|
|
12
|
+
import java.util.List;
|
|
13
|
+
|
|
14
|
+
/** Registers the install referrer module with React Native's autolinking. */
|
|
15
|
+
public class TolinkuInstallReferrerPackage implements ReactPackage {
|
|
16
|
+
|
|
17
|
+
@Override
|
|
18
|
+
@NonNull
|
|
19
|
+
public List<NativeModule> createNativeModules(@NonNull ReactApplicationContext reactContext) {
|
|
20
|
+
List<NativeModule> modules = new ArrayList<>();
|
|
21
|
+
modules.add(new TolinkuInstallReferrerModule(reactContext));
|
|
22
|
+
return modules;
|
|
23
|
+
}
|
|
24
|
+
|
|
25
|
+
@Override
|
|
26
|
+
@NonNull
|
|
27
|
+
public List<ViewManager> createViewManagers(@NonNull ReactApplicationContext reactContext) {
|
|
28
|
+
return Collections.emptyList();
|
|
29
|
+
}
|
|
30
|
+
}
|
package/dist/index.d.mts
CHANGED
|
@@ -319,13 +319,68 @@ declare class Referrals {
|
|
|
319
319
|
}>;
|
|
320
320
|
}
|
|
321
321
|
|
|
322
|
+
/**
|
|
323
|
+
* Pull our token out of a Play referrer string.
|
|
324
|
+
*
|
|
325
|
+
* The referrer is shared. A developer's own `utm_source` and anything else they
|
|
326
|
+
* attached sit in the same string, so the token is found among the pairs rather
|
|
327
|
+
* than assumed to be the whole value. A percent-encoded `%3D` is tolerated
|
|
328
|
+
* because Play normally decodes it, and that assumption is not worth a lost
|
|
329
|
+
* install if it is ever wrong.
|
|
330
|
+
*/
|
|
331
|
+
declare function parseInstallReferrer(referrer: string | null | undefined): string | null;
|
|
332
|
+
/** Anything that can hand back a Play referrer string. */
|
|
333
|
+
type ReferrerProvider = () => Promise<string | null> | string | null;
|
|
334
|
+
/**
|
|
335
|
+
* Best effort at the referrer token for this install.
|
|
336
|
+
*
|
|
337
|
+
* Android only, and null everywhere else: there is no equivalent on iOS, which
|
|
338
|
+
* is why signal matching exists at all. Never throws, because attribution must
|
|
339
|
+
* not be able to fail a first launch.
|
|
340
|
+
*/
|
|
341
|
+
declare function getInstallReferrerToken(provider?: ReferrerProvider): Promise<string | null>;
|
|
342
|
+
|
|
322
343
|
declare class Deferred {
|
|
323
344
|
private client;
|
|
324
345
|
constructor(client: HttpClient);
|
|
325
346
|
/** Claim a deferred deep link by referrer token (from Play Store referrer or clipboard) */
|
|
326
|
-
claimByToken(token: string): Promise<DeferredLink | null>;
|
|
347
|
+
claimByToken(token: string, appspaceId?: string): Promise<DeferredLink | null>;
|
|
348
|
+
/**
|
|
349
|
+
* Recover the link that led to this install, trying both mechanisms.
|
|
350
|
+
*
|
|
351
|
+
* The Play Install Referrer is asked first on Android: it names the exact
|
|
352
|
+
* click, survives for days, and does not care which network the device was
|
|
353
|
+
* on. Device signals are the fallback, and the only option on iOS, where no
|
|
354
|
+
* equivalent exists.
|
|
355
|
+
*
|
|
356
|
+
* Call once on first launch. Safe to call again, but a claim is consumed the
|
|
357
|
+
* first time it succeeds, so a second call returns null.
|
|
358
|
+
*
|
|
359
|
+
* Reading the referrer needs a native Play Services binding, which this
|
|
360
|
+
* package deliberately does not bundle. Pass `referrerProvider`, or install a
|
|
361
|
+
* supported referrer package and it is used automatically. Without either,
|
|
362
|
+
* Android falls back to signal matching.
|
|
363
|
+
*/
|
|
364
|
+
claimDeferredLink(options: {
|
|
365
|
+
appspaceId: string;
|
|
366
|
+
referrerProvider?: ReferrerProvider;
|
|
367
|
+
/** Claim again even if an attempt was already recorded. For tests. */
|
|
368
|
+
force?: boolean;
|
|
369
|
+
}): Promise<DeferredLink | null>;
|
|
370
|
+
private alreadyAttempted;
|
|
371
|
+
private rememberAttempt;
|
|
327
372
|
/** Claim a deferred deep link by device signal matching */
|
|
328
373
|
claimBySignals(options: ClaimBySignalsOptions): Promise<DeferredLink | null>;
|
|
374
|
+
/**
|
|
375
|
+
* The signal claim, with whether the server actually answered.
|
|
376
|
+
*
|
|
377
|
+
* `settled` separates "nothing is waiting for this device", which no amount
|
|
378
|
+
* of asking will change, from "the request never got there". Both surface as
|
|
379
|
+
* null to callers of claimBySignals, but claimDeferredLink has to tell them
|
|
380
|
+
* apart: recording an attempt that never reached the server would spend an
|
|
381
|
+
* install's one chance at attribution on a dropped connection.
|
|
382
|
+
*/
|
|
383
|
+
private attemptSignals;
|
|
329
384
|
}
|
|
330
385
|
|
|
331
386
|
/**
|
|
@@ -338,7 +393,7 @@ declare class Deferred {
|
|
|
338
393
|
* await Tolinku.track('signup', { source: 'onboarding' });
|
|
339
394
|
*/
|
|
340
395
|
declare class Tolinku {
|
|
341
|
-
static readonly VERSION = "0.
|
|
396
|
+
static readonly VERSION = "0.5.0";
|
|
342
397
|
private static client;
|
|
343
398
|
private static analyticsInstance;
|
|
344
399
|
private static ecommerceInstance;
|
|
@@ -352,6 +407,15 @@ declare class Tolinku {
|
|
|
352
407
|
* If init() is called a second time without calling destroy() first,
|
|
353
408
|
* a warning is logged and the existing instance is returned.
|
|
354
409
|
*/
|
|
410
|
+
/**
|
|
411
|
+
* Configure the SDK.
|
|
412
|
+
*
|
|
413
|
+
* The name the Android, iOS and Flutter SDKs use for this. {@link init} does
|
|
414
|
+
* the same thing and still works; it is what this package shipped and
|
|
415
|
+
* breaking it would serve nobody. It is meant for deprecation later, once
|
|
416
|
+
* moving off it is a one-line change rather than a surprise.
|
|
417
|
+
*/
|
|
418
|
+
static configure(config: TolinkuConfig): void;
|
|
355
419
|
static init(config: TolinkuConfig): void;
|
|
356
420
|
/** Check whether the SDK has been initialized. */
|
|
357
421
|
static isConfigured(): boolean;
|
|
@@ -370,6 +434,38 @@ declare class Tolinku {
|
|
|
370
434
|
* Events are batched and flushed automatically.
|
|
371
435
|
*/
|
|
372
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>;
|
|
373
469
|
/**
|
|
374
470
|
* Immediately flush all queued analytics and ecommerce events to the server.
|
|
375
471
|
*/
|
|
@@ -417,4 +513,4 @@ declare function TolinkuMessages({ trigger, triggerValue, onDismiss, onButtonPre
|
|
|
417
513
|
*/
|
|
418
514
|
declare function isSafeUrl(url: string): boolean;
|
|
419
515
|
|
|
420
|
-
export { type AddPaymentInfoParams, type AddToCartParams, type AddToWishlistParams, type BeginCheckoutParams, type ClaimBySignalsOptions, type CompleteReferralOptions, type CompleteReferralResult, type CreateReferralOptions, type CreateReferralResult, type DeferredLink, type EcommerceItem, type LeaderboardEntry, type Message, type MessageComponent, type MessageContent, type MilestoneOptions, type MilestoneResult, type PurchaseParams, type RateParams, type ReferralInfo, type RefundParams, type RemoveFromCartParams, type ResolvedTolinkuConfig, type SearchParams, type ShareParams, type ShowMessageOptions, type SpendCreditsParams, Tolinku, type TolinkuConfig, TolinkuError, TolinkuMessages, type TrackProperties, type ViewItemParams, isSafeUrl };
|
|
516
|
+
export { type AddPaymentInfoParams, type AddToCartParams, type AddToWishlistParams, type BeginCheckoutParams, type ClaimBySignalsOptions, type CompleteReferralOptions, type CompleteReferralResult, type CreateReferralOptions, type CreateReferralResult, type DeferredLink, type EcommerceItem, type LeaderboardEntry, type Message, type MessageComponent, type MessageContent, type MilestoneOptions, type MilestoneResult, type PurchaseParams, type RateParams, type ReferralInfo, type ReferrerProvider, type RefundParams, type RemoveFromCartParams, type ResolvedTolinkuConfig, type SearchParams, type ShareParams, type ShowMessageOptions, type SpendCreditsParams, Tolinku, type TolinkuConfig, TolinkuError, TolinkuMessages, type TrackProperties, type ViewItemParams, getInstallReferrerToken, isSafeUrl, parseInstallReferrer };
|
package/dist/index.d.ts
CHANGED
|
@@ -319,13 +319,68 @@ declare class Referrals {
|
|
|
319
319
|
}>;
|
|
320
320
|
}
|
|
321
321
|
|
|
322
|
+
/**
|
|
323
|
+
* Pull our token out of a Play referrer string.
|
|
324
|
+
*
|
|
325
|
+
* The referrer is shared. A developer's own `utm_source` and anything else they
|
|
326
|
+
* attached sit in the same string, so the token is found among the pairs rather
|
|
327
|
+
* than assumed to be the whole value. A percent-encoded `%3D` is tolerated
|
|
328
|
+
* because Play normally decodes it, and that assumption is not worth a lost
|
|
329
|
+
* install if it is ever wrong.
|
|
330
|
+
*/
|
|
331
|
+
declare function parseInstallReferrer(referrer: string | null | undefined): string | null;
|
|
332
|
+
/** Anything that can hand back a Play referrer string. */
|
|
333
|
+
type ReferrerProvider = () => Promise<string | null> | string | null;
|
|
334
|
+
/**
|
|
335
|
+
* Best effort at the referrer token for this install.
|
|
336
|
+
*
|
|
337
|
+
* Android only, and null everywhere else: there is no equivalent on iOS, which
|
|
338
|
+
* is why signal matching exists at all. Never throws, because attribution must
|
|
339
|
+
* not be able to fail a first launch.
|
|
340
|
+
*/
|
|
341
|
+
declare function getInstallReferrerToken(provider?: ReferrerProvider): Promise<string | null>;
|
|
342
|
+
|
|
322
343
|
declare class Deferred {
|
|
323
344
|
private client;
|
|
324
345
|
constructor(client: HttpClient);
|
|
325
346
|
/** Claim a deferred deep link by referrer token (from Play Store referrer or clipboard) */
|
|
326
|
-
claimByToken(token: string): Promise<DeferredLink | null>;
|
|
347
|
+
claimByToken(token: string, appspaceId?: string): Promise<DeferredLink | null>;
|
|
348
|
+
/**
|
|
349
|
+
* Recover the link that led to this install, trying both mechanisms.
|
|
350
|
+
*
|
|
351
|
+
* The Play Install Referrer is asked first on Android: it names the exact
|
|
352
|
+
* click, survives for days, and does not care which network the device was
|
|
353
|
+
* on. Device signals are the fallback, and the only option on iOS, where no
|
|
354
|
+
* equivalent exists.
|
|
355
|
+
*
|
|
356
|
+
* Call once on first launch. Safe to call again, but a claim is consumed the
|
|
357
|
+
* first time it succeeds, so a second call returns null.
|
|
358
|
+
*
|
|
359
|
+
* Reading the referrer needs a native Play Services binding, which this
|
|
360
|
+
* package deliberately does not bundle. Pass `referrerProvider`, or install a
|
|
361
|
+
* supported referrer package and it is used automatically. Without either,
|
|
362
|
+
* Android falls back to signal matching.
|
|
363
|
+
*/
|
|
364
|
+
claimDeferredLink(options: {
|
|
365
|
+
appspaceId: string;
|
|
366
|
+
referrerProvider?: ReferrerProvider;
|
|
367
|
+
/** Claim again even if an attempt was already recorded. For tests. */
|
|
368
|
+
force?: boolean;
|
|
369
|
+
}): Promise<DeferredLink | null>;
|
|
370
|
+
private alreadyAttempted;
|
|
371
|
+
private rememberAttempt;
|
|
327
372
|
/** Claim a deferred deep link by device signal matching */
|
|
328
373
|
claimBySignals(options: ClaimBySignalsOptions): Promise<DeferredLink | null>;
|
|
374
|
+
/**
|
|
375
|
+
* The signal claim, with whether the server actually answered.
|
|
376
|
+
*
|
|
377
|
+
* `settled` separates "nothing is waiting for this device", which no amount
|
|
378
|
+
* of asking will change, from "the request never got there". Both surface as
|
|
379
|
+
* null to callers of claimBySignals, but claimDeferredLink has to tell them
|
|
380
|
+
* apart: recording an attempt that never reached the server would spend an
|
|
381
|
+
* install's one chance at attribution on a dropped connection.
|
|
382
|
+
*/
|
|
383
|
+
private attemptSignals;
|
|
329
384
|
}
|
|
330
385
|
|
|
331
386
|
/**
|
|
@@ -338,7 +393,7 @@ declare class Deferred {
|
|
|
338
393
|
* await Tolinku.track('signup', { source: 'onboarding' });
|
|
339
394
|
*/
|
|
340
395
|
declare class Tolinku {
|
|
341
|
-
static readonly VERSION = "0.
|
|
396
|
+
static readonly VERSION = "0.5.0";
|
|
342
397
|
private static client;
|
|
343
398
|
private static analyticsInstance;
|
|
344
399
|
private static ecommerceInstance;
|
|
@@ -352,6 +407,15 @@ declare class Tolinku {
|
|
|
352
407
|
* If init() is called a second time without calling destroy() first,
|
|
353
408
|
* a warning is logged and the existing instance is returned.
|
|
354
409
|
*/
|
|
410
|
+
/**
|
|
411
|
+
* Configure the SDK.
|
|
412
|
+
*
|
|
413
|
+
* The name the Android, iOS and Flutter SDKs use for this. {@link init} does
|
|
414
|
+
* the same thing and still works; it is what this package shipped and
|
|
415
|
+
* breaking it would serve nobody. It is meant for deprecation later, once
|
|
416
|
+
* moving off it is a one-line change rather than a surprise.
|
|
417
|
+
*/
|
|
418
|
+
static configure(config: TolinkuConfig): void;
|
|
355
419
|
static init(config: TolinkuConfig): void;
|
|
356
420
|
/** Check whether the SDK has been initialized. */
|
|
357
421
|
static isConfigured(): boolean;
|
|
@@ -370,6 +434,38 @@ declare class Tolinku {
|
|
|
370
434
|
* Events are batched and flushed automatically.
|
|
371
435
|
*/
|
|
372
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>;
|
|
373
469
|
/**
|
|
374
470
|
* Immediately flush all queued analytics and ecommerce events to the server.
|
|
375
471
|
*/
|
|
@@ -417,4 +513,4 @@ declare function TolinkuMessages({ trigger, triggerValue, onDismiss, onButtonPre
|
|
|
417
513
|
*/
|
|
418
514
|
declare function isSafeUrl(url: string): boolean;
|
|
419
515
|
|
|
420
|
-
export { type AddPaymentInfoParams, type AddToCartParams, type AddToWishlistParams, type BeginCheckoutParams, type ClaimBySignalsOptions, type CompleteReferralOptions, type CompleteReferralResult, type CreateReferralOptions, type CreateReferralResult, type DeferredLink, type EcommerceItem, type LeaderboardEntry, type Message, type MessageComponent, type MessageContent, type MilestoneOptions, type MilestoneResult, type PurchaseParams, type RateParams, type ReferralInfo, type RefundParams, type RemoveFromCartParams, type ResolvedTolinkuConfig, type SearchParams, type ShareParams, type ShowMessageOptions, type SpendCreditsParams, Tolinku, type TolinkuConfig, TolinkuError, TolinkuMessages, type TrackProperties, type ViewItemParams, isSafeUrl };
|
|
516
|
+
export { type AddPaymentInfoParams, type AddToCartParams, type AddToWishlistParams, type BeginCheckoutParams, type ClaimBySignalsOptions, type CompleteReferralOptions, type CompleteReferralResult, type CreateReferralOptions, type CreateReferralResult, type DeferredLink, type EcommerceItem, type LeaderboardEntry, type Message, type MessageComponent, type MessageContent, type MilestoneOptions, type MilestoneResult, type PurchaseParams, type RateParams, type ReferralInfo, type ReferrerProvider, type RefundParams, type RemoveFromCartParams, type ResolvedTolinkuConfig, type SearchParams, type ShareParams, type ShowMessageOptions, type SpendCreditsParams, Tolinku, type TolinkuConfig, TolinkuError, TolinkuMessages, type TrackProperties, type ViewItemParams, getInstallReferrerToken, isSafeUrl, parseInstallReferrer };
|