@adshift/react-native-plugin 1.0.0 → 2.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (180) hide show
  1. package/AdShiftReactNativePlugin.podspec +11 -7
  2. package/CHANGELOG.md +138 -0
  3. package/README.md +513 -542
  4. package/android/build.gradle +17 -3
  5. package/android/consumer-rules.pro +21 -0
  6. package/android/src/main/java/com/adshift/reactnativeplugin/AdShiftReactNativePluginModule.kt +786 -229
  7. package/android/src/test/java/com/adshift/reactnativeplugin/ConsentSnapshotTest.kt +180 -0
  8. package/android/src/test/java/com/adshift/reactnativeplugin/DeepLinkDeliveryTest.kt +146 -0
  9. package/android/src/test/java/com/adshift/reactnativeplugin/InitializeOrderingTest.kt +111 -0
  10. package/android/src/test/java/com/adshift/reactnativeplugin/IntentLinkDedupTest.kt +168 -0
  11. package/android/src/test/java/com/adshift/reactnativeplugin/LaunchIntentForwardingTest.kt +106 -0
  12. package/android/src/test/java/com/adshift/reactnativeplugin/ModuleTestSupport.kt +167 -0
  13. package/android/src/test/java/com/adshift/reactnativeplugin/StartVerdictTest.kt +164 -0
  14. package/ios/AdShiftReactNativePlugin.h +7 -7
  15. package/ios/AdShiftReactNativePlugin.mm +200 -181
  16. package/ios/AdShiftReactNativePluginHelper.swift +584 -286
  17. package/ios/Core/BridgeRules.swift +82 -0
  18. package/lib/commonjs/Adshift.js +1138 -0
  19. package/lib/commonjs/Adshift.js.map +1 -0
  20. package/lib/commonjs/NativeAdShiftReactNativePlugin.js +22 -0
  21. package/lib/commonjs/NativeAdShiftReactNativePlugin.js.map +1 -0
  22. package/lib/commonjs/index.js +94 -0
  23. package/lib/commonjs/index.js.map +1 -0
  24. package/lib/commonjs/jest/index.js +164 -0
  25. package/lib/commonjs/jest/index.js.map +1 -0
  26. package/lib/commonjs/nativeSdkVersions.js +17 -0
  27. package/lib/commonjs/nativeSdkVersions.js.map +1 -0
  28. package/lib/commonjs/package.json +1 -0
  29. package/lib/commonjs/types/AdshiftAdRevenue.js +47 -0
  30. package/lib/commonjs/types/AdshiftAdRevenue.js.map +1 -0
  31. package/lib/commonjs/types/AdshiftConfig.js +45 -0
  32. package/lib/commonjs/types/AdshiftConfig.js.map +1 -0
  33. package/lib/commonjs/types/AdshiftConsent.js +113 -0
  34. package/lib/commonjs/types/AdshiftConsent.js.map +1 -0
  35. package/lib/commonjs/types/AdshiftConsentSnapshot.js +69 -0
  36. package/lib/commonjs/types/AdshiftConsentSnapshot.js.map +1 -0
  37. package/lib/commonjs/types/AdshiftDeepLink.js +154 -0
  38. package/lib/commonjs/types/AdshiftDeepLink.js.map +1 -0
  39. package/lib/commonjs/types/AdshiftError.js +91 -0
  40. package/lib/commonjs/types/AdshiftError.js.map +1 -0
  41. package/lib/commonjs/types/AdshiftEventParam.js +140 -0
  42. package/lib/commonjs/types/AdshiftEventParam.js.map +1 -0
  43. package/lib/commonjs/types/AdshiftEventType.js +88 -0
  44. package/lib/commonjs/types/AdshiftEventType.js.map +1 -0
  45. package/lib/commonjs/types/AdshiftThirdPartySharing.js +70 -0
  46. package/lib/commonjs/types/AdshiftThirdPartySharing.js.map +1 -0
  47. package/lib/commonjs/types/index.js +123 -0
  48. package/lib/commonjs/types/index.js.map +1 -0
  49. package/lib/commonjs/version.js +9 -0
  50. package/lib/commonjs/version.js.map +1 -0
  51. package/lib/module/Adshift.js +962 -296
  52. package/lib/module/Adshift.js.map +1 -1
  53. package/lib/module/NativeAdShiftReactNativePlugin.js +10 -7
  54. package/lib/module/NativeAdShiftReactNativePlugin.js.map +1 -1
  55. package/lib/module/index.js +26 -25
  56. package/lib/module/index.js.map +1 -1
  57. package/lib/module/jest/index.js +144 -0
  58. package/lib/module/jest/index.js.map +1 -0
  59. package/lib/module/nativeSdkVersions.js +13 -0
  60. package/lib/module/nativeSdkVersions.js.map +1 -0
  61. package/lib/module/types/AdshiftAdRevenue.js +43 -0
  62. package/lib/module/types/AdshiftAdRevenue.js.map +1 -0
  63. package/lib/module/types/AdshiftConfig.js +23 -26
  64. package/lib/module/types/AdshiftConfig.js.map +1 -1
  65. package/lib/module/types/AdshiftConsent.js +57 -50
  66. package/lib/module/types/AdshiftConsent.js.map +1 -1
  67. package/lib/module/types/AdshiftConsentSnapshot.js +65 -0
  68. package/lib/module/types/AdshiftConsentSnapshot.js.map +1 -0
  69. package/lib/module/types/AdshiftDeepLink.js +97 -67
  70. package/lib/module/types/AdshiftDeepLink.js.map +1 -1
  71. package/lib/module/types/AdshiftError.js +87 -0
  72. package/lib/module/types/AdshiftError.js.map +1 -0
  73. package/lib/module/types/AdshiftEventParam.js +135 -0
  74. package/lib/module/types/AdshiftEventParam.js.map +1 -0
  75. package/lib/module/types/AdshiftEventType.js +11 -36
  76. package/lib/module/types/AdshiftEventType.js.map +1 -1
  77. package/lib/module/types/AdshiftThirdPartySharing.js +65 -0
  78. package/lib/module/types/AdshiftThirdPartySharing.js.map +1 -0
  79. package/lib/module/types/index.js +9 -7
  80. package/lib/module/types/index.js.map +1 -1
  81. package/lib/module/version.js +5 -0
  82. package/lib/module/version.js.map +1 -0
  83. package/lib/typescript/commonjs/package.json +1 -0
  84. package/lib/typescript/commonjs/src/Adshift.d.ts +314 -0
  85. package/lib/typescript/commonjs/src/Adshift.d.ts.map +1 -0
  86. package/lib/typescript/commonjs/src/NativeAdShiftReactNativePlugin.d.ts +102 -0
  87. package/lib/typescript/commonjs/src/NativeAdShiftReactNativePlugin.d.ts.map +1 -0
  88. package/lib/typescript/commonjs/src/index.d.ts +51 -0
  89. package/lib/typescript/commonjs/src/index.d.ts.map +1 -0
  90. package/lib/typescript/commonjs/src/jest/index.d.ts +103 -0
  91. package/lib/typescript/commonjs/src/jest/index.d.ts.map +1 -0
  92. package/lib/typescript/commonjs/src/nativeSdkVersions.d.ts +11 -0
  93. package/lib/typescript/commonjs/src/nativeSdkVersions.d.ts.map +1 -0
  94. package/lib/typescript/commonjs/src/types/AdshiftAdRevenue.d.ts +56 -0
  95. package/lib/typescript/commonjs/src/types/AdshiftAdRevenue.d.ts.map +1 -0
  96. package/lib/typescript/commonjs/src/types/AdshiftConfig.d.ts +104 -0
  97. package/lib/typescript/commonjs/src/types/AdshiftConfig.d.ts.map +1 -0
  98. package/lib/typescript/commonjs/src/types/AdshiftConsent.d.ts +76 -0
  99. package/lib/typescript/commonjs/src/types/AdshiftConsent.d.ts.map +1 -0
  100. package/lib/typescript/commonjs/src/types/AdshiftConsentSnapshot.d.ts +56 -0
  101. package/lib/typescript/commonjs/src/types/AdshiftConsentSnapshot.d.ts.map +1 -0
  102. package/lib/typescript/commonjs/src/types/AdshiftDeepLink.d.ts +89 -0
  103. package/lib/typescript/commonjs/src/types/AdshiftDeepLink.d.ts.map +1 -0
  104. package/lib/typescript/commonjs/src/types/AdshiftError.d.ts +57 -0
  105. package/lib/typescript/commonjs/src/types/AdshiftError.d.ts.map +1 -0
  106. package/lib/typescript/commonjs/src/types/AdshiftEventParam.d.ts +111 -0
  107. package/lib/typescript/commonjs/src/types/AdshiftEventParam.d.ts.map +1 -0
  108. package/lib/typescript/{src → commonjs/src}/types/AdshiftEventType.d.ts +12 -35
  109. package/lib/typescript/commonjs/src/types/AdshiftEventType.d.ts.map +1 -0
  110. package/lib/typescript/commonjs/src/types/AdshiftThirdPartySharing.d.ts +53 -0
  111. package/lib/typescript/commonjs/src/types/AdshiftThirdPartySharing.d.ts.map +1 -0
  112. package/lib/typescript/commonjs/src/types/index.d.ts +17 -0
  113. package/lib/typescript/commonjs/src/types/index.d.ts.map +1 -0
  114. package/lib/typescript/commonjs/src/version.d.ts +2 -0
  115. package/lib/typescript/commonjs/src/version.d.ts.map +1 -0
  116. package/lib/typescript/module/src/Adshift.d.ts +314 -0
  117. package/lib/typescript/module/src/Adshift.d.ts.map +1 -0
  118. package/lib/typescript/module/src/NativeAdShiftReactNativePlugin.d.ts +102 -0
  119. package/lib/typescript/module/src/NativeAdShiftReactNativePlugin.d.ts.map +1 -0
  120. package/lib/typescript/module/src/index.d.ts +51 -0
  121. package/lib/typescript/module/src/index.d.ts.map +1 -0
  122. package/lib/typescript/module/src/jest/index.d.ts +103 -0
  123. package/lib/typescript/module/src/jest/index.d.ts.map +1 -0
  124. package/lib/typescript/module/src/nativeSdkVersions.d.ts +11 -0
  125. package/lib/typescript/module/src/nativeSdkVersions.d.ts.map +1 -0
  126. package/lib/typescript/module/src/types/AdshiftAdRevenue.d.ts +56 -0
  127. package/lib/typescript/module/src/types/AdshiftAdRevenue.d.ts.map +1 -0
  128. package/lib/typescript/module/src/types/AdshiftConfig.d.ts +104 -0
  129. package/lib/typescript/module/src/types/AdshiftConfig.d.ts.map +1 -0
  130. package/lib/typescript/module/src/types/AdshiftConsent.d.ts +76 -0
  131. package/lib/typescript/module/src/types/AdshiftConsent.d.ts.map +1 -0
  132. package/lib/typescript/module/src/types/AdshiftConsentSnapshot.d.ts +56 -0
  133. package/lib/typescript/module/src/types/AdshiftConsentSnapshot.d.ts.map +1 -0
  134. package/lib/typescript/module/src/types/AdshiftDeepLink.d.ts +89 -0
  135. package/lib/typescript/module/src/types/AdshiftDeepLink.d.ts.map +1 -0
  136. package/lib/typescript/module/src/types/AdshiftError.d.ts +57 -0
  137. package/lib/typescript/module/src/types/AdshiftError.d.ts.map +1 -0
  138. package/lib/typescript/module/src/types/AdshiftEventParam.d.ts +111 -0
  139. package/lib/typescript/module/src/types/AdshiftEventParam.d.ts.map +1 -0
  140. package/lib/typescript/module/src/types/AdshiftEventType.d.ts +64 -0
  141. package/lib/typescript/module/src/types/AdshiftEventType.d.ts.map +1 -0
  142. package/lib/typescript/module/src/types/AdshiftThirdPartySharing.d.ts +53 -0
  143. package/lib/typescript/module/src/types/AdshiftThirdPartySharing.d.ts.map +1 -0
  144. package/lib/typescript/module/src/types/index.d.ts +17 -0
  145. package/lib/typescript/module/src/types/index.d.ts.map +1 -0
  146. package/lib/typescript/module/src/version.d.ts +2 -0
  147. package/lib/typescript/module/src/version.d.ts.map +1 -0
  148. package/package.json +50 -11
  149. package/src/Adshift.ts +1276 -342
  150. package/src/NativeAdShiftReactNativePlugin.ts +81 -115
  151. package/src/index.tsx +40 -25
  152. package/src/jest/index.ts +224 -0
  153. package/src/nativeSdkVersions.ts +10 -0
  154. package/src/types/AdshiftAdRevenue.ts +58 -0
  155. package/src/types/AdshiftConfig.ts +101 -53
  156. package/src/types/AdshiftConsent.ts +75 -72
  157. package/src/types/AdshiftConsentSnapshot.ts +103 -0
  158. package/src/types/AdshiftDeepLink.ts +123 -102
  159. package/src/types/AdshiftError.ts +107 -0
  160. package/src/types/AdshiftEventParam.ts +216 -0
  161. package/src/types/AdshiftEventType.ts +13 -35
  162. package/src/types/AdshiftThirdPartySharing.ts +63 -0
  163. package/src/types/index.ts +38 -6
  164. package/src/version.ts +2 -0
  165. package/lib/typescript/src/Adshift.d.ts +0 -335
  166. package/lib/typescript/src/Adshift.d.ts.map +0 -1
  167. package/lib/typescript/src/NativeAdShiftReactNativePlugin.d.ts +0 -143
  168. package/lib/typescript/src/NativeAdShiftReactNativePlugin.d.ts.map +0 -1
  169. package/lib/typescript/src/index.d.ts +0 -47
  170. package/lib/typescript/src/index.d.ts.map +0 -1
  171. package/lib/typescript/src/types/AdshiftConfig.d.ts +0 -74
  172. package/lib/typescript/src/types/AdshiftConfig.d.ts.map +0 -1
  173. package/lib/typescript/src/types/AdshiftConsent.d.ts +0 -88
  174. package/lib/typescript/src/types/AdshiftConsent.d.ts.map +0 -1
  175. package/lib/typescript/src/types/AdshiftDeepLink.d.ts +0 -93
  176. package/lib/typescript/src/types/AdshiftDeepLink.d.ts.map +0 -1
  177. package/lib/typescript/src/types/AdshiftEventType.d.ts.map +0 -1
  178. package/lib/typescript/src/types/index.d.ts +0 -5
  179. package/lib/typescript/src/types/index.d.ts.map +0 -1
  180. /package/lib/typescript/{package.json → module/package.json} +0 -0
