@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.
Files changed (54) hide show
  1. package/AdShiftReactNativePlugin.podspec +30 -0
  2. package/LICENSE +45 -0
  3. package/README.md +810 -0
  4. package/android/build.gradle +80 -0
  5. package/android/gradle.properties +5 -0
  6. package/android/src/main/AndroidManifest.xml +2 -0
  7. package/android/src/main/java/com/adshift/reactnativeplugin/AdShiftReactNativePluginModule.kt +420 -0
  8. package/android/src/main/java/com/adshift/reactnativeplugin/AdShiftReactNativePluginPackage.kt +33 -0
  9. package/ios/AdShiftReactNativePlugin.h +24 -0
  10. package/ios/AdShiftReactNativePlugin.mm +258 -0
  11. package/ios/AdShiftReactNativePluginHelper.swift +413 -0
  12. package/lib/module/Adshift.js +468 -0
  13. package/lib/module/Adshift.js.map +1 -0
  14. package/lib/module/NativeAdShiftReactNativePlugin.js +18 -0
  15. package/lib/module/NativeAdShiftReactNativePlugin.js.map +1 -0
  16. package/lib/module/index.js +57 -0
  17. package/lib/module/index.js.map +1 -0
  18. package/lib/module/package.json +1 -0
  19. package/lib/module/types/AdshiftConfig.js +44 -0
  20. package/lib/module/types/AdshiftConfig.js.map +1 -0
  21. package/lib/module/types/AdshiftConsent.js +101 -0
  22. package/lib/module/types/AdshiftConsent.js.map +1 -0
  23. package/lib/module/types/AdshiftDeepLink.js +121 -0
  24. package/lib/module/types/AdshiftDeepLink.js.map +1 -0
  25. package/lib/module/types/AdshiftEventType.js +108 -0
  26. package/lib/module/types/AdshiftEventType.js.map +1 -0
  27. package/lib/module/types/index.js +10 -0
  28. package/lib/module/types/index.js.map +1 -0
  29. package/lib/typescript/package.json +1 -0
  30. package/lib/typescript/src/Adshift.d.ts +335 -0
  31. package/lib/typescript/src/Adshift.d.ts.map +1 -0
  32. package/lib/typescript/src/NativeAdShiftReactNativePlugin.d.ts +143 -0
  33. package/lib/typescript/src/NativeAdShiftReactNativePlugin.d.ts.map +1 -0
  34. package/lib/typescript/src/index.d.ts +47 -0
  35. package/lib/typescript/src/index.d.ts.map +1 -0
  36. package/lib/typescript/src/types/AdshiftConfig.d.ts +74 -0
  37. package/lib/typescript/src/types/AdshiftConfig.d.ts.map +1 -0
  38. package/lib/typescript/src/types/AdshiftConsent.d.ts +88 -0
  39. package/lib/typescript/src/types/AdshiftConsent.d.ts.map +1 -0
  40. package/lib/typescript/src/types/AdshiftDeepLink.d.ts +93 -0
  41. package/lib/typescript/src/types/AdshiftDeepLink.d.ts.map +1 -0
  42. package/lib/typescript/src/types/AdshiftEventType.d.ts +87 -0
  43. package/lib/typescript/src/types/AdshiftEventType.d.ts.map +1 -0
  44. package/lib/typescript/src/types/index.d.ts +5 -0
  45. package/lib/typescript/src/types/index.d.ts.map +1 -0
  46. package/package.json +143 -0
  47. package/src/Adshift.ts +539 -0
  48. package/src/NativeAdShiftReactNativePlugin.ts +177 -0
  49. package/src/index.tsx +68 -0
  50. package/src/types/AdshiftConfig.ts +108 -0
  51. package/src/types/AdshiftConsent.ts +127 -0
  52. package/src/types/AdshiftDeepLink.ts +194 -0
  53. package/src/types/AdshiftEventType.ts +135 -0
  54. package/src/types/index.ts +7 -0
package/README.md ADDED
@@ -0,0 +1,810 @@
1
+ # AdShift React Native Plugin
2
+
3
+ [![npm version](https://img.shields.io/npm/v/@adshift/react-native-plugin.svg)](https://www.npmjs.com/package/@adshift/react-native-plugin)
4
+ [![Platform](https://img.shields.io/badge/platform-iOS%20%7C%20Android-blue.svg)](https://www.npmjs.com/package/@adshift/react-native-plugin)
5
+ [![React Native](https://img.shields.io/badge/React%20Native-0.82%2B-61dafb.svg)](https://reactnative.dev/)
6
+ [![License](https://img.shields.io/badge/license-Proprietary-red.svg)](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.