@ethicly/react-native 0.0.0-stage → 0.2.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 (70) hide show
  1. package/CHANGELOG.md +75 -0
  2. package/LICENSE +21 -0
  3. package/README.md +313 -2
  4. package/core/package.json +6 -0
  5. package/interstitial/package.json +6 -0
  6. package/lib/commonjs/core/adapters.js +287 -0
  7. package/lib/commonjs/core/beacons.js +70 -0
  8. package/lib/commonjs/core/cache.js +206 -0
  9. package/lib/commonjs/core/click.js +19 -0
  10. package/lib/commonjs/core/client.js +489 -0
  11. package/lib/commonjs/core/config.js +113 -0
  12. package/lib/commonjs/core/http.js +115 -0
  13. package/lib/commonjs/core/index.js +20 -0
  14. package/lib/commonjs/core/outbox.js +192 -0
  15. package/lib/commonjs/core/tracker.js +374 -0
  16. package/lib/commonjs/core/types.js +4 -0
  17. package/lib/commonjs/index.js +22 -0
  18. package/lib/commonjs/interstitial.js +7 -0
  19. package/lib/commonjs/react/EthiclyInterstitial.js +286 -0
  20. package/lib/commonjs/react/useEthiclyInterstitial.js +54 -0
  21. package/lib/commonjs/version.js +5 -0
  22. package/lib/module/core/adapters.js +276 -0
  23. package/lib/module/core/beacons.js +64 -0
  24. package/lib/module/core/cache.js +202 -0
  25. package/lib/module/core/click.js +15 -0
  26. package/lib/module/core/client.js +485 -0
  27. package/lib/module/core/config.js +104 -0
  28. package/lib/module/core/http.js +105 -0
  29. package/lib/module/core/index.js +6 -0
  30. package/lib/module/core/outbox.js +186 -0
  31. package/lib/module/core/tracker.js +370 -0
  32. package/lib/module/core/types.js +3 -0
  33. package/lib/module/index.js +4 -0
  34. package/lib/module/interstitial.js +3 -0
  35. package/lib/module/react/EthiclyInterstitial.js +260 -0
  36. package/lib/module/react/useEthiclyInterstitial.js +51 -0
  37. package/lib/module/version.js +2 -0
  38. package/lib/typescript/core/adapters.d.ts +138 -0
  39. package/lib/typescript/core/beacons.d.ts +32 -0
  40. package/lib/typescript/core/cache.d.ts +53 -0
  41. package/lib/typescript/core/click.d.ts +8 -0
  42. package/lib/typescript/core/client.d.ts +58 -0
  43. package/lib/typescript/core/config.d.ts +24 -0
  44. package/lib/typescript/core/http.d.ts +34 -0
  45. package/lib/typescript/core/index.d.ts +8 -0
  46. package/lib/typescript/core/outbox.d.ts +56 -0
  47. package/lib/typescript/core/tracker.d.ts +95 -0
  48. package/lib/typescript/core/types.d.ts +170 -0
  49. package/lib/typescript/index.d.ts +3 -0
  50. package/lib/typescript/interstitial.d.ts +2 -0
  51. package/lib/typescript/react/EthiclyInterstitial.d.ts +39 -0
  52. package/lib/typescript/react/useEthiclyInterstitial.d.ts +20 -0
  53. package/lib/typescript/version.d.ts +2 -0
  54. package/package.json +101 -4
  55. package/src/core/adapters.ts +337 -0
  56. package/src/core/beacons.ts +81 -0
  57. package/src/core/cache.ts +216 -0
  58. package/src/core/click.ts +16 -0
  59. package/src/core/client.ts +547 -0
  60. package/src/core/config.ts +111 -0
  61. package/src/core/http.ts +115 -0
  62. package/src/core/index.ts +14 -0
  63. package/src/core/outbox.ts +193 -0
  64. package/src/core/tracker.ts +371 -0
  65. package/src/core/types.ts +180 -0
  66. package/src/index.ts +5 -0
  67. package/src/interstitial.ts +4 -0
  68. package/src/react/EthiclyInterstitial.tsx +386 -0
  69. package/src/react/useEthiclyInterstitial.ts +74 -0
  70. package/src/version.ts +2 -0
