@adshift/react-native-plugin 1.0.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/AdShiftReactNativePlugin.podspec +30 -0
- package/LICENSE +45 -0
- package/README.md +810 -0
- package/android/build.gradle +80 -0
- package/android/gradle.properties +5 -0
- package/android/src/main/AndroidManifest.xml +2 -0
- package/android/src/main/java/com/adshift/reactnativeplugin/AdShiftReactNativePluginModule.kt +420 -0
- package/android/src/main/java/com/adshift/reactnativeplugin/AdShiftReactNativePluginPackage.kt +33 -0
- package/ios/AdShiftReactNativePlugin.h +24 -0
- package/ios/AdShiftReactNativePlugin.mm +258 -0
- package/ios/AdShiftReactNativePluginHelper.swift +413 -0
- package/lib/module/Adshift.js +468 -0
- package/lib/module/Adshift.js.map +1 -0
- package/lib/module/NativeAdShiftReactNativePlugin.js +18 -0
- package/lib/module/NativeAdShiftReactNativePlugin.js.map +1 -0
- package/lib/module/index.js +57 -0
- package/lib/module/index.js.map +1 -0
- package/lib/module/package.json +1 -0
- package/lib/module/types/AdshiftConfig.js +44 -0
- package/lib/module/types/AdshiftConfig.js.map +1 -0
- package/lib/module/types/AdshiftConsent.js +101 -0
- package/lib/module/types/AdshiftConsent.js.map +1 -0
- package/lib/module/types/AdshiftDeepLink.js +121 -0
- package/lib/module/types/AdshiftDeepLink.js.map +1 -0
- package/lib/module/types/AdshiftEventType.js +108 -0
- package/lib/module/types/AdshiftEventType.js.map +1 -0
- package/lib/module/types/index.js +10 -0
- package/lib/module/types/index.js.map +1 -0
- package/lib/typescript/package.json +1 -0
- package/lib/typescript/src/Adshift.d.ts +335 -0
- package/lib/typescript/src/Adshift.d.ts.map +1 -0
- package/lib/typescript/src/NativeAdShiftReactNativePlugin.d.ts +143 -0
- package/lib/typescript/src/NativeAdShiftReactNativePlugin.d.ts.map +1 -0
- package/lib/typescript/src/index.d.ts +47 -0
- package/lib/typescript/src/index.d.ts.map +1 -0
- package/lib/typescript/src/types/AdshiftConfig.d.ts +74 -0
- package/lib/typescript/src/types/AdshiftConfig.d.ts.map +1 -0
- package/lib/typescript/src/types/AdshiftConsent.d.ts +88 -0
- package/lib/typescript/src/types/AdshiftConsent.d.ts.map +1 -0
- package/lib/typescript/src/types/AdshiftDeepLink.d.ts +93 -0
- package/lib/typescript/src/types/AdshiftDeepLink.d.ts.map +1 -0
- package/lib/typescript/src/types/AdshiftEventType.d.ts +87 -0
- package/lib/typescript/src/types/AdshiftEventType.d.ts.map +1 -0
- package/lib/typescript/src/types/index.d.ts +5 -0
- package/lib/typescript/src/types/index.d.ts.map +1 -0
- package/package.json +143 -0
- package/src/Adshift.ts +539 -0
- package/src/NativeAdShiftReactNativePlugin.ts +177 -0
- package/src/index.tsx +68 -0
- package/src/types/AdshiftConfig.ts +108 -0
- package/src/types/AdshiftConsent.ts +127 -0
- package/src/types/AdshiftDeepLink.ts +194 -0
- package/src/types/AdshiftEventType.ts +135 -0
- package/src/types/index.ts +7 -0
package/README.md
ADDED
|
@@ -0,0 +1,810 @@
|
|
|
1
|
+
# AdShift React Native Plugin
|
|
2
|
+
|
|
3
|
+
[](https://www.npmjs.com/package/@adshift/react-native-plugin)
|
|
4
|
+
[](https://www.npmjs.com/package/@adshift/react-native-plugin)
|
|
5
|
+
[](https://reactnative.dev/)
|
|
6
|
+
[](LICENSE)
|
|
7
|
+
|
|
8
|
+
Official AdShift SDK for React Native. This plugin wraps the native [iOS SDK](https://github.com/AdShift/ios-sdk) and [Android SDK](https://github.com/AdShift/android-sdk), providing a unified TypeScript API for React Native apps.
|
|
9
|
+
|
|
10
|
+
Enable mobile attribution, in-app event tracking, SKAdNetwork 4.0+ integration, deep linking, and GDPR/TCF 2.2 compliance in your React Native apps.
|
|
11
|
+
|
|
12
|
+
---
|
|
13
|
+
|
|
14
|
+
## 📚 Table of Contents
|
|
15
|
+
|
|
16
|
+
- [Features](#features)
|
|
17
|
+
- [Requirements](#requirements)
|
|
18
|
+
- [Installation](#installation)
|
|
19
|
+
- [Quick Start](#quick-start)
|
|
20
|
+
- [API Reference](#api-reference)
|
|
21
|
+
- [SDK Lifecycle](#sdk-lifecycle)
|
|
22
|
+
- [Event Tracking](#event-tracking)
|
|
23
|
+
- [Consent Management](#consent-management)
|
|
24
|
+
- [Deep Linking](#deep-linking)
|
|
25
|
+
- [Configuration](#configuration)
|
|
26
|
+
- [Platform-Specific Setup](#platform-specific-setup)
|
|
27
|
+
- [iOS Setup](#ios-setup)
|
|
28
|
+
- [Android Setup](#android-setup)
|
|
29
|
+
- [TypeScript Support](#typescript-support)
|
|
30
|
+
- [Example App](#example-app)
|
|
31
|
+
- [Troubleshooting](#troubleshooting)
|
|
32
|
+
- [Support](#support)
|
|
33
|
+
|
|
34
|
+
---
|
|
35
|
+
|
|
36
|
+
## Features
|
|
37
|
+
|
|
38
|
+
- ✅ **Install Attribution** — Accurate install tracking across platforms
|
|
39
|
+
- ✅ **In-App Event Tracking** — Track user actions and conversions with 30+ predefined events
|
|
40
|
+
- ✅ **SKAdNetwork 4.0+** — Full support for iOS privacy-preserving attribution
|
|
41
|
+
- ✅ **Deep Linking** — Direct and deferred deep link support with unified API
|
|
42
|
+
- ✅ **GDPR/DMA Compliance** — Manual consent and TCF 2.2 automatic collection
|
|
43
|
+
- ✅ **Offline Mode** — Events are cached and sent when connectivity returns
|
|
44
|
+
- ✅ **New Architecture** — Built for React Native 0.82+ with Turbo Modules
|
|
45
|
+
- ✅ **TypeScript First** — Full type definitions with IntelliSense support
|
|
46
|
+
- ✅ **Cross-Platform** — Single API for iOS and Android
|
|
47
|
+
|
|
48
|
+
---
|
|
49
|
+
|
|
50
|
+
## Requirements
|
|
51
|
+
|
|
52
|
+
| Platform | Minimum Version |
|
|
53
|
+
|----------|-----------------|
|
|
54
|
+
| **React Native** | 0.82.0+ (New Architecture) |
|
|
55
|
+
| **iOS** | 15.0+ |
|
|
56
|
+
| **Android** | API 21+ (Android 5.0) |
|
|
57
|
+
| **Node.js** | 18+ |
|
|
58
|
+
| **TypeScript** | 5.0+ (recommended) |
|
|
59
|
+
|
|
60
|
+
> ⚠️ **Note:** This plugin requires React Native's New Architecture (Turbo Modules). Old Architecture (Bridge) is not supported.
|
|
61
|
+
|
|
62
|
+
---
|
|
63
|
+
|
|
64
|
+
## Installation
|
|
65
|
+
|
|
66
|
+
### Using npm
|
|
67
|
+
|
|
68
|
+
```bash
|
|
69
|
+
npm install @adshift/react-native-plugin
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
### Using yarn
|
|
73
|
+
|
|
74
|
+
```bash
|
|
75
|
+
yarn add @adshift/react-native-plugin
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
### iOS Setup (CocoaPods)
|
|
79
|
+
|
|
80
|
+
After installing the npm package:
|
|
81
|
+
|
|
82
|
+
```bash
|
|
83
|
+
cd ios && pod install
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
### Android Setup
|
|
87
|
+
|
|
88
|
+
No additional setup required — the plugin auto-links with React Native.
|
|
89
|
+
|
|
90
|
+
---
|
|
91
|
+
|
|
92
|
+
## Quick Start
|
|
93
|
+
|
|
94
|
+
### 1. Initialize the SDK
|
|
95
|
+
|
|
96
|
+
> ⚠️ **Important:** iOS and Android apps have **different API keys**. Get both from your AdShift dashboard.
|
|
97
|
+
|
|
98
|
+
```typescript
|
|
99
|
+
import { Platform } from 'react-native';
|
|
100
|
+
import { Adshift } from '@adshift/react-native-plugin';
|
|
101
|
+
|
|
102
|
+
// API keys are different for iOS and Android
|
|
103
|
+
const API_KEYS = {
|
|
104
|
+
ios: 'YOUR_IOS_API_KEY',
|
|
105
|
+
android: 'YOUR_ANDROID_API_KEY',
|
|
106
|
+
};
|
|
107
|
+
|
|
108
|
+
// Initialize in your app's entry point (App.tsx or index.js)
|
|
109
|
+
Adshift.initialize({
|
|
110
|
+
apiKey: Platform.select({
|
|
111
|
+
ios: API_KEYS.ios,
|
|
112
|
+
android: API_KEYS.android,
|
|
113
|
+
default: API_KEYS.android,
|
|
114
|
+
})!,
|
|
115
|
+
isDebug: __DEV__, // Enable debug logs in development
|
|
116
|
+
});
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
### 2. Start Tracking
|
|
120
|
+
|
|
121
|
+
```typescript
|
|
122
|
+
// Start the SDK (typically after user consent or app launch)
|
|
123
|
+
const result = await Adshift.start();
|
|
124
|
+
|
|
125
|
+
if (result.success) {
|
|
126
|
+
console.log('AdShift started successfully');
|
|
127
|
+
}
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
### 3. Track Events
|
|
131
|
+
|
|
132
|
+
```typescript
|
|
133
|
+
import { Adshift, AdshiftEventType } from '@adshift/react-native-plugin';
|
|
134
|
+
|
|
135
|
+
// Track a simple event
|
|
136
|
+
await Adshift.trackEvent(AdshiftEventType.LOGIN);
|
|
137
|
+
|
|
138
|
+
// Track event with parameters
|
|
139
|
+
await Adshift.trackEvent(AdshiftEventType.ADD_TO_CART, {
|
|
140
|
+
product_id: 'SKU123',
|
|
141
|
+
price: 29.99,
|
|
142
|
+
quantity: 1,
|
|
143
|
+
});
|
|
144
|
+
|
|
145
|
+
// Track purchase (for SKAdNetwork conversion value)
|
|
146
|
+
await Adshift.trackPurchase({
|
|
147
|
+
productId: 'premium_subscription',
|
|
148
|
+
revenue: 9.99,
|
|
149
|
+
currency: 'USD',
|
|
150
|
+
transactionId: 'TXN_12345',
|
|
151
|
+
});
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
### 4. Handle Deep Links
|
|
155
|
+
|
|
156
|
+
```typescript
|
|
157
|
+
import { useEffect, useRef } from 'react';
|
|
158
|
+
import { Adshift } from '@adshift/react-native-plugin';
|
|
159
|
+
import type { DeepLinkSubscription } from '@adshift/react-native-plugin';
|
|
160
|
+
|
|
161
|
+
function App() {
|
|
162
|
+
const subscriptionRef = useRef<DeepLinkSubscription | null>(null);
|
|
163
|
+
|
|
164
|
+
useEffect(() => {
|
|
165
|
+
// Listen for deep links (direct and deferred)
|
|
166
|
+
subscriptionRef.current = Adshift.onDeepLink((deepLink) => {
|
|
167
|
+
if (deepLink.status === 'found') {
|
|
168
|
+
console.log('Deep link URL:', deepLink.deepLink);
|
|
169
|
+
console.log('Is deferred:', deepLink.isDeferred);
|
|
170
|
+
// Navigate based on deepLink.deepLinkValue or deepLink.params
|
|
171
|
+
}
|
|
172
|
+
});
|
|
173
|
+
|
|
174
|
+
return () => {
|
|
175
|
+
subscriptionRef.current?.remove();
|
|
176
|
+
};
|
|
177
|
+
}, []);
|
|
178
|
+
|
|
179
|
+
return <YourApp />;
|
|
180
|
+
}
|
|
181
|
+
```
|
|
182
|
+
|
|
183
|
+
---
|
|
184
|
+
|
|
185
|
+
## API Reference
|
|
186
|
+
|
|
187
|
+
### SDK Lifecycle
|
|
188
|
+
|
|
189
|
+
#### `Adshift.initialize(config)`
|
|
190
|
+
|
|
191
|
+
Configure the SDK. Call this before any other SDK method.
|
|
192
|
+
|
|
193
|
+
> ⚠️ **Note:** iOS and Android apps require **separate API keys** from the AdShift dashboard.
|
|
194
|
+
|
|
195
|
+
```typescript
|
|
196
|
+
import { Platform } from 'react-native';
|
|
197
|
+
import type { AdshiftConfig } from '@adshift/react-native-plugin';
|
|
198
|
+
|
|
199
|
+
const config: AdshiftConfig = {
|
|
200
|
+
apiKey: Platform.OS === 'ios' ? 'IOS_KEY' : 'ANDROID_KEY', // Required - platform-specific!
|
|
201
|
+
isDebug: true, // Optional: Enable debug logs
|
|
202
|
+
appOpenDebounceMs: 10000, // Optional: Debounce for app_open events (ms)
|
|
203
|
+
|
|
204
|
+
// iOS only
|
|
205
|
+
disableSKAN: false, // Optional: Disable SKAdNetwork
|
|
206
|
+
waitForATTBeforeStart: true, // Optional: Wait for ATT before install event
|
|
207
|
+
attTimeoutMs: 30000, // Optional: ATT timeout (ms)
|
|
208
|
+
|
|
209
|
+
// Android only
|
|
210
|
+
collectOaid: false, // Optional: Collect OAID (China devices)
|
|
211
|
+
};
|
|
212
|
+
|
|
213
|
+
Adshift.initialize(config);
|
|
214
|
+
```
|
|
215
|
+
|
|
216
|
+
#### `Adshift.start()`
|
|
217
|
+
|
|
218
|
+
Start the SDK and begin tracking. Returns a promise with the result.
|
|
219
|
+
|
|
220
|
+
```typescript
|
|
221
|
+
const result = await Adshift.start();
|
|
222
|
+
// result: { success: boolean, message?: string }
|
|
223
|
+
```
|
|
224
|
+
|
|
225
|
+
#### `Adshift.stop()`
|
|
226
|
+
|
|
227
|
+
Stop the SDK. Events will not be tracked until `start()` is called again.
|
|
228
|
+
|
|
229
|
+
```typescript
|
|
230
|
+
Adshift.stop();
|
|
231
|
+
```
|
|
232
|
+
|
|
233
|
+
#### `Adshift.isStarted()`
|
|
234
|
+
|
|
235
|
+
Check if the SDK is currently running.
|
|
236
|
+
|
|
237
|
+
```typescript
|
|
238
|
+
const isRunning = Adshift.isStarted(); // boolean
|
|
239
|
+
```
|
|
240
|
+
|
|
241
|
+
---
|
|
242
|
+
|
|
243
|
+
### Event Tracking
|
|
244
|
+
|
|
245
|
+
#### `Adshift.trackEvent(eventName, values?)`
|
|
246
|
+
|
|
247
|
+
Track an in-app event with optional parameters.
|
|
248
|
+
|
|
249
|
+
```typescript
|
|
250
|
+
// Simple event
|
|
251
|
+
await Adshift.trackEvent(AdshiftEventType.LOGIN);
|
|
252
|
+
|
|
253
|
+
// Event with parameters
|
|
254
|
+
await Adshift.trackEvent(AdshiftEventType.SEARCH, {
|
|
255
|
+
search_term: 'running shoes',
|
|
256
|
+
results_count: 42,
|
|
257
|
+
});
|
|
258
|
+
|
|
259
|
+
// Custom event
|
|
260
|
+
await Adshift.trackEvent('custom_button_click', {
|
|
261
|
+
button_name: 'checkout',
|
|
262
|
+
});
|
|
263
|
+
```
|
|
264
|
+
|
|
265
|
+
#### `Adshift.trackPurchase(params)`
|
|
266
|
+
|
|
267
|
+
Track a purchase event. Use this for accurate SKAdNetwork conversion value calculation.
|
|
268
|
+
|
|
269
|
+
```typescript
|
|
270
|
+
await Adshift.trackPurchase({
|
|
271
|
+
productId: 'com.app.premium',
|
|
272
|
+
revenue: 9.99, // Use 'revenue' for SKAN CV calculation
|
|
273
|
+
currency: 'USD',
|
|
274
|
+
transactionId: 'txn_123',
|
|
275
|
+
});
|
|
276
|
+
```
|
|
277
|
+
|
|
278
|
+
> 💡 **Tip:** Use `revenue` (not `price`) for accurate SKAdNetwork attribution.
|
|
279
|
+
|
|
280
|
+
#### Predefined Event Types
|
|
281
|
+
|
|
282
|
+
```typescript
|
|
283
|
+
import { AdshiftEventType } from '@adshift/react-native-plugin';
|
|
284
|
+
|
|
285
|
+
// Available events
|
|
286
|
+
AdshiftEventType.LOGIN
|
|
287
|
+
AdshiftEventType.PURCHASE
|
|
288
|
+
AdshiftEventType.ADD_TO_CART
|
|
289
|
+
AdshiftEventType.ADD_TO_WISHLIST
|
|
290
|
+
AdshiftEventType.COMPLETE_REGISTRATION
|
|
291
|
+
AdshiftEventType.INITIATED_CHECKOUT
|
|
292
|
+
AdshiftEventType.ADD_PAYMENT_INFO
|
|
293
|
+
AdshiftEventType.SUBSCRIBE
|
|
294
|
+
AdshiftEventType.START_TRIAL
|
|
295
|
+
AdshiftEventType.LEVEL_ACHIEVED
|
|
296
|
+
AdshiftEventType.ACHIEVEMENT_UNLOCKED
|
|
297
|
+
AdshiftEventType.TUTORIAL_COMPLETION
|
|
298
|
+
AdshiftEventType.CONTENT_VIEW
|
|
299
|
+
AdshiftEventType.LIST_VIEW
|
|
300
|
+
AdshiftEventType.SEARCH
|
|
301
|
+
AdshiftEventType.RATE
|
|
302
|
+
AdshiftEventType.SHARE
|
|
303
|
+
AdshiftEventType.INVITE
|
|
304
|
+
AdshiftEventType.RE_ENGAGE
|
|
305
|
+
AdshiftEventType.UPDATE
|
|
306
|
+
AdshiftEventType.OPENED_FROM_PUSH_NOTIFICATION
|
|
307
|
+
AdshiftEventType.AD_CLICK
|
|
308
|
+
AdshiftEventType.AD_VIEW
|
|
309
|
+
AdshiftEventType.SPENT_CREDITS
|
|
310
|
+
AdshiftEventType.TRAVEL_BOOKING
|
|
311
|
+
AdshiftEventType.LOCATION_CHANGED
|
|
312
|
+
AdshiftEventType.LOCATION_COORDINATES
|
|
313
|
+
AdshiftEventType.ORDER_ID
|
|
314
|
+
AdshiftEventType.CUSTOMER_SEGMENT
|
|
315
|
+
```
|
|
316
|
+
|
|
317
|
+
---
|
|
318
|
+
|
|
319
|
+
### Consent Management
|
|
320
|
+
|
|
321
|
+
#### Manual Consent (GDPR/DMA)
|
|
322
|
+
|
|
323
|
+
```typescript
|
|
324
|
+
import { AdshiftConsent } from '@adshift/react-native-plugin';
|
|
325
|
+
|
|
326
|
+
// For GDPR users — grant all consent
|
|
327
|
+
Adshift.setConsentData(
|
|
328
|
+
AdshiftConsent.forGDPRUser({
|
|
329
|
+
hasConsentForDataUsage: true,
|
|
330
|
+
hasConsentForAdsPersonalization: true,
|
|
331
|
+
hasConsentForAdStorage: true,
|
|
332
|
+
})
|
|
333
|
+
);
|
|
334
|
+
|
|
335
|
+
// For GDPR users — deny consent
|
|
336
|
+
Adshift.setConsentData(
|
|
337
|
+
AdshiftConsent.forGDPRUser({
|
|
338
|
+
hasConsentForDataUsage: false,
|
|
339
|
+
hasConsentForAdsPersonalization: false,
|
|
340
|
+
hasConsentForAdStorage: false,
|
|
341
|
+
})
|
|
342
|
+
);
|
|
343
|
+
|
|
344
|
+
// For non-GDPR users (e.g., US users without state privacy laws)
|
|
345
|
+
Adshift.setConsentData(AdshiftConsent.forNonGDPRUser());
|
|
346
|
+
```
|
|
347
|
+
|
|
348
|
+
#### TCF 2.2 Automatic Collection
|
|
349
|
+
|
|
350
|
+
If you use a CMP (Consent Management Platform) that stores IAB TCF data:
|
|
351
|
+
|
|
352
|
+
```typescript
|
|
353
|
+
// Enable TCF collection BEFORE calling start()
|
|
354
|
+
Adshift.enableTCFDataCollection(true);
|
|
355
|
+
|
|
356
|
+
// Start SDK after CMP dialog completes
|
|
357
|
+
await Adshift.start();
|
|
358
|
+
|
|
359
|
+
// Refresh consent after user changes preferences
|
|
360
|
+
const snapshot = await Adshift.refreshConsent();
|
|
361
|
+
console.log('Consent source:', snapshot.source);
|
|
362
|
+
console.log('Has consent:', snapshot.hasConsent);
|
|
363
|
+
```
|
|
364
|
+
|
|
365
|
+
#### Consent Snapshot Response
|
|
366
|
+
|
|
367
|
+
```typescript
|
|
368
|
+
interface ConsentSnapshot {
|
|
369
|
+
source: 'manual' | 'tcf' | 'gpp' | 'none';
|
|
370
|
+
gdprApplies?: number;
|
|
371
|
+
tcStringPresent: boolean;
|
|
372
|
+
adUserDataEnabled?: boolean;
|
|
373
|
+
adPersonalizationEnabled?: boolean;
|
|
374
|
+
adStorageEnabled?: boolean;
|
|
375
|
+
appliedAtMillis: number;
|
|
376
|
+
hasConsent: boolean; // Convenience field
|
|
377
|
+
}
|
|
378
|
+
```
|
|
379
|
+
|
|
380
|
+
---
|
|
381
|
+
|
|
382
|
+
### Deep Linking
|
|
383
|
+
|
|
384
|
+
#### Listen for Deep Links
|
|
385
|
+
|
|
386
|
+
Subscribe to deep link events for both direct and deferred deep links:
|
|
387
|
+
|
|
388
|
+
```typescript
|
|
389
|
+
import { Adshift, AdshiftDeepLinkStatus } from '@adshift/react-native-plugin';
|
|
390
|
+
import type { DeepLinkSubscription, AdshiftDeepLink } from '@adshift/react-native-plugin';
|
|
391
|
+
|
|
392
|
+
const subscription: DeepLinkSubscription = Adshift.onDeepLink((deepLink: AdshiftDeepLink) => {
|
|
393
|
+
switch (deepLink.status) {
|
|
394
|
+
case AdshiftDeepLinkStatus.FOUND:
|
|
395
|
+
console.log('URL:', deepLink.deepLink);
|
|
396
|
+
console.log('Value:', deepLink.deepLinkValue);
|
|
397
|
+
console.log('Is Deferred:', deepLink.isDeferred);
|
|
398
|
+
console.log('Params:', deepLink.params);
|
|
399
|
+
// Navigate to appropriate screen
|
|
400
|
+
break;
|
|
401
|
+
|
|
402
|
+
case AdshiftDeepLinkStatus.NOT_FOUND:
|
|
403
|
+
// No deep link available
|
|
404
|
+
break;
|
|
405
|
+
|
|
406
|
+
case AdshiftDeepLinkStatus.ERROR:
|
|
407
|
+
console.error('Deep link error:', deepLink.errorMessage);
|
|
408
|
+
break;
|
|
409
|
+
}
|
|
410
|
+
});
|
|
411
|
+
|
|
412
|
+
// Clean up when done
|
|
413
|
+
subscription.remove();
|
|
414
|
+
```
|
|
415
|
+
|
|
416
|
+
#### Handle Incoming URLs
|
|
417
|
+
|
|
418
|
+
When your app receives a URL (e.g., from `Linking` API):
|
|
419
|
+
|
|
420
|
+
```typescript
|
|
421
|
+
import { Linking } from 'react-native';
|
|
422
|
+
|
|
423
|
+
// Handle URL when app is already open
|
|
424
|
+
Linking.addEventListener('url', async ({ url }) => {
|
|
425
|
+
const result = await Adshift.handleDeepLink(url);
|
|
426
|
+
console.log('Deep link result:', result);
|
|
427
|
+
});
|
|
428
|
+
|
|
429
|
+
// Handle URL that launched the app
|
|
430
|
+
const initialUrl = await Linking.getInitialURL();
|
|
431
|
+
if (initialUrl) {
|
|
432
|
+
await Adshift.handleDeepLink(initialUrl);
|
|
433
|
+
}
|
|
434
|
+
```
|
|
435
|
+
|
|
436
|
+
#### Deep Link Response
|
|
437
|
+
|
|
438
|
+
```typescript
|
|
439
|
+
interface AdshiftDeepLink {
|
|
440
|
+
status: 'found' | 'notFound' | 'error';
|
|
441
|
+
deepLink?: string; // Full URL
|
|
442
|
+
deepLinkValue?: string; // Routing value (e.g., 'product/123')
|
|
443
|
+
deepLinkSub1?: string; // Sub-parameter 1
|
|
444
|
+
deepLinkSub2?: string; // Sub-parameter 2
|
|
445
|
+
deepLinkSub3?: string; // Sub-parameter 3
|
|
446
|
+
deepLinkSub4?: string; // Sub-parameter 4
|
|
447
|
+
deepLinkSub5?: string; // Sub-parameter 5
|
|
448
|
+
params?: Record<string, string>; // All query parameters
|
|
449
|
+
isDeferred: boolean; // true if from deferred flow
|
|
450
|
+
errorMessage?: string; // Error description
|
|
451
|
+
}
|
|
452
|
+
```
|
|
453
|
+
|
|
454
|
+
---
|
|
455
|
+
|
|
456
|
+
### Configuration
|
|
457
|
+
|
|
458
|
+
#### Set Customer User ID
|
|
459
|
+
|
|
460
|
+
Associate events with your own user identifier:
|
|
461
|
+
|
|
462
|
+
```typescript
|
|
463
|
+
Adshift.setCustomerUserId('user_12345');
|
|
464
|
+
```
|
|
465
|
+
|
|
466
|
+
> 💡 **Tip:** Set CUID before `start()` to associate it with the install event.
|
|
467
|
+
|
|
468
|
+
#### Debug Mode
|
|
469
|
+
|
|
470
|
+
```typescript
|
|
471
|
+
Adshift.setDebugEnabled(true);
|
|
472
|
+
```
|
|
473
|
+
|
|
474
|
+
#### App Open Debounce
|
|
475
|
+
|
|
476
|
+
Control how often `app_open` events are sent when the app returns from background:
|
|
477
|
+
|
|
478
|
+
```typescript
|
|
479
|
+
// Only send app_open if user was away for 30+ seconds
|
|
480
|
+
Adshift.setAppOpenDebounceMs(30000);
|
|
481
|
+
|
|
482
|
+
// Send app_open every time (no debounce)
|
|
483
|
+
Adshift.setAppOpenDebounceMs(0);
|
|
484
|
+
```
|
|
485
|
+
|
|
486
|
+
#### Get SDK Info
|
|
487
|
+
|
|
488
|
+
```typescript
|
|
489
|
+
const info = Adshift.getInfo();
|
|
490
|
+
console.log(info.platform); // 'ios' or 'android'
|
|
491
|
+
console.log(info.version); // Plugin version
|
|
492
|
+
```
|
|
493
|
+
|
|
494
|
+
---
|
|
495
|
+
|
|
496
|
+
## Platform-Specific Setup
|
|
497
|
+
|
|
498
|
+
### iOS Setup
|
|
499
|
+
|
|
500
|
+
#### 1. Update Podfile
|
|
501
|
+
|
|
502
|
+
Ensure your iOS deployment target is 15.0+:
|
|
503
|
+
|
|
504
|
+
```ruby
|
|
505
|
+
# ios/Podfile
|
|
506
|
+
platform :ios, '15.0'
|
|
507
|
+
```
|
|
508
|
+
|
|
509
|
+
Then run:
|
|
510
|
+
|
|
511
|
+
```bash
|
|
512
|
+
cd ios && pod install
|
|
513
|
+
```
|
|
514
|
+
|
|
515
|
+
#### 2. Add App Tracking Transparency (Recommended)
|
|
516
|
+
|
|
517
|
+
To request IDFA permission, add to `Info.plist`:
|
|
518
|
+
|
|
519
|
+
```xml
|
|
520
|
+
<key>NSUserTrackingUsageDescription</key>
|
|
521
|
+
<string>This app uses tracking to provide personalized ads and measure ad effectiveness.</string>
|
|
522
|
+
```
|
|
523
|
+
|
|
524
|
+
Then configure SDK to wait for ATT:
|
|
525
|
+
|
|
526
|
+
```typescript
|
|
527
|
+
Adshift.initialize({
|
|
528
|
+
apiKey: 'YOUR_API_KEY',
|
|
529
|
+
waitForATTBeforeStart: true,
|
|
530
|
+
attTimeoutMs: 30000, // 30 seconds
|
|
531
|
+
});
|
|
532
|
+
```
|
|
533
|
+
|
|
534
|
+
#### 3. Configure SKAdNetwork Postback
|
|
535
|
+
|
|
536
|
+
Add to `Info.plist` to receive direct SKAN postbacks:
|
|
537
|
+
|
|
538
|
+
```xml
|
|
539
|
+
<key>NSAdvertisingAttributionReportEndpoint</key>
|
|
540
|
+
<string>https://adshift-skadnetwork.com</string>
|
|
541
|
+
```
|
|
542
|
+
|
|
543
|
+
#### 4. Configure Universal Links (Deep Linking)
|
|
544
|
+
|
|
545
|
+
1. Add Associated Domains capability in Xcode
|
|
546
|
+
2. Add your domain: `applinks:yourapp.rightlink.me`
|
|
547
|
+
3. Configure `apple-app-site-association` on your server
|
|
548
|
+
|
|
549
|
+
For custom URL schemes, add to `Info.plist`:
|
|
550
|
+
|
|
551
|
+
```xml
|
|
552
|
+
<key>CFBundleURLTypes</key>
|
|
553
|
+
<array>
|
|
554
|
+
<dict>
|
|
555
|
+
<key>CFBundleURLSchemes</key>
|
|
556
|
+
<array>
|
|
557
|
+
<string>yourapp</string>
|
|
558
|
+
</array>
|
|
559
|
+
</dict>
|
|
560
|
+
</array>
|
|
561
|
+
```
|
|
562
|
+
|
|
563
|
+
---
|
|
564
|
+
|
|
565
|
+
### Android Setup
|
|
566
|
+
|
|
567
|
+
#### 1. Update build.gradle
|
|
568
|
+
|
|
569
|
+
Ensure minimum SDK is 21+:
|
|
570
|
+
|
|
571
|
+
```kotlin
|
|
572
|
+
// android/app/build.gradle
|
|
573
|
+
android {
|
|
574
|
+
defaultConfig {
|
|
575
|
+
minSdkVersion 21
|
|
576
|
+
}
|
|
577
|
+
}
|
|
578
|
+
```
|
|
579
|
+
|
|
580
|
+
#### 2. Permissions
|
|
581
|
+
|
|
582
|
+
These permissions are included in the SDK manifest automatically:
|
|
583
|
+
|
|
584
|
+
```xml
|
|
585
|
+
<uses-permission android:name="android.permission.INTERNET" />
|
|
586
|
+
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
|
|
587
|
+
<uses-permission android:name="com.google.android.gms.permission.AD_ID" />
|
|
588
|
+
```
|
|
589
|
+
|
|
590
|
+
To remove AD_ID permission (for COPPA compliance):
|
|
591
|
+
|
|
592
|
+
```xml
|
|
593
|
+
<uses-permission android:name="com.google.android.gms.permission.AD_ID"
|
|
594
|
+
tools:node="remove" />
|
|
595
|
+
```
|
|
596
|
+
|
|
597
|
+
#### 3. Configure App Links (Deep Linking)
|
|
598
|
+
|
|
599
|
+
Add intent filter to `AndroidManifest.xml`:
|
|
600
|
+
|
|
601
|
+
```xml
|
|
602
|
+
<activity android:name=".MainActivity">
|
|
603
|
+
<!-- Existing intent filters... -->
|
|
604
|
+
|
|
605
|
+
<!-- App Links for deep linking -->
|
|
606
|
+
<intent-filter android:autoVerify="true">
|
|
607
|
+
<action android:name="android.intent.action.VIEW" />
|
|
608
|
+
<category android:name="android.intent.category.DEFAULT" />
|
|
609
|
+
<category android:name="android.intent.category.BROWSABLE" />
|
|
610
|
+
<data
|
|
611
|
+
android:scheme="https"
|
|
612
|
+
android:host="yourapp.rightlink.me" />
|
|
613
|
+
</intent-filter>
|
|
614
|
+
|
|
615
|
+
<!-- Custom URL Scheme -->
|
|
616
|
+
<intent-filter>
|
|
617
|
+
<action android:name="android.intent.action.VIEW" />
|
|
618
|
+
<category android:name="android.intent.category.DEFAULT" />
|
|
619
|
+
<category android:name="android.intent.category.BROWSABLE" />
|
|
620
|
+
<data android:scheme="yourapp" android:host="open" />
|
|
621
|
+
</intent-filter>
|
|
622
|
+
</activity>
|
|
623
|
+
```
|
|
624
|
+
|
|
625
|
+
#### 4. ProGuard Rules (if using code shrinking)
|
|
626
|
+
|
|
627
|
+
Add to `proguard-rules.pro`:
|
|
628
|
+
|
|
629
|
+
```pro
|
|
630
|
+
# AdShift SDK
|
|
631
|
+
-keep class com.adshift.sdk.** { *; }
|
|
632
|
+
-keep interface com.adshift.sdk.** { *; }
|
|
633
|
+
```
|
|
634
|
+
|
|
635
|
+
---
|
|
636
|
+
|
|
637
|
+
## TypeScript Support
|
|
638
|
+
|
|
639
|
+
This plugin is written in TypeScript and provides full type definitions out of the box.
|
|
640
|
+
|
|
641
|
+
### Importing Types
|
|
642
|
+
|
|
643
|
+
```typescript
|
|
644
|
+
import {
|
|
645
|
+
Adshift,
|
|
646
|
+
AdshiftEventType,
|
|
647
|
+
AdshiftConsent,
|
|
648
|
+
AdshiftDeepLinkStatus,
|
|
649
|
+
} from '@adshift/react-native-plugin';
|
|
650
|
+
|
|
651
|
+
import type {
|
|
652
|
+
AdshiftConfig,
|
|
653
|
+
AdshiftDeepLink,
|
|
654
|
+
StartResult,
|
|
655
|
+
EventValues,
|
|
656
|
+
PurchaseParams,
|
|
657
|
+
DeepLinkSubscription,
|
|
658
|
+
DeepLinkCallback,
|
|
659
|
+
} from '@adshift/react-native-plugin';
|
|
660
|
+
```
|
|
661
|
+
|
|
662
|
+
### Type Definitions
|
|
663
|
+
|
|
664
|
+
```typescript
|
|
665
|
+
// Configuration
|
|
666
|
+
interface AdshiftConfig {
|
|
667
|
+
apiKey: string;
|
|
668
|
+
isDebug?: boolean;
|
|
669
|
+
appOpenDebounceMs?: number;
|
|
670
|
+
// iOS only
|
|
671
|
+
disableSKAN?: boolean;
|
|
672
|
+
waitForATTBeforeStart?: boolean;
|
|
673
|
+
attTimeoutMs?: number;
|
|
674
|
+
// Android only
|
|
675
|
+
collectOaid?: boolean;
|
|
676
|
+
}
|
|
677
|
+
|
|
678
|
+
// Event values
|
|
679
|
+
type EventValues = Record<string, string | number | boolean>;
|
|
680
|
+
|
|
681
|
+
// Purchase parameters
|
|
682
|
+
interface PurchaseParams {
|
|
683
|
+
productId: string;
|
|
684
|
+
revenue: number;
|
|
685
|
+
currency: string;
|
|
686
|
+
transactionId: string;
|
|
687
|
+
}
|
|
688
|
+
|
|
689
|
+
// Start result
|
|
690
|
+
interface StartResult {
|
|
691
|
+
success: boolean;
|
|
692
|
+
message?: string;
|
|
693
|
+
}
|
|
694
|
+
|
|
695
|
+
// Deep link callback
|
|
696
|
+
type DeepLinkCallback = (deepLink: AdshiftDeepLink) => void;
|
|
697
|
+
|
|
698
|
+
// Subscription handle
|
|
699
|
+
interface DeepLinkSubscription {
|
|
700
|
+
remove: () => void;
|
|
701
|
+
}
|
|
702
|
+
```
|
|
703
|
+
|
|
704
|
+
---
|
|
705
|
+
|
|
706
|
+
## Example App
|
|
707
|
+
|
|
708
|
+
The plugin includes a comprehensive example app demonstrating all features:
|
|
709
|
+
|
|
710
|
+
```bash
|
|
711
|
+
cd example
|
|
712
|
+
yarn install
|
|
713
|
+
cd ios && pod install && cd ..
|
|
714
|
+
|
|
715
|
+
# Run on iOS
|
|
716
|
+
yarn ios
|
|
717
|
+
|
|
718
|
+
# Run on Android
|
|
719
|
+
yarn android
|
|
720
|
+
```
|
|
721
|
+
|
|
722
|
+
The example app includes:
|
|
723
|
+
- SDK initialization and lifecycle management
|
|
724
|
+
- All event types with parameter examples
|
|
725
|
+
- Consent management UI (GDPR/TCF)
|
|
726
|
+
- Deep link testing
|
|
727
|
+
- Live event log console
|
|
728
|
+
|
|
729
|
+
---
|
|
730
|
+
|
|
731
|
+
## Troubleshooting
|
|
732
|
+
|
|
733
|
+
### iOS Issues
|
|
734
|
+
|
|
735
|
+
#### "Module 'AdshiftSDK' not found"
|
|
736
|
+
|
|
737
|
+
```bash
|
|
738
|
+
cd ios
|
|
739
|
+
pod deintegrate
|
|
740
|
+
pod install
|
|
741
|
+
```
|
|
742
|
+
|
|
743
|
+
#### ATT Dialog Not Showing
|
|
744
|
+
|
|
745
|
+
1. Ensure `NSUserTrackingUsageDescription` is in `Info.plist`
|
|
746
|
+
2. Set `waitForATTBeforeStart: true` in config
|
|
747
|
+
3. Test on physical device (simulator may not show ATT)
|
|
748
|
+
|
|
749
|
+
#### Deep Links Not Working
|
|
750
|
+
|
|
751
|
+
1. Verify Associated Domains capability is enabled
|
|
752
|
+
2. Check `apple-app-site-association` file is accessible
|
|
753
|
+
3. Test with: `xcrun simctl openurl booted "yourapp://open?test=1"`
|
|
754
|
+
|
|
755
|
+
### Android Issues
|
|
756
|
+
|
|
757
|
+
#### Build Fails with Dependency Conflicts
|
|
758
|
+
|
|
759
|
+
Add to `android/build.gradle`:
|
|
760
|
+
|
|
761
|
+
```gradle
|
|
762
|
+
allprojects {
|
|
763
|
+
configurations.all {
|
|
764
|
+
resolutionStrategy {
|
|
765
|
+
force 'com.google.android.gms:play-services-ads-identifier:18.0.1'
|
|
766
|
+
}
|
|
767
|
+
}
|
|
768
|
+
}
|
|
769
|
+
```
|
|
770
|
+
|
|
771
|
+
#### Deep Links Not Working
|
|
772
|
+
|
|
773
|
+
1. Verify intent-filter in `AndroidManifest.xml`
|
|
774
|
+
2. Check App Links verification: `adb shell pm get-app-links your.package.name`
|
|
775
|
+
3. Test with: `adb shell am start -W -a android.intent.action.VIEW -d "yourapp://open?test=1"`
|
|
776
|
+
|
|
777
|
+
### General Issues
|
|
778
|
+
|
|
779
|
+
#### Events Not Sending
|
|
780
|
+
|
|
781
|
+
1. Check `Adshift.isStarted()` returns `true`
|
|
782
|
+
2. Enable debug mode: `Adshift.setDebugEnabled(true)`
|
|
783
|
+
3. Check network connectivity
|
|
784
|
+
4. Verify API key is correct
|
|
785
|
+
|
|
786
|
+
#### TypeScript Errors
|
|
787
|
+
|
|
788
|
+
Ensure you're using TypeScript 5.0+ and have the latest types:
|
|
789
|
+
|
|
790
|
+
```bash
|
|
791
|
+
yarn add @adshift/react-native-plugin@latest
|
|
792
|
+
```
|
|
793
|
+
|
|
794
|
+
---
|
|
795
|
+
|
|
796
|
+
## Support
|
|
797
|
+
|
|
798
|
+
- 📖 **Documentation:** https://dev.adshift.com/docs/react-native-sdk
|
|
799
|
+
- 🐛 **Issues:** https://github.com/AdShift/react_native_plugin/issues
|
|
800
|
+
- 📧 **Email:** support@adshift.com
|
|
801
|
+
|
|
802
|
+
---
|
|
803
|
+
|
|
804
|
+
## License
|
|
805
|
+
|
|
806
|
+
This SDK is proprietary software. See [LICENSE](LICENSE) for details.
|
|
807
|
+
|
|
808
|
+
---
|
|
809
|
+
|
|
810
|
+
© 2024-2026 AdShift. All rights reserved.
|