@adshift/react-native-plugin 1.0.0 → 2.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.
Files changed (180) hide show
  1. package/AdShiftReactNativePlugin.podspec +11 -7
  2. package/CHANGELOG.md +138 -0
  3. package/README.md +513 -542
  4. package/android/build.gradle +17 -3
  5. package/android/consumer-rules.pro +21 -0
  6. package/android/src/main/java/com/adshift/reactnativeplugin/AdShiftReactNativePluginModule.kt +786 -229
  7. package/android/src/test/java/com/adshift/reactnativeplugin/ConsentSnapshotTest.kt +180 -0
  8. package/android/src/test/java/com/adshift/reactnativeplugin/DeepLinkDeliveryTest.kt +146 -0
  9. package/android/src/test/java/com/adshift/reactnativeplugin/InitializeOrderingTest.kt +111 -0
  10. package/android/src/test/java/com/adshift/reactnativeplugin/IntentLinkDedupTest.kt +168 -0
  11. package/android/src/test/java/com/adshift/reactnativeplugin/LaunchIntentForwardingTest.kt +106 -0
  12. package/android/src/test/java/com/adshift/reactnativeplugin/ModuleTestSupport.kt +167 -0
  13. package/android/src/test/java/com/adshift/reactnativeplugin/StartVerdictTest.kt +164 -0
  14. package/ios/AdShiftReactNativePlugin.h +7 -7
  15. package/ios/AdShiftReactNativePlugin.mm +200 -181
  16. package/ios/AdShiftReactNativePluginHelper.swift +584 -286
  17. package/ios/Core/BridgeRules.swift +82 -0
  18. package/lib/commonjs/Adshift.js +1138 -0
  19. package/lib/commonjs/Adshift.js.map +1 -0
  20. package/lib/commonjs/NativeAdShiftReactNativePlugin.js +22 -0
  21. package/lib/commonjs/NativeAdShiftReactNativePlugin.js.map +1 -0
  22. package/lib/commonjs/index.js +94 -0
  23. package/lib/commonjs/index.js.map +1 -0
  24. package/lib/commonjs/jest/index.js +164 -0
  25. package/lib/commonjs/jest/index.js.map +1 -0
  26. package/lib/commonjs/nativeSdkVersions.js +17 -0
  27. package/lib/commonjs/nativeSdkVersions.js.map +1 -0
  28. package/lib/commonjs/package.json +1 -0
  29. package/lib/commonjs/types/AdshiftAdRevenue.js +47 -0
  30. package/lib/commonjs/types/AdshiftAdRevenue.js.map +1 -0
  31. package/lib/commonjs/types/AdshiftConfig.js +45 -0
  32. package/lib/commonjs/types/AdshiftConfig.js.map +1 -0
  33. package/lib/commonjs/types/AdshiftConsent.js +113 -0
  34. package/lib/commonjs/types/AdshiftConsent.js.map +1 -0
  35. package/lib/commonjs/types/AdshiftConsentSnapshot.js +69 -0
  36. package/lib/commonjs/types/AdshiftConsentSnapshot.js.map +1 -0
  37. package/lib/commonjs/types/AdshiftDeepLink.js +154 -0
  38. package/lib/commonjs/types/AdshiftDeepLink.js.map +1 -0
  39. package/lib/commonjs/types/AdshiftError.js +91 -0
  40. package/lib/commonjs/types/AdshiftError.js.map +1 -0
  41. package/lib/commonjs/types/AdshiftEventParam.js +140 -0
  42. package/lib/commonjs/types/AdshiftEventParam.js.map +1 -0
  43. package/lib/commonjs/types/AdshiftEventType.js +88 -0
  44. package/lib/commonjs/types/AdshiftEventType.js.map +1 -0
  45. package/lib/commonjs/types/AdshiftThirdPartySharing.js +70 -0
  46. package/lib/commonjs/types/AdshiftThirdPartySharing.js.map +1 -0
  47. package/lib/commonjs/types/index.js +123 -0
  48. package/lib/commonjs/types/index.js.map +1 -0
  49. package/lib/commonjs/version.js +9 -0
  50. package/lib/commonjs/version.js.map +1 -0
  51. package/lib/module/Adshift.js +962 -296
  52. package/lib/module/Adshift.js.map +1 -1
  53. package/lib/module/NativeAdShiftReactNativePlugin.js +10 -7
  54. package/lib/module/NativeAdShiftReactNativePlugin.js.map +1 -1
  55. package/lib/module/index.js +26 -25
  56. package/lib/module/index.js.map +1 -1
  57. package/lib/module/jest/index.js +144 -0
  58. package/lib/module/jest/index.js.map +1 -0
  59. package/lib/module/nativeSdkVersions.js +13 -0
  60. package/lib/module/nativeSdkVersions.js.map +1 -0
  61. package/lib/module/types/AdshiftAdRevenue.js +43 -0
  62. package/lib/module/types/AdshiftAdRevenue.js.map +1 -0
  63. package/lib/module/types/AdshiftConfig.js +23 -26
  64. package/lib/module/types/AdshiftConfig.js.map +1 -1
  65. package/lib/module/types/AdshiftConsent.js +57 -50
  66. package/lib/module/types/AdshiftConsent.js.map +1 -1
  67. package/lib/module/types/AdshiftConsentSnapshot.js +65 -0
  68. package/lib/module/types/AdshiftConsentSnapshot.js.map +1 -0
  69. package/lib/module/types/AdshiftDeepLink.js +97 -67
  70. package/lib/module/types/AdshiftDeepLink.js.map +1 -1
  71. package/lib/module/types/AdshiftError.js +87 -0
  72. package/lib/module/types/AdshiftError.js.map +1 -0
  73. package/lib/module/types/AdshiftEventParam.js +135 -0
  74. package/lib/module/types/AdshiftEventParam.js.map +1 -0
  75. package/lib/module/types/AdshiftEventType.js +11 -36
  76. package/lib/module/types/AdshiftEventType.js.map +1 -1
  77. package/lib/module/types/AdshiftThirdPartySharing.js +65 -0
  78. package/lib/module/types/AdshiftThirdPartySharing.js.map +1 -0
  79. package/lib/module/types/index.js +9 -7
  80. package/lib/module/types/index.js.map +1 -1
  81. package/lib/module/version.js +5 -0
  82. package/lib/module/version.js.map +1 -0
  83. package/lib/typescript/commonjs/package.json +1 -0
  84. package/lib/typescript/commonjs/src/Adshift.d.ts +314 -0
  85. package/lib/typescript/commonjs/src/Adshift.d.ts.map +1 -0
  86. package/lib/typescript/commonjs/src/NativeAdShiftReactNativePlugin.d.ts +102 -0
  87. package/lib/typescript/commonjs/src/NativeAdShiftReactNativePlugin.d.ts.map +1 -0
  88. package/lib/typescript/commonjs/src/index.d.ts +51 -0
  89. package/lib/typescript/commonjs/src/index.d.ts.map +1 -0
  90. package/lib/typescript/commonjs/src/jest/index.d.ts +103 -0
  91. package/lib/typescript/commonjs/src/jest/index.d.ts.map +1 -0
  92. package/lib/typescript/commonjs/src/nativeSdkVersions.d.ts +11 -0
  93. package/lib/typescript/commonjs/src/nativeSdkVersions.d.ts.map +1 -0
  94. package/lib/typescript/commonjs/src/types/AdshiftAdRevenue.d.ts +56 -0
  95. package/lib/typescript/commonjs/src/types/AdshiftAdRevenue.d.ts.map +1 -0
  96. package/lib/typescript/commonjs/src/types/AdshiftConfig.d.ts +104 -0
  97. package/lib/typescript/commonjs/src/types/AdshiftConfig.d.ts.map +1 -0
  98. package/lib/typescript/commonjs/src/types/AdshiftConsent.d.ts +76 -0
  99. package/lib/typescript/commonjs/src/types/AdshiftConsent.d.ts.map +1 -0
  100. package/lib/typescript/commonjs/src/types/AdshiftConsentSnapshot.d.ts +56 -0
  101. package/lib/typescript/commonjs/src/types/AdshiftConsentSnapshot.d.ts.map +1 -0
  102. package/lib/typescript/commonjs/src/types/AdshiftDeepLink.d.ts +89 -0
  103. package/lib/typescript/commonjs/src/types/AdshiftDeepLink.d.ts.map +1 -0
  104. package/lib/typescript/commonjs/src/types/AdshiftError.d.ts +57 -0
  105. package/lib/typescript/commonjs/src/types/AdshiftError.d.ts.map +1 -0
  106. package/lib/typescript/commonjs/src/types/AdshiftEventParam.d.ts +111 -0
  107. package/lib/typescript/commonjs/src/types/AdshiftEventParam.d.ts.map +1 -0
  108. package/lib/typescript/{src → commonjs/src}/types/AdshiftEventType.d.ts +12 -35
  109. package/lib/typescript/commonjs/src/types/AdshiftEventType.d.ts.map +1 -0
  110. package/lib/typescript/commonjs/src/types/AdshiftThirdPartySharing.d.ts +53 -0
  111. package/lib/typescript/commonjs/src/types/AdshiftThirdPartySharing.d.ts.map +1 -0
  112. package/lib/typescript/commonjs/src/types/index.d.ts +17 -0
  113. package/lib/typescript/commonjs/src/types/index.d.ts.map +1 -0
  114. package/lib/typescript/commonjs/src/version.d.ts +2 -0
  115. package/lib/typescript/commonjs/src/version.d.ts.map +1 -0
  116. package/lib/typescript/module/src/Adshift.d.ts +314 -0
  117. package/lib/typescript/module/src/Adshift.d.ts.map +1 -0
  118. package/lib/typescript/module/src/NativeAdShiftReactNativePlugin.d.ts +102 -0
  119. package/lib/typescript/module/src/NativeAdShiftReactNativePlugin.d.ts.map +1 -0
  120. package/lib/typescript/module/src/index.d.ts +51 -0
  121. package/lib/typescript/module/src/index.d.ts.map +1 -0
  122. package/lib/typescript/module/src/jest/index.d.ts +103 -0
  123. package/lib/typescript/module/src/jest/index.d.ts.map +1 -0
  124. package/lib/typescript/module/src/nativeSdkVersions.d.ts +11 -0
  125. package/lib/typescript/module/src/nativeSdkVersions.d.ts.map +1 -0
  126. package/lib/typescript/module/src/types/AdshiftAdRevenue.d.ts +56 -0
  127. package/lib/typescript/module/src/types/AdshiftAdRevenue.d.ts.map +1 -0
  128. package/lib/typescript/module/src/types/AdshiftConfig.d.ts +104 -0
  129. package/lib/typescript/module/src/types/AdshiftConfig.d.ts.map +1 -0
  130. package/lib/typescript/module/src/types/AdshiftConsent.d.ts +76 -0
  131. package/lib/typescript/module/src/types/AdshiftConsent.d.ts.map +1 -0
  132. package/lib/typescript/module/src/types/AdshiftConsentSnapshot.d.ts +56 -0
  133. package/lib/typescript/module/src/types/AdshiftConsentSnapshot.d.ts.map +1 -0
  134. package/lib/typescript/module/src/types/AdshiftDeepLink.d.ts +89 -0
  135. package/lib/typescript/module/src/types/AdshiftDeepLink.d.ts.map +1 -0
  136. package/lib/typescript/module/src/types/AdshiftError.d.ts +57 -0
  137. package/lib/typescript/module/src/types/AdshiftError.d.ts.map +1 -0
  138. package/lib/typescript/module/src/types/AdshiftEventParam.d.ts +111 -0
  139. package/lib/typescript/module/src/types/AdshiftEventParam.d.ts.map +1 -0
  140. package/lib/typescript/module/src/types/AdshiftEventType.d.ts +64 -0
  141. package/lib/typescript/module/src/types/AdshiftEventType.d.ts.map +1 -0
  142. package/lib/typescript/module/src/types/AdshiftThirdPartySharing.d.ts +53 -0
  143. package/lib/typescript/module/src/types/AdshiftThirdPartySharing.d.ts.map +1 -0
  144. package/lib/typescript/module/src/types/index.d.ts +17 -0
  145. package/lib/typescript/module/src/types/index.d.ts.map +1 -0
  146. package/lib/typescript/module/src/version.d.ts +2 -0
  147. package/lib/typescript/module/src/version.d.ts.map +1 -0
  148. package/package.json +50 -11
  149. package/src/Adshift.ts +1276 -342
  150. package/src/NativeAdShiftReactNativePlugin.ts +81 -115
  151. package/src/index.tsx +40 -25
  152. package/src/jest/index.ts +224 -0
  153. package/src/nativeSdkVersions.ts +10 -0
  154. package/src/types/AdshiftAdRevenue.ts +58 -0
  155. package/src/types/AdshiftConfig.ts +101 -53
  156. package/src/types/AdshiftConsent.ts +75 -72
  157. package/src/types/AdshiftConsentSnapshot.ts +103 -0
  158. package/src/types/AdshiftDeepLink.ts +123 -102
  159. package/src/types/AdshiftError.ts +107 -0
  160. package/src/types/AdshiftEventParam.ts +216 -0
  161. package/src/types/AdshiftEventType.ts +13 -35
  162. package/src/types/AdshiftThirdPartySharing.ts +63 -0
  163. package/src/types/index.ts +38 -6
  164. package/src/version.ts +2 -0
  165. package/lib/typescript/src/Adshift.d.ts +0 -335
  166. package/lib/typescript/src/Adshift.d.ts.map +0 -1
  167. package/lib/typescript/src/NativeAdShiftReactNativePlugin.d.ts +0 -143
  168. package/lib/typescript/src/NativeAdShiftReactNativePlugin.d.ts.map +0 -1
  169. package/lib/typescript/src/index.d.ts +0 -47
  170. package/lib/typescript/src/index.d.ts.map +0 -1
  171. package/lib/typescript/src/types/AdshiftConfig.d.ts +0 -74
  172. package/lib/typescript/src/types/AdshiftConfig.d.ts.map +0 -1
  173. package/lib/typescript/src/types/AdshiftConsent.d.ts +0 -88
  174. package/lib/typescript/src/types/AdshiftConsent.d.ts.map +0 -1
  175. package/lib/typescript/src/types/AdshiftDeepLink.d.ts +0 -93
  176. package/lib/typescript/src/types/AdshiftDeepLink.d.ts.map +0 -1
  177. package/lib/typescript/src/types/AdshiftEventType.d.ts.map +0 -1
  178. package/lib/typescript/src/types/index.d.ts +0 -5
  179. package/lib/typescript/src/types/index.d.ts.map +0 -1
  180. /package/lib/typescript/{package.json → module/package.json} +0 -0
