@trackstall/sdk 0.1.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 +75 -0
- package/index.d.ts +843 -0
- package/index.js +2734 -0
- package/package.json +53 -0
package/README.md
ADDED
|
@@ -0,0 +1,75 @@
|
|
|
1
|
+
# @trackstall/sdk
|
|
2
|
+
|
|
3
|
+
Client SDK for [TrackStall](https://github.com/trackstall/trackstall) — a self-hosted,
|
|
4
|
+
multi-tenant Mobile Measurement Partner. Works in React Native, plain JS, and web.
|
|
5
|
+
|
|
6
|
+
The SDK sends **clicks**, **install matches**, **install referrers**, **ATT/IDFA**, and
|
|
7
|
+
**attribution events** to the TrackStall backend, which fans them out to Meta CAPI and
|
|
8
|
+
TikTok Events API (server-side) and, optionally, the native Meta/TikTok SDKs (dual-send
|
|
9
|
+
with a shared `eventId` for dedup). It never talks to ad networks directly.
|
|
10
|
+
|
|
11
|
+
This is a **self-contained build**: `@trackstall/core`, `js-sha256`, and `uuid` are inlined.
|
|
12
|
+
The native ad SDKs are optional peers — install only the ones you use.
|
|
13
|
+
|
|
14
|
+
## Install
|
|
15
|
+
|
|
16
|
+
```bash
|
|
17
|
+
npm i @trackstall/sdk
|
|
18
|
+
|
|
19
|
+
# optional native dual-send + ATT/IDFA + Android install referrer
|
|
20
|
+
npm i react-native-fbsdk-next @layers/expo-tiktok-business
|
|
21
|
+
npx expo install expo-tracking-transparency expo-device
|
|
22
|
+
npm i react-native-play-install-referrer
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
## Quick start
|
|
26
|
+
|
|
27
|
+
```ts
|
|
28
|
+
import { createTrackStallClient } from '@trackstall/sdk';
|
|
29
|
+
import { Platform } from 'react-native';
|
|
30
|
+
|
|
31
|
+
export const ts = createTrackStallClient({
|
|
32
|
+
appId: 'your-app-id',
|
|
33
|
+
publicKey: 'tsk_pub_…',
|
|
34
|
+
endpoint: 'https://api.your-trackstall.io',
|
|
35
|
+
platform: Platform.OS, // 'ios' | 'android' | 'web'
|
|
36
|
+
});
|
|
37
|
+
|
|
38
|
+
// 1) boot — once
|
|
39
|
+
await ts.initialize();
|
|
40
|
+
|
|
41
|
+
// 2) iOS: ask ATT early (captures the IDFA automatically when authorized)
|
|
42
|
+
if (Platform.OS === 'ios') await ts.requestAttPermission();
|
|
43
|
+
|
|
44
|
+
// 3) identity — use the SAME id everywhere (e.g. your RevenueCat app_user_id)
|
|
45
|
+
ts.setUser({ userId });
|
|
46
|
+
|
|
47
|
+
// 4) install match — once on first launch
|
|
48
|
+
if (Platform.OS === 'android') {
|
|
49
|
+
await ts.reportInstallReferrer({ referrer }); // from Play Install Referrer API
|
|
50
|
+
} else if (clickToken) {
|
|
51
|
+
await ts.matchInstall({ clickToken }); // iOS web→app deep link
|
|
52
|
+
}
|
|
53
|
+
|
|
54
|
+
// 5) conversions
|
|
55
|
+
await ts.track({
|
|
56
|
+
name: 'subscribe',
|
|
57
|
+
revenue: { grossValue: 9.99, netValue: 6.99, currency: 'USD', store: 'apple', transactionId: 'txn_…' },
|
|
58
|
+
productId: 'pro_weekly',
|
|
59
|
+
});
|
|
60
|
+
|
|
61
|
+
// 6) drain queues when the app backgrounds
|
|
62
|
+
await ts.flush();
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
## Two event lanes
|
|
66
|
+
|
|
67
|
+
- `track()` → **attribution** events (`/v1/events` → Meta CAPI / TikTok EAPI + native dual-send).
|
|
68
|
+
- `logEvent()` → **product analytics** (`/v1/track`), dashboard-only, never forwarded to ad networks.
|
|
69
|
+
|
|
70
|
+
The SDK auto-collects device fingerprint signals (screen/OS/model) and locale/timezone on
|
|
71
|
+
`initialize()`; pass `config.device` to override, or `disableAutoDeviceContext: true` to disable.
|
|
72
|
+
|
|
73
|
+
## License
|
|
74
|
+
|
|
75
|
+
MIT
|