@layers/react-native 1.1.0 → 1.3.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 +380 -149
- package/dist/TrackingTransparency-CMedp3bh.js +321 -0
- package/dist/TrackingTransparency-CMedp3bh.js.map +1 -0
- package/dist/{att-Hyj9b7AG.d.ts → att-BlUZv4_u.d.ts} +1 -1
- package/dist/{att-Hyj9b7AG.d.ts.map → att-BlUZv4_u.d.ts.map} +1 -1
- package/dist/{att-C5tL1hKX.js → att-DaUoQWpj.js} +2 -2
- package/dist/{att-C5tL1hKX.js.map → att-DaUoQWpj.js.map} +1 -1
- package/dist/att.d.ts +1 -1
- package/dist/att.js +1 -1
- package/dist/chunk-DyChAoct.js +27 -0
- package/dist/index-CSCJSzRS.d.ts +181 -0
- package/dist/index-CSCJSzRS.d.ts.map +1 -0
- package/dist/index.d.ts +4 -4
- package/dist/index.js +4 -4
- package/dist/react.d.ts +3 -3
- package/dist/react.js +3 -3
- package/dist/{skan-_aDXcXWQ.js → skan-DFFAN4wu.js} +2 -2
- package/dist/{skan-_aDXcXWQ.js.map → skan-DFFAN4wu.js.map} +1 -1
- package/dist/{skan-C-RMfcG8.d.ts → skan-DvnRgJo1.d.ts} +1 -1
- package/dist/{skan-C-RMfcG8.d.ts.map → skan-DvnRgJo1.d.ts.map} +1 -1
- package/dist/skan.d.ts +1 -1
- package/dist/skan.js +1 -1
- package/dist/{src-B_57eFbh.js → src-DTBDULvf.js} +258 -11
- package/dist/src-DTBDULvf.js.map +1 -0
- package/package.json +2 -2
- package/dist/chunk-B1JASekH.js +0 -7
- package/dist/index-yowJkVyZ.d.ts +0 -88
- package/dist/index-yowJkVyZ.d.ts.map +0 -1
- package/dist/src-B_57eFbh.js.map +0 -1
package/README.md
CHANGED
|
@@ -1,84 +1,249 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Layers React Native SDK
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
`@layers/react-native` is the Layers analytics SDK for React Native apps. It provides event tracking, screen tracking, user identification, App Tracking Transparency (ATT), SKAdNetwork (SKAN), deep link handling, clipboard-based deferred deep links, consent management, and automatic lifecycle and connectivity handling.
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
Use this package for **bare React Native** projects. For **Expo managed workflow** projects, use [`@layers/expo`](https://www.npmjs.com/package/@layers/expo) instead.
|
|
6
|
+
|
|
7
|
+
## Requirements
|
|
8
|
+
|
|
9
|
+
- React Native 0.70.0+
|
|
10
|
+
- React 18.0+
|
|
11
|
+
- iOS 14.0+ / Android API 21+
|
|
12
|
+
|
|
13
|
+
## Installation
|
|
6
14
|
|
|
7
15
|
```bash
|
|
8
16
|
npm install @layers/react-native
|
|
9
17
|
# or
|
|
10
|
-
|
|
18
|
+
yarn add @layers/react-native
|
|
11
19
|
```
|
|
12
20
|
|
|
13
|
-
### Peer Dependencies
|
|
14
|
-
|
|
15
|
-
| Package | Required | What degrades without it |
|
|
16
|
-
| ------------------------------------------- | -------- | ----------------------------------------------------- |
|
|
17
|
-
| `react` | Yes | -- |
|
|
18
|
-
| `react-native` | Yes | -- |
|
|
19
|
-
| `@react-native-async-storage/async-storage` | Optional | Events are only persisted in memory; lost on app kill |
|
|
20
|
-
| `@react-native-community/netinfo` | Optional | SDK assumes always-online; no offline queueing |
|
|
21
|
+
### Recommended Peer Dependencies
|
|
21
22
|
|
|
22
23
|
```bash
|
|
23
24
|
npm install @react-native-async-storage/async-storage @react-native-community/netinfo
|
|
24
25
|
```
|
|
25
26
|
|
|
27
|
+
These are optional but strongly recommended:
|
|
28
|
+
|
|
29
|
+
- **@react-native-async-storage/async-storage** (>=1.21.0) -- Enables persistent event storage across app restarts. Without it, events are stored in memory only.
|
|
30
|
+
- **@react-native-community/netinfo** (>=11.0.0) -- Enables automatic flush when the device reconnects to the network.
|
|
31
|
+
- **@react-native-clipboard/clipboard** (>=1.13.0) -- Enables clipboard attribution for iOS deferred deep links.
|
|
32
|
+
|
|
33
|
+
### iOS Setup
|
|
34
|
+
|
|
35
|
+
```bash
|
|
36
|
+
cd ios && pod install
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
Add `NSUserTrackingUsageDescription` to your `Info.plist` if you plan to use ATT.
|
|
40
|
+
|
|
26
41
|
## Quick Start
|
|
27
42
|
|
|
28
|
-
```
|
|
43
|
+
```typescript
|
|
29
44
|
import { LayersReactNative } from '@layers/react-native';
|
|
30
45
|
|
|
46
|
+
// Create and initialize
|
|
31
47
|
const layers = new LayersReactNative({
|
|
32
|
-
apiKey: 'your-api-key',
|
|
33
48
|
appId: 'your-app-id',
|
|
34
|
-
environment: 'production'
|
|
35
|
-
enableDebug: __DEV__
|
|
49
|
+
environment: 'production'
|
|
36
50
|
});
|
|
37
|
-
|
|
38
51
|
await layers.init();
|
|
39
52
|
|
|
40
53
|
// Track events
|
|
41
|
-
|
|
54
|
+
layers.track('button_tapped', { button_name: 'signup' });
|
|
42
55
|
|
|
43
|
-
// Track
|
|
44
|
-
|
|
56
|
+
// Track screen views
|
|
57
|
+
layers.screen('Home');
|
|
45
58
|
|
|
46
|
-
// Identify
|
|
47
|
-
layers.setAppUserId('
|
|
59
|
+
// Identify users
|
|
60
|
+
layers.setAppUserId('user_123');
|
|
48
61
|
```
|
|
49
62
|
|
|
50
63
|
## Configuration
|
|
51
64
|
|
|
52
|
-
|
|
65
|
+
### LayersRNConfig
|
|
66
|
+
|
|
67
|
+
```typescript
|
|
68
|
+
interface LayersRNConfig {
|
|
69
|
+
appId: string;
|
|
70
|
+
environment: 'development' | 'staging' | 'production';
|
|
71
|
+
appUserId?: string;
|
|
72
|
+
enableDebug?: boolean; // default: false
|
|
73
|
+
baseUrl?: string; // default: "https://in.layers.com"
|
|
74
|
+
flushIntervalMs?: number; // default: 30000
|
|
75
|
+
flushThreshold?: number; // default: 10
|
|
76
|
+
maxQueueSize?: number; // default: 1000
|
|
77
|
+
autoTrackAppOpen?: boolean; // default: true
|
|
78
|
+
autoTrackDeepLinks?: boolean; // default: true
|
|
79
|
+
}
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
| Option | Type | Default | Description |
|
|
83
|
+
| -------------------- | ------------- | ------------------------- | ------------------------------------------------ |
|
|
84
|
+
| `appId` | `string` | _required_ | Your Layers application identifier. |
|
|
85
|
+
| `environment` | `Environment` | _required_ | `'development'`, `'staging'`, or `'production'`. |
|
|
86
|
+
| `appUserId` | `string` | `undefined` | Optional user ID to set at construction time. |
|
|
87
|
+
| `enableDebug` | `boolean` | `false` | Enable verbose console logging. |
|
|
88
|
+
| `baseUrl` | `string` | `"https://in.layers.com"` | Custom ingest API endpoint. |
|
|
89
|
+
| `flushIntervalMs` | `number` | `30000` | Automatic flush interval in milliseconds. |
|
|
90
|
+
| `flushThreshold` | `number` | `10` | Queue size that triggers an automatic flush. |
|
|
91
|
+
| `maxQueueSize` | `number` | `1000` | Maximum events in the queue before dropping. |
|
|
92
|
+
| `autoTrackAppOpen` | `boolean` | `true` | Automatically track `app_open` on init. |
|
|
93
|
+
| `autoTrackDeepLinks` | `boolean` | `true` | Automatically track `deep_link_opened` events. |
|
|
94
|
+
|
|
95
|
+
## Core API
|
|
96
|
+
|
|
97
|
+
### Constructor & Initialization
|
|
98
|
+
|
|
99
|
+
```typescript
|
|
100
|
+
const layers = new LayersReactNative(config: LayersRNConfig);
|
|
101
|
+
await layers.init();
|
|
102
|
+
```
|
|
53
103
|
|
|
54
|
-
|
|
55
|
-
| ----------------- | -------------------------------------------- | ----------------------- | ------------------------------------ |
|
|
56
|
-
| `apiKey` | `string` | _required_ | API key from the Layers dashboard |
|
|
57
|
-
| `appId` | `string` | _required_ | Application identifier |
|
|
58
|
-
| `environment` | `'development' \| 'staging' \| 'production'` | _required_ | Deployment environment |
|
|
59
|
-
| `appUserId` | `string` | `undefined` | Pre-set user ID at init time |
|
|
60
|
-
| `enableDebug` | `boolean` | `false` | Verbose console logging |
|
|
61
|
-
| `baseUrl` | `string` | `https://in.layers.com` | Override the ingest endpoint |
|
|
62
|
-
| `flushIntervalMs` | `number` | `30000` | Periodic flush interval (ms) |
|
|
63
|
-
| `flushThreshold` | `number` | `20` | Queue depth that triggers auto-flush |
|
|
64
|
-
| `maxQueueSize` | `number` | `10000` | Max events in queue before dropping |
|
|
104
|
+
The constructor creates the SDK instance with an in-memory queue. Calling `init()` upgrades to AsyncStorage-backed persistence, collects device info, fetches remote config, reads clipboard attribution (iOS), fires `app_open`, and sets up auto-tracking.
|
|
65
105
|
|
|
66
|
-
|
|
106
|
+
You can call `track()` and `screen()` before `init()` completes -- events are queued in memory.
|
|
67
107
|
|
|
68
|
-
|
|
108
|
+
### Event Tracking
|
|
109
|
+
|
|
110
|
+
```typescript
|
|
111
|
+
track(eventName: string, properties?: EventProperties): void
|
|
112
|
+
```
|
|
69
113
|
|
|
70
|
-
```
|
|
71
|
-
layers.
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
114
|
+
```typescript
|
|
115
|
+
layers.track('purchase_completed', {
|
|
116
|
+
product_id: 'sku_123',
|
|
117
|
+
price: 9.99,
|
|
118
|
+
currency: 'USD'
|
|
119
|
+
});
|
|
75
120
|
```
|
|
76
121
|
|
|
77
|
-
|
|
122
|
+
### Screen Tracking
|
|
123
|
+
|
|
124
|
+
```typescript
|
|
125
|
+
screen(screenName: string, properties?: EventProperties): void
|
|
126
|
+
```
|
|
78
127
|
|
|
79
|
-
|
|
128
|
+
```typescript
|
|
129
|
+
layers.screen('ProductDetail', { product_id: 'sku_123' });
|
|
130
|
+
```
|
|
80
131
|
|
|
81
|
-
|
|
132
|
+
### User Identity
|
|
133
|
+
|
|
134
|
+
```typescript
|
|
135
|
+
// Set the app user ID (set-user-once: ignored if already set)
|
|
136
|
+
setAppUserId(appUserId: string): void
|
|
137
|
+
|
|
138
|
+
// Clear the current user ID (allows setting a new one)
|
|
139
|
+
clearAppUserId(): void
|
|
140
|
+
|
|
141
|
+
// Get the current user ID
|
|
142
|
+
getAppUserId(): string | undefined
|
|
143
|
+
|
|
144
|
+
// Set user properties
|
|
145
|
+
async setUserProperties(properties: UserProperties): Promise<void>
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
```typescript
|
|
149
|
+
// After login
|
|
150
|
+
layers.setAppUserId('user_123');
|
|
151
|
+
await layers.setUserProperties({
|
|
152
|
+
email: 'user@example.com',
|
|
153
|
+
plan: 'premium'
|
|
154
|
+
});
|
|
155
|
+
|
|
156
|
+
// On logout
|
|
157
|
+
layers.clearAppUserId();
|
|
158
|
+
```
|
|
159
|
+
|
|
160
|
+
> **Set-user-once semantics**: Once `setAppUserId()` is called, subsequent calls are ignored until `clearAppUserId()` is called. This prevents accidental user ID changes.
|
|
161
|
+
|
|
162
|
+
### Consent Management
|
|
163
|
+
|
|
164
|
+
```typescript
|
|
165
|
+
async setConsent(consent: ConsentState): Promise<void>
|
|
166
|
+
getConsentState(): ConsentState
|
|
167
|
+
```
|
|
168
|
+
|
|
169
|
+
```typescript
|
|
170
|
+
interface ConsentState {
|
|
171
|
+
analytics?: boolean;
|
|
172
|
+
advertising?: boolean;
|
|
173
|
+
}
|
|
174
|
+
```
|
|
175
|
+
|
|
176
|
+
```typescript
|
|
177
|
+
// User accepts all tracking
|
|
178
|
+
await layers.setConsent({ analytics: true, advertising: true });
|
|
179
|
+
|
|
180
|
+
// User denies advertising
|
|
181
|
+
await layers.setConsent({ analytics: true, advertising: false });
|
|
182
|
+
|
|
183
|
+
// Read current consent
|
|
184
|
+
const consent = layers.getConsentState();
|
|
185
|
+
```
|
|
186
|
+
|
|
187
|
+
### Flush & Shutdown
|
|
188
|
+
|
|
189
|
+
```typescript
|
|
190
|
+
// Flush queued events to the server
|
|
191
|
+
async flush(): Promise<void>
|
|
192
|
+
|
|
193
|
+
// Shut down the SDK (removes listeners, stops timers)
|
|
194
|
+
shutdown(): void
|
|
195
|
+
```
|
|
196
|
+
|
|
197
|
+
### Session & Device
|
|
198
|
+
|
|
199
|
+
```typescript
|
|
200
|
+
// Get the current session ID
|
|
201
|
+
getSessionId(): string
|
|
202
|
+
|
|
203
|
+
// Override device context fields
|
|
204
|
+
setDeviceInfo(deviceInfo: DeviceContext): void
|
|
205
|
+
```
|
|
206
|
+
|
|
207
|
+
### Error Handling
|
|
208
|
+
|
|
209
|
+
```typescript
|
|
210
|
+
// Register an error listener
|
|
211
|
+
on(event: 'error', listener: (error: Error) => void): this
|
|
212
|
+
|
|
213
|
+
// Remove an error listener
|
|
214
|
+
off(event: 'error', listener: (error: Error) => void): this
|
|
215
|
+
```
|
|
216
|
+
|
|
217
|
+
```typescript
|
|
218
|
+
layers.on('error', (error) => {
|
|
219
|
+
console.error('Layers error:', error.message);
|
|
220
|
+
// Forward to your crash reporting service
|
|
221
|
+
});
|
|
222
|
+
```
|
|
223
|
+
|
|
224
|
+
## App Tracking Transparency (ATT) -- iOS
|
|
225
|
+
|
|
226
|
+
### Integrated ATT (Recommended)
|
|
227
|
+
|
|
228
|
+
The `requestTrackingPermission()` method on the SDK instance handles the full ATT flow:
|
|
229
|
+
|
|
230
|
+
```typescript
|
|
231
|
+
const status = await layers.requestTrackingPermission();
|
|
232
|
+
// Returns: 'authorized' | 'denied' | 'restricted' | 'not_determined'
|
|
233
|
+
```
|
|
234
|
+
|
|
235
|
+
This method automatically:
|
|
236
|
+
|
|
237
|
+
1. Shows the ATT dialog (or uses `expo-tracking-transparency` if available)
|
|
238
|
+
2. Collects IDFA if authorized
|
|
239
|
+
3. Updates device context with IDFA and ATT status
|
|
240
|
+
4. Sets advertising consent based on the result
|
|
241
|
+
|
|
242
|
+
### Standalone ATT Functions
|
|
243
|
+
|
|
244
|
+
For more granular control, use the exported functions:
|
|
245
|
+
|
|
246
|
+
```typescript
|
|
82
247
|
import {
|
|
83
248
|
getATTStatus,
|
|
84
249
|
getAdvertisingId,
|
|
@@ -87,167 +252,233 @@ import {
|
|
|
87
252
|
requestTrackingAuthorization
|
|
88
253
|
} from '@layers/react-native';
|
|
89
254
|
|
|
90
|
-
|
|
91
|
-
const
|
|
255
|
+
const status = await getATTStatus();
|
|
256
|
+
const isAvailable = await isATTAvailable();
|
|
257
|
+
const idfa = await getAdvertisingId(); // null if not authorized
|
|
258
|
+
const idfv = await getVendorId(); // always available on iOS
|
|
259
|
+
```
|
|
92
260
|
|
|
93
|
-
|
|
94
|
-
const status = await requestTrackingAuthorization();
|
|
95
|
-
// Returns: 'authorized' | 'denied' | 'restricted' | 'not_determined'
|
|
261
|
+
### ATTStatus
|
|
96
262
|
|
|
97
|
-
|
|
98
|
-
|
|
263
|
+
```typescript
|
|
264
|
+
type ATTStatus = 'not_determined' | 'restricted' | 'denied' | 'authorized';
|
|
265
|
+
```
|
|
99
266
|
|
|
100
|
-
|
|
101
|
-
const idfa = await getAdvertisingId();
|
|
267
|
+
> **Important**: Add `NSUserTrackingUsageDescription` to your `Info.plist`.
|
|
102
268
|
|
|
103
|
-
|
|
104
|
-
const idfv = await getVendorId();
|
|
269
|
+
## SKAdNetwork (SKAN) -- iOS
|
|
105
270
|
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
271
|
+
SKAN is auto-configured from the server's remote config. The SDK creates a `SKANManager` instance and automatically forwards every `track()` call through the SKAN rule engine.
|
|
272
|
+
|
|
273
|
+
### Accessing the Auto-Configured Manager
|
|
274
|
+
|
|
275
|
+
```typescript
|
|
276
|
+
const skanManager = layers.getSkanManager();
|
|
277
|
+
if (skanManager) {
|
|
278
|
+
const metrics = skanManager.getMetrics();
|
|
279
|
+
console.log('SKAN value:', metrics.currentValue);
|
|
280
|
+
console.log('SKAN preset:', metrics.currentPreset);
|
|
111
281
|
}
|
|
112
282
|
```
|
|
113
283
|
|
|
114
|
-
|
|
284
|
+
### Manual SKAN Configuration
|
|
115
285
|
|
|
116
|
-
|
|
286
|
+
If you need to configure SKAN manually instead of relying on remote config:
|
|
117
287
|
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
```ts
|
|
288
|
+
```typescript
|
|
121
289
|
import { SKANManager } from '@layers/react-native';
|
|
122
290
|
|
|
123
|
-
const skan = new SKANManager((
|
|
124
|
-
console.log(`Conversion: ${
|
|
291
|
+
const skan = new SKANManager((data) => {
|
|
292
|
+
console.log(`Conversion value updated: ${data.previousValue} -> ${data.newValue}`);
|
|
125
293
|
});
|
|
126
294
|
|
|
127
|
-
await skan.initialize();
|
|
128
|
-
|
|
129
295
|
// Use a built-in preset
|
|
130
296
|
skan.setPreset('subscriptions'); // or 'engagement' or 'iap'
|
|
297
|
+
await skan.initialize();
|
|
131
298
|
|
|
132
299
|
// Or define custom rules
|
|
133
300
|
skan.setCustomRules([
|
|
134
|
-
{
|
|
135
|
-
|
|
136
|
-
|
|
301
|
+
{
|
|
302
|
+
eventName: 'purchase_success',
|
|
303
|
+
conditions: { revenue: { '>=': 10 } },
|
|
304
|
+
conversionValue: 63,
|
|
305
|
+
coarseValue: 'high',
|
|
306
|
+
priority: 10
|
|
307
|
+
},
|
|
308
|
+
{
|
|
309
|
+
eventName: 'trial_start',
|
|
310
|
+
conversionValue: 20,
|
|
311
|
+
priority: 5
|
|
312
|
+
}
|
|
137
313
|
]);
|
|
314
|
+
await skan.initialize();
|
|
138
315
|
|
|
139
|
-
//
|
|
140
|
-
await skan.processEvent('
|
|
316
|
+
// Process events manually
|
|
317
|
+
await skan.processEvent('purchase_success', { revenue: 49.99 });
|
|
318
|
+
```
|
|
141
319
|
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
320
|
+
### SKANConversionRule
|
|
321
|
+
|
|
322
|
+
```typescript
|
|
323
|
+
interface SKANConversionRule {
|
|
324
|
+
eventName: string;
|
|
325
|
+
conditions?: Record<string, unknown>; // Operator-based: { '>': 10, '<': 100 }
|
|
326
|
+
conversionValue: number; // 0-63 (SKAN 3.0) or 0-7 (SKAN 4.0)
|
|
327
|
+
coarseValue?: 'low' | 'medium' | 'high'; // SKAN 4.0 only
|
|
328
|
+
lockWindow?: boolean; // SKAN 4.0 only
|
|
329
|
+
priority?: number;
|
|
330
|
+
description?: string;
|
|
331
|
+
}
|
|
145
332
|
```
|
|
146
333
|
|
|
147
|
-
|
|
334
|
+
### SKANMetrics
|
|
335
|
+
|
|
336
|
+
```typescript
|
|
337
|
+
interface SKANMetrics {
|
|
338
|
+
isSupported: boolean;
|
|
339
|
+
version: string;
|
|
340
|
+
currentValue: number | null;
|
|
341
|
+
currentPreset: string | null;
|
|
342
|
+
ruleCount: number;
|
|
343
|
+
evaluationCount: number;
|
|
344
|
+
}
|
|
345
|
+
```
|
|
346
|
+
|
|
347
|
+
### Available Presets
|
|
348
|
+
|
|
349
|
+
- **`subscriptions`** -- Optimized for subscription apps (trial start, subscription start/renew)
|
|
350
|
+
- **`engagement`** -- Optimized for engagement-driven apps (content views, sessions, bookmarks)
|
|
351
|
+
- **`iap`** -- Optimized for in-app purchase revenue tracking (purchase tiers by revenue)
|
|
148
352
|
|
|
149
353
|
## Deep Links
|
|
150
354
|
|
|
151
|
-
###
|
|
355
|
+
### Auto-Tracking (Default)
|
|
152
356
|
|
|
153
|
-
|
|
357
|
+
When `autoTrackDeepLinks` is `true` (default), the SDK automatically tracks a `deep_link_opened` event for every incoming deep link. The event includes the full URL, scheme, host, path, and all query parameters (UTM, click IDs) as flat top-level properties.
|
|
358
|
+
|
|
359
|
+
### Manual Deep Link Handling
|
|
360
|
+
|
|
361
|
+
```typescript
|
|
154
362
|
import { parseDeepLink, setupDeepLinkListener } from '@layers/react-native';
|
|
155
363
|
|
|
156
364
|
const unsubscribe = setupDeepLinkListener((data) => {
|
|
157
|
-
console.log(data.url);
|
|
158
|
-
console.log(data.
|
|
159
|
-
console.log(data.
|
|
160
|
-
console.log(data.
|
|
161
|
-
console.log(data.queryParams);
|
|
162
|
-
|
|
163
|
-
// Track the deep link as an event
|
|
164
|
-
layers.track('deep_link', {
|
|
165
|
-
url: data.url,
|
|
166
|
-
source: data.queryParams.ref
|
|
167
|
-
});
|
|
365
|
+
console.log('Deep link:', data.url);
|
|
366
|
+
console.log('Host:', data.host);
|
|
367
|
+
console.log('Path:', data.path);
|
|
368
|
+
console.log('UTM Source:', data.queryParams.utm_source);
|
|
369
|
+
console.log('Click ID:', data.queryParams.fbclid);
|
|
168
370
|
});
|
|
169
371
|
|
|
170
|
-
//
|
|
171
|
-
unsubscribe();
|
|
372
|
+
// Later: unsubscribe()
|
|
172
373
|
```
|
|
173
374
|
|
|
174
|
-
|
|
375
|
+
The listener handles both:
|
|
175
376
|
|
|
176
|
-
|
|
377
|
+
- **Initial URL** (cold start): Checks `Linking.getInitialURL()` on setup.
|
|
378
|
+
- **Subsequent URLs** (warm start): Listens to `Linking` `url` events.
|
|
177
379
|
|
|
178
|
-
|
|
179
|
-
import { useLayersExpoRouterTracking } from '@layers/react-native';
|
|
180
|
-
import { usePathname, useGlobalSearchParams } from 'expo-router';
|
|
380
|
+
### parseDeepLink
|
|
181
381
|
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
382
|
+
```typescript
|
|
383
|
+
function parseDeepLink(url: string): DeepLinkData | null;
|
|
384
|
+
```
|
|
385
|
+
|
|
386
|
+
```typescript
|
|
387
|
+
interface DeepLinkData {
|
|
388
|
+
url: string;
|
|
389
|
+
scheme: string;
|
|
390
|
+
host: string;
|
|
391
|
+
path: string;
|
|
392
|
+
queryParams: Record<string, string>;
|
|
393
|
+
timestamp: number;
|
|
185
394
|
}
|
|
186
395
|
```
|
|
187
396
|
|
|
188
|
-
|
|
397
|
+
## Clipboard Attribution -- iOS
|
|
189
398
|
|
|
190
|
-
|
|
399
|
+
On iOS, the SDK reads the clipboard on first launch (during `init()`) for a Layers click URL. If found, the click URL and click ID are included as properties on the `app_open` event. This is controlled by the server's remote config (`clipboard_attribution_enabled`).
|
|
191
400
|
|
|
192
|
-
|
|
193
|
-
// Allow analytics, deny advertising
|
|
194
|
-
await layers.setConsent({ analytics: true, advertising: false });
|
|
401
|
+
For manual reading:
|
|
195
402
|
|
|
196
|
-
|
|
197
|
-
|
|
403
|
+
```typescript
|
|
404
|
+
import { readClipboardAttribution } from '@layers/react-native';
|
|
405
|
+
|
|
406
|
+
const data = await readClipboardAttribution();
|
|
407
|
+
if (data) {
|
|
408
|
+
console.log('Click URL:', data.clickUrl);
|
|
409
|
+
console.log('Click ID:', data.clickId);
|
|
410
|
+
}
|
|
198
411
|
```
|
|
199
412
|
|
|
200
|
-
|
|
413
|
+
```typescript
|
|
414
|
+
interface ClipboardAttribution {
|
|
415
|
+
clickUrl: string;
|
|
416
|
+
clickId: string;
|
|
417
|
+
}
|
|
418
|
+
```
|
|
201
419
|
|
|
202
|
-
|
|
420
|
+
Requires `@react-native-clipboard/clipboard` as a peer dependency.
|
|
203
421
|
|
|
204
|
-
|
|
422
|
+
## Expo Router Integration
|
|
205
423
|
|
|
206
|
-
|
|
207
|
-
layers.on('error', (err) => {
|
|
208
|
-
console.error('Layers SDK error:', err.message);
|
|
209
|
-
});
|
|
424
|
+
For automatic screen tracking with Expo Router:
|
|
210
425
|
|
|
211
|
-
|
|
212
|
-
layers
|
|
213
|
-
|
|
426
|
+
```typescript
|
|
427
|
+
import { useLayersExpoRouterTracking } from '@layers/react-native';
|
|
428
|
+
import { usePathname, useGlobalSearchParams } from 'expo-router';
|
|
214
429
|
|
|
215
|
-
|
|
430
|
+
function RootLayout() {
|
|
431
|
+
useLayersExpoRouterTracking(layers, usePathname, useGlobalSearchParams);
|
|
216
432
|
|
|
217
|
-
|
|
433
|
+
return <Stack />;
|
|
434
|
+
}
|
|
435
|
+
```
|
|
218
436
|
|
|
219
|
-
|
|
437
|
+
This hook automatically tracks a `screen` event every time the Expo Router pathname changes, including route parameters as event properties.
|
|
220
438
|
|
|
221
|
-
|
|
222
|
-
[Layers] track("app_open", 1 properties)
|
|
223
|
-
[Layers] screen("home", 0 properties)
|
|
224
|
-
[Layers] setAppUserId("user-123")
|
|
225
|
-
```
|
|
439
|
+
## Install ID
|
|
226
440
|
|
|
227
|
-
|
|
441
|
+
The SDK generates and persists a unique install ID via AsyncStorage:
|
|
228
442
|
|
|
229
|
-
|
|
443
|
+
```typescript
|
|
444
|
+
import { getOrSetInstallId } from '@layers/react-native';
|
|
230
445
|
|
|
231
|
-
|
|
232
|
-
const mockLayers = {
|
|
233
|
-
init: jest.fn().mockResolvedValue(undefined),
|
|
234
|
-
track: jest.fn().mockResolvedValue(undefined),
|
|
235
|
-
screen: jest.fn().mockResolvedValue(undefined),
|
|
236
|
-
setAppUserId: jest.fn(),
|
|
237
|
-
clearAppUserId: jest.fn(),
|
|
238
|
-
getAppUserId: jest.fn(),
|
|
239
|
-
setConsent: jest.fn().mockResolvedValue(undefined),
|
|
240
|
-
getConsentState: jest.fn().mockReturnValue({}),
|
|
241
|
-
setUserProperties: jest.fn().mockResolvedValue(undefined),
|
|
242
|
-
setDeviceInfo: jest.fn(),
|
|
243
|
-
flush: jest.fn().mockResolvedValue(undefined),
|
|
244
|
-
shutdown: jest.fn(),
|
|
245
|
-
getSessionId: jest.fn().mockReturnValue('mock-session-id'),
|
|
246
|
-
on: jest.fn().mockReturnThis(),
|
|
247
|
-
off: jest.fn().mockReturnThis()
|
|
248
|
-
};
|
|
446
|
+
const installId = await getOrSetInstallId();
|
|
249
447
|
```
|
|
250
448
|
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
449
|
+
This ID persists across app sessions and is included in the device context.
|
|
450
|
+
|
|
451
|
+
## Automatic Behaviors
|
|
452
|
+
|
|
453
|
+
- **app_open event**: Tracked on `init()` with clipboard attribution (iOS).
|
|
454
|
+
- **deep_link_opened event**: Tracked automatically for all incoming deep links.
|
|
455
|
+
- **Background flush**: Events are flushed when the app goes to background/inactive.
|
|
456
|
+
- **Foreground flush**: Events are flushed when the app becomes active.
|
|
457
|
+
- **Network reconnect flush**: Events are flushed when the device reconnects (requires `@react-native-community/netinfo`).
|
|
458
|
+
- **Periodic flush**: Events are flushed on a timer (configurable).
|
|
459
|
+
- **Remote config**: Server configuration is fetched during init.
|
|
460
|
+
- **SKAN auto-config**: SKAN preset/rules from remote config are applied automatically (iOS).
|
|
461
|
+
- **Device context**: Platform, OS version, device model, locale, screen size, timezone, IDFV (iOS), and install ID are collected automatically.
|
|
462
|
+
- **Event persistence**: Events are persisted via AsyncStorage (if available) and rehydrated on restart.
|
|
463
|
+
|
|
464
|
+
## TypeScript Types
|
|
465
|
+
|
|
466
|
+
All types are exported from the package:
|
|
467
|
+
|
|
468
|
+
```typescript
|
|
469
|
+
import type {
|
|
470
|
+
ATTStatus,
|
|
471
|
+
ClipboardAttribution,
|
|
472
|
+
ConsentState,
|
|
473
|
+
DeepLinkData,
|
|
474
|
+
DeviceContext,
|
|
475
|
+
Environment,
|
|
476
|
+
ErrorListener,
|
|
477
|
+
EventProperties,
|
|
478
|
+
LayersRNConfig,
|
|
479
|
+
SKANConversionRule,
|
|
480
|
+
SKANMetrics,
|
|
481
|
+
SKANPresetConfig,
|
|
482
|
+
UserProperties
|
|
483
|
+
} from '@layers/react-native';
|
|
484
|
+
```
|