package/README.md CHANGED
@@ -5,799 +5,772 @@
5
5
  [![React Native](https://img.shields.io/badge/React%20Native-0.82%2B-61dafb.svg)](https://reactnative.dev/)
6
6
  [![License](https://img.shields.io/badge/license-Proprietary-red.svg)](LICENSE)
7
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.
8
+ Official AdShift SDK for React Native. The plugin wraps the native [iOS SDK](https://github.com/AdShift/ios-sdk) and [Android SDK](https://github.com/AdShift/android-sdk) behind one TypeScript API: install attribution, in-app events, ad revenue, SKAdNetwork, deep linking (direct, deferred and push) and GDPR/TCF 2.2 consent.
11
9
 
12
10
  ---
13
11
 
14
- ## 📚 Table of Contents
12
+ ## Table of Contents
15
13
 
16
- - [Features](#features)
17
14
  - [Requirements](#requirements)
18
15
  - [Installation](#installation)
19
16
  - [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)
17
+ - [Lifecycle](#lifecycle)
18
+ - [Event Tracking](#event-tracking)
19
+ - [Ad Revenue](#ad-revenue)
20
+ - [Deep Linking](#deep-linking)
21
+ - [Push Notifications](#push-notifications)
22
+ - [Consent (GDPR/DMA)](#consent-gdprdma)
23
+ - [Configuration](#configuration)
24
+ - [Errors](#errors)
25
+ - [Platform Setup](#platform-setup)
26
+ - [Store Privacy Declarations](#store-privacy-declarations)
27
+ - [Expo](#expo)
28
+ - [Testing](#testing)
29
+ - [Development Notes](#development-notes)
30
+ - [Upgrading from 1.x](#upgrading-from-1x)
30
31
  - [Example App](#example-app)
31
32
  - [Troubleshooting](#troubleshooting)
33
+ - [For Maintainers](#for-maintainers)
32
34
  - [Support](#support)
33
35
 
34
36
  ---
35
37
 
36
- ## Features
38
+ ## Requirements
37
39
 
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
40
+ | | Minimum |
41
+ |---|---|
42
+ | **React Native** | 0.82.0 (New Architecture only) |
43
+ | **iOS** | 15.1, Xcode 16.1+ |
44
+ | **Android** | API 24 (Android 7.0), `compileSdk` 35+, Kotlin 2.0+ |
45
+ | **Node.js** | 20+ (this repository is developed on the version in `.nvmrc`) |
46
+ | **TypeScript** | 5.0+ (recommended) |
47
47
 
48
- ---
48
+ Mac Catalyst and visionOS are not supported (the native iOS SDK ships iOS-only binaries).
49
49
 
50
- ## Requirements
50
+ ### Native SDK versions
51
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) |
52
+ Each plugin release pins exact native SDK versions. Do not override them in your `Podfile` or Gradle files.
59
53
 
60
- > ⚠️ **Note:** This plugin requires React Native's New Architecture (Turbo Modules). Old Architecture (Bridge) is not supported.
54
+ | Plugin | Android SDK | iOS SDK |
55
+ |---|---|---|
56
+ | 2.1.x | `com.adshift:android-sdk:3.2.0` | `AdshiftSDK 2.4.0` |
57
+ | 2.0.x | `com.adshift:android-sdk:3.1.0` | `AdshiftSDK 2.2.0` |
61
58
 
62
59
  ---
63
60
 
64
61
  ## Installation
65
62
 
66
- ### Using npm
67
-
68
63
  ```bash
69
64
  npm install @adshift/react-native-plugin
70
- ```
71
-
72
- ### Using yarn
73
-
74
- ```bash
65
+ # or
75
66
  yarn add @adshift/react-native-plugin
76
67
  ```
77
68
 
78
- ### iOS Setup (CocoaPods)
79
-
80
- After installing the npm package:
69
+ **iOS**
81
70
 
82
71
  ```bash
83
72
  cd ios && pod install
84
73
  ```
85
74
 
86
- ### Android Setup
75
+ Then add the two `RCTLinkingManager` handlers to `AppDelegate.swift` (see [Platform Setup → iOS](#ios)); the plugin relies on them to receive links while the app is running.
87
76
 
88
- No additional setup required — the plugin auto-links with React Native.
77
+ **Android** — nothing else to do; the module autolinks. See [Platform Setup → Android](#android) for backup rules and the `AD_ID` permission.
89
78
 
90
79
  ---
91
80
 
92
81
  ## Quick Start
93
82
 
94
- ### 1. Initialize the SDK
95
-
96
- > ⚠️ **Important:** iOS and Android apps have **different API keys**. Get both from your AdShift dashboard.
97
-
98
83
  ```typescript
99
- import { Platform } from 'react-native';
100
- import { Adshift } from '@adshift/react-native-plugin';
84
+ import {
85
+ Adshift,
86
+ AdshiftEventParam,
87
+ AdshiftEventType,
88
+ AdshiftConsent,
89
+ AdshiftDeepLinkStatus,
90
+ } from '@adshift/react-native-plugin';
101
91
 
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
- };
92
+ // 1. Register the deep link listener first. It is safe before initialize();
93
+ // results that arrive earlier are buffered and delivered to the first listener.
94
+ const subscription = Adshift.onDeepLink((deepLink) => {
95
+ if (deepLink.status === AdshiftDeepLinkStatus.Found) {
96
+ // route on deepLink.deepLinkValue or deepLink.params
97
+ }
98
+ });
107
99
 
108
- // Initialize in your app's entry point (App.tsx or index.js)
100
+ // 2. Initialize once, as early as possible
109
101
  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
102
+ apiKey: 'YOUR_API_KEY',
103
+ isDebug: __DEV__,
104
+ brandedDomains: ['links.yourbrand.com'],
116
105
  });
117
- ```
118
106
 
119
- ### 2. Start Tracking
107
+ // 3. Consent (every launch, before start)
108
+ Adshift.setConsentData(AdshiftConsent.forNonGDPRUser());
120
109
 
121
- ```typescript
122
- // Start the SDK (typically after user consent or app launch)
110
+ // 4. Start. Never rejects; check result.success.
123
111
  const result = await Adshift.start();
124
112
 
125
- if (result.success) {
126
- console.log('AdShift started successfully');
127
- }
113
+ // 5. Track. Calls made before start() resolves are queued and sent afterwards.
114
+ await Adshift.trackEvent(AdshiftEventType.Purchase, {
115
+ [AdshiftEventParam.Revenue]: 9.99,
116
+ [AdshiftEventParam.Currency]: 'USD',
117
+ });
118
+
119
+ // Later
120
+ subscription.remove();
128
121
  ```
129
122
 
130
- ### 3. Track Events
123
+ ---
131
124
 
132
- ```typescript
133
- import { Adshift, AdshiftEventType } from '@adshift/react-native-plugin';
125
+ ## Lifecycle
134
126
 
135
- // Track a simple event
136
- await Adshift.trackEvent(AdshiftEventType.LOGIN);
127
+ ### `Adshift.initialize(config)`
137
128
 
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
- });
129
+ Configures the SDK. Call once; the first configuration is kept and later calls are ignored. Throws `AdshiftError` with `INVALID_ARGUMENT` when `apiKey` is missing or an option is malformed.
144
130
 
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
- ```
131
+ See [`AdshiftConfig`](#adshiftconfig) for every option.
132
+
133
+ ### `Adshift.start(): Promise<StartResult>`
153
134
 
154
- ### 4. Handle Deep Links
135
+ Starts tracking. Resolves once the SDK has started locally and **never rejects**:
155
136
 
156
137
  ```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 />;
138
+ interface StartResult {
139
+ success: boolean;
140
+ apiKeyValidationStatus?: 'pending' | 'valid' | 'invalid';
141
+ errorCode?: AdshiftErrorCode; // when success is false
142
+ errorMessage?: string;
180
143
  }
181
144
  ```
182
145
 
183
- ---
146
+ - The API key is verified with the AdShift backend in the background. `apiKeyValidationStatus` is the verdict at the moment `start()` resolved: `valid`, `invalid`, or `pending` while the answer is not in. `config.onError` reports `INVALID_API_KEY` when `start()` itself returns `invalid`. On iOS the verdict usually arrives after `start()` resolved, so a rejected key is reported by the next `start()`; on Android `start()` waits up to 5 s for it. Events tracked meanwhile stay queued on the device by the native SDK.
147
+ - A device excluded from tracking resolves `{ success: false, errorCode: 'OPTED_OUT' }`.
148
+ - On iOS `start()` resolves after the local set-up and does not wait for the ATT decision or the SKAdNetwork configuration. With `waitForATTBeforeStart` the native SDK records events as usual and holds their delivery until the ATT decision, up to `attTimeoutMs`.
149
+ - Calling `start()` again while started resolves `{ success: true }` immediately. Calling it before `initialize()` resolves `{ success: false, errorCode: 'NOT_INITIALIZED' }`.
150
+ - Everything queued with `trackEvent`, `trackPurchase` and `logAdRevenue` between `initialize()` and a successful `start()` is dispatched in order when `start()` succeeds. If the start failed for a reason retrying cannot fix — `INVALID_API_KEY`, `OPTED_OUT`, `NOT_INITIALIZED` — the queued promises reject with that code. If it failed for any other reason, they keep waiting for the next `start()`, so the data survives a start that failed while the device was offline. Queued promises stay pending until some `start()` finishes, which is why `start()` belongs on every launch path.
184
151
 
185
- ## API Reference
152
+ ### `Adshift.stop(): void`
186
153
 
187
- ### SDK Lifecycle
154
+ Pauses delivery. Tracking calls reject with `NOT_STARTED` until the next successful `start()`. This is not an opt-out; opt-out is configured on the AdShift side.
188
155
 
189
- #### `Adshift.initialize(config)`
156
+ Deep link forwarding keeps working after `stop()`: a link that opens the app still reaches the SDK, so attribution of that click is not lost, and the SDK decides what to do with it while delivery is paused. Configuration setters and `refreshConsent()` also keep working, so consent changes apply while delivery is paused. Calls queued before the interrupted `start()` reject with `NOT_STARTED`.
190
157
 
191
- Configure the SDK. Call this before any other SDK method.
158
+ ### `Adshift.isStarted(): boolean`
192
159
 
193
- > ⚠️ **Note:** iOS and Android apps require **separate API keys** from the AdShift dashboard.
160
+ `true` between a successful `start()` and `stop()`. Safe before `initialize()`. Reflects the JavaScript side: after a JS reload in development or an OTA update the native SDK may still be running while `isStarted()` returns `false` — call `start()` again.
194
161
 
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
- ```
162
+ ### `Adshift.getAdShiftDeviceId(): Promise<string | null>`
215
163
 
216
- #### `Adshift.start()`
164
+ The AdShift device identifier; `null` before `initialize()`.
217
165
 
218
- Start the SDK and begin tracking. Returns a promise with the result.
166
+ ### `Adshift.getInfo()`
219
167
 
220
168
  ```typescript
221
- const result = await Adshift.start();
222
- // result: { success: boolean, message?: string }
169
+ { platform: 'ios' | 'android', version: '2.1.0', nativeSdkVersions: { android: '3.2.0', ios: '2.4.0' } }
223
170
  ```
224
171
 
225
- #### `Adshift.stop()`
172
+ ---
226
173
 
227
- Stop the SDK. Events will not be tracked until `start()` is called again.
174
+ ## Event Tracking
175
+
176
+ ### `Adshift.trackEvent(eventName, values?): Promise<void>`
228
177
 
229
178
  ```typescript
230
- Adshift.stop();
179
+ await Adshift.trackEvent(AdshiftEventType.AddToCart, {
180
+ [AdshiftEventParam.ContentId]: 'SKU123',
181
+ [AdshiftEventParam.Price]: 29.99,
182
+ in_stock: true, // custom parameters are fine alongside the standard ones
183
+ });
184
+ await Adshift.trackEvent('custom_event');
231
185
  ```
232
186
 
233
- #### `Adshift.isStarted()`
187
+ `values` accepts strings, numbers and booleans (no nested objects). The promise resolves once the SDK has accepted the event; delivery is asynchronous and survives offline periods. Rejections use [`AdshiftError`](#errors).
188
+
189
+ `app_install` and `app_open` are reserved — the SDK sends them itself, so passing them here rejects with `INVALID_ARGUMENT` instead of adding hand-made records to your install and session counts.
234
190
 
235
- Check if the SDK is currently running.
191
+ ### `Adshift.trackPurchase(params): Promise<void>`
236
192
 
237
193
  ```typescript
238
- const isRunning = Adshift.isStarted(); // boolean
194
+ await Adshift.trackPurchase({
195
+ productId: 'premium_monthly',
196
+ revenue: 9.99,
197
+ currency: 'USD',
198
+ transactionId: 'GPA.1234-5678-9012-34567',
199
+ });
239
200
  ```
240
201
 
241
- ---
202
+ ### Predefined event types
242
203
 
243
- ### Event Tracking
204
+ `AdshiftEventType` exposes 30 standard events:
244
205
 
245
- #### `Adshift.trackEvent(eventName, values?)`
206
+ | Category | Constants |
207
+ |---|---|
208
+ | E-commerce | `AddToCart`, `AddToWishList`, `AddPaymentInfo`, `InitiatedCheckout`, `Purchase`, `ContentView`, `ListView`, `Search` |
209
+ | User lifecycle | `CompleteRegistration`, `Login`, `TutorialCompletion`, `Subscribe`, `StartTrial` |
210
+ | Gaming | `LevelAchieved`, `AchievementUnlocked`, `SpentCredit` |
211
+ | Engagement | `Rate`, `Share`, `Invite`, `ReEngage`, `Update`, `OpenedFromPushNotification` |
212
+ | Travel | `TravelBooking` |
213
+ | Ads | `AdClick`, `AdView`, `AdRevenue` |
214
+ | Location | `LocationChanged`, `LocationCoordinates` |
215
+ | Other | `OrderId`, `CustomerSegment` |
246
216
 
247
- Track an in-app event with optional parameters.
217
+ `getAllEventTypes()` returns the wire names as an array.
248
218
 
249
- ```typescript
250
- // Simple event
251
- await Adshift.trackEvent(AdshiftEventType.LOGIN);
219
+ ### Standard parameter names
252
220
 
253
- // Event with parameters
254
- await Adshift.trackEvent(AdshiftEventType.SEARCH, {
255
- search_term: 'running shoes',
256
- results_count: 42,
257
- });
221
+ `AdshiftEventParam` holds the 81 parameter names reports aggregate — the same set the native SDKs expose. Use them for anything that has to be counted, revenue above all:
258
222
 
259
- // Custom event
260
- await Adshift.trackEvent('custom_button_click', {
261
- button_name: 'checkout',
223
+ ```typescript
224
+ await Adshift.trackEvent(AdshiftEventType.Purchase, {
225
+ [AdshiftEventParam.Revenue]: 9.99,
226
+ [AdshiftEventParam.Currency]: 'USD',
227
+ [AdshiftEventParam.Quantity]: 1,
228
+ gift_wrapped: true,
262
229
  });
263
230
  ```
264
231
 
265
- #### `Adshift.trackPurchase(params)`
232
+ Any other key is stored with the event as a custom parameter, so `revenue: 9.99` arrives intact but is not counted as revenue. Nothing is rewritten for you: in development the plugin warns once per name when a value looks like a standard parameter spelled the plain way (`price`, `contentId`, `latitude`) and tells you which constant to use. `getAllEventParams()` returns the whole set as an array.
233
+
234
+ `trackPurchase()` and `logAdRevenue()` need none of this — they fill the revenue and currency names from their own arguments.
235
+
236
+ ---
266
237
 
267
- Track a purchase event. Use this for accurate SKAdNetwork conversion value calculation.
238
+ ## Ad Revenue
239
+
240
+ ### `Adshift.logAdRevenue(params): Promise<void>`
268
241
 
269
242
  ```typescript
270
- await Adshift.trackPurchase({
271
- productId: 'com.app.premium',
272
- revenue: 9.99, // Use 'revenue' for SKAN CV calculation
243
+ import { AdshiftMediationNetwork } from '@adshift/react-native-plugin';
244
+
245
+ await Adshift.logAdRevenue({
246
+ monetizationNetwork: 'admob',
247
+ mediationNetwork: AdshiftMediationNetwork.GoogleAdMob,
273
248
  currency: 'USD',
274
- transactionId: 'txn_123',
249
+ revenue: 0.0125,
250
+ adUnitId: 'ca-app-pub-1234/5678', // optional
251
+ precision: 'estimated', // optional
252
+ additionalParameters: { placement: 'home_banner' }, // optional
275
253
  });
276
254
  ```
277
255
 
278
- > 💡 **Tip:** Use `revenue` (not `price`) for accurate SKAdNetwork attribution.
256
+ `mediationNetwork` must be an `AdshiftMediationNetwork` value (`AppLovinMAX`, `GoogleAdMob`, `IronSource`, `Chartboost`, `TopOn`, `TradPlus`, `AdMost`, `Appodeal`, `Fyber`, `Unity`, `Yandex`, `CustomMediation`, `DirectMonetization`, `Other`). `revenue` is the value of one impression and must be positive; the native SDKs drop implausibly large per-impression amounts (above 10 in the given currency unit, regardless of currency).
279
257
 
280
- #### Predefined Event Types
258
+ ---
281
259
 
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
- ```
260
+ ## Deep Linking
316
261
 
317
- ---
262
+ ### The contract
318
263
 
319
- ### Consent Management
264
+ - Every link that opens the app and reaches the SDK — direct, deferred (first launch after install) and push — produces exactly one `onDeepLink` result.
265
+ - `status === 'found'` means the link was delivered; it does **not** mean it is an attribution link. Route on `deepLinkValue`, `params` or the URL and ignore links you do not care about.
266
+ - Results are delivered only through `onDeepLink`. `handleDeepLink()` and `handlePushNotification()` resolve when the SDK has accepted the input.
320
267
 
321
- #### Manual Consent (GDPR/DMA)
268
+ ### `Adshift.onDeepLink(callback): DeepLinkSubscription`
322
269
 
323
270
  ```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
- );
271
+ useEffect(() => {
272
+ const subscription = Adshift.onDeepLink((deepLink) => {
273
+ if (deepLink.status !== AdshiftDeepLinkStatus.Found) return;
274
+ if (deepLink.deepLinkValue === 'product') {
275
+ navigate('Product', { id: deepLink.params?.product_id });
276
+ }
277
+ });
278
+ return () => subscription.remove();
279
+ }, []);
280
+ ```
334
281
 
335
- // For GDPR users — deny consent
336
- Adshift.setConsentData(
337
- AdshiftConsent.forGDPRUser({
338
- hasConsentForDataUsage: false,
339
- hasConsentForAdsPersonalization: false,
340
- hasConsentForAdStorage: false,
341
- })
342
- );
282
+ - Safe before `initialize()`. Up to 20 results that arrive while no listener is registered are buffered and replayed to the first listener. When the buffer is full a direct result is dropped before a deferred one, because a deferred result cannot be produced again.
283
+ - Listeners are called on the JS thread; an exception in one listener does not affect the others. `remove()` is idempotent.
343
284
 
344
- // For non-GDPR users (e.g., US users without state privacy laws)
345
- Adshift.setConsentData(AdshiftConsent.forNonGDPRUser());
285
+ ```typescript
286
+ interface AdshiftDeepLink {
287
+ deepLink?: string; // the URL
288
+ deepLinkValue?: string; // deep_link_value for routing
289
+ params?: Record<string, string>; // query parameters
290
+ isDeferred: boolean; // first launch after install
291
+ isFirstSession?: boolean; // Android only, on every result
292
+ status: AdshiftDeepLinkStatus; // Found | NotFound | Error
293
+ errorMessage?: string; // with Error; wording differs per platform
294
+ deepLinkSub1?: string; /* … */ deepLinkSub5?: string;
295
+ }
346
296
  ```
347
297
 
348
- #### TCF 2.2 Automatic Collection
298
+ ### Automatic forwarding (default)
349
299
 
350
- If you use a CMP (Consent Management Platform) that stores IAB TCF data:
300
+ With `autoHandleDeepLinks: true` (the default) you write no linking code:
351
301
 
352
- ```typescript
353
- // Enable TCF collection BEFORE calling start()
354
- Adshift.enableTCFDataCollection(true);
302
+ - **Android** — the plugin reads the launch Intent and every new Intent (App Links, custom schemes, push taps that carry `as_push_link`). Relaunches from Recents and the launcher are not re-processed.
303
+ - **iOS** — the plugin uses React Native's `Linking` (`getInitialURL` and the `url` event). Your `AppDelegate.swift` must forward URLs to `RCTLinkingManager` (see [Platform Setup → iOS](#ios)); without it links opened while the app is running never reach JavaScript.
355
304
 
356
- // Start SDK after CMP dialog completes
357
- await Adshift.start();
305
+ `start()` waits (up to 3 s) for the launch URL to be handed to the SDK, so the first `app_open` carries the click parameters.
358
306
 
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
- ```
307
+ ### Manual forwarding
364
308
 
365
- #### Consent Snapshot Response
309
+ Set `autoHandleDeepLinks: false` and forward URLs yourself:
366
310
 
367
311
  ```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
- }
312
+ await Adshift.handleDeepLink(url); // resolves once accepted; result arrives via onDeepLink
378
313
  ```
379
314
 
315
+ Rejects with `NOT_INITIALIZED` or `INVALID_ARGUMENT` (empty or malformed URL). If you keep an old `Linking → handleDeepLink` handler while automatic forwarding is on, the plugin ignores a URL it forwarded itself within the previous two seconds, so nothing is counted twice.
316
+
317
+ ### Deferred deep links
318
+
319
+ On the first launch after install the SDK resolves the deferred deep link (if the user clicked an AdShift link before installing) and delivers it through `onDeepLink` with `isDeferred: true`. Nothing to configure.
320
+
380
321
  ---
381
322
 
382
- ### Deep Linking
323
+ ## Push Notifications
383
324
 
384
- #### Listen for Deep Links
325
+ The SDK reads an AdShift link from a push payload under the top-level key `as_push_link`. Register your own key paths with `pushDeepLinkPaths` in `initialize()` or `Adshift.addPushNotificationDeepLinkPath(['data', 'link'])` — they are searched in the order you register them.
385
326
 
386
- Subscribe to deep link events for both direct and deferred deep links:
327
+ Registering your own paths takes over from `as_push_link`. If your payloads use both, list it explicitly:
387
328
 
388
329
  ```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();
330
+ pushDeepLinkPaths: [['data', 'link'], ['as_push_link']],
414
331
  ```
415
332
 
416
- #### Handle Incoming URLs
417
-
418
- When your app receives a URL (e.g., from `Linking` API):
333
+ - **Android** — a tap on a notification whose Intent carries the payload extras is handled automatically (with `autoHandleDeepLinks`).
334
+ - **iOS**, or when you build the notification yourself — hand the payload over:
419
335
 
420
336
  ```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);
337
+ // @react-native-firebase/messaging
338
+ messaging().onNotificationOpenedApp((message) => {
339
+ Adshift.handlePushNotification(message.data ?? {});
427
340
  });
341
+ const initial = await messaging().getInitialNotification();
342
+ if (initial) await Adshift.handlePushNotification(initial.data ?? {});
428
343
 
429
- // Handle URL that launched the app
430
- const initialUrl = await Linking.getInitialURL();
431
- if (initialUrl) {
432
- await Adshift.handleDeepLink(initialUrl);
433
- }
344
+ // notifee
345
+ notifee.onForegroundEvent(({ type, detail }) => {
346
+ if (type === EventType.PRESS) Adshift.handlePushNotification(detail.notification?.data ?? {});
347
+ });
434
348
  ```
435
349
 
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
- ```
350
+ `handlePushNotification` resolves `true` when the payload carried an AdShift link (the result arrives through `onDeepLink`). Only taps should be forwarded, not deliveries. Call it before `start()` when the payload is known at launch, so the first `app_open` carries the push parameters.
453
351
 
454
352
  ---
455
353
 
456
- ### Configuration
354
+ ## Consent (GDPR/DMA)
457
355
 
458
- #### Set Customer User ID
356
+ Set consent on every launch, before `start()`, and again whenever the user changes it.
459
357
 
460
- Associate events with your own user identifier:
358
+ ### Manual consent
461
359
 
462
360
  ```typescript
463
- Adshift.setCustomerUserId('user_12345');
361
+ // User subject to GDPR; omitted flags are "not decided" and are not sent
362
+ Adshift.setConsentData(
363
+ AdshiftConsent.forGDPRUser({
364
+ hasConsentForDataUsage: true,
365
+ hasConsentForAdsPersonalization: false,
366
+ hasConsentForAdStorage: true,
367
+ })
368
+ );
369
+
370
+ // User not subject to GDPR: everything is permitted, individual flags are not sent
371
+ Adshift.setConsentData(AdshiftConsent.forNonGDPRUser());
464
372
  ```
465
373
 
466
- > 💡 **Tip:** Set CUID before `start()` to associate it with the install event.
374
+ Each flag is `boolean | null` (`ConsentFlag`). `AdshiftConsent.isConsentGranted(consent)` applies the SDK rule (non-GDPR → granted; GDPR → data usage **and** ad storage must be `true`).
467
375
 
468
- #### Debug Mode
376
+ ### TCF 2.2 / CMP
469
377
 
470
378
  ```typescript
471
- Adshift.setDebugEnabled(true);
379
+ Adshift.enableTCFDataCollection(true); // before start()
380
+ await Adshift.start();
381
+
382
+ // after the CMP dialog closes
383
+ const snapshot: ConsentSnapshot = await Adshift.refreshConsent();
472
384
  ```
473
385
 
474
- #### App Open Debounce
386
+ ### GPP (US state privacy)
475
387
 
476
- Control how often `app_open` events are sent when the app returns from background:
388
+ Two independent axes. `enableGPPDataCollection` forwards the IAB GPP string the
389
+ CMP wrote, alongside whatever decides the GDPR axis — including a consent set
390
+ through `setConsentData()`. It does not gate the advertising identifier on the
391
+ device; a US opt-out limits what may be done with an event afterwards.
477
392
 
478
393
  ```typescript
479
- // Only send app_open if user was away for 30+ seconds
480
- Adshift.setAppOpenDebounceMs(30000);
394
+ Adshift.enableGPPDataCollection(true); // before start()
395
+ await Adshift.start();
396
+
397
+ // after the CMP writes its GPP string
398
+ const snapshot = await Adshift.refreshConsent();
399
+ snapshot.gppPresent; // true once a GPP string is on the device
400
+ ```
401
+
402
+ ### Third-party sharing
403
+
404
+ A third axis, and the one with the opposite default: nothing said here means
405
+ sharing is allowed. So state it only once the user has actually been asked — a
406
+ `allowed()` set at startup as a default records a declaration the user never
407
+ made, and events already sent cannot be recalled when a real answer arrives.
408
+
409
+ ```typescript
410
+ // The user asked not to have their data passed on
411
+ Adshift.setThirdPartySharing(AdshiftThirdPartySharing.optedOut());
412
+
413
+ // The user was asked and did not opt out
414
+ Adshift.setThirdPartySharing(AdshiftThirdPartySharing.allowed());
481
415
 
482
- // Send app_open every time (no debounce)
483
- Adshift.setAppOpenDebounceMs(0);
416
+ // Back to having no answer on record, which is not the same as `allowed()`
417
+ Adshift.clearThirdPartySharing();
484
418
  ```
485
419
 
486
- #### Get SDK Info
420
+ Nothing is gated on the device either way; the answer travels with the events.
487
421
 
488
422
  ```typescript
489
- const info = Adshift.getInfo();
490
- console.log(info.platform); // 'ios' or 'android'
491
- console.log(info.version); // Plugin version
423
+ interface ConsentSnapshot {
424
+ source: 'manual' | 'tcf' | 'gpp' | 'none';
425
+ gdprApplies?: number;
426
+ tcStringPresent: boolean;
427
+ gppPresent?: boolean;
428
+ cmpDetected: boolean;
429
+ adUserDataEnabled?: boolean;
430
+ adPersonalizationEnabled?: boolean;
431
+ adStorageEnabled?: boolean;
432
+ appliedAtMillis: number;
433
+ adIdentifiersAllowed: boolean;
434
+ }
492
435
  ```
493
436
 
437
+ `source` names what decided the GDPR axis, where manual outranks TCF. It is not a
438
+ ranking across all three axes: a GPP string and a sharing answer ride alongside
439
+ whatever `source` says, and neither is displaced by calling `setConsentData()`.
440
+
441
+ `cmpDetected` separates the two states nothing else here can tell apart. A CMP
442
+ installed but not yet answered looks identical to no CMP at all, and the two are
443
+ fixed by opposite actions: `false` when you expect a CMP means it never ran or was
444
+ never wired up, while `true` with `source: 'none'` means it ran and the user has
445
+ not answered yet, which resolves itself once they do.
446
+
447
+ `adIdentifiersAllowed` answers whether consent lets the SDK attach the advertising identifier (GAID or OAID on Android, IDFA on iOS) to what it reports; the `adshift_device_id` is never affected. Both ad storage and ad user data have to be allowed, and each platform applies that to the flags its own way — under GDPR an undecided flag counts as a refusal on Android, while iOS refuses only on an explicit denial. Read this field instead of comparing the flags yourself.
448
+
494
449
  ---
495
450
 
496
- ## Platform-Specific Setup
451
+ ## Configuration
497
452
 
498
- ### iOS Setup
453
+ ### `AdshiftConfig`
499
454
 
500
- #### 1. Update Podfile
455
+ | Option | Type | Default | Notes |
456
+ |---|---|---|---|
457
+ | `apiKey` | `string` | — | Required |
458
+ | `isDebug` | `boolean` | SDK default | Verbose native logging |
459
+ | `appOpenDebounceMs` | `number` | `10000` | Debounce for automatic `app_open` |
460
+ | `brandedDomains` | `string[]` | — | Custom attribution domains |
461
+ | `metaAppId` | `string` | — | Meta App Links parsing (Android) |
462
+ | `pushDeepLinkPaths` | `string[][]` | `[['as_push_link']]` | Extra key paths in push payloads |
463
+ | `autoHandleDeepLinks` | `boolean` | `true` | Automatic URL forwarding |
464
+ | `disableSKAN` | `boolean` | `false` | iOS |
465
+ | `waitForATTBeforeStart` | `boolean` | `false` | iOS; only when **your app** shows the ATT prompt |
466
+ | `attTimeoutMs` | `number` | `30000` | iOS; clamped to 5 000–120 000 |
467
+ | `collectOaid` | `boolean` | `true` | Android; OAID on devices without Google Play services |
501
468
 
502
- Ensure your iOS deployment target is 15.0+:
469
+ Only options you set are passed to the native SDK; everything else keeps the SDK default.
503
470
 
504
- ```ruby
505
- # ios/Podfile
506
- platform :ios, '15.0'
507
- ```
471
+ ### Runtime setters
508
472
 
509
- Then run:
473
+ None of these raise. A value that fails validation is skipped and reported (see
474
+ [Errors](#errors)), and a call made before `initialize()` is kept and applied
475
+ afterwards, so setup code does not depend on call order.
510
476
 
511
- ```bash
512
- cd ios && pod install
477
+ ```typescript
478
+ Adshift.setCustomerUserId('user_123'); // before or after start()
479
+ Adshift.setDebugEnabled(true);
480
+ Adshift.setAppOpenDebounceMs(5000);
481
+ Adshift.setBrandedDomains(['links.yourbrand.com']); // before start()
482
+ Adshift.setMetaAppId('1234567890'); // Android; no-op on iOS
483
+ Adshift.setOaidData(oaidFromYourOwnCode); // Android; no-op on iOS
484
+ Adshift.addPushNotificationDeepLinkPath(['data', 'deep_link']);
513
485
  ```
514
486
 
515
- #### 2. Add App Tracking Transparency (Recommended)
487
+ ---
516
488
 
517
- To request IDFA permission, add to `Info.plist`:
489
+ ## Errors
518
490
 
519
- ```xml
520
- <key>NSUserTrackingUsageDescription</key>
521
- <string>This app uses tracking to provide personalized ads and measure ad effectiveness.</string>
522
- ```
491
+ **The plugin never raises into your code.** Methods that return a promise reject
492
+ with an `AdshiftError`; methods that return nothing skip the call and report it,
493
+ because an error thrown from an event handler or a native callback would take
494
+ down the app instead of the call. Nothing the plugin does can crash your app.
523
495
 
524
- Then configure SDK to wait for ATT:
496
+ Failures the plugin cannot answer with a rejected promise are reported on two
497
+ channels: the console in development, and `config.onError` in every build.
525
498
 
526
499
  ```typescript
527
500
  Adshift.initialize({
528
- apiKey: 'YOUR_API_KEY',
529
- waitForATTBeforeStart: true,
530
- attTimeoutMs: 30000, // 30 seconds
501
+ apiKey: 'your-api-key',
502
+ onError: (error) => {
503
+ // Integration mistakes, a config the plugin refused, a rejected API key.
504
+ Sentry.captureMessage(`AdShift: ${error.code} ${error.message}`);
505
+ },
531
506
  });
532
507
  ```
533
508
 
534
- #### 3. Configure SKAdNetwork Postback
509
+ Every rejected promise and every report is an `AdshiftError`:
535
510
 
536
- Add to `Info.plist` to receive direct SKAN postbacks:
537
-
538
- ```xml
539
- <key>NSAdvertisingAttributionReportEndpoint</key>
540
- <string>https://adshift-skadnetwork.com</string>
511
+ ```typescript
512
+ import { AdshiftErrorCode, isAdshiftError } from '@adshift/react-native-plugin';
513
+
514
+ try {
515
+ await Adshift.trackEvent('x');
516
+ } catch (error) {
517
+ if (isAdshiftError(error)) {
518
+ error.code; // AdshiftErrorCode
519
+ error.message;
520
+ error.userInfo.nativeCode; // raw native code, when available
521
+ error.userInfo.nativeDomain; // iOS NSError domain, when available
522
+ }
523
+ }
541
524
  ```
542
525
 
543
- #### 4. Configure Universal Links (Deep Linking)
526
+ | Code | Meaning |
527
+ |---|---|
528
+ | `NOT_INITIALIZED` | `initialize()` has not been called |
529
+ | `NOT_STARTED` | `stop()` was called; call `start()` |
530
+ | `INVALID_API_KEY` | The backend rejected the API key |
531
+ | `OPTED_OUT` | Tracking is disabled for this app on the AdShift side |
532
+ | `QUEUE_FULL` | More than 100 calls are waiting for `start()`, or the Android SDK refused the call because its own queue is full |
533
+ | `INVALID_ARGUMENT` | A parameter failed validation |
534
+ | `UNKNOWN` | Anything else; see `userInfo.nativeCode` |
544
535
 
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
536
+ `start()` never rejects; it reports these codes in `StartResult.errorCode`.
548
537
 
549
- For custom URL schemes, add to `Info.plist`:
538
+ ---
550
539
 
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
- ```
540
+ ## Platform Setup
562
541
 
563
- ---
542
+ ### iOS
564
543
 
565
- ### Android Setup
544
+ **1. Deployment target** — `platform :ios, '15.1'` or higher in `ios/Podfile` (React Native 0.82 already requires this). The plugin builds with the default static libraries, `use_frameworks! :linkage => :static` and dynamic frameworks.
566
545
 
567
- #### 1. Update build.gradle
546
+ **2. `AppDelegate.swift`** — forward URLs to React Native so `Linking` (and the plugin) receive them. The bare React Native template does not include these methods; **Expo projects need none of this** (see [Expo](#expo)):
568
547
 
569
- Ensure minimum SDK is 21+:
548
+ ```swift
549
+ import React
570
550
 
571
- ```kotlin
572
- // android/app/build.gradle
573
- android {
574
- defaultConfig {
575
- minSdkVersion 21
576
- }
551
+ // inside class AppDelegate
552
+
553
+ func application(
554
+ _ app: UIApplication,
555
+ open url: URL,
556
+ options: [UIApplication.OpenURLOptionsKey: Any] = [:]
557
+ ) -> Bool {
558
+ return RCTLinkingManager.application(app, open: url, options: options)
559
+ }
560
+
561
+ func application(
562
+ _ application: UIApplication,
563
+ continue userActivity: NSUserActivity,
564
+ restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void
565
+ ) -> Bool {
566
+ return RCTLinkingManager.application(
567
+ application,
568
+ continue: userActivity,
569
+ restorationHandler: restorationHandler
570
+ )
577
571
  }
578
572
  ```
579
573
 
580
- #### 2. Permissions
574
+ **3. Universal Links and custom schemes** — add the Associated Domains capability (`applinks:yourapp.rightlink.me` or your branded domain) and, for custom schemes, `CFBundleURLTypes` in `Info.plist`.
581
575
 
582
- These permissions are included in the SDK manifest automatically:
576
+ **4. App Tracking Transparency** — if your app shows the ATT prompt, add `NSUserTrackingUsageDescription` to `Info.plist` and set `waitForATTBeforeStart: true`; event delivery then waits for the decision up to `attTimeoutMs`, while `start()` resolves right away. If your app does not prompt, leave the option off.
577
+
578
+ **5. SKAdNetwork and AdAttributionKit postbacks** — add to `Info.plist`:
583
579
 
584
580
  ```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" />
581
+ <key>NSAdvertisingAttributionReportEndpoint</key>
582
+ <string>https://adshift.com</string>
583
+ <key>AttributionCopyEndpoint</key>
584
+ <string>https://adshift.com</string>
585
+ <key>EligibleForAdAttributionKitReengagementPostbackCopies</key>
586
+ <true/>
588
587
  ```
589
588
 
590
- To remove AD_ID permission (for COPPA compliance):
589
+ `NSAdvertisingAttributionReportEndpoint` sends AdShift copies of the SKAdNetwork postbacks, `AttributionCopyEndpoint` copies of the AdAttributionKit install postbacks (iOS 17.4 and later), and the boolean adds the re-engagement copies.
591
590
 
592
- ```xml
593
- <uses-permission android:name="com.google.android.gms.permission.AD_ID"
594
- tools:node="remove" />
595
- ```
591
+ The native SDK ships its own privacy manifest; the plugin adds no tracked APIs. For what to put in App Store Connect, see [Store Privacy Declarations](#store-privacy-declarations).
592
+
593
+ **6. Pod linkage** — the plugin is built in all three CocoaPods linkage modes: the React Native default, where pods are static libraries, plus `use_frameworks! :linkage => :static` and `use_frameworks! :linkage => :dynamic`. Nothing extra is needed on your side for any of them.
596
594
 
597
- #### 3. Configure App Links (Deep Linking)
595
+ ### Android
598
596
 
599
- Add intent filter to `AndroidManifest.xml`:
597
+ **1. Requirements** — `minSdkVersion 24`, `compileSdkVersion 35+`.
598
+
599
+ **2. Dependencies brought by the native SDK** — `okhttp 4.12`, `retrofit 2.9`, `gson 2.10`, `installreferrer 2.2`, `play-services-ads-identifier 18.0.1`, `androidx.lifecycle:lifecycle-process`. Gradle resolves conflicts to the highest version; if you pin `okhttp` lower than 4.12 in your app, raise it.
600
+
601
+ **3. Permissions** — the SDK manifest declares `INTERNET`, `ACCESS_NETWORK_STATE` and `com.google.android.gms.permission.AD_ID`, plus two permissions and a set of `<queries>` entries used to read the OAID on devices without Google Play services. All of them merge into your app. Apps in the Families program, and any app directed to children under COPPA, must remove `AD_ID`:
600
602
 
601
603
  ```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>
604
+ <uses-permission android:name="com.google.android.gms.permission.AD_ID" tools:node="remove" />
623
605
  ```
624
606
 
625
- #### 4. ProGuard Rules (if using code shrinking)
607
+ Without that permission the advertising id is no longer read, and attribution continues on the SDK's own install identifier. The OAID permissions and queries can be removed the same way — see the [Android SDK README](https://github.com/AdShift/android-sdk#permissions).
626
608
 
627
- Add to `proguard-rules.pro`:
609
+ **4. Backup rules** — the SDK manifest sets `android:fullBackupContent` and `android:dataExtractionRules` on `<application>` so its identifiers are never restored on a new install. The React Native template (`android:allowBackup="false"`, no rules attribute) merges cleanly. If your app declares its own rules attributes, the build fails with a manifest merger conflict: add `tools:replace` for the attributes you declare **and** copy the SDK's exclusions into your rules files — see the [Android SDK README, "Backup Rules"](https://github.com/AdShift/android-sdk#backup-rules).
628
610
 
629
- ```pro
630
- # AdShift SDK
631
- -keep class com.adshift.sdk.** { *; }
632
- -keep interface com.adshift.sdk.** { *; }
633
- ```
611
+ **5. App Links** — add the intent filters for your branded domain / custom scheme to `MainActivity`; `launchMode="singleTask"` (the template default) is recommended. No JavaScript code is needed.
612
+
613
+ **6. Code shrinking** — the native SDK ships consumer ProGuard rules, so `minifyEnabled true` needs no keep rules of your own, and release builds with shrinking enabled are part of our build checks. Those rules keep the SDK's public API and its wire models and leave the rest to R8, so SDK frames in crash reports arrive obfuscated; upload your release `mapping.txt`. Do not add `-keep class com.adshift.sdk.** { *; }` — it is not needed and forces the whole native SDK into the APK unshrunk.
614
+
615
+ **7. Devices without Google Play services** — the SDK reads the OAID itself when `collectOaid` is on (the default). If your app already obtains it, pass it with `Adshift.setOaidData(oaid)` and set `collectOaid: false`.
634
616
 
635
617
  ---
636
618
 
637
- ## TypeScript Support
619
+ ## Store Privacy Declarations
638
620
 
639
- This plugin is written in TypeScript and provides full type definitions out of the box.
621
+ Both stores ask the publisher to declare what the app collects, and that includes what the SDK sends on your behalf. The plugin itself collects nothing: it forwards calls to the native SDK. The tables below say which declarations follow from installing the SDK and which ones only apply if your app makes a particular call. The wording of your forms is yours to decide — this is the input, not the answer.
640
622
 
641
- ### Importing Types
623
+ **Always sent, once the SDK starts**
642
624
 
643
- ```typescript
644
- import {
645
- Adshift,
646
- AdshiftEventType,
647
- AdshiftConsent,
648
- AdshiftDeepLinkStatus,
649
- } from '@adshift/react-native-plugin';
625
+ | What | Apple App Privacy | Google Play Data safety |
626
+ | --- | --- | --- |
627
+ | The SDK's install identifier, the vendor identifier on iOS, and the advertising id when consent and platform settings allow it | Identifiers → Device ID | Device or other IDs |
628
+ | Installs, app opens and foreground time | Usage Data → Product Interaction | App activity → App interactions |
629
+ | Device model, OS version, language, carrier, connection type | Usage Data | App info and performance |
630
+ | The opening URL when the app is launched from a link | Usage Data → Other Usage Data | App activity → Other actions |
631
+ | The consent state you reported, including the IAB TC string when one is present, and the ATT status on iOS | Usage Data → Other Usage Data | App info and performance |
650
632
 
651
- import type {
652
- AdshiftConfig,
653
- AdshiftDeepLink,
654
- StartResult,
655
- EventValues,
656
- PurchaseParams,
657
- DeepLinkSubscription,
658
- DeepLinkCallback,
659
- } from '@adshift/react-native-plugin';
660
- ```
633
+ **Only if your app calls it**
661
634
 
662
- ### Type Definitions
635
+ | Your call | Apple App Privacy | Google Play Data safety |
636
+ | --- | --- | --- |
637
+ | `setCustomerUserId` | Identifiers → User ID | Personal info → User IDs |
638
+ | `trackPurchase` | Purchases → Purchase History | Financial info → Purchase history |
639
+ | `logAdRevenue` | Usage Data → Advertising Data | App activity → Other actions |
640
+ | `trackEvent` with your own parameters | depends on what you put in them | depends on what you put in them |
663
641
 
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
- }
642
+ Notes that decide several rows for you:
677
643
 
678
- // Event values
679
- type EventValues = Record<string, string | number | boolean>;
644
+ - **The advertising id is optional in practice.** On Android it is read only while the `AD_ID` permission is present (see [Platform Setup → Android](#android)); on iOS only after the user allows tracking through ATT. Removing the permission, or never showing the ATT prompt, keeps the identifier out of your declaration — attribution continues on the SDK's own install identifier, which is still collected.
645
+ - **Consent gates it too.** When you report a refusal through the consent API, the advertising id is withheld; `Adshift.refreshConsent()` returns `adIdentifiersAllowed` so you can see the current answer.
646
+ - **No location is collected.** No location permission or API is used. The country reported by the SDK comes from the device's region setting.
647
+ - **Custom event parameters are yours.** Whatever you pass to `trackEvent` is sent as you wrote it, so anything personal in there belongs in your declaration.
648
+ - **Opening URLs are forwarded whole**, including links that have nothing to do with a campaign, for as long as `autoHandleDeepLinks` is on. If your links can carry personal data in their parameters, either keep it out of them or turn the option off and pass only the links you choose with `Adshift.handleDeepLink(url)`.
649
+ - **Everything travels over HTTPS.**
680
650
 
681
- // Purchase parameters
682
- interface PurchaseParams {
683
- productId: string;
684
- revenue: number;
685
- currency: string;
686
- transactionId: string;
687
- }
651
+ Whether your app's data counts as "shared" under Play's definition, and whether the identifiers are used for tracking under Apple's definition, depends on your agreement with AdShift rather than on the SDK — settle those two with us before you submit.
688
652
 
689
- // Start result
690
- interface StartResult {
691
- success: boolean;
692
- message?: string;
693
- }
653
+ ---
694
654
 
695
- // Deep link callback
696
- type DeepLinkCallback = (deepLink: AdshiftDeepLink) => void;
655
+ ## Expo
697
656
 
698
- // Subscription handle
699
- interface DeepLinkSubscription {
700
- remove: () => void;
701
- }
702
- ```
657
+ The plugin contains native code, so it works with **development builds / prebuild** (`expo run:ios`, `expo run:android`, EAS Build) and not with Expo Go.
703
658
 
704
- ---
659
+ No config plugin is needed, and neither is any native edit:
705
660
 
706
- ## Example App
661
+ - Autolinking and codegen pick the module up.
662
+ - Expo forwards opened URLs and universal links to React Native's `Linking` itself, so skip step 2 of the [iOS setup](#ios) — the generated `AppDelegate.swift` is regenerated by `expo prebuild` anyway.
663
+ - Everything else belongs in `app.json`: `ios.associatedDomains` for universal links, `ios.infoPlist` for `NSUserTrackingUsageDescription` and the three postback keys from step 5, `android.intentFilters` for App Links, and `scheme` for a custom scheme.
707
664
 
708
- The plugin includes a comprehensive example app demonstrating all features:
665
+ An OTA update via Expo Updates reloads JavaScript — see [Development Notes](#development-notes).
709
666
 
710
- ```bash
711
- cd example
712
- yarn install
713
- cd ios && pod install && cd ..
667
+ ---
668
+
669
+ ## Testing
714
670
 
715
- # Run on iOS
716
- yarn ios
671
+ The package resolves its native module at import time, which fails in a plain Jest environment. Use the bundled mock:
717
672
 
718
- # Run on Android
719
- yarn android
673
+ ```js
674
+ // jest.setup.js
675
+ jest.mock('@adshift/react-native-plugin', () =>
676
+ require('@adshift/react-native-plugin/jest').createAdshiftMock()
677
+ );
720
678
  ```
721
679
 
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
680
+ Every method is a `jest.fn()` with a sensible resolved default; `Adshift.__emitDeepLink(deepLink)` delivers a deep link to registered listeners and `Adshift.__reset()` clears state. The mock exports the same helpers as the package (`AdshiftConsent`, `AdshiftDeepLink`, `AdshiftEventType`, …).
681
+
682
+ The package ships both ES module and CommonJS builds, so the default `react-native` Jest preset loads it without changes to `transformIgnorePatterns`.
728
683
 
729
684
  ---
730
685
 
731
- ## Troubleshooting
686
+ ## Development Notes
732
687
 
733
- ### iOS Issues
688
+ - **JS reload (Fast Refresh, Dev Menu reload, `DevSettings.reload()`, Expo Updates / CodePush)** recreates the JavaScript module: the deep link buffer and the pending-call queue are empty, `isStarted()` is `false` until you call `start()` again, and `initialize()` accepts the configuration again. The native SDK keeps running; deep links tapped after the reload are still delivered to the new JavaScript instance.
689
+ - **Debug logging** — `isDebug: true` (or `setDebugEnabled(true)`) turns on the native SDK's verbose logs (Logcat tags `AdShiftSDK` and `AdShiftRN` on Android, the unified log on iOS). The plugin never logs URLs or event values.
734
690
 
735
- #### "Module 'AdshiftSDK' not found"
691
+ ---
692
+
693
+ ## Upgrading from 1.x
694
+
695
+ 2.x targets Android SDK 3.2.0 and iOS SDK 2.4.0 (see [Native SDK versions](#native-sdk-versions)) and is a breaking release.
696
+
697
+ **Removed**
698
+ - `NativeAdShiftReactNativePlugin` and `AdShiftNativeSpec` exports — the native module is internal.
699
+ - `configToMap`, `consentToMap`, `deepLinkToMap` exports — internal bridge helpers with no use outside the plugin. If you called them, drop the call: the plugin converts its own arguments.
700
+ - `StartResult.message`.
701
+
702
+ **Changed**
703
+ - `start()` resolves `{ success, apiKeyValidationStatus?, errorCode?, errorMessage? }` after the *local* start and no longer waits for API key verification. It never rejects.
704
+ - `handleDeepLink(url)` returns `Promise<void>`; the result arrives through `onDeepLink`. Register `onDeepLink` before `initialize()` to be sure nothing is missed (results are buffered anyway).
705
+ - No method raises any more. Promises still reject; the rest report through `config.onError` and skip the call. Remove `try/catch` around `initialize()` and the setters, and read `onError` instead.
706
+ - Setters called before `initialize()` are kept and applied afterwards instead of failing.
707
+ - Deep links are forwarded automatically by default (`autoHandleDeepLinks`). Remove your `Linking.addEventListener('url', …) → handleDeepLink` code, or keep it — the plugin deduplicates its own forwards. On iOS add the `RCTLinkingManager` handlers to `AppDelegate.swift`.
708
+ - Consent flags are tri-state (`boolean | null`); `AdshiftConsent.forGDPRUser()` accepts partial input and `forNonGDPRUser()` sends no individual flags. `AdshiftConsent.isConsentGranted` requires explicit `true`.
709
+ - `refreshConsent()` resolves a typed `ConsentSnapshot`.
710
+ - `AdshiftDeepLink.params` is `Record<string, string>`; `isFirstSession` added (Android).
711
+ - `trackEvent`/`trackPurchase` calls before `start()` are queued (up to 100) instead of failing; after `stop()` they reject with `NOT_STARTED`.
712
+ - All errors are `AdshiftError` with `code` from `AdshiftErrorCode`; native codes moved to `userInfo.nativeCode`.
713
+ - `getInfo()` returns the real plugin version and `nativeSdkVersions`.
714
+ - Minimum iOS is 15.1; Android `minSdk` 24.
715
+
716
+ **Added**
717
+ - `logAdRevenue()`, `AdshiftMediationNetwork`, `AdshiftEventType.AdRevenue`.
718
+ - `getAdShiftDeviceId()`, `setBrandedDomains()`, `setMetaAppId()`, `addPushNotificationDeepLinkPath()`, `handlePushNotification()`.
719
+ - `AdshiftConfig.brandedDomains`, `metaAppId`, `pushDeepLinkPaths`, `autoHandleDeepLinks`, `onError`.
720
+ - `AdshiftErrorCode`, `isAdshiftError`, `PLUGIN_VERSION`, `ConsentSnapshot`, `ConsentFlag`.
721
+ - Jest mock at `@adshift/react-native-plugin/jest`.
722
+
723
+ ---
724
+
725
+ ## Example App
736
726
 
737
727
  ```bash
738
- cd ios
739
- pod deintegrate
740
- pod install
728
+ yarn
729
+ cd example/ios && bundle install && bundle exec pod install && cd ../..
730
+ yarn example ios # or: yarn example android
741
731
  ```
742
732
 
743
- #### ATT Dialog Not Showing
733
+ Replace `API_KEYS` in `example/src/App.tsx` with keys from the AdShift dashboard. The app demonstrates lifecycle, queueing before `start()`, events, ad revenue, consent, deep links (automatic, manual and push payloads) and error reporting.
744
734
 
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)
735
+ ---
748
736
 
749
- #### Deep Links Not Working
737
+ ## Troubleshooting
750
738
 
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"`
739
+ **Links do not arrive on iOS while the app is running** — add the `RCTLinkingManager` methods to `AppDelegate.swift` ([Platform Setup → iOS](#ios)).
754
740
 
755
- ### Android Issues
741
+ **A link is delivered twice on iOS** — you forward URLs manually from `Linking` while `autoHandleDeepLinks` is on and the second call arrives more than two seconds after the first. Remove your handler or set `autoHandleDeepLinks: false`.
756
742
 
757
- #### Build Fails with Dependency Conflicts
743
+ **The first events on iOS arrive late** — `waitForATTBeforeStart: true` without an ATT prompt holds their delivery for `attTimeoutMs`. Set the option only when your app actually prompts.
758
744
 
759
- Add to `android/build.gradle`:
745
+ **Manifest merger conflict on `fullBackupContent` / `dataExtractionRules`** — see [Android backup rules](#android).
760
746
 
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
- ```
747
+ **`TurboModuleRegistry.getEnforcing(...): 'AdShiftReactNativePlugin' could not be found`** — the app runs the old architecture or was not rebuilt after installing the package. Rebuild with the New Architecture enabled (default since React Native 0.76; the only mode since 0.82).
770
748
 
771
- #### Deep Links Not Working
749
+ **Jest fails at import** — register the mock from [Testing](#testing).
772
750
 
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"`
751
+ **Events are not sent** — check `start()` resolved with `success: true`, enable `isDebug` and read the native logs; a rejected API key shows up as `apiKeyValidationStatus: 'invalid'` and through `config.onError` as `INVALID_API_KEY`, on iOS usually from the next `start()`.
776
752
 
777
- ### General Issues
778
-
779
- #### Events Not Sending
753
+ ---
780
754
 
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
755
+ ## For Maintainers
785
756
 
786
- #### TypeScript Errors
757
+ **Release**
758
+ 1. Update `CHANGELOG.md` (including the native SDK matrix row) and the pins (`android/build.gradle`, `AdShiftReactNativePlugin.podspec`, `NATIVE_SDK_VERSIONS` in `src/Adshift.ts`).
759
+ 2. `yarn version <new version>` regenerates `src/version.ts`; commit.
760
+ 3. Push a tag: `v2.0.0-rc.1` publishes to the `next` dist-tag, `v2.0.0` to `latest`. The workflow fails if the tag does not match `package.json`.
761
+ 4. Publishing uses npm **trusted publishing** (OIDC) from `.github/workflows/publish.yml`; no npm token is stored in the repository. The package's trusted publisher on npmjs.com must point at this repository and workflow file.
787
762
 
788
- Ensure you're using TypeScript 5.0+ and have the latest types:
763
+ **Verification before GA** — an RC must run through the manual device test plan in a fresh RN 0.82+ app and at least one real application on `@adshift/react-native-plugin@next`.
789
764
 
790
- ```bash
791
- yarn add @adshift/react-native-plugin@latest
792
- ```
765
+ **Rollback** — never `npm unpublish`. Deprecate the faulty version (`npm deprecate @adshift/react-native-plugin@x.y.z "…"`) and publish a fixed patch. A defect in a native SDK is fixed by a plugin patch release with a bumped pin.
793
766
 
794
767
  ---
795
768
 
796
769
  ## Support
797
770
 
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
771
+ - Documentation: https://dev.adshift.com/docs/react-native-plugin
772
+ - Issues: https://github.com/AdShift/react_native_plugin/issues
773
+ - Email: support@adshift.com
801
774
 
802
775
  ---
803
776
 
@@ -805,6 +778,4 @@ yarn add @adshift/react-native-plugin@latest
805
778
 
806
779
  This SDK is proprietary software. See [LICENSE](LICENSE) for details.
807
780
 
808
- ---
809
-
810
781
  © 2024-2026 AdShift. All rights reserved.