package/CHANGELOG.md ADDED
@@ -0,0 +1,75 @@
1
+ # Changelog
2
+
3
+ All notable changes to `@ethicly/react-native` are recorded here. The format
4
+ follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the
5
+ package uses [Semantic Versioning](https://semver.org/). Every version speaks
6
+ contract v1 of the Ethicly app API (`docs/APP_API_V1.md`).
7
+
8
+ ## [0.2.0] - 2026-11-15
9
+
10
+ ### Added
11
+
12
+ - Unsent beacons survive the app being killed. What a rendered ad still owes
13
+ the server (`/impression` with its `client_impression_id`, `/viewable`,
14
+ video events) is kept in `storage` and sent on the next start. Only
15
+ idempotent beacons are kept, so a replay never counts anything twice;
16
+ `/click` is never kept or retried. At most 20 ads, each dropped one hour
17
+ after it was shown. Held back while a kill switch (`app_disabled`,
18
+ `sdk_unsupported`) is on or the key is refused.
19
+ - Sessions: coming back after 30 minutes or more in the background
20
+ (`SESSION_TIMEOUT_MS`) starts a new session, so `interstitial.max_per_session`
21
+ counts from zero again. Uses React Native's `AppState`; the new
22
+ `appState` option replaces it, and `appState: null` turns sessions off.
23
+ - `min_gap_s` survives restarts: the last shown time is stored through
24
+ `storage`. A stored time in the future is ignored.
25
+ - `<EthiclyInterstitial />` is safe-area aware: a new `insets` prop, else
26
+ `react-native-safe-area-context` when the app has it (read without
27
+ requiring its provider), else the status bar height on Android. The 0.1
28
+ positions (56 from the top, 44 from the bottom) are a floor, so insets only
29
+ move the controls inward and phones without a notch look as before.
30
+ - `createExpoFileCache` takes `import * as FileSystem from 'expo-file-system'`
31
+ on any Expo SDK from 50: the object API of SDK 54+ (`File`, `Directory`,
32
+ `Paths`) or the legacy functions (also from `expo-file-system/legacy`).
33
+ Anything else streams, with one warning.
34
+ - Optional peer dependencies: `expo-file-system`,
35
+ `@react-native-async-storage/async-storage`, `react-native-safe-area-context`.
36
+
37
+ ### Changed
38
+
39
+ - `testMode` is ignored in a React Native release build (`__DEV__` false):
40
+ ads are served and billed normally, and the SDK logs an error through the
41
+ logger and once through `console.error`. Where `__DEV__` is not defined
42
+ (Node scripts, tests) test mode still works.
43
+ - Beacon retries wait a random time between 0 and the backoff ceiling (full
44
+ jitter), so installs that failed together do not retry together. The ceiling
45
+ is unchanged: 1 s doubling, capped at 60 s, for up to one hour.
46
+ - `canShow()` answers false until the stored frequency state has loaded, a
47
+ moment after `createEthicly`; `ready`, `preload()` and `loadInterstitial()`
48
+ wait for it.
49
+
50
+ ## [0.1.0] - 2026-11-14
51
+
52
+ First version.
53
+
54
+ ### Added
55
+
56
+ - Headless core: `/config` with caching and last-known fallback, kill switch,
57
+ `min_sdk`, interstitial serve, video and poster prefetch with an LRU cache,
58
+ frequency caps, `setAdsEnabled`, test mode.
59
+ - Tracker: immediate `/impression` with an idempotent `client_impression_id`,
60
+ `/viewable` after continuous visible playback, quartile video events,
61
+ `/click` with the `ethicly_click` token, one hour expiry, retry rules.
62
+ - `useEthiclyInterstitial` hook.
63
+ - Creative cache bounded on disk: size checked before writing, index saved
64
+ before each download, unindexed files swept on load.
65
+ - Optional `<EthiclyInterstitial />` screen (`@ethicly/react-native/interstitial`,
66
+ needs `expo-video`): StrictMode safe, skip countdown with a wall-clock
67
+ fallback, Android back once Skip is allowed, `skipStyle` and `skipTextStyle`.
68
+ - The skip control is a solid black pill reading "Skip in N", then "Skip Ad"
69
+ with a skip-to-end icon.
70
+ - A small "Sponsored by Ethicly.ch" line under the call-to-action button.
71
+ - Video starts with sound by default (`interstitial.audio` `on`); `optional`
72
+ starts muted, `none` is always muted.
73
+ - `prepare` builds `lib/`, so `npm pack` gives an installable tarball.
74
+ - Example Expo app.
75
+
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Ethicly
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,314 @@
1
- # Temporary Holding Version
1
+ # @ethicly/react-native
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Fullscreen video ads from Ethicly for React Native and Expo apps. Version 0.2 (see `CHANGELOG.md`).
4
+
5
+ The core is **headless**: it fetches the ad, downloads the video, and does all
6
+ the tracking, while your app keeps its own player and its own house ads. A
7
+ ready-made fullscreen screen is available as a separate, optional entry.
8
+
9
+ It speaks contract v1 of the Ethicly app API (`docs/APP_API_V1.md` in the
10
+ Ethicly repo). It ships no native code of its own.
11
+
12
+ | | |
13
+ |---|---|
14
+ | React Native | 0.72 or later |
15
+ | Expo | SDK 50 or later for the core, the hook and the on-disk cache (either `expo-file-system` API); SDK 52 or later for the ready-made screen (it uses `expo-video`) |
16
+ | iOS / Android | whatever your React Native version supports |
17
+
18
+ ## Integrate in 5 steps
19
+
20
+ 1. **Install** from npm (it ships `lib/` with CommonJS, ES modules and type
21
+ declarations, and no native code):
22
+
23
+ ```
24
+ npm install @ethicly/react-native
25
+ ```
26
+
27
+ Updates are `npm install @ethicly/react-native@latest`; every version is
28
+ listed in `CHANGELOG.md`. A tarball from Ethicly
29
+ (`npm install ./ethicly-react-native-<version>.tgz`) installs the same
30
+ package. For on-disk caching and a persistent config also have
31
+ `@react-native-async-storage/async-storage` and `expo-file-system` (most
32
+ Expo apps already do). Add `expo-video` only if you want the ready-made
33
+ screen. All three are optional peer dependencies, as is
34
+ `react-native-safe-area-context`, which the screen uses when present.
35
+
36
+ 2. **Create one client at app start** and keep it for the life of the process:
37
+
38
+ ```ts
39
+ import { Linking, Platform } from 'react-native';
40
+ import AsyncStorage from '@react-native-async-storage/async-storage';
41
+ import * as FileSystem from 'expo-file-system'; // any Expo SDK 50+ ('expo-file-system/legacy' works too)
42
+ import { createEthicly, createExpoFileCache } from '@ethicly/react-native';
43
+
44
+ export const ethicly = createEthicly({
45
+ apiKey: 'YOUR-PUBLISHER-KEY',
46
+ platform: Platform.OS === 'android' ? 'android' : 'ios',
47
+ appVersion: '4.2.0', // your app's version
48
+ storage: AsyncStorage,
49
+ fileCache: createExpoFileCache(FileSystem),
50
+ openUrl: (url) => Linking.openURL(url),
51
+ testMode: __DEV__, // ignored in a release build
52
+ logger: __DEV__ ? console : undefined,
53
+ });
54
+ ```
55
+
56
+ 3. **Tell it about paid users.** `ethicly.setAdsEnabled(false)` for anyone who
57
+ removed ads. It stops serve requests and downloads. You can also pass
58
+ `adsEnabled: false` to `createEthicly`.
59
+
60
+ 4. **Preload early, load at the break.** Call `ethicly.preload()` some time
61
+ before the ad is needed (for example when a lesson opens). At the break
62
+ ("Mark Complete"):
63
+
64
+ ```ts
65
+ const res = await ethicly.loadInterstitial();
66
+ if (!res.ad) {
67
+ showHouseAd(); // res.reason says why: no fill, capped, disabled...
68
+ } else {
69
+ showMyPlayer(res.ad, res.tracker); // your existing player
70
+ }
71
+ ```
72
+
73
+ `loadInterstitial()` already applies the frequency caps
74
+ (`interstitial.max_per_session`, `interstitial.min_gap_s`) and the one hour
75
+ token lifetime. `ethicly.canShow()` answers the same question without
76
+ loading; it is false for the first moment after `createEthicly`, until the
77
+ stored frequency state has loaded (`await ethicly.ready` if you need it).
78
+
79
+ `max_per_session` counts per session, held in memory: it starts from zero
80
+ on a cold start and when the app comes back after 30 minutes or more in
81
+ the background (`SESSION_TIMEOUT_MS`, from React Native's `AppState`). The
82
+ time of the last ad is stored through `storage`, so `min_gap_s` also holds
83
+ across restarts.
84
+
85
+ 5. **Call the tracker from your player.** Play `ad.media.videoUri` (a local
86
+ file when cached), show `ad.ctaLabel` on the button, allow skipping after
87
+ `ad.skipAfterMs`, play with sound unless `ad.audio` is `none` (always
88
+ muted) or `optional` (start muted), then:
89
+
90
+ | When | Call |
91
+ |---|---|
92
+ | the ad appears on screen | `tracker.shown()` |
93
+ | every player time update (250 ms is fine) | `tracker.progress(positionMs, { visible })`, where `visible` is "on screen, app in the foreground, playing" |
94
+ | the video reaches the end | `tracker.complete()` |
95
+ | the user skips | `tracker.skipped(positionMs)` |
96
+ | playback fails | `tracker.error()` |
97
+ | the user taps the button | `tracker.clicked()` (it opens the link through `openUrl`) |
98
+ | the ad screen goes away | `tracker.closed()` |
99
+
100
+ Every tracker method is safe to call at any time and never throws.
101
+
102
+ ### Or use the ready-made screen
103
+
104
+ ```tsx
105
+ import { useEthiclyInterstitial } from '@ethicly/react-native';
106
+ import { EthiclyInterstitial } from '@ethicly/react-native/interstitial';
107
+
108
+ const interstitial = useEthiclyInterstitial(ethicly);
109
+
110
+ async function onMarkComplete() {
111
+ if (!(await interstitial.show())) showHouseAd();
112
+ }
113
+
114
+ {interstitial.ad && interstitial.tracker && (
115
+ <EthiclyInterstitial
116
+ ad={interstitial.ad}
117
+ tracker={interstitial.tracker}
118
+ onClose={interstitial.dismiss}
119
+ onRemoveAds={() => { interstitial.dismiss(); navigation.navigate('Upgrade'); }}
120
+ />
121
+ )}
122
+ ```
123
+
124
+ The controls stay clear of the notch, status bar and home indicator. Pass
125
+ `insets={useSafeAreaInsets()}` if you like; otherwise the screen reads
126
+ `react-native-safe-area-context` itself when the app has it (it works with or
127
+ without a `SafeAreaProvider`), and without it uses the status bar height on
128
+ Android. The 0.1 positions (56 points from the top, 44 from the bottom) are a
129
+ floor: insets only ever move the controls inward, so a phone without a notch
130
+ looks exactly as before.
131
+
132
+ The screen is a fullscreen modal: the video fills it, a small "Ad" label sits
133
+ top left, a white button shows `ctaLabel` ("Learn more" when the advertiser
134
+ set none), and either `onRemoveAds` (a "Remove ads" link) or
135
+ `renderBelowButton` fills the space under the button, above a small
136
+ "Sponsored by Ethicly.ch" line. Audio follows
137
+ `interstitial.audio`: `on` (the default) starts with sound and offers a mute
138
+ toggle (expo-video plays through the iPhone silent switch and pauses other
139
+ audio while the ad has sound), `optional` starts muted with a sound toggle, `none` is always muted.
140
+
141
+ The skip control is a solid black pill that reads "Skip in N", then
142
+ "Skip Ad" with a skip-to-end icon (restyle it with the `skipStyle` and `skipTextStyle` props). The
143
+ countdown follows playback, with foreground time on screen as a fallback, so a
144
+ stalled video never traps the user. After the user opens the link and comes
145
+ back, Skip is available at once. Android back closes the ad only once Skip is
146
+ available. If the ad expired before it reached the screen, the screen closes
147
+ itself through `onClose` without recording an impression.
148
+
149
+ ### The creative cache
150
+
151
+ `createExpoFileCache(FileSystem)` takes the `expo-file-system` module as your
152
+ app imports it, on any Expo SDK from 50. On SDK 54 and later
153
+ `import * as FileSystem from 'expo-file-system'` is the object API (`File`,
154
+ `Directory`, `Paths`) and the adapter uses it; before SDK 54, or from
155
+ `expo-file-system/legacy`, it uses the legacy functions. You never need to
156
+ tell it which. Given anything else it streams creatives and logs one warning.
157
+
158
+ It keeps creatives in `<cache directory>/ethicly-ads/`
159
+ within `prefetch.max_cache_mb` and `prefetch.max_cached_creatives` (from
160
+ `/config`), least recently used first. Each file's size is checked before it
161
+ is written (a HEAD request for `Content-Length`, and the download is cancelled
162
+ once it passes the remaining budget; with the object API of expo-file-system
163
+ 19 to 54, which has no progress callback, a file that lands over the budget is
164
+ deleted at once), so an oversized video streams instead.
165
+ The cache index is saved before every download starts; on first use the SDK
166
+ deletes any file in its directory that the index does not list. With the
167
+ default in-memory `storage` the index is lost when the app exits, so the
168
+ directory is emptied at the next start: disk use stays bounded either way, but
169
+ pass `AsyncStorage` to keep creatives across launches. A custom
170
+ `FileCacheAdapter` should implement `list()` (and ideally `uriFor()`) for the
171
+ same guarantee.
172
+
173
+ ## Test mode
174
+
175
+ `testMode: true` adds `test=1` to the serve request. You get real ads and run
176
+ every beacon, and the server stores nothing: no impression, no click, no
177
+ earnings. The `/impression` answer is logged as a test impression.
178
+
179
+ **A release build never runs in test mode.** In a React Native release build
180
+ (`__DEV__` false) the SDK ignores `testMode: true`: it serves and bills
181
+ normally and logs an error through `logger` and once through `console.error`,
182
+ so a forgotten flag cannot cost the publisher its earnings. Still tie it to
183
+ `__DEV__`. Where `__DEV__` is not defined at all (a Node script such as
184
+ `npm run test:live`, or tests) the code is not a shipped app, and test mode
185
+ works as asked.
186
+
187
+ ## Reliability
188
+
189
+ - Beacon retries (timeouts, 5xx, 429) wait a random time between 0 and a
190
+ ceiling that doubles from 1 s to 60 s (full jitter), for up to one hour.
191
+ - What a rendered ad still owes the server is kept in `storage` and sent on
192
+ the next start if the app is killed first: `/impression` (same
193
+ `client_impression_id`, so the server answers with the row it already has),
194
+ `/viewable` (billed at most once) and video events (applied monotonically).
195
+ None of them can be counted twice. `/click` is never stored or retried. At
196
+ most 20 ads are kept, each for one hour after it was shown. Pass
197
+ `AsyncStorage` as `storage` for this; the default in-memory storage loses it
198
+ with the process. There is one outbox per storage object, so pass the same
199
+ `AsyncStorage` module to every client.
200
+ - Beacons of an ad that was shown are still sent after `setAdsEnabled(false)`:
201
+ the ad really was on screen. They are held back while a kill switch is on
202
+ (`app_disabled`, `sdk_unsupported`) or the key is refused, and then expire
203
+ one hour after the ad was shown.
204
+ - Storage keys are per API key (`ethicly:v1:<kind>:<key>`). A key you no
205
+ longer use leaves a few small entries behind; they are harmless.
206
+
207
+ ## API
208
+
209
+ ```ts
210
+ createEthicly(options: {
211
+ apiKey: string;
212
+ platform: 'ios' | 'android';
213
+ appVersion: string;
214
+ baseUrl?: string; // default https://ads.ethicly.ch/functions/v1/get-ad-with-geo
215
+ testMode?: boolean; // ignored in a release build
216
+ adsEnabled?: boolean; // default true
217
+ storage?: KeyValueStorage; // AsyncStorage shape; default in memory
218
+ fileCache?: FileCacheAdapter; // download/exists/delete/size/list; default streams
219
+ openUrl?: (url: string) => unknown;
220
+ fetch?: FetchLike; // default global fetch
221
+ now?: () => number;
222
+ logger?: { debug?, info?, warn?, error? };
223
+ appState?: AppStateLike | null; // default React Native's AppState; null: one session per process
224
+ }): Ethicly
225
+
226
+ createExpoFileCache(fs, subdirectory = 'ethicly-ads/', logger?): FileCacheAdapter
227
+
228
+ interface Ethicly {
229
+ ready: Promise<void>;
230
+ preload(): Promise<InterstitialResult>;
231
+ loadInterstitial(): Promise<InterstitialResult>;
232
+ canShow(): boolean; // false until the stored frequency state loaded
233
+ setAdsEnabled(enabled: boolean): void;
234
+ isAdsEnabled(): boolean;
235
+ getConfig(): EthiclyConfig;
236
+ refreshConfig(): Promise<void>;
237
+ lastNoFillReason: NoFillReason | null;
238
+ sdkVersion: string;
239
+ }
240
+
241
+ type InterstitialResult =
242
+ | { ad: EthiclyAd; tracker: Tracker }
243
+ | { ad: null; tracker: null; reason: NoFillReason };
244
+
245
+ interface EthiclyAd {
246
+ id: number; ctaLabel: string; destinationUrl: string; skipAfterMs: number;
247
+ audio: 'none' | 'optional' | 'on'; title: string | null; test: boolean;
248
+ servedAt: number; expiresAt: number;
249
+ media: { kind: 'video' | 'image'; uri: string; videoUri: string | null; posterUri: string | null;
250
+ durationMs: number | null; mime: string | null; width: number; height: number; cached: boolean };
251
+ }
252
+
253
+ interface Tracker {
254
+ shown(size?: { width?: number; height?: number }): Promise<void>;
255
+ progress(positionMs: number, opts: { visible: boolean; durationMs?: number }): void;
256
+ complete(): void;
257
+ skipped(positionMs: number): void;
258
+ error(): void;
259
+ clicked(): Promise<string>; // the URL that was opened
260
+ closed(): Promise<void>;
261
+ isExpired(): boolean;
262
+ }
263
+ ```
264
+
265
+ `NoFillReason` is a server reason (`no_matching_ad`, `no_approved_ads`,
266
+ `app_disabled`, `sdk_unsupported`, `interstitial_disabled`, ...) or one of the
267
+ SDK's own: `ads_disabled`, `frequency_capped`, `unknown_key`, `invalid_key`,
268
+ `rate_limited`, `network_error`, `server_error`, `invalid_response`. Treat
269
+ every one of them as "show the house ad".
270
+
271
+ Also exported: `useEthiclyInterstitial`, `createMemoryStorage`,
272
+ `createMemoryFileCache`, `createExpoFileCache`, `appendClickToken`,
273
+ `compareVersions`, `SDK_VERSION`, `SESSION_TIMEOUT_MS`. The core alone is at
274
+ `@ethicly/react-native/core` (no React import).
275
+
276
+ ## What it sends, and what it never sends
277
+
278
+ The SDK sends the publisher key, `platform`, its own version, your
279
+ `appVersion`, a random UUID per rendered ad (for retry idempotency; it comes
280
+ from `crypto.randomUUID` or `crypto.getRandomValues` and falls back to
281
+ `Math.random` only when the runtime has no `crypto` at all, for example Hermes
282
+ without a polyfill such as `react-native-get-random-values`), the ad
283
+ and impression ids, and the country code the server returned. It sends no
284
+ advertising identifier, no device or vendor id, no user id and no location.
285
+ The server's full inventory is in "Data collected" in `docs/APP_API_V1.md`.
286
+
287
+ ## Development
288
+
289
+ ```
290
+ npm install
291
+ npm run typecheck
292
+ npm test # jest in Node, against recorded fixtures
293
+ npm run test:live # one test-mode run against production (stores nothing)
294
+ npm run build # lib/commonjs, lib/module, lib/typescript (also run by `prepare`)
295
+ npm pack # installable tarball
296
+ ```
297
+
298
+ ### Releasing
299
+
300
+ Bump `version` in `package.json` and `package-lock.json`, add the
301
+ `CHANGELOG.md` section in a normal PR and merge it. Then tag the merge commit:
302
+
303
+ ```
304
+ git tag sdk-v0.2.0 <merge commit on main> && git push origin sdk-v0.2.0
305
+ ```
306
+
307
+ `.github/workflows/sdk-release.yml` re-runs the checks, refuses a tag that
308
+ does not match `package.json` or is not on main, publishes to npm (secret
309
+ `NPM_TOKEN` in the `npm-publish` environment, whose reviewers approve each run) and creates a GitHub release with the tarball and that version's
310
+ changelog. Running the workflow by hand is a dry run.
311
+
312
+ `example/` is a minimal Expo app with both the headless flow and the
313
+ ready-made screen, in test mode. It reads the publisher key from
314
+ `EXPO_PUBLIC_ETHICLY_KEY` (for example `EXPO_PUBLIC_ETHICLY_KEY=... npx expo start`).
@@ -0,0 +1,6 @@
1
+ {
2
+ "main": "../lib/commonjs/core/index.js",
3
+ "module": "../lib/module/core/index.js",
4
+ "types": "../lib/typescript/core/index.d.ts",
5
+ "react-native": "../src/core/index.ts"
6
+ }
@@ -0,0 +1,6 @@
1
+ {
2
+ "main": "../lib/commonjs/interstitial.js",
3
+ "module": "../lib/module/interstitial.js",
4
+ "types": "../lib/typescript/interstitial.d.ts",
5
+ "react-native": "../src/interstitial.ts"
6
+ }