@adshift/react-native-plugin 1.0.0 → 2.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/AdShiftReactNativePlugin.podspec +11 -7
- package/CHANGELOG.md +122 -0
- package/README.md +506 -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 +1135 -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 +959 -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 +311 -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 +311 -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 +49 -10
- package/src/Adshift.ts +1273 -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,765 @@
|
|
|
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.0.x | `com.adshift:android-sdk:3.1.0` | `AdshiftSDK 2.2.0` |
|
|
61
57
|
|
|
62
58
|
---
|
|
63
59
|
|
|
64
60
|
## Installation
|
|
65
61
|
|
|
66
|
-
### Using npm
|
|
67
|
-
|
|
68
62
|
```bash
|
|
69
63
|
npm install @adshift/react-native-plugin
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
### Using yarn
|
|
73
|
-
|
|
74
|
-
```bash
|
|
64
|
+
# or
|
|
75
65
|
yarn add @adshift/react-native-plugin
|
|
76
66
|
```
|
|
77
67
|
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
After installing the npm package:
|
|
68
|
+
**iOS**
|
|
81
69
|
|
|
82
70
|
```bash
|
|
83
71
|
cd ios && pod install
|
|
84
72
|
```
|
|
85
73
|
|
|
86
|
-
|
|
74
|
+
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
75
|
|
|
88
|
-
|
|
76
|
+
**Android** — nothing else to do; the module autolinks. See [Platform Setup → Android](#android) for backup rules and the `AD_ID` permission.
|
|
89
77
|
|
|
90
78
|
---
|
|
91
79
|
|
|
92
80
|
## Quick Start
|
|
93
81
|
|
|
94
|
-
### 1. Initialize the SDK
|
|
95
|
-
|
|
96
|
-
> ⚠️ **Important:** iOS and Android apps have **different API keys**. Get both from your AdShift dashboard.
|
|
97
|
-
|
|
98
82
|
```typescript
|
|
99
|
-
import {
|
|
100
|
-
|
|
83
|
+
import {
|
|
84
|
+
Adshift,
|
|
85
|
+
AdshiftEventParam,
|
|
86
|
+
AdshiftEventType,
|
|
87
|
+
AdshiftConsent,
|
|
88
|
+
AdshiftDeepLinkStatus,
|
|
89
|
+
} from '@adshift/react-native-plugin';
|
|
101
90
|
|
|
102
|
-
//
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
91
|
+
// 1. Register the deep link listener first. It is safe before initialize();
|
|
92
|
+
// results that arrive earlier are buffered and delivered to the first listener.
|
|
93
|
+
const subscription = Adshift.onDeepLink((deepLink) => {
|
|
94
|
+
if (deepLink.status === AdshiftDeepLinkStatus.Found) {
|
|
95
|
+
// route on deepLink.deepLinkValue or deepLink.params
|
|
96
|
+
}
|
|
97
|
+
});
|
|
107
98
|
|
|
108
|
-
// Initialize
|
|
99
|
+
// 2. Initialize once, as early as possible
|
|
109
100
|
Adshift.initialize({
|
|
110
|
-
apiKey:
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
default: API_KEYS.android,
|
|
114
|
-
})!,
|
|
115
|
-
isDebug: __DEV__, // Enable debug logs in development
|
|
101
|
+
apiKey: 'YOUR_API_KEY',
|
|
102
|
+
isDebug: __DEV__,
|
|
103
|
+
brandedDomains: ['links.yourbrand.com'],
|
|
116
104
|
});
|
|
117
|
-
```
|
|
118
105
|
|
|
119
|
-
|
|
106
|
+
// 3. Consent (every launch, before start)
|
|
107
|
+
Adshift.setConsentData(AdshiftConsent.forNonGDPRUser());
|
|
120
108
|
|
|
121
|
-
|
|
122
|
-
// Start the SDK (typically after user consent or app launch)
|
|
109
|
+
// 4. Start. Never rejects; check result.success.
|
|
123
110
|
const result = await Adshift.start();
|
|
124
111
|
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
112
|
+
// 5. Track. Calls made before start() resolves are queued and sent afterwards.
|
|
113
|
+
await Adshift.trackEvent(AdshiftEventType.Purchase, {
|
|
114
|
+
[AdshiftEventParam.Revenue]: 9.99,
|
|
115
|
+
[AdshiftEventParam.Currency]: 'USD',
|
|
116
|
+
});
|
|
117
|
+
|
|
118
|
+
// Later
|
|
119
|
+
subscription.remove();
|
|
128
120
|
```
|
|
129
121
|
|
|
130
|
-
|
|
122
|
+
---
|
|
131
123
|
|
|
132
|
-
|
|
133
|
-
import { Adshift, AdshiftEventType } from '@adshift/react-native-plugin';
|
|
124
|
+
## Lifecycle
|
|
134
125
|
|
|
135
|
-
|
|
136
|
-
await Adshift.trackEvent(AdshiftEventType.LOGIN);
|
|
126
|
+
### `Adshift.initialize(config)`
|
|
137
127
|
|
|
138
|
-
|
|
139
|
-
await Adshift.trackEvent(AdshiftEventType.ADD_TO_CART, {
|
|
140
|
-
product_id: 'SKU123',
|
|
141
|
-
price: 29.99,
|
|
142
|
-
quantity: 1,
|
|
143
|
-
});
|
|
128
|
+
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
129
|
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
revenue: 9.99,
|
|
149
|
-
currency: 'USD',
|
|
150
|
-
transactionId: 'TXN_12345',
|
|
151
|
-
});
|
|
152
|
-
```
|
|
130
|
+
See [`AdshiftConfig`](#adshiftconfig) for every option.
|
|
131
|
+
|
|
132
|
+
### `Adshift.start(): Promise<StartResult>`
|
|
153
133
|
|
|
154
|
-
|
|
134
|
+
Starts tracking. Resolves once the SDK has started locally and **never rejects**:
|
|
155
135
|
|
|
156
136
|
```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 />;
|
|
137
|
+
interface StartResult {
|
|
138
|
+
success: boolean;
|
|
139
|
+
apiKeyValidationStatus?: 'pending' | 'valid' | 'invalid';
|
|
140
|
+
errorCode?: AdshiftErrorCode; // when success is false
|
|
141
|
+
errorMessage?: string;
|
|
180
142
|
}
|
|
181
143
|
```
|
|
182
144
|
|
|
183
|
-
|
|
145
|
+
- The API key is verified with the AdShift backend in the background, so `apiKeyValidationStatus` reports `valid` or `invalid` once the answer is in, and `pending` while it is not. A key the backend rejects after `start()` resolved is reported through `config.onError` as `INVALID_API_KEY`, and events stay buffered by the native SDK.
|
|
146
|
+
- A device excluded from tracking resolves `{ success: false, errorCode: 'OPTED_OUT' }`.
|
|
147
|
+
- On iOS `start()` may take a few seconds on the first launch (SKAdNetwork configuration) and, if you enabled `waitForATTBeforeStart`, waits for the ATT decision up to `attTimeoutMs`.
|
|
148
|
+
- Calling `start()` again while started resolves `{ success: true }` immediately. Calling it before `initialize()` resolves `{ success: false, errorCode: 'NOT_INITIALIZED' }`.
|
|
149
|
+
- 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
150
|
|
|
185
|
-
|
|
151
|
+
### `Adshift.stop(): void`
|
|
186
152
|
|
|
187
|
-
|
|
153
|
+
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
154
|
|
|
189
|
-
|
|
155
|
+
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
156
|
|
|
191
|
-
|
|
157
|
+
### `Adshift.isStarted(): boolean`
|
|
192
158
|
|
|
193
|
-
|
|
159
|
+
`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
160
|
|
|
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
|
-
```
|
|
161
|
+
### `Adshift.getAdShiftDeviceId(): Promise<string | null>`
|
|
215
162
|
|
|
216
|
-
|
|
163
|
+
The AdShift device identifier; `null` before `initialize()`.
|
|
217
164
|
|
|
218
|
-
|
|
165
|
+
### `Adshift.getInfo()`
|
|
219
166
|
|
|
220
167
|
```typescript
|
|
221
|
-
|
|
222
|
-
// result: { success: boolean, message?: string }
|
|
168
|
+
{ platform: 'ios' | 'android', version: '2.0.0', nativeSdkVersions: { android: '3.1.0', ios: '2.2.0' } }
|
|
223
169
|
```
|
|
224
170
|
|
|
225
|
-
|
|
171
|
+
---
|
|
226
172
|
|
|
227
|
-
|
|
173
|
+
## Event Tracking
|
|
174
|
+
|
|
175
|
+
### `Adshift.trackEvent(eventName, values?): Promise<void>`
|
|
228
176
|
|
|
229
177
|
```typescript
|
|
230
|
-
Adshift.
|
|
178
|
+
await Adshift.trackEvent(AdshiftEventType.AddToCart, {
|
|
179
|
+
[AdshiftEventParam.ContentId]: 'SKU123',
|
|
180
|
+
[AdshiftEventParam.Price]: 29.99,
|
|
181
|
+
in_stock: true, // custom parameters are fine alongside the standard ones
|
|
182
|
+
});
|
|
183
|
+
await Adshift.trackEvent('custom_event');
|
|
231
184
|
```
|
|
232
185
|
|
|
233
|
-
|
|
186
|
+
`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).
|
|
187
|
+
|
|
188
|
+
`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
189
|
|
|
235
|
-
|
|
190
|
+
### `Adshift.trackPurchase(params): Promise<void>`
|
|
236
191
|
|
|
237
192
|
```typescript
|
|
238
|
-
|
|
193
|
+
await Adshift.trackPurchase({
|
|
194
|
+
productId: 'premium_monthly',
|
|
195
|
+
revenue: 9.99,
|
|
196
|
+
currency: 'USD',
|
|
197
|
+
transactionId: 'GPA.1234-5678-9012-34567',
|
|
198
|
+
});
|
|
239
199
|
```
|
|
240
200
|
|
|
241
|
-
|
|
201
|
+
### Predefined event types
|
|
242
202
|
|
|
243
|
-
|
|
203
|
+
`AdshiftEventType` exposes 30 standard events:
|
|
244
204
|
|
|
245
|
-
|
|
205
|
+
| Category | Constants |
|
|
206
|
+
|---|---|
|
|
207
|
+
| E-commerce | `AddToCart`, `AddToWishList`, `AddPaymentInfo`, `InitiatedCheckout`, `Purchase`, `ContentView`, `ListView`, `Search` |
|
|
208
|
+
| User lifecycle | `CompleteRegistration`, `Login`, `TutorialCompletion`, `Subscribe`, `StartTrial` |
|
|
209
|
+
| Gaming | `LevelAchieved`, `AchievementUnlocked`, `SpentCredit` |
|
|
210
|
+
| Engagement | `Rate`, `Share`, `Invite`, `ReEngage`, `Update`, `OpenedFromPushNotification` |
|
|
211
|
+
| Travel | `TravelBooking` |
|
|
212
|
+
| Ads | `AdClick`, `AdView`, `AdRevenue` |
|
|
213
|
+
| Location | `LocationChanged`, `LocationCoordinates` |
|
|
214
|
+
| Other | `OrderId`, `CustomerSegment` |
|
|
246
215
|
|
|
247
|
-
|
|
216
|
+
`getAllEventTypes()` returns the wire names as an array.
|
|
248
217
|
|
|
249
|
-
|
|
250
|
-
// Simple event
|
|
251
|
-
await Adshift.trackEvent(AdshiftEventType.LOGIN);
|
|
218
|
+
### Standard parameter names
|
|
252
219
|
|
|
253
|
-
|
|
254
|
-
await Adshift.trackEvent(AdshiftEventType.SEARCH, {
|
|
255
|
-
search_term: 'running shoes',
|
|
256
|
-
results_count: 42,
|
|
257
|
-
});
|
|
220
|
+
`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
221
|
|
|
259
|
-
|
|
260
|
-
await Adshift.trackEvent(
|
|
261
|
-
|
|
222
|
+
```typescript
|
|
223
|
+
await Adshift.trackEvent(AdshiftEventType.Purchase, {
|
|
224
|
+
[AdshiftEventParam.Revenue]: 9.99,
|
|
225
|
+
[AdshiftEventParam.Currency]: 'USD',
|
|
226
|
+
[AdshiftEventParam.Quantity]: 1,
|
|
227
|
+
gift_wrapped: true,
|
|
262
228
|
});
|
|
263
229
|
```
|
|
264
230
|
|
|
265
|
-
|
|
231
|
+
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.
|
|
232
|
+
|
|
233
|
+
`trackPurchase()` and `logAdRevenue()` need none of this — they fill the revenue and currency names from their own arguments.
|
|
234
|
+
|
|
235
|
+
---
|
|
266
236
|
|
|
267
|
-
|
|
237
|
+
## Ad Revenue
|
|
238
|
+
|
|
239
|
+
### `Adshift.logAdRevenue(params): Promise<void>`
|
|
268
240
|
|
|
269
241
|
```typescript
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
242
|
+
import { AdshiftMediationNetwork } from '@adshift/react-native-plugin';
|
|
243
|
+
|
|
244
|
+
await Adshift.logAdRevenue({
|
|
245
|
+
monetizationNetwork: 'admob',
|
|
246
|
+
mediationNetwork: AdshiftMediationNetwork.GoogleAdMob,
|
|
273
247
|
currency: 'USD',
|
|
274
|
-
|
|
248
|
+
revenue: 0.0125,
|
|
249
|
+
adUnitId: 'ca-app-pub-1234/5678', // optional
|
|
250
|
+
precision: 'estimated', // optional
|
|
251
|
+
additionalParameters: { placement: 'home_banner' }, // optional
|
|
275
252
|
});
|
|
276
253
|
```
|
|
277
254
|
|
|
278
|
-
|
|
255
|
+
`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
256
|
|
|
280
|
-
|
|
257
|
+
---
|
|
281
258
|
|
|
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
|
-
```
|
|
259
|
+
## Deep Linking
|
|
316
260
|
|
|
317
|
-
|
|
261
|
+
### The contract
|
|
318
262
|
|
|
319
|
-
|
|
263
|
+
- Every link that opens the app and reaches the SDK — direct, deferred (first launch after install) and push — produces exactly one `onDeepLink` result.
|
|
264
|
+
- `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.
|
|
265
|
+
- Results are delivered only through `onDeepLink`. `handleDeepLink()` and `handlePushNotification()` resolve when the SDK has accepted the input.
|
|
320
266
|
|
|
321
|
-
|
|
267
|
+
### `Adshift.onDeepLink(callback): DeepLinkSubscription`
|
|
322
268
|
|
|
323
269
|
```typescript
|
|
324
|
-
|
|
325
|
-
|
|
326
|
-
|
|
327
|
-
|
|
328
|
-
|
|
329
|
-
|
|
330
|
-
|
|
331
|
-
|
|
332
|
-
|
|
333
|
-
|
|
270
|
+
useEffect(() => {
|
|
271
|
+
const subscription = Adshift.onDeepLink((deepLink) => {
|
|
272
|
+
if (deepLink.status !== AdshiftDeepLinkStatus.Found) return;
|
|
273
|
+
if (deepLink.deepLinkValue === 'product') {
|
|
274
|
+
navigate('Product', { id: deepLink.params?.product_id });
|
|
275
|
+
}
|
|
276
|
+
});
|
|
277
|
+
return () => subscription.remove();
|
|
278
|
+
}, []);
|
|
279
|
+
```
|
|
334
280
|
|
|
335
|
-
|
|
336
|
-
|
|
337
|
-
AdshiftConsent.forGDPRUser({
|
|
338
|
-
hasConsentForDataUsage: false,
|
|
339
|
-
hasConsentForAdsPersonalization: false,
|
|
340
|
-
hasConsentForAdStorage: false,
|
|
341
|
-
})
|
|
342
|
-
);
|
|
281
|
+
- 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.
|
|
282
|
+
- Listeners are called on the JS thread; an exception in one listener does not affect the others. `remove()` is idempotent.
|
|
343
283
|
|
|
344
|
-
|
|
345
|
-
|
|
284
|
+
```typescript
|
|
285
|
+
interface AdshiftDeepLink {
|
|
286
|
+
deepLink?: string; // the URL
|
|
287
|
+
deepLinkValue?: string; // deep_link_value for routing
|
|
288
|
+
params?: Record<string, string>; // query parameters
|
|
289
|
+
isDeferred: boolean; // first launch after install
|
|
290
|
+
isFirstSession?: boolean; // Android only, on every result
|
|
291
|
+
status: AdshiftDeepLinkStatus; // Found | NotFound | Error
|
|
292
|
+
errorMessage?: string; // with Error; wording differs per platform
|
|
293
|
+
deepLinkSub1?: string; /* … */ deepLinkSub5?: string;
|
|
294
|
+
}
|
|
346
295
|
```
|
|
347
296
|
|
|
348
|
-
|
|
297
|
+
### Automatic forwarding (default)
|
|
349
298
|
|
|
350
|
-
|
|
299
|
+
With `autoHandleDeepLinks: true` (the default) you write no linking code:
|
|
351
300
|
|
|
352
|
-
|
|
353
|
-
|
|
354
|
-
Adshift.enableTCFDataCollection(true);
|
|
301
|
+
- **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.
|
|
302
|
+
- **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
303
|
|
|
356
|
-
|
|
357
|
-
await Adshift.start();
|
|
304
|
+
`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
305
|
|
|
359
|
-
|
|
360
|
-
const snapshot = await Adshift.refreshConsent();
|
|
361
|
-
console.log('Consent source:', snapshot.source);
|
|
362
|
-
console.log('Has consent:', snapshot.hasConsent);
|
|
363
|
-
```
|
|
306
|
+
### Manual forwarding
|
|
364
307
|
|
|
365
|
-
|
|
308
|
+
Set `autoHandleDeepLinks: false` and forward URLs yourself:
|
|
366
309
|
|
|
367
310
|
```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
|
-
}
|
|
311
|
+
await Adshift.handleDeepLink(url); // resolves once accepted; result arrives via onDeepLink
|
|
378
312
|
```
|
|
379
313
|
|
|
314
|
+
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.
|
|
315
|
+
|
|
316
|
+
### Deferred deep links
|
|
317
|
+
|
|
318
|
+
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.
|
|
319
|
+
|
|
380
320
|
---
|
|
381
321
|
|
|
382
|
-
|
|
322
|
+
## Push Notifications
|
|
383
323
|
|
|
384
|
-
|
|
324
|
+
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
325
|
|
|
386
|
-
|
|
326
|
+
Registering your own paths takes over from `as_push_link`. If your payloads use both, list it explicitly:
|
|
387
327
|
|
|
388
328
|
```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();
|
|
329
|
+
pushDeepLinkPaths: [['data', 'link'], ['as_push_link']],
|
|
414
330
|
```
|
|
415
331
|
|
|
416
|
-
|
|
417
|
-
|
|
418
|
-
When your app receives a URL (e.g., from `Linking` API):
|
|
332
|
+
- **Android** — a tap on a notification whose Intent carries the payload extras is handled automatically (with `autoHandleDeepLinks`).
|
|
333
|
+
- **iOS**, or when you build the notification yourself — hand the payload over:
|
|
419
334
|
|
|
420
335
|
```typescript
|
|
421
|
-
|
|
422
|
-
|
|
423
|
-
|
|
424
|
-
Linking.addEventListener('url', async ({ url }) => {
|
|
425
|
-
const result = await Adshift.handleDeepLink(url);
|
|
426
|
-
console.log('Deep link result:', result);
|
|
336
|
+
// @react-native-firebase/messaging
|
|
337
|
+
messaging().onNotificationOpenedApp((message) => {
|
|
338
|
+
Adshift.handlePushNotification(message.data ?? {});
|
|
427
339
|
});
|
|
340
|
+
const initial = await messaging().getInitialNotification();
|
|
341
|
+
if (initial) await Adshift.handlePushNotification(initial.data ?? {});
|
|
428
342
|
|
|
429
|
-
//
|
|
430
|
-
|
|
431
|
-
if (
|
|
432
|
-
|
|
433
|
-
}
|
|
343
|
+
// notifee
|
|
344
|
+
notifee.onForegroundEvent(({ type, detail }) => {
|
|
345
|
+
if (type === EventType.PRESS) Adshift.handlePushNotification(detail.notification?.data ?? {});
|
|
346
|
+
});
|
|
434
347
|
```
|
|
435
348
|
|
|
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
|
-
```
|
|
349
|
+
`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
350
|
|
|
454
351
|
---
|
|
455
352
|
|
|
456
|
-
|
|
353
|
+
## Consent (GDPR/DMA)
|
|
457
354
|
|
|
458
|
-
|
|
355
|
+
Set consent on every launch, before `start()`, and again whenever the user changes it.
|
|
459
356
|
|
|
460
|
-
|
|
357
|
+
### Manual consent
|
|
461
358
|
|
|
462
359
|
```typescript
|
|
463
|
-
|
|
360
|
+
// User subject to GDPR; omitted flags are "not decided" and are not sent
|
|
361
|
+
Adshift.setConsentData(
|
|
362
|
+
AdshiftConsent.forGDPRUser({
|
|
363
|
+
hasConsentForDataUsage: true,
|
|
364
|
+
hasConsentForAdsPersonalization: false,
|
|
365
|
+
hasConsentForAdStorage: true,
|
|
366
|
+
})
|
|
367
|
+
);
|
|
368
|
+
|
|
369
|
+
// User not subject to GDPR: everything is permitted, individual flags are not sent
|
|
370
|
+
Adshift.setConsentData(AdshiftConsent.forNonGDPRUser());
|
|
464
371
|
```
|
|
465
372
|
|
|
466
|
-
|
|
373
|
+
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
374
|
|
|
468
|
-
|
|
375
|
+
### TCF 2.2 / CMP
|
|
469
376
|
|
|
470
377
|
```typescript
|
|
471
|
-
Adshift.
|
|
378
|
+
Adshift.enableTCFDataCollection(true); // before start()
|
|
379
|
+
await Adshift.start();
|
|
380
|
+
|
|
381
|
+
// after the CMP dialog closes
|
|
382
|
+
const snapshot: ConsentSnapshot = await Adshift.refreshConsent();
|
|
472
383
|
```
|
|
473
384
|
|
|
474
|
-
|
|
385
|
+
### GPP (US state privacy)
|
|
475
386
|
|
|
476
|
-
|
|
387
|
+
Two independent axes. `enableGPPDataCollection` forwards the IAB GPP string the
|
|
388
|
+
CMP wrote, alongside whatever decides the GDPR axis — including a consent set
|
|
389
|
+
through `setConsentData()`. It does not gate the advertising identifier on the
|
|
390
|
+
device; a US opt-out limits what may be done with an event afterwards.
|
|
477
391
|
|
|
478
392
|
```typescript
|
|
479
|
-
//
|
|
480
|
-
Adshift.
|
|
393
|
+
Adshift.enableGPPDataCollection(true); // before start()
|
|
394
|
+
await Adshift.start();
|
|
395
|
+
|
|
396
|
+
// after the CMP writes its GPP string
|
|
397
|
+
const snapshot = await Adshift.refreshConsent();
|
|
398
|
+
snapshot.gppPresent; // true once a GPP string is on the device
|
|
399
|
+
```
|
|
400
|
+
|
|
401
|
+
### Third-party sharing
|
|
402
|
+
|
|
403
|
+
A third axis, and the one with the opposite default: nothing said here means
|
|
404
|
+
sharing is allowed. So state it only once the user has actually been asked — a
|
|
405
|
+
`allowed()` set at startup as a default records a declaration the user never
|
|
406
|
+
made, and events already sent cannot be recalled when a real answer arrives.
|
|
407
|
+
|
|
408
|
+
```typescript
|
|
409
|
+
// The user asked not to have their data passed on
|
|
410
|
+
Adshift.setThirdPartySharing(AdshiftThirdPartySharing.optedOut());
|
|
411
|
+
|
|
412
|
+
// The user was asked and did not opt out
|
|
413
|
+
Adshift.setThirdPartySharing(AdshiftThirdPartySharing.allowed());
|
|
481
414
|
|
|
482
|
-
//
|
|
483
|
-
Adshift.
|
|
415
|
+
// Back to having no answer on record, which is not the same as `allowed()`
|
|
416
|
+
Adshift.clearThirdPartySharing();
|
|
484
417
|
```
|
|
485
418
|
|
|
486
|
-
|
|
419
|
+
Nothing is gated on the device either way; the answer travels with the events.
|
|
487
420
|
|
|
488
421
|
```typescript
|
|
489
|
-
|
|
490
|
-
|
|
491
|
-
|
|
422
|
+
interface ConsentSnapshot {
|
|
423
|
+
source: 'manual' | 'tcf' | 'gpp' | 'none';
|
|
424
|
+
gdprApplies?: number;
|
|
425
|
+
tcStringPresent: boolean;
|
|
426
|
+
gppPresent?: boolean;
|
|
427
|
+
cmpDetected: boolean;
|
|
428
|
+
adUserDataEnabled?: boolean;
|
|
429
|
+
adPersonalizationEnabled?: boolean;
|
|
430
|
+
adStorageEnabled?: boolean;
|
|
431
|
+
appliedAtMillis: number;
|
|
432
|
+
adIdentifiersAllowed: boolean;
|
|
433
|
+
}
|
|
492
434
|
```
|
|
493
435
|
|
|
436
|
+
`source` names what decided the GDPR axis, where manual outranks TCF. It is not a
|
|
437
|
+
ranking across all three axes: a GPP string and a sharing answer ride alongside
|
|
438
|
+
whatever `source` says, and neither is displaced by calling `setConsentData()`.
|
|
439
|
+
|
|
440
|
+
`cmpDetected` separates the two states nothing else here can tell apart. A CMP
|
|
441
|
+
installed but not yet answered looks identical to no CMP at all, and the two are
|
|
442
|
+
fixed by opposite actions: `false` when you expect a CMP means it never ran or was
|
|
443
|
+
never wired up, while `true` with `source: 'none'` means it ran and the user has
|
|
444
|
+
not answered yet, which resolves itself once they do.
|
|
445
|
+
|
|
446
|
+
`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.
|
|
447
|
+
|
|
494
448
|
---
|
|
495
449
|
|
|
496
|
-
##
|
|
450
|
+
## Configuration
|
|
497
451
|
|
|
498
|
-
###
|
|
452
|
+
### `AdshiftConfig`
|
|
499
453
|
|
|
500
|
-
|
|
454
|
+
| Option | Type | Default | Notes |
|
|
455
|
+
|---|---|---|---|
|
|
456
|
+
| `apiKey` | `string` | — | Required |
|
|
457
|
+
| `isDebug` | `boolean` | SDK default | Verbose native logging |
|
|
458
|
+
| `appOpenDebounceMs` | `number` | `10000` | Debounce for automatic `app_open` |
|
|
459
|
+
| `brandedDomains` | `string[]` | — | Custom attribution domains |
|
|
460
|
+
| `metaAppId` | `string` | — | Meta App Links parsing (Android) |
|
|
461
|
+
| `pushDeepLinkPaths` | `string[][]` | `[['as_push_link']]` | Extra key paths in push payloads |
|
|
462
|
+
| `autoHandleDeepLinks` | `boolean` | `true` | Automatic URL forwarding |
|
|
463
|
+
| `disableSKAN` | `boolean` | `false` | iOS |
|
|
464
|
+
| `waitForATTBeforeStart` | `boolean` | `false` | iOS; only when **your app** shows the ATT prompt |
|
|
465
|
+
| `attTimeoutMs` | `number` | `30000` | iOS; clamped to 5 000–120 000 |
|
|
466
|
+
| `collectOaid` | `boolean` | `true` | Android; OAID on devices without Google Play services |
|
|
501
467
|
|
|
502
|
-
|
|
468
|
+
Only options you set are passed to the native SDK; everything else keeps the SDK default.
|
|
503
469
|
|
|
504
|
-
|
|
505
|
-
# ios/Podfile
|
|
506
|
-
platform :ios, '15.0'
|
|
507
|
-
```
|
|
470
|
+
### Runtime setters
|
|
508
471
|
|
|
509
|
-
|
|
472
|
+
None of these raise. A value that fails validation is skipped and reported (see
|
|
473
|
+
[Errors](#errors)), and a call made before `initialize()` is kept and applied
|
|
474
|
+
afterwards, so setup code does not depend on call order.
|
|
510
475
|
|
|
511
|
-
```
|
|
512
|
-
|
|
476
|
+
```typescript
|
|
477
|
+
Adshift.setCustomerUserId('user_123'); // before or after start()
|
|
478
|
+
Adshift.setDebugEnabled(true);
|
|
479
|
+
Adshift.setAppOpenDebounceMs(5000);
|
|
480
|
+
Adshift.setBrandedDomains(['links.yourbrand.com']); // before start()
|
|
481
|
+
Adshift.setMetaAppId('1234567890'); // Android; no-op on iOS
|
|
482
|
+
Adshift.setOaidData(oaidFromYourOwnCode); // Android; no-op on iOS
|
|
483
|
+
Adshift.addPushNotificationDeepLinkPath(['data', 'deep_link']);
|
|
513
484
|
```
|
|
514
485
|
|
|
515
|
-
|
|
486
|
+
---
|
|
516
487
|
|
|
517
|
-
|
|
488
|
+
## Errors
|
|
518
489
|
|
|
519
|
-
|
|
520
|
-
|
|
521
|
-
|
|
522
|
-
|
|
490
|
+
**The plugin never raises into your code.** Methods that return a promise reject
|
|
491
|
+
with an `AdshiftError`; methods that return nothing skip the call and report it,
|
|
492
|
+
because an error thrown from an event handler or a native callback would take
|
|
493
|
+
down the app instead of the call. Nothing the plugin does can crash your app.
|
|
523
494
|
|
|
524
|
-
|
|
495
|
+
Failures the plugin cannot answer with a rejected promise are reported on two
|
|
496
|
+
channels: the console in development, and `config.onError` in every build.
|
|
525
497
|
|
|
526
498
|
```typescript
|
|
527
499
|
Adshift.initialize({
|
|
528
|
-
apiKey: '
|
|
529
|
-
|
|
530
|
-
|
|
500
|
+
apiKey: 'your-api-key',
|
|
501
|
+
onError: (error) => {
|
|
502
|
+
// Integration mistakes, a config the plugin refused, a rejected API key.
|
|
503
|
+
Sentry.captureMessage(`AdShift: ${error.code} ${error.message}`);
|
|
504
|
+
},
|
|
531
505
|
});
|
|
532
506
|
```
|
|
533
507
|
|
|
534
|
-
|
|
508
|
+
Every rejected promise and every report is an `AdshiftError`:
|
|
535
509
|
|
|
536
|
-
|
|
537
|
-
|
|
538
|
-
|
|
539
|
-
|
|
540
|
-
|
|
510
|
+
```typescript
|
|
511
|
+
import { AdshiftErrorCode, isAdshiftError } from '@adshift/react-native-plugin';
|
|
512
|
+
|
|
513
|
+
try {
|
|
514
|
+
await Adshift.trackEvent('x');
|
|
515
|
+
} catch (error) {
|
|
516
|
+
if (isAdshiftError(error)) {
|
|
517
|
+
error.code; // AdshiftErrorCode
|
|
518
|
+
error.message;
|
|
519
|
+
error.userInfo.nativeCode; // raw native code, when available
|
|
520
|
+
error.userInfo.nativeDomain; // iOS NSError domain, when available
|
|
521
|
+
}
|
|
522
|
+
}
|
|
541
523
|
```
|
|
542
524
|
|
|
543
|
-
|
|
525
|
+
| Code | Meaning |
|
|
526
|
+
|---|---|
|
|
527
|
+
| `NOT_INITIALIZED` | `initialize()` has not been called |
|
|
528
|
+
| `NOT_STARTED` | `stop()` was called; call `start()` |
|
|
529
|
+
| `INVALID_API_KEY` | The backend rejected the API key |
|
|
530
|
+
| `OPTED_OUT` | Tracking is disabled for this app on the AdShift side |
|
|
531
|
+
| `QUEUE_FULL` | More than 100 calls are waiting for `start()`, or the Android SDK refused the call because its own queue is full |
|
|
532
|
+
| `INVALID_ARGUMENT` | A parameter failed validation |
|
|
533
|
+
| `UNKNOWN` | Anything else; see `userInfo.nativeCode` |
|
|
544
534
|
|
|
545
|
-
|
|
546
|
-
2. Add your domain: `applinks:yourapp.rightlink.me`
|
|
547
|
-
3. Configure `apple-app-site-association` on your server
|
|
535
|
+
`start()` never rejects; it reports these codes in `StartResult.errorCode`.
|
|
548
536
|
|
|
549
|
-
|
|
537
|
+
---
|
|
550
538
|
|
|
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
|
-
```
|
|
539
|
+
## Platform Setup
|
|
562
540
|
|
|
563
|
-
|
|
541
|
+
### iOS
|
|
564
542
|
|
|
565
|
-
|
|
543
|
+
**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
544
|
|
|
567
|
-
|
|
545
|
+
**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
546
|
|
|
569
|
-
|
|
547
|
+
```swift
|
|
548
|
+
import React
|
|
570
549
|
|
|
571
|
-
|
|
572
|
-
|
|
573
|
-
|
|
574
|
-
|
|
575
|
-
|
|
576
|
-
|
|
550
|
+
// inside class AppDelegate
|
|
551
|
+
|
|
552
|
+
func application(
|
|
553
|
+
_ app: UIApplication,
|
|
554
|
+
open url: URL,
|
|
555
|
+
options: [UIApplication.OpenURLOptionsKey: Any] = [:]
|
|
556
|
+
) -> Bool {
|
|
557
|
+
return RCTLinkingManager.application(app, open: url, options: options)
|
|
558
|
+
}
|
|
559
|
+
|
|
560
|
+
func application(
|
|
561
|
+
_ application: UIApplication,
|
|
562
|
+
continue userActivity: NSUserActivity,
|
|
563
|
+
restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void
|
|
564
|
+
) -> Bool {
|
|
565
|
+
return RCTLinkingManager.application(
|
|
566
|
+
application,
|
|
567
|
+
continue: userActivity,
|
|
568
|
+
restorationHandler: restorationHandler
|
|
569
|
+
)
|
|
577
570
|
}
|
|
578
571
|
```
|
|
579
572
|
|
|
580
|
-
|
|
573
|
+
**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`.
|
|
574
|
+
|
|
575
|
+
**4. App Tracking Transparency** — if your app shows the ATT prompt, add `NSUserTrackingUsageDescription` to `Info.plist` and set `waitForATTBeforeStart: true`; `start()` then waits for the decision up to `attTimeoutMs`. If your app does not prompt, leave the option off.
|
|
581
576
|
|
|
582
|
-
|
|
577
|
+
**5. SKAdNetwork postbacks** — add to `Info.plist`:
|
|
583
578
|
|
|
584
579
|
```xml
|
|
585
|
-
<
|
|
586
|
-
<
|
|
587
|
-
<uses-permission android:name="com.google.android.gms.permission.AD_ID" />
|
|
580
|
+
<key>NSAdvertisingAttributionReportEndpoint</key>
|
|
581
|
+
<string>https://adshift-skadnetwork.com</string>
|
|
588
582
|
```
|
|
589
583
|
|
|
590
|
-
|
|
584
|
+
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).
|
|
591
585
|
|
|
592
|
-
|
|
593
|
-
|
|
594
|
-
|
|
595
|
-
```
|
|
586
|
+
**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.
|
|
587
|
+
|
|
588
|
+
### Android
|
|
596
589
|
|
|
597
|
-
|
|
590
|
+
**1. Requirements** — `minSdkVersion 24`, `compileSdkVersion 35+`.
|
|
598
591
|
|
|
599
|
-
|
|
592
|
+
**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.
|
|
593
|
+
|
|
594
|
+
**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
595
|
|
|
601
596
|
```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>
|
|
597
|
+
<uses-permission android:name="com.google.android.gms.permission.AD_ID" tools:node="remove" />
|
|
623
598
|
```
|
|
624
599
|
|
|
625
|
-
|
|
600
|
+
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
601
|
|
|
627
|
-
|
|
602
|
+
**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
603
|
|
|
629
|
-
|
|
630
|
-
|
|
631
|
-
|
|
632
|
-
|
|
633
|
-
|
|
604
|
+
**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.
|
|
605
|
+
|
|
606
|
+
**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.
|
|
607
|
+
|
|
608
|
+
**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
609
|
|
|
635
610
|
---
|
|
636
611
|
|
|
637
|
-
##
|
|
612
|
+
## Store Privacy Declarations
|
|
638
613
|
|
|
639
|
-
|
|
614
|
+
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
615
|
|
|
641
|
-
|
|
616
|
+
**Always sent, once the SDK starts**
|
|
642
617
|
|
|
643
|
-
|
|
644
|
-
|
|
645
|
-
|
|
646
|
-
|
|
647
|
-
|
|
648
|
-
|
|
649
|
-
|
|
618
|
+
| What | Apple App Privacy | Google Play Data safety |
|
|
619
|
+
| --- | --- | --- |
|
|
620
|
+
| 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 |
|
|
621
|
+
| Installs, app opens and foreground time | Usage Data → Product Interaction | App activity → App interactions |
|
|
622
|
+
| Device model, OS version, language, carrier, connection type | Usage Data | App info and performance |
|
|
623
|
+
| The opening URL when the app is launched from a link | Usage Data → Other Usage Data | App activity → Other actions |
|
|
624
|
+
| 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
625
|
|
|
651
|
-
|
|
652
|
-
AdshiftConfig,
|
|
653
|
-
AdshiftDeepLink,
|
|
654
|
-
StartResult,
|
|
655
|
-
EventValues,
|
|
656
|
-
PurchaseParams,
|
|
657
|
-
DeepLinkSubscription,
|
|
658
|
-
DeepLinkCallback,
|
|
659
|
-
} from '@adshift/react-native-plugin';
|
|
660
|
-
```
|
|
626
|
+
**Only if your app calls it**
|
|
661
627
|
|
|
662
|
-
|
|
628
|
+
| Your call | Apple App Privacy | Google Play Data safety |
|
|
629
|
+
| --- | --- | --- |
|
|
630
|
+
| `setCustomerUserId` | Identifiers → User ID | Personal info → User IDs |
|
|
631
|
+
| `trackPurchase` | Purchases → Purchase History | Financial info → Purchase history |
|
|
632
|
+
| `logAdRevenue` | Usage Data → Advertising Data | App activity → Other actions |
|
|
633
|
+
| `trackEvent` with your own parameters | depends on what you put in them | depends on what you put in them |
|
|
663
634
|
|
|
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
|
-
}
|
|
635
|
+
Notes that decide several rows for you:
|
|
677
636
|
|
|
678
|
-
|
|
679
|
-
|
|
637
|
+
- **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.
|
|
638
|
+
- **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.
|
|
639
|
+
- **No location is collected.** No location permission or API is used. The country reported by the SDK comes from the device's region setting.
|
|
640
|
+
- **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.
|
|
641
|
+
- **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)`.
|
|
642
|
+
- **Everything travels over HTTPS.**
|
|
680
643
|
|
|
681
|
-
|
|
682
|
-
interface PurchaseParams {
|
|
683
|
-
productId: string;
|
|
684
|
-
revenue: number;
|
|
685
|
-
currency: string;
|
|
686
|
-
transactionId: string;
|
|
687
|
-
}
|
|
644
|
+
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
645
|
|
|
689
|
-
|
|
690
|
-
interface StartResult {
|
|
691
|
-
success: boolean;
|
|
692
|
-
message?: string;
|
|
693
|
-
}
|
|
646
|
+
---
|
|
694
647
|
|
|
695
|
-
|
|
696
|
-
type DeepLinkCallback = (deepLink: AdshiftDeepLink) => void;
|
|
648
|
+
## Expo
|
|
697
649
|
|
|
698
|
-
|
|
699
|
-
interface DeepLinkSubscription {
|
|
700
|
-
remove: () => void;
|
|
701
|
-
}
|
|
702
|
-
```
|
|
650
|
+
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
651
|
|
|
704
|
-
|
|
652
|
+
No config plugin is needed, and neither is any native edit:
|
|
705
653
|
|
|
706
|
-
|
|
654
|
+
- Autolinking and codegen pick the module up.
|
|
655
|
+
- 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.
|
|
656
|
+
- Everything else belongs in `app.json`: `ios.associatedDomains` for universal links, `ios.infoPlist` for `NSUserTrackingUsageDescription` and `NSAdvertisingAttributionReportEndpoint`, `android.intentFilters` for App Links, and `scheme` for a custom scheme.
|
|
707
657
|
|
|
708
|
-
|
|
658
|
+
An OTA update via Expo Updates reloads JavaScript — see [Development Notes](#development-notes).
|
|
709
659
|
|
|
710
|
-
|
|
711
|
-
cd example
|
|
712
|
-
yarn install
|
|
713
|
-
cd ios && pod install && cd ..
|
|
660
|
+
---
|
|
714
661
|
|
|
715
|
-
|
|
716
|
-
yarn ios
|
|
662
|
+
## Testing
|
|
717
663
|
|
|
718
|
-
|
|
719
|
-
|
|
664
|
+
The package resolves its native module at import time, which fails in a plain Jest environment. Use the bundled mock:
|
|
665
|
+
|
|
666
|
+
```js
|
|
667
|
+
// jest.setup.js
|
|
668
|
+
jest.mock('@adshift/react-native-plugin', () =>
|
|
669
|
+
require('@adshift/react-native-plugin/jest').createAdshiftMock()
|
|
670
|
+
);
|
|
720
671
|
```
|
|
721
672
|
|
|
722
|
-
The
|
|
723
|
-
|
|
724
|
-
-
|
|
725
|
-
- Consent management UI (GDPR/TCF)
|
|
726
|
-
- Deep link testing
|
|
727
|
-
- Live event log console
|
|
673
|
+
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`, …).
|
|
674
|
+
|
|
675
|
+
The package ships both ES module and CommonJS builds, so the default `react-native` Jest preset loads it without changes to `transformIgnorePatterns`.
|
|
728
676
|
|
|
729
677
|
---
|
|
730
678
|
|
|
731
|
-
##
|
|
679
|
+
## Development Notes
|
|
680
|
+
|
|
681
|
+
- **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.
|
|
682
|
+
- **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.
|
|
683
|
+
|
|
684
|
+
---
|
|
732
685
|
|
|
733
|
-
|
|
686
|
+
## Upgrading from 1.x
|
|
687
|
+
|
|
688
|
+
2.0.0 targets Android SDK 3.1.0 and iOS SDK 2.2.0 and is a breaking release.
|
|
689
|
+
|
|
690
|
+
**Removed**
|
|
691
|
+
- `NativeAdShiftReactNativePlugin` and `AdShiftNativeSpec` exports — the native module is internal.
|
|
692
|
+
- `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.
|
|
693
|
+
- `StartResult.message`.
|
|
694
|
+
|
|
695
|
+
**Changed**
|
|
696
|
+
- `start()` resolves `{ success, apiKeyValidationStatus?, errorCode?, errorMessage? }` after the *local* start and no longer waits for API key verification. It never rejects.
|
|
697
|
+
- `handleDeepLink(url)` returns `Promise<void>`; the result arrives through `onDeepLink`. Register `onDeepLink` before `initialize()` to be sure nothing is missed (results are buffered anyway).
|
|
698
|
+
- 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.
|
|
699
|
+
- Setters called before `initialize()` are kept and applied afterwards instead of failing.
|
|
700
|
+
- 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`.
|
|
701
|
+
- Consent flags are tri-state (`boolean | null`); `AdshiftConsent.forGDPRUser()` accepts partial input and `forNonGDPRUser()` sends no individual flags. `AdshiftConsent.isConsentGranted` requires explicit `true`.
|
|
702
|
+
- `refreshConsent()` resolves a typed `ConsentSnapshot`.
|
|
703
|
+
- `AdshiftDeepLink.params` is `Record<string, string>`; `isFirstSession` added (Android).
|
|
704
|
+
- `trackEvent`/`trackPurchase` calls before `start()` are queued (up to 100) instead of failing; after `stop()` they reject with `NOT_STARTED`.
|
|
705
|
+
- All errors are `AdshiftError` with `code` from `AdshiftErrorCode`; native codes moved to `userInfo.nativeCode`.
|
|
706
|
+
- `getInfo()` returns the real plugin version and `nativeSdkVersions`.
|
|
707
|
+
- Minimum iOS is 15.1; Android `minSdk` 24.
|
|
708
|
+
|
|
709
|
+
**Added**
|
|
710
|
+
- `logAdRevenue()`, `AdshiftMediationNetwork`, `AdshiftEventType.AdRevenue`.
|
|
711
|
+
- `getAdShiftDeviceId()`, `setBrandedDomains()`, `setMetaAppId()`, `addPushNotificationDeepLinkPath()`, `handlePushNotification()`.
|
|
712
|
+
- `AdshiftConfig.brandedDomains`, `metaAppId`, `pushDeepLinkPaths`, `autoHandleDeepLinks`, `onError`.
|
|
713
|
+
- `AdshiftErrorCode`, `isAdshiftError`, `PLUGIN_VERSION`, `ConsentSnapshot`, `ConsentFlag`.
|
|
714
|
+
- Jest mock at `@adshift/react-native-plugin/jest`.
|
|
734
715
|
|
|
735
|
-
|
|
716
|
+
---
|
|
717
|
+
|
|
718
|
+
## Example App
|
|
736
719
|
|
|
737
720
|
```bash
|
|
738
|
-
|
|
739
|
-
pod
|
|
740
|
-
|
|
721
|
+
yarn
|
|
722
|
+
cd example/ios && bundle install && bundle exec pod install && cd ../..
|
|
723
|
+
yarn example ios # or: yarn example android
|
|
741
724
|
```
|
|
742
725
|
|
|
743
|
-
|
|
744
|
-
|
|
745
|
-
1. Ensure `NSUserTrackingUsageDescription` is in `Info.plist`
|
|
746
|
-
2. Set `waitForATTBeforeStart: true` in config
|
|
747
|
-
3. Test on physical device (simulator may not show ATT)
|
|
726
|
+
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.
|
|
748
727
|
|
|
749
|
-
|
|
728
|
+
---
|
|
750
729
|
|
|
751
|
-
|
|
752
|
-
2. Check `apple-app-site-association` file is accessible
|
|
753
|
-
3. Test with: `xcrun simctl openurl booted "yourapp://open?test=1"`
|
|
730
|
+
## Troubleshooting
|
|
754
731
|
|
|
755
|
-
|
|
732
|
+
**Links do not arrive on iOS while the app is running** — add the `RCTLinkingManager` methods to `AppDelegate.swift` ([Platform Setup → iOS](#ios)).
|
|
756
733
|
|
|
757
|
-
|
|
734
|
+
**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`.
|
|
758
735
|
|
|
759
|
-
|
|
736
|
+
**`start()` takes long on iOS** — `waitForATTBeforeStart: true` without an ATT prompt waits for `attTimeoutMs`. Set the option only when your app actually prompts.
|
|
760
737
|
|
|
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
|
-
```
|
|
738
|
+
**Manifest merger conflict on `fullBackupContent` / `dataExtractionRules`** — see [Android backup rules](#android).
|
|
770
739
|
|
|
771
|
-
|
|
740
|
+
**`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).
|
|
772
741
|
|
|
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"`
|
|
742
|
+
**Jest fails at import** — register the mock from [Testing](#testing).
|
|
776
743
|
|
|
777
|
-
|
|
744
|
+
**Events are not sent** — check `start()` resolved with `success: true`, enable `isDebug` and read the native logs; a rejected API key shows up through `config.onError` as `INVALID_API_KEY`.
|
|
778
745
|
|
|
779
|
-
|
|
746
|
+
---
|
|
780
747
|
|
|
781
|
-
|
|
782
|
-
2. Enable debug mode: `Adshift.setDebugEnabled(true)`
|
|
783
|
-
3. Check network connectivity
|
|
784
|
-
4. Verify API key is correct
|
|
748
|
+
## For Maintainers
|
|
785
749
|
|
|
786
|
-
|
|
750
|
+
**Release**
|
|
751
|
+
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`).
|
|
752
|
+
2. `yarn version <new version>` regenerates `src/version.ts`; commit.
|
|
753
|
+
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`.
|
|
754
|
+
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
755
|
|
|
788
|
-
|
|
756
|
+
**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
757
|
|
|
790
|
-
|
|
791
|
-
yarn add @adshift/react-native-plugin@latest
|
|
792
|
-
```
|
|
758
|
+
**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
759
|
|
|
794
760
|
---
|
|
795
761
|
|
|
796
762
|
## Support
|
|
797
763
|
|
|
798
|
-
-
|
|
799
|
-
-
|
|
800
|
-
-
|
|
764
|
+
- Documentation: https://dev.adshift.com/docs/react-native-sdk
|
|
765
|
+
- Issues: https://github.com/AdShift/react_native_plugin/issues
|
|
766
|
+
- Email: support@adshift.com
|
|
801
767
|
|
|
802
768
|
---
|
|
803
769
|
|
|
@@ -805,6 +771,4 @@ yarn add @adshift/react-native-plugin@latest
|
|
|
805
771
|
|
|
806
772
|
This SDK is proprietary software. See [LICENSE](LICENSE) for details.
|
|
807
773
|
|
|
808
|
-
---
|
|
809
|
-
|
|
810
774
|
© 2024-2026 AdShift. All rights reserved.
|