@@ -1,66 +1,89 @@
1
+ import type { AdshiftError } from './AdshiftError';
2
+
1
3
  /**
2
4
  * Configuration for initializing the AdShift SDK.
3
5
  *
6
+ * Every option other than `apiKey` is optional; omitted options keep the
7
+ * native SDK defaults. All options must be set before `Adshift.start()`.
8
+ *
4
9
  * @example
5
10
  * ```typescript
6
- * const config: AdshiftConfig = {
11
+ * Adshift.initialize({
7
12
  * apiKey: 'your-api-key',
8
- * isDebug: true,
9
- * };
10
- * await Adshift.initialize(config);
13
+ * isDebug: __DEV__,
14
+ * brandedDomains: ['links.example.com'],
15
+ * });
11
16
  * ```
12
17
  */
13
18
  export interface AdshiftConfig {
14
19
  /**
15
- * API key for authenticating with AdShift backend.
16
- *
17
- * Required. Get your API key from the AdShift dashboard.
20
+ * API key from the AdShift dashboard. Required.
18
21
  */
19
22
  apiKey: string;
20
23
 
21
24
  /**
22
- * Enable debug logging.
23
- *
24
- * When true, SDK will output verbose logs for debugging.
25
+ * Enable verbose SDK logging.
25
26
  * @default false
26
27
  */
27
28
  isDebug?: boolean;
28
29
 
29
30
  /**
30
- * Debounce interval for automatic APP_OPEN events (in milliseconds).
31
- *
32
- * Controls how often APP_OPEN events are sent when app returns from background.
33
- * @default 10000 (10 seconds)
31
+ * Debounce interval for automatic `app_open` events, in milliseconds.
32
+ * @default 10000
34
33
  */
35
34
  appOpenDebounceMs?: number;
36
35
 
37
- // ============ iOS-only options ============
36
+ /**
37
+ * Branded (custom) attribution domains, e.g. `links.example.com`.
38
+ * Links on these hosts are treated as attribution links.
39
+ */
40
+ brandedDomains?: string[];
41
+
42
+ /**
43
+ * Meta app id used to parse Meta App Links.
44
+ * @platform android
45
+ */
46
+ metaAppId?: string;
47
+
48
+ /**
49
+ * Key paths inside a push notification payload that carry an AdShift deep
50
+ * link, e.g. `[['data', 'as_push_link']]`. Registering your own paths takes
51
+ * over from the top-level `as_push_link` the SDK reads on its own, so list
52
+ * that key too if your payloads also use it.
53
+ */
54
+ pushDeepLinkPaths?: string[][];
38
55
 
39
56
  /**
40
- * Disable SKAdNetwork integration (iOS only).
57
+ * Forward every URL that opens the app to the SDK automatically.
41
58
  *
42
- * Set to true to completely disable SKAN functionality.
43
- * @default false (SKAN enabled)
59
+ * Android: the plugin reads the launch Intent and every new Intent.
60
+ * iOS: the plugin uses `Linking` (`getInitialURL` and the `url` event).
61
+ * Set to `false` to call `Adshift.handleDeepLink()` yourself.
62
+ * @default true
63
+ */
64
+ autoHandleDeepLinks?: boolean;
65
+
66
+ // ============ iOS-only options ============
67
+
68
+ /**
69
+ * Disable SKAdNetwork integration.
70
+ * @default false
44
71
  * @platform ios
45
72
  */
46
73
  disableSKAN?: boolean;
47
74
 
48
75
  /**
49
- * Wait for ATT authorization before sending install event (iOS only).
50
- *
51
- * When enabled, SDK will wait for App Tracking Transparency authorization
52
- * before sending the install event to include IDFA if user grants permission.
76
+ * Wait for the App Tracking Transparency decision before the first
77
+ * install/open event. Only useful when the app requests ATT itself.
53
78
  * @default false
54
79
  * @platform ios
55
80
  */
56
81
  waitForATTBeforeStart?: boolean;
57
82
 
58
83
  /**
59
- * Timeout for ATT authorization wait in milliseconds (iOS only).
60
- *
61
- * Maximum time to wait for ATT response when `waitForATTBeforeStart` is enabled.
62
- * Range: 5000 - 120000 (5s - 2 minutes)
63
- * @default 30000 (30 seconds)
84
+ * Maximum time to wait for the ATT decision, in milliseconds. The SDK
85
+ * clamps the value to 5000 – 120000 instead of rejecting it.
86
+ * @default 30000
64
87
  * @platform ios
65
88
  */
66
89
  attTimeoutMs?: number;
@@ -68,41 +91,66 @@ export interface AdshiftConfig {
68
91
  // ============ Android-only options ============
69
92
 
70
93
  /**
71
- * Enable OAID collection (Android only).
72
- *
73
- * OAID is an alternative to Google Advertising ID used on Chinese Android devices.
94
+ * Enable OAID collection on devices without Google Play services.
74
95
  * @default true
75
96
  * @platform android
76
97
  */
77
98
  collectOaid?: boolean;
99
+
100
+ // ============ Diagnostics ============
101
+
102
+ /**
103
+ * Called when the SDK declines a call it cannot make: an invalid argument,
104
+ * an unusable config, or an API key the backend rejected.
105
+ *
106
+ * Methods that return nothing cannot answer the caller, and the SDK never
107
+ * raises into your code, so this is how those failures become visible. In
108
+ * development they are also written to the console. Wire it to your own
109
+ * reporting to catch integration mistakes in release builds.
110
+ *
111
+ * @example
112
+ * ```typescript
113
+ * Adshift.initialize({
114
+ * apiKey: 'your-api-key',
115
+ * onError: (error) => Sentry.captureMessage(`AdShift: ${error.code}`),
116
+ * });
117
+ * ```
118
+ */
119
+ onError?: (error: AdshiftError) => void;
78
120
  }
79
121
 
80
122
  /**
81
- * Converts AdshiftConfig to a plain object for native bridge communication.
82
- * Filters out undefined values.
123
+ * Converts `AdshiftConfig` to a plain object for the native bridge.
124
+ * Only defined, serializable keys are included.
125
+ *
126
+ * @internal
83
127
  */
84
- export function configToMap(config: AdshiftConfig): Record<string, unknown> {
85
- const map: Record<string, unknown> = {
86
- apiKey: config.apiKey,
87
- isDebug: config.isDebug ?? false,
88
- appOpenDebounceMs: config.appOpenDebounceMs ?? 10000,
89
- };
90
-
91
- // iOS only
92
- if (config.disableSKAN !== undefined) {
93
- map.disableSKAN = config.disableSKAN;
94
- }
95
- if (config.waitForATTBeforeStart !== undefined) {
96
- map.waitForATTBeforeStart = config.waitForATTBeforeStart;
97
- }
98
- if (config.attTimeoutMs !== undefined) {
99
- map.attTimeoutMs = config.attTimeoutMs;
100
- }
128
+ /**
129
+ * Options that travel to the native SDK, in the order they are declared above.
130
+ * Only these keys cross the bridge: a value the bridge cannot convert throws
131
+ * where `initialize()` is called, which in most apps is module scope.
132
+ */
133
+ const BRIDGED_KEYS = [
134
+ 'apiKey',
135
+ 'isDebug',
136
+ 'appOpenDebounceMs',
137
+ 'brandedDomains',
138
+ 'metaAppId',
139
+ 'pushDeepLinkPaths',
140
+ 'autoHandleDeepLinks',
141
+ 'disableSKAN',
142
+ 'waitForATTBeforeStart',
143
+ 'attTimeoutMs',
144
+ 'collectOaid',
145
+ ] as const satisfies ReadonlyArray<keyof AdshiftConfig>;
101
146
 
102
- // Android only
103
- if (config.collectOaid !== undefined) {
104
- map.collectOaid = config.collectOaid;
147
+ export function configToMap(config: AdshiftConfig): Record<string, unknown> {
148
+ const map: Record<string, unknown> = {};
149
+ for (const key of BRIDGED_KEYS) {
150
+ const value = config[key];
151
+ if (value !== undefined && typeof value !== 'function') {
152
+ map[key] = value;
153
+ }
105
154
  }
106
-
107
155
  return map;
108
156
  }
@@ -1,127 +1,130 @@
1
+ /**
2
+ * A single consent decision.
3
+ *
4
+ * `true` = granted, `false` = denied, `null` = not decided yet.
5
+ * Undecided flags are not sent to the backend.
6
+ */
7
+ export type ConsentFlag = boolean | null;
8
+
1
9
  /**
2
10
  * User consent data for GDPR/DMA compliance.
3
11
  *
4
12
  * @example
5
13
  * ```typescript
6
- * // For GDPR users who accepted all
7
- * const consent = AdshiftConsent.forGDPRUser({
8
- * hasConsentForDataUsage: true,
9
- * hasConsentForAdsPersonalization: true,
10
- * hasConsentForAdStorage: true,
11
- * });
14
+ * // GDPR user who accepted everything
15
+ * Adshift.setConsentData(
16
+ * AdshiftConsent.forGDPRUser({
17
+ * hasConsentForDataUsage: true,
18
+ * hasConsentForAdsPersonalization: true,
19
+ * hasConsentForAdStorage: true,
20
+ * })
21
+ * );
12
22
  *
13
- * // For non-GDPR users
14
- * const consent = AdshiftConsent.forNonGDPRUser();
15
- *
16
- * await Adshift.setConsentData(consent);
23
+ * // Non-GDPR user
24
+ * Adshift.setConsentData(AdshiftConsent.forNonGDPRUser());
17
25
  * ```
18
26
  */
19
27
  export interface AdshiftConsent {
20
- /**
21
- * Whether the user is subject to GDPR.
22
- */
28
+ /** Whether the user is subject to GDPR. */
23
29
  isUserSubjectToGDPR: boolean;
24
30
 
25
- /**
26
- * Whether user has consented to data usage.
27
- */
28
- hasConsentForDataUsage: boolean;
31
+ /** Consent to data usage. Ignored when `isUserSubjectToGDPR` is false. */
32
+ hasConsentForDataUsage?: ConsentFlag;
29
33
 
30
- /**
31
- * Whether user has consented to ads personalization.
32
- */
33
- hasConsentForAdsPersonalization: boolean;
34
+ /** Consent to ads personalization. Ignored when `isUserSubjectToGDPR` is false. */
35
+ hasConsentForAdsPersonalization?: ConsentFlag;
34
36
 
35
- /**
36
- * Whether user has consented to ad storage.
37
- */
38
- hasConsentForAdStorage: boolean;
37
+ /** Consent to ad storage. Ignored when `isUserSubjectToGDPR` is false. */
38
+ hasConsentForAdStorage?: ConsentFlag;
39
39
  }
40
40
 
41
41
  /**
42
- * Helper functions for creating AdshiftConsent objects.
42
+ * Helper functions for creating `AdshiftConsent` objects.
43
43
  */
44
44
  export const AdshiftConsent = {
45
45
  /**
46
46
  * Creates consent for a user subject to GDPR.
47
47
  *
48
- * Use this when user is in a GDPR region and has provided explicit consent.
49
- *
50
- * @example
51
- * ```typescript
52
- * const consent = AdshiftConsent.forGDPRUser({
53
- * hasConsentForDataUsage: true,
54
- * hasConsentForAdsPersonalization: true,
55
- * hasConsentForAdStorage: true,
56
- * });
57
- * ```
48
+ * Flags that are omitted or `null` are treated as not decided.
58
49
  */
59
50
  forGDPRUser(options: {
60
- hasConsentForDataUsage: boolean;
61
- hasConsentForAdsPersonalization: boolean;
62
- hasConsentForAdStorage: boolean;
51
+ hasConsentForDataUsage?: ConsentFlag;
52
+ hasConsentForAdsPersonalization?: ConsentFlag;
53
+ hasConsentForAdStorage?: ConsentFlag;
63
54
  }): AdshiftConsent {
64
55
  return {
65
56
  isUserSubjectToGDPR: true,
66
- hasConsentForDataUsage: options.hasConsentForDataUsage,
67
- hasConsentForAdsPersonalization: options.hasConsentForAdsPersonalization,
68
- hasConsentForAdStorage: options.hasConsentForAdStorage,
57
+ hasConsentForDataUsage: options.hasConsentForDataUsage ?? null,
58
+ hasConsentForAdsPersonalization:
59
+ options.hasConsentForAdsPersonalization ?? null,
60
+ hasConsentForAdStorage: options.hasConsentForAdStorage ?? null,
69
61
  };
70
62
  },
71
63
 
72
64
  /**
73
65
  * Creates consent for a user NOT subject to GDPR.
74
66
  *
75
- * Use this when user is in a non-GDPR region (e.g., US, Asia).
76
- * All consent flags are set to true by default.
77
- *
78
- * @example
79
- * ```typescript
80
- * const consent = AdshiftConsent.forNonGDPRUser();
81
- * ```
67
+ * All processing is treated as permitted; individual flags are not sent.
82
68
  */
83
69
  forNonGDPRUser(): AdshiftConsent {
84
- return {
85
- isUserSubjectToGDPR: false,
86
- hasConsentForDataUsage: true,
87
- hasConsentForAdsPersonalization: true,
88
- hasConsentForAdStorage: true,
89
- };
70
+ return { isUserSubjectToGDPR: false };
90
71
  },
91
72
 
92
73
  /**
93
- * Determines whether consent is granted for tracking.
94
- *
95
- * If user is not subject to GDPR, consent is assumed granted.
96
- * If subject to GDPR, both data usage and ad storage must be granted.
74
+ * Whether consent is granted for tracking, following the SDK rule:
75
+ * non-GDPR users are always granted; GDPR users need explicit consent to
76
+ * both data usage and ad storage.
97
77
  */
98
78
  isConsentGranted(consent: AdshiftConsent): boolean {
99
79
  if (!consent.isUserSubjectToGDPR) return true;
100
- return consent.hasConsentForDataUsage && consent.hasConsentForAdStorage;
80
+ return (
81
+ consent.hasConsentForDataUsage === true &&
82
+ consent.hasConsentForAdStorage === true
83
+ );
101
84
  },
102
85
 
103
86
  /**
104
- * Creates consent from a plain object (native bridge response).
87
+ * Creates consent from a plain object.
88
+ *
89
+ * @internal
105
90
  */
106
91
  fromMap(map: Record<string, unknown>): AdshiftConsent {
92
+ const isGDPR = map.isUserSubjectToGDPR === true;
93
+ if (!isGDPR) {
94
+ return { isUserSubjectToGDPR: false };
95
+ }
107
96
  return {
108
- isUserSubjectToGDPR: (map.isUserSubjectToGDPR as boolean) ?? false,
109
- hasConsentForDataUsage: (map.hasConsentForDataUsage as boolean) ?? false,
110
- hasConsentForAdsPersonalization:
111
- (map.hasConsentForAdsPersonalization as boolean) ?? false,
112
- hasConsentForAdStorage: (map.hasConsentForAdStorage as boolean) ?? false,
97
+ isUserSubjectToGDPR: true,
98
+ hasConsentForDataUsage: readFlag(map.hasConsentForDataUsage),
99
+ hasConsentForAdsPersonalization: readFlag(
100
+ map.hasConsentForAdsPersonalization
101
+ ),
102
+ hasConsentForAdStorage: readFlag(map.hasConsentForAdStorage),
113
103
  };
114
104
  },
115
105
  };
116
106
 
107
+ function readFlag(value: unknown): ConsentFlag {
108
+ return typeof value === 'boolean' ? value : null;
109
+ }
110
+
117
111
  /**
118
- * Converts AdshiftConsent to a plain object for native bridge communication.
112
+ * Converts `AdshiftConsent` to a plain object for the native bridge.
113
+ * Undecided flags are sent as `null`.
114
+ *
115
+ * @internal
119
116
  */
120
- export function consentToMap(consent: AdshiftConsent): Record<string, boolean> {
117
+ export function consentToMap(
118
+ consent: AdshiftConsent
119
+ ): Record<string, boolean | null> {
120
+ if (!consent.isUserSubjectToGDPR) {
121
+ return { isUserSubjectToGDPR: false };
122
+ }
121
123
  return {
122
- isUserSubjectToGDPR: consent.isUserSubjectToGDPR,
123
- hasConsentForDataUsage: consent.hasConsentForDataUsage,
124
- hasConsentForAdsPersonalization: consent.hasConsentForAdsPersonalization,
125
- hasConsentForAdStorage: consent.hasConsentForAdStorage,
124
+ isUserSubjectToGDPR: true,
125
+ hasConsentForDataUsage: consent.hasConsentForDataUsage ?? null,
126
+ hasConsentForAdsPersonalization:
127
+ consent.hasConsentForAdsPersonalization ?? null,
128
+ hasConsentForAdStorage: consent.hasConsentForAdStorage ?? null,
126
129
  };
127
130
  }
@@ -0,0 +1,103 @@
1
+ /**
2
+ * Where the current consent state comes from.
3
+ *
4
+ * - `manual`: set through `Adshift.setConsentData()`
5
+ * - `tcf`: read from an IAB TCF v2.2 CMP
6
+ * - `gpp`: read from an IAB GPP string written by the CMP
7
+ * - `none`: no consent information available
8
+ */
9
+ export type ConsentSource = 'manual' | 'tcf' | 'gpp' | 'none';
10
+
11
+ /**
12
+ * Consent state as seen by the SDK, returned by `Adshift.refreshConsent()`.
13
+ */
14
+ export interface ConsentSnapshot {
15
+ source: ConsentSource;
16
+ /** IAB `gdprApplies` value when known (0 or 1). */
17
+ gdprApplies?: number;
18
+ /** Whether a TCF consent string is present on the device. */
19
+ tcStringPresent: boolean;
20
+ /** Whether a GPP string is present on the device. */
21
+ gppPresent?: boolean;
22
+ /**
23
+ * Whether a CMP has run on this device, judged by the keys a CMP writes when
24
+ * it starts rather than by a consent payload being readable.
25
+ *
26
+ * This is the field that separates the two cases the flags above cannot: a CMP
27
+ * installed but not yet answered looks identical to no CMP at all, and the two
28
+ * are fixed by opposite actions. `false` while you expect a CMP means it never
29
+ * ran or was never wired up; `true` with `source: 'none'` means it ran and the
30
+ * user has not answered yet, which resolves itself once they do.
31
+ */
32
+ cmpDetected: boolean;
33
+ /** Ad user data flag, when decided. */
34
+ adUserDataEnabled?: boolean;
35
+ /** Ad personalization flag, when decided. */
36
+ adPersonalizationEnabled?: boolean;
37
+ /** Ad storage flag, when decided. */
38
+ adStorageEnabled?: boolean;
39
+ /** When the snapshot was applied, in milliseconds since epoch. */
40
+ appliedAtMillis: number;
41
+ /**
42
+ * Whether consent lets the SDK attach the platform advertising identifier
43
+ * (GAID or OAID on Android, IDFA on iOS) to what it reports. The
44
+ * `adshift_device_id` is never affected.
45
+ *
46
+ * Each platform answers with the rule it applies to the flags above, and
47
+ * those rules differ, so read this instead of comparing the flags yourself.
48
+ */
49
+ adIdentifiersAllowed: boolean;
50
+ }
51
+
52
+ const SOURCES: ReadonlySet<string> = new Set(['manual', 'tcf', 'gpp', 'none']);
53
+
54
+ /**
55
+ * The platforms name the GPP source differently: Android reports `gpp_us_nat`,
56
+ * iOS reports `gpp`. Both mean the same axis, so they are reported as one value
57
+ * rather than leaving one platform to fall through to `none`.
58
+ *
59
+ * `gpp` is the name reported here because `gpp_us_nat` is one section of the
60
+ * framework — the US national one. A CMP writing a state section instead would
61
+ * make that name wrong, and the section actually read is a separate fact the
62
+ * backend already records. Naming the axis after the framework survives that.
63
+ */
64
+ const SOURCE_ALIASES: Readonly<Record<string, ConsentSource>> = Object.freeze({
65
+ gpp_us_nat: 'gpp',
66
+ });
67
+
68
+ /**
69
+ * Builds a `ConsentSnapshot` from a native bridge object.
70
+ *
71
+ * @internal
72
+ */
73
+ export function consentSnapshotFromMap(
74
+ map: Record<string, unknown>
75
+ ): ConsentSnapshot {
76
+ const rawSource = typeof map.source === 'string' ? map.source : 'none';
77
+ const aliased = SOURCE_ALIASES[rawSource] ?? rawSource;
78
+ const source = (SOURCES.has(aliased) ? aliased : 'none') as ConsentSource;
79
+ const snapshot: ConsentSnapshot = {
80
+ source,
81
+ tcStringPresent: map.tcStringPresent === true,
82
+ cmpDetected: map.cmpDetected === true,
83
+ appliedAtMillis:
84
+ typeof map.appliedAtMillis === 'number' ? map.appliedAtMillis : 0,
85
+ adIdentifiersAllowed: map.adIdentifiersAllowed === true,
86
+ };
87
+ if (typeof map.gdprApplies === 'number') {
88
+ snapshot.gdprApplies = map.gdprApplies;
89
+ }
90
+ if (typeof map.gppPresent === 'boolean') {
91
+ snapshot.gppPresent = map.gppPresent;
92
+ }
93
+ if (typeof map.adUserDataEnabled === 'boolean') {
94
+ snapshot.adUserDataEnabled = map.adUserDataEnabled;
95
+ }
96
+ if (typeof map.adPersonalizationEnabled === 'boolean') {
97
+ snapshot.adPersonalizationEnabled = map.adPersonalizationEnabled;
98
+ }
99
+ if (typeof map.adStorageEnabled === 'boolean') {
100
+ snapshot.adStorageEnabled = map.adStorageEnabled;
101
+ }
102
+ return snapshot;
103
+ }