@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.
- package/AdShiftReactNativePlugin.podspec +11 -7
- package/CHANGELOG.md +138 -0
- package/README.md +513 -542
- package/android/build.gradle +17 -3
- package/android/consumer-rules.pro +21 -0
- package/android/src/main/java/com/adshift/reactnativeplugin/AdShiftReactNativePluginModule.kt +786 -229
- package/android/src/test/java/com/adshift/reactnativeplugin/ConsentSnapshotTest.kt +180 -0
- package/android/src/test/java/com/adshift/reactnativeplugin/DeepLinkDeliveryTest.kt +146 -0
- package/android/src/test/java/com/adshift/reactnativeplugin/InitializeOrderingTest.kt +111 -0
- package/android/src/test/java/com/adshift/reactnativeplugin/IntentLinkDedupTest.kt +168 -0
- package/android/src/test/java/com/adshift/reactnativeplugin/LaunchIntentForwardingTest.kt +106 -0
- package/android/src/test/java/com/adshift/reactnativeplugin/ModuleTestSupport.kt +167 -0
- package/android/src/test/java/com/adshift/reactnativeplugin/StartVerdictTest.kt +164 -0
- package/ios/AdShiftReactNativePlugin.h +7 -7
- package/ios/AdShiftReactNativePlugin.mm +200 -181
- package/ios/AdShiftReactNativePluginHelper.swift +584 -286
- package/ios/Core/BridgeRules.swift +82 -0
- package/lib/commonjs/Adshift.js +1138 -0
- package/lib/commonjs/Adshift.js.map +1 -0
- package/lib/commonjs/NativeAdShiftReactNativePlugin.js +22 -0
- package/lib/commonjs/NativeAdShiftReactNativePlugin.js.map +1 -0
- package/lib/commonjs/index.js +94 -0
- package/lib/commonjs/index.js.map +1 -0
- package/lib/commonjs/jest/index.js +164 -0
- package/lib/commonjs/jest/index.js.map +1 -0
- package/lib/commonjs/nativeSdkVersions.js +17 -0
- package/lib/commonjs/nativeSdkVersions.js.map +1 -0
- package/lib/commonjs/package.json +1 -0
- package/lib/commonjs/types/AdshiftAdRevenue.js +47 -0
- package/lib/commonjs/types/AdshiftAdRevenue.js.map +1 -0
- package/lib/commonjs/types/AdshiftConfig.js +45 -0
- package/lib/commonjs/types/AdshiftConfig.js.map +1 -0
- package/lib/commonjs/types/AdshiftConsent.js +113 -0
- package/lib/commonjs/types/AdshiftConsent.js.map +1 -0
- package/lib/commonjs/types/AdshiftConsentSnapshot.js +69 -0
- package/lib/commonjs/types/AdshiftConsentSnapshot.js.map +1 -0
- package/lib/commonjs/types/AdshiftDeepLink.js +154 -0
- package/lib/commonjs/types/AdshiftDeepLink.js.map +1 -0
- package/lib/commonjs/types/AdshiftError.js +91 -0
- package/lib/commonjs/types/AdshiftError.js.map +1 -0
- package/lib/commonjs/types/AdshiftEventParam.js +140 -0
- package/lib/commonjs/types/AdshiftEventParam.js.map +1 -0
- package/lib/commonjs/types/AdshiftEventType.js +88 -0
- package/lib/commonjs/types/AdshiftEventType.js.map +1 -0
- package/lib/commonjs/types/AdshiftThirdPartySharing.js +70 -0
- package/lib/commonjs/types/AdshiftThirdPartySharing.js.map +1 -0
- package/lib/commonjs/types/index.js +123 -0
- package/lib/commonjs/types/index.js.map +1 -0
- package/lib/commonjs/version.js +9 -0
- package/lib/commonjs/version.js.map +1 -0
- package/lib/module/Adshift.js +962 -296
- package/lib/module/Adshift.js.map +1 -1
- package/lib/module/NativeAdShiftReactNativePlugin.js +10 -7
- package/lib/module/NativeAdShiftReactNativePlugin.js.map +1 -1
- package/lib/module/index.js +26 -25
- package/lib/module/index.js.map +1 -1
- package/lib/module/jest/index.js +144 -0
- package/lib/module/jest/index.js.map +1 -0
- package/lib/module/nativeSdkVersions.js +13 -0
- package/lib/module/nativeSdkVersions.js.map +1 -0
- package/lib/module/types/AdshiftAdRevenue.js +43 -0
- package/lib/module/types/AdshiftAdRevenue.js.map +1 -0
- package/lib/module/types/AdshiftConfig.js +23 -26
- package/lib/module/types/AdshiftConfig.js.map +1 -1
- package/lib/module/types/AdshiftConsent.js +57 -50
- package/lib/module/types/AdshiftConsent.js.map +1 -1
- package/lib/module/types/AdshiftConsentSnapshot.js +65 -0
- package/lib/module/types/AdshiftConsentSnapshot.js.map +1 -0
- package/lib/module/types/AdshiftDeepLink.js +97 -67
- package/lib/module/types/AdshiftDeepLink.js.map +1 -1
- package/lib/module/types/AdshiftError.js +87 -0
- package/lib/module/types/AdshiftError.js.map +1 -0
- package/lib/module/types/AdshiftEventParam.js +135 -0
- package/lib/module/types/AdshiftEventParam.js.map +1 -0
- package/lib/module/types/AdshiftEventType.js +11 -36
- package/lib/module/types/AdshiftEventType.js.map +1 -1
- package/lib/module/types/AdshiftThirdPartySharing.js +65 -0
- package/lib/module/types/AdshiftThirdPartySharing.js.map +1 -0
- package/lib/module/types/index.js +9 -7
- package/lib/module/types/index.js.map +1 -1
- package/lib/module/version.js +5 -0
- package/lib/module/version.js.map +1 -0
- package/lib/typescript/commonjs/package.json +1 -0
- package/lib/typescript/commonjs/src/Adshift.d.ts +314 -0
- package/lib/typescript/commonjs/src/Adshift.d.ts.map +1 -0
- package/lib/typescript/commonjs/src/NativeAdShiftReactNativePlugin.d.ts +102 -0
- package/lib/typescript/commonjs/src/NativeAdShiftReactNativePlugin.d.ts.map +1 -0
- package/lib/typescript/commonjs/src/index.d.ts +51 -0
- package/lib/typescript/commonjs/src/index.d.ts.map +1 -0
- package/lib/typescript/commonjs/src/jest/index.d.ts +103 -0
- package/lib/typescript/commonjs/src/jest/index.d.ts.map +1 -0
- package/lib/typescript/commonjs/src/nativeSdkVersions.d.ts +11 -0
- package/lib/typescript/commonjs/src/nativeSdkVersions.d.ts.map +1 -0
- package/lib/typescript/commonjs/src/types/AdshiftAdRevenue.d.ts +56 -0
- package/lib/typescript/commonjs/src/types/AdshiftAdRevenue.d.ts.map +1 -0
- package/lib/typescript/commonjs/src/types/AdshiftConfig.d.ts +104 -0
- package/lib/typescript/commonjs/src/types/AdshiftConfig.d.ts.map +1 -0
- package/lib/typescript/commonjs/src/types/AdshiftConsent.d.ts +76 -0
- package/lib/typescript/commonjs/src/types/AdshiftConsent.d.ts.map +1 -0
- package/lib/typescript/commonjs/src/types/AdshiftConsentSnapshot.d.ts +56 -0
- package/lib/typescript/commonjs/src/types/AdshiftConsentSnapshot.d.ts.map +1 -0
- package/lib/typescript/commonjs/src/types/AdshiftDeepLink.d.ts +89 -0
- package/lib/typescript/commonjs/src/types/AdshiftDeepLink.d.ts.map +1 -0
- package/lib/typescript/commonjs/src/types/AdshiftError.d.ts +57 -0
- package/lib/typescript/commonjs/src/types/AdshiftError.d.ts.map +1 -0
- package/lib/typescript/commonjs/src/types/AdshiftEventParam.d.ts +111 -0
- package/lib/typescript/commonjs/src/types/AdshiftEventParam.d.ts.map +1 -0
- package/lib/typescript/{src → commonjs/src}/types/AdshiftEventType.d.ts +12 -35
- package/lib/typescript/commonjs/src/types/AdshiftEventType.d.ts.map +1 -0
- package/lib/typescript/commonjs/src/types/AdshiftThirdPartySharing.d.ts +53 -0
- package/lib/typescript/commonjs/src/types/AdshiftThirdPartySharing.d.ts.map +1 -0
- package/lib/typescript/commonjs/src/types/index.d.ts +17 -0
- package/lib/typescript/commonjs/src/types/index.d.ts.map +1 -0
- package/lib/typescript/commonjs/src/version.d.ts +2 -0
- package/lib/typescript/commonjs/src/version.d.ts.map +1 -0
- package/lib/typescript/module/src/Adshift.d.ts +314 -0
- package/lib/typescript/module/src/Adshift.d.ts.map +1 -0
- package/lib/typescript/module/src/NativeAdShiftReactNativePlugin.d.ts +102 -0
- package/lib/typescript/module/src/NativeAdShiftReactNativePlugin.d.ts.map +1 -0
- package/lib/typescript/module/src/index.d.ts +51 -0
- package/lib/typescript/module/src/index.d.ts.map +1 -0
- package/lib/typescript/module/src/jest/index.d.ts +103 -0
- package/lib/typescript/module/src/jest/index.d.ts.map +1 -0
- package/lib/typescript/module/src/nativeSdkVersions.d.ts +11 -0
- package/lib/typescript/module/src/nativeSdkVersions.d.ts.map +1 -0
- package/lib/typescript/module/src/types/AdshiftAdRevenue.d.ts +56 -0
- package/lib/typescript/module/src/types/AdshiftAdRevenue.d.ts.map +1 -0
- package/lib/typescript/module/src/types/AdshiftConfig.d.ts +104 -0
- package/lib/typescript/module/src/types/AdshiftConfig.d.ts.map +1 -0
- package/lib/typescript/module/src/types/AdshiftConsent.d.ts +76 -0
- package/lib/typescript/module/src/types/AdshiftConsent.d.ts.map +1 -0
- package/lib/typescript/module/src/types/AdshiftConsentSnapshot.d.ts +56 -0
- package/lib/typescript/module/src/types/AdshiftConsentSnapshot.d.ts.map +1 -0
- package/lib/typescript/module/src/types/AdshiftDeepLink.d.ts +89 -0
- package/lib/typescript/module/src/types/AdshiftDeepLink.d.ts.map +1 -0
- package/lib/typescript/module/src/types/AdshiftError.d.ts +57 -0
- package/lib/typescript/module/src/types/AdshiftError.d.ts.map +1 -0
- package/lib/typescript/module/src/types/AdshiftEventParam.d.ts +111 -0
- package/lib/typescript/module/src/types/AdshiftEventParam.d.ts.map +1 -0
- package/lib/typescript/module/src/types/AdshiftEventType.d.ts +64 -0
- package/lib/typescript/module/src/types/AdshiftEventType.d.ts.map +1 -0
- package/lib/typescript/module/src/types/AdshiftThirdPartySharing.d.ts +53 -0
- package/lib/typescript/module/src/types/AdshiftThirdPartySharing.d.ts.map +1 -0
- package/lib/typescript/module/src/types/index.d.ts +17 -0
- package/lib/typescript/module/src/types/index.d.ts.map +1 -0
- package/lib/typescript/module/src/version.d.ts +2 -0
- package/lib/typescript/module/src/version.d.ts.map +1 -0
- package/package.json +50 -11
- package/src/Adshift.ts +1276 -342
- package/src/NativeAdShiftReactNativePlugin.ts +81 -115
- package/src/index.tsx +40 -25
- package/src/jest/index.ts +224 -0
- package/src/nativeSdkVersions.ts +10 -0
- package/src/types/AdshiftAdRevenue.ts +58 -0
- package/src/types/AdshiftConfig.ts +101 -53
- package/src/types/AdshiftConsent.ts +75 -72
- package/src/types/AdshiftConsentSnapshot.ts +103 -0
- package/src/types/AdshiftDeepLink.ts +123 -102
- package/src/types/AdshiftError.ts +107 -0
- package/src/types/AdshiftEventParam.ts +216 -0
- package/src/types/AdshiftEventType.ts +13 -35
- package/src/types/AdshiftThirdPartySharing.ts +63 -0
- package/src/types/index.ts +38 -6
- package/src/version.ts +2 -0
- package/lib/typescript/src/Adshift.d.ts +0 -335
- package/lib/typescript/src/Adshift.d.ts.map +0 -1
- package/lib/typescript/src/NativeAdShiftReactNativePlugin.d.ts +0 -143
- package/lib/typescript/src/NativeAdShiftReactNativePlugin.d.ts.map +0 -1
- package/lib/typescript/src/index.d.ts +0 -47
- package/lib/typescript/src/index.d.ts.map +0 -1
- package/lib/typescript/src/types/AdshiftConfig.d.ts +0 -74
- package/lib/typescript/src/types/AdshiftConfig.d.ts.map +0 -1
- package/lib/typescript/src/types/AdshiftConsent.d.ts +0 -88
- package/lib/typescript/src/types/AdshiftConsent.d.ts.map +0 -1
- package/lib/typescript/src/types/AdshiftDeepLink.d.ts +0 -93
- package/lib/typescript/src/types/AdshiftDeepLink.d.ts.map +0 -1
- package/lib/typescript/src/types/AdshiftEventType.d.ts.map +0 -1
- package/lib/typescript/src/types/index.d.ts +0 -5
- package/lib/typescript/src/types/index.d.ts.map +0 -1
- /package/lib/typescript/{package.json → module/package.json} +0 -0
package/README.md
CHANGED
|
@@ -5,799 +5,772 @@
|
|
|
5
5
|
[](https://reactnative.dev/)
|
|
6
6
|
[](LICENSE)
|
|
7
7
|
|
|
8
|
-
Official AdShift SDK for React Native.
|
|
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
|
-
##
|
|
12
|
+
## Table of Contents
|
|
15
13
|
|
|
16
|
-
- [Features](#features)
|
|
17
14
|
- [Requirements](#requirements)
|
|
18
15
|
- [Installation](#installation)
|
|
19
16
|
- [Quick Start](#quick-start)
|
|
20
|
-
- [
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
- [
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
- [
|
|
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
|
-
##
|
|
38
|
+
## Requirements
|
|
37
39
|
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
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
|
-
|
|
50
|
+
### Native SDK versions
|
|
51
51
|
|
|
52
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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 {
|
|
100
|
-
|
|
84
|
+
import {
|
|
85
|
+
Adshift,
|
|
86
|
+
AdshiftEventParam,
|
|
87
|
+
AdshiftEventType,
|
|
88
|
+
AdshiftConsent,
|
|
89
|
+
AdshiftDeepLinkStatus,
|
|
90
|
+
} from '@adshift/react-native-plugin';
|
|
101
91
|
|
|
102
|
-
//
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
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
|
|
100
|
+
// 2. Initialize once, as early as possible
|
|
109
101
|
Adshift.initialize({
|
|
110
|
-
apiKey:
|
|
111
|
-
|
|
112
|
-
|
|
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
|
-
|
|
107
|
+
// 3. Consent (every launch, before start)
|
|
108
|
+
Adshift.setConsentData(AdshiftConsent.forNonGDPRUser());
|
|
120
109
|
|
|
121
|
-
|
|
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
|
-
|
|
126
|
-
|
|
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
|
-
|
|
123
|
+
---
|
|
131
124
|
|
|
132
|
-
|
|
133
|
-
import { Adshift, AdshiftEventType } from '@adshift/react-native-plugin';
|
|
125
|
+
## Lifecycle
|
|
134
126
|
|
|
135
|
-
|
|
136
|
-
await Adshift.trackEvent(AdshiftEventType.LOGIN);
|
|
127
|
+
### `Adshift.initialize(config)`
|
|
137
128
|
|
|
138
|
-
|
|
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
|
-
|
|
146
|
-
|
|
147
|
-
|
|
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
|
-
|
|
135
|
+
Starts tracking. Resolves once the SDK has started locally and **never rejects**:
|
|
155
136
|
|
|
156
137
|
```typescript
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
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
|
-
|
|
152
|
+
### `Adshift.stop(): void`
|
|
186
153
|
|
|
187
|
-
|
|
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
|
-
|
|
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
|
-
|
|
158
|
+
### `Adshift.isStarted(): boolean`
|
|
192
159
|
|
|
193
|
-
|
|
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
|
-
|
|
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
|
-
|
|
164
|
+
The AdShift device identifier; `null` before `initialize()`.
|
|
217
165
|
|
|
218
|
-
|
|
166
|
+
### `Adshift.getInfo()`
|
|
219
167
|
|
|
220
168
|
```typescript
|
|
221
|
-
|
|
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
|
-
|
|
172
|
+
---
|
|
226
173
|
|
|
227
|
-
|
|
174
|
+
## Event Tracking
|
|
175
|
+
|
|
176
|
+
### `Adshift.trackEvent(eventName, values?): Promise<void>`
|
|
228
177
|
|
|
229
178
|
```typescript
|
|
230
|
-
Adshift.
|
|
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
|
-
|
|
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
|
-
|
|
191
|
+
### `Adshift.trackPurchase(params): Promise<void>`
|
|
236
192
|
|
|
237
193
|
```typescript
|
|
238
|
-
|
|
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
|
-
|
|
204
|
+
`AdshiftEventType` exposes 30 standard events:
|
|
244
205
|
|
|
245
|
-
|
|
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
|
-
|
|
217
|
+
`getAllEventTypes()` returns the wire names as an array.
|
|
248
218
|
|
|
249
|
-
|
|
250
|
-
// Simple event
|
|
251
|
-
await Adshift.trackEvent(AdshiftEventType.LOGIN);
|
|
219
|
+
### Standard parameter names
|
|
252
220
|
|
|
253
|
-
|
|
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
|
-
|
|
260
|
-
await Adshift.trackEvent(
|
|
261
|
-
|
|
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
|
-
|
|
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
|
-
|
|
238
|
+
## Ad Revenue
|
|
239
|
+
|
|
240
|
+
### `Adshift.logAdRevenue(params): Promise<void>`
|
|
268
241
|
|
|
269
242
|
```typescript
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
258
|
+
---
|
|
281
259
|
|
|
282
|
-
|
|
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
|
-
|
|
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
|
-
|
|
268
|
+
### `Adshift.onDeepLink(callback): DeepLinkSubscription`
|
|
322
269
|
|
|
323
270
|
```typescript
|
|
324
|
-
|
|
325
|
-
|
|
326
|
-
|
|
327
|
-
|
|
328
|
-
|
|
329
|
-
|
|
330
|
-
|
|
331
|
-
|
|
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
|
-
|
|
336
|
-
|
|
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
|
-
|
|
345
|
-
|
|
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
|
-
|
|
298
|
+
### Automatic forwarding (default)
|
|
349
299
|
|
|
350
|
-
|
|
300
|
+
With `autoHandleDeepLinks: true` (the default) you write no linking code:
|
|
351
301
|
|
|
352
|
-
|
|
353
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
309
|
+
Set `autoHandleDeepLinks: false` and forward URLs yourself:
|
|
366
310
|
|
|
367
311
|
```typescript
|
|
368
|
-
|
|
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
|
-
|
|
323
|
+
## Push Notifications
|
|
383
324
|
|
|
384
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
422
|
-
|
|
423
|
-
|
|
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
|
-
//
|
|
430
|
-
|
|
431
|
-
if (
|
|
432
|
-
|
|
433
|
-
}
|
|
344
|
+
// notifee
|
|
345
|
+
notifee.onForegroundEvent(({ type, detail }) => {
|
|
346
|
+
if (type === EventType.PRESS) Adshift.handlePushNotification(detail.notification?.data ?? {});
|
|
347
|
+
});
|
|
434
348
|
```
|
|
435
349
|
|
|
436
|
-
|
|
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
|
-
|
|
354
|
+
## Consent (GDPR/DMA)
|
|
457
355
|
|
|
458
|
-
|
|
356
|
+
Set consent on every launch, before `start()`, and again whenever the user changes it.
|
|
459
357
|
|
|
460
|
-
|
|
358
|
+
### Manual consent
|
|
461
359
|
|
|
462
360
|
```typescript
|
|
463
|
-
|
|
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
|
-
|
|
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
|
-
|
|
376
|
+
### TCF 2.2 / CMP
|
|
469
377
|
|
|
470
378
|
```typescript
|
|
471
|
-
Adshift.
|
|
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
|
-
|
|
386
|
+
### GPP (US state privacy)
|
|
475
387
|
|
|
476
|
-
|
|
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
|
-
//
|
|
480
|
-
Adshift.
|
|
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
|
-
//
|
|
483
|
-
Adshift.
|
|
416
|
+
// Back to having no answer on record, which is not the same as `allowed()`
|
|
417
|
+
Adshift.clearThirdPartySharing();
|
|
484
418
|
```
|
|
485
419
|
|
|
486
|
-
|
|
420
|
+
Nothing is gated on the device either way; the answer travels with the events.
|
|
487
421
|
|
|
488
422
|
```typescript
|
|
489
|
-
|
|
490
|
-
|
|
491
|
-
|
|
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
|
-
##
|
|
451
|
+
## Configuration
|
|
497
452
|
|
|
498
|
-
###
|
|
453
|
+
### `AdshiftConfig`
|
|
499
454
|
|
|
500
|
-
|
|
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
|
-
|
|
469
|
+
Only options you set are passed to the native SDK; everything else keeps the SDK default.
|
|
503
470
|
|
|
504
|
-
|
|
505
|
-
# ios/Podfile
|
|
506
|
-
platform :ios, '15.0'
|
|
507
|
-
```
|
|
471
|
+
### Runtime setters
|
|
508
472
|
|
|
509
|
-
|
|
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
|
-
```
|
|
512
|
-
|
|
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
|
-
|
|
487
|
+
---
|
|
516
488
|
|
|
517
|
-
|
|
489
|
+
## Errors
|
|
518
490
|
|
|
519
|
-
|
|
520
|
-
|
|
521
|
-
|
|
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
|
-
|
|
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: '
|
|
529
|
-
|
|
530
|
-
|
|
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
|
-
|
|
509
|
+
Every rejected promise and every report is an `AdshiftError`:
|
|
535
510
|
|
|
536
|
-
|
|
537
|
-
|
|
538
|
-
|
|
539
|
-
|
|
540
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
538
|
+
---
|
|
550
539
|
|
|
551
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
548
|
+
```swift
|
|
549
|
+
import React
|
|
570
550
|
|
|
571
|
-
|
|
572
|
-
|
|
573
|
-
|
|
574
|
-
|
|
575
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
<
|
|
586
|
-
<
|
|
587
|
-
<
|
|
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
|
-
|
|
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
|
-
|
|
593
|
-
|
|
594
|
-
|
|
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
|
-
|
|
595
|
+
### Android
|
|
598
596
|
|
|
599
|
-
|
|
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
|
-
<
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
630
|
-
|
|
631
|
-
|
|
632
|
-
|
|
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
|
-
##
|
|
619
|
+
## Store Privacy Declarations
|
|
638
620
|
|
|
639
|
-
|
|
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
|
-
|
|
623
|
+
**Always sent, once the SDK starts**
|
|
642
624
|
|
|
643
|
-
|
|
644
|
-
|
|
645
|
-
|
|
646
|
-
|
|
647
|
-
|
|
648
|
-
|
|
649
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
679
|
-
|
|
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
|
-
|
|
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
|
-
|
|
690
|
-
interface StartResult {
|
|
691
|
-
success: boolean;
|
|
692
|
-
message?: string;
|
|
693
|
-
}
|
|
653
|
+
---
|
|
694
654
|
|
|
695
|
-
|
|
696
|
-
type DeepLinkCallback = (deepLink: AdshiftDeepLink) => void;
|
|
655
|
+
## Expo
|
|
697
656
|
|
|
698
|
-
|
|
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
|
-
|
|
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
|
-
|
|
665
|
+
An OTA update via Expo Updates reloads JavaScript — see [Development Notes](#development-notes).
|
|
709
666
|
|
|
710
|
-
|
|
711
|
-
|
|
712
|
-
|
|
713
|
-
cd ios && pod install && cd ..
|
|
667
|
+
---
|
|
668
|
+
|
|
669
|
+
## Testing
|
|
714
670
|
|
|
715
|
-
|
|
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
|
-
|
|
719
|
-
|
|
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
|
|
723
|
-
|
|
724
|
-
-
|
|
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
|
-
##
|
|
686
|
+
## Development Notes
|
|
732
687
|
|
|
733
|
-
|
|
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
|
-
|
|
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
|
-
|
|
739
|
-
pod
|
|
740
|
-
|
|
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
|
-
|
|
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
|
-
|
|
746
|
-
2. Set `waitForATTBeforeStart: true` in config
|
|
747
|
-
3. Test on physical device (simulator may not show ATT)
|
|
735
|
+
---
|
|
748
736
|
|
|
749
|
-
|
|
737
|
+
## Troubleshooting
|
|
750
738
|
|
|
751
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
745
|
+
**Manifest merger conflict on `fullBackupContent` / `dataExtractionRules`** — see [Android backup rules](#android).
|
|
760
746
|
|
|
761
|
-
|
|
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
|
-
|
|
749
|
+
**Jest fails at import** — register the mock from [Testing](#testing).
|
|
772
750
|
|
|
773
|
-
|
|
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
|
-
|
|
778
|
-
|
|
779
|
-
#### Events Not Sending
|
|
753
|
+
---
|
|
780
754
|
|
|
781
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
-
|
|
799
|
-
-
|
|
800
|
-
-
|
|
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.
|