@ethicly/react-native 0.0.0-stage → 0.2.1

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 +133 -0
  2. package/LICENSE +21 -0
  3. package/README.md +428 -2
  4. package/core/package.json +6 -0
  5. package/interstitial/package.json +6 -0
  6. package/lib/commonjs/core/adapters.js +326 -0
  7. package/lib/commonjs/core/beacons.js +70 -0
  8. package/lib/commonjs/core/cache.js +261 -0
  9. package/lib/commonjs/core/click.js +29 -0
  10. package/lib/commonjs/core/client.js +585 -0
  11. package/lib/commonjs/core/config.js +128 -0
  12. package/lib/commonjs/core/http.js +115 -0
  13. package/lib/commonjs/core/index.js +21 -0
  14. package/lib/commonjs/core/outbox.js +192 -0
  15. package/lib/commonjs/core/tracker.js +379 -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 +319 -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 +315 -0
  23. package/lib/module/core/beacons.js +64 -0
  24. package/lib/module/core/cache.js +257 -0
  25. package/lib/module/core/click.js +24 -0
  26. package/lib/module/core/client.js +581 -0
  27. package/lib/module/core/config.js +118 -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 +375 -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 +292 -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 +139 -0
  39. package/lib/typescript/core/beacons.d.ts +32 -0
  40. package/lib/typescript/core/cache.d.ts +71 -0
  41. package/lib/typescript/core/click.d.ts +13 -0
  42. package/lib/typescript/core/client.d.ts +78 -0
  43. package/lib/typescript/core/config.d.ts +33 -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 +175 -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 +51 -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 +365 -0
  56. package/src/core/beacons.ts +81 -0
  57. package/src/core/cache.ts +261 -0
  58. package/src/core/click.ts +26 -0
  59. package/src/core/client.ts +665 -0
  60. package/src/core/config.ts +124 -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 +376 -0
  65. package/src/core/types.ts +185 -0
  66. package/src/index.ts +5 -0
  67. package/src/interstitial.ts +4 -0
  68. package/src/react/EthiclyInterstitial.tsx +432 -0
  69. package/src/react/useEthiclyInterstitial.ts +74 -0
  70. package/src/version.ts +2 -0
package/CHANGELOG.md ADDED
@@ -0,0 +1,133 @@
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.
7
+
8
+ ## [0.2.1] - 2026-11-21
9
+
10
+ ### Fixed
11
+
12
+ - `loadInterstitial()` no longer waits for the whole creative download. When
13
+ no preloaded ad is ready it waits at most `loadTimeoutMs` (default 3000 ms),
14
+ then returns the ad with the remote URL in `media.videoUri` (the player
15
+ streams it) while the download carries on in the background for next time.
16
+ Tapping "Mark Complete" before a preload finished could hang the break for
17
+ tens of seconds.
18
+ - A slow or trickling creative download no longer holds up later downloads:
19
+ each file gets one minute, then it is cancelled (when the file cache can
20
+ cancel) or abandoned, and the creative streams.
21
+ - `setAdsEnabled(false)` now also cancels a creative download in flight and
22
+ drops the ad being downloaded.
23
+ - Still-image ads in `<EthiclyInterstitial />` count toward viewability only
24
+ after the image has loaded. An image that fails to load reports
25
+ `tracker.error()`, counts nothing, and can be closed at once.
26
+ - Only `http:` and `https:` destinations are accepted. An ad with any other
27
+ scheme (`tel:`, `intent:`, `javascript:`, an app scheme) is refused as
28
+ `invalid_response`, logged once, and the tracker never opens such a URL.
29
+ - `createExpoFileCache` no longer warns to the console in a release build
30
+ unless a logger is passed.
31
+
32
+ ### Added
33
+
34
+ - `audio` option on `createEthicly` (`'on' | 'optional' | 'none'`): the app
35
+ chooses the sound for every ad, over the server's `interstitial.audio`.
36
+ `ad.audio` is the effective value. Default unchanged: sound on.
37
+ - `audio` prop on `<EthiclyInterstitial />`, over `ad.audio` for one screen.
38
+ - `loadTimeoutMs` option on `createEthicly`, and `DEFAULT_LOAD_TIMEOUT_MS`.
39
+ - Optional `cancel()` on `FileCacheAdapter`; both `createExpoFileCache`
40
+ variants implement it.
41
+ - `<EthiclyInterstitial />` shows a small "Test ad" label on a test-mode ad.
42
+ - README: "Sound" (with what `'on'` does on an iPhone) and "App Store and
43
+ Google Play disclosures".
44
+
45
+ ### Changed
46
+
47
+ - The build runs on `prepack` instead of `prepare`, so installing the SDK
48
+ from a local folder (the example app) no longer needs TypeScript in the SDK
49
+ folder. Published tarballs are unchanged.
50
+ - The skip delay is kept within 8 to 15 seconds, for both `/config`'s
51
+ `interstitial.skip_after_ms` and the ad's `skip_after_ms` (default still
52
+ 8 s). Skip still unlocks when the video ends, after the call to action, and
53
+ after the skip delay in foreground time if playback stalls.
54
+ - `<EthiclyInterstitial />` no longer passes the deprecated
55
+ `allowsFullscreen` to `VideoView` (native controls are off, so there is no
56
+ fullscreen button either way).
57
+ - Docs: apps with a paid tier create the client with `adsEnabled: false` and
58
+ call `setAdsEnabled(true)` for free users; show nothing for `ads_disabled`
59
+ (a paid user), the house ad for every other no-fill reason;
60
+ `useEthiclyInterstitial` comes from `@ethicly/react-native` (only
61
+ `EthiclyInterstitial` is in `/interstitial`); `appVersion` from
62
+ `expo-application`; `npx expo install expo-video` adds a config plugin, so
63
+ development builds need a new native build. Release notes moved out of the
64
+ package README.
65
+
66
+ ## [0.2.0] - 2026-11-15
67
+
68
+ ### Added
69
+
70
+ - Unsent beacons survive the app being killed. What a rendered ad still owes
71
+ the server (`/impression` with its `client_impression_id`, `/viewable`,
72
+ video events) is kept in `storage` and sent on the next start. Only
73
+ idempotent beacons are kept, so a replay never counts anything twice;
74
+ `/click` is never kept or retried. At most 20 ads, each dropped one hour
75
+ after it was shown. Held back while a kill switch (`app_disabled`,
76
+ `sdk_unsupported`) is on or the key is refused.
77
+ - Sessions: coming back after 30 minutes or more in the background
78
+ (`SESSION_TIMEOUT_MS`) starts a new session, so `interstitial.max_per_session`
79
+ counts from zero again. Uses React Native's `AppState`; the new
80
+ `appState` option replaces it, and `appState: null` turns sessions off.
81
+ - `min_gap_s` survives restarts: the last shown time is stored through
82
+ `storage`. A stored time in the future is ignored.
83
+ - `<EthiclyInterstitial />` is safe-area aware: a new `insets` prop, else
84
+ `react-native-safe-area-context` when the app has it (read without
85
+ requiring its provider), else the status bar height on Android. The 0.1
86
+ positions (56 from the top, 44 from the bottom) are a floor, so insets only
87
+ move the controls inward and phones without a notch look as before.
88
+ - `createExpoFileCache` takes `import * as FileSystem from 'expo-file-system'`
89
+ on any Expo SDK from 50: the object API of SDK 54+ (`File`, `Directory`,
90
+ `Paths`) or the legacy functions (also from `expo-file-system/legacy`).
91
+ Anything else streams, with one warning.
92
+ - Optional peer dependencies: `expo-file-system`,
93
+ `@react-native-async-storage/async-storage`, `react-native-safe-area-context`.
94
+
95
+ ### Changed
96
+
97
+ - `testMode` is ignored in a React Native release build (`__DEV__` false):
98
+ ads are served and billed normally, and the SDK logs an error through the
99
+ logger and once through `console.error`. Where `__DEV__` is not defined
100
+ (Node scripts, tests) test mode still works.
101
+ - Beacon retries wait a random time between 0 and the backoff ceiling (full
102
+ jitter), so installs that failed together do not retry together. The ceiling
103
+ is unchanged: 1 s doubling, capped at 60 s, for up to one hour.
104
+ - `canShow()` answers false until the stored frequency state has loaded, a
105
+ moment after `createEthicly`; `ready`, `preload()` and `loadInterstitial()`
106
+ wait for it.
107
+
108
+ ## [0.1.0] - 2026-11-14
109
+
110
+ First version.
111
+
112
+ ### Added
113
+
114
+ - Headless core: `/config` with caching and last-known fallback, kill switch,
115
+ `min_sdk`, interstitial serve, video and poster prefetch with an LRU cache,
116
+ frequency caps, `setAdsEnabled`, test mode.
117
+ - Tracker: immediate `/impression` with an idempotent `client_impression_id`,
118
+ `/viewable` after continuous visible playback, quartile video events,
119
+ `/click` with the `ethicly_click` token, one hour expiry, retry rules.
120
+ - `useEthiclyInterstitial` hook.
121
+ - Creative cache bounded on disk: size checked before writing, index saved
122
+ before each download, unindexed files swept on load.
123
+ - Optional `<EthiclyInterstitial />` screen (`@ethicly/react-native/interstitial`,
124
+ needs `expo-video`): StrictMode safe, skip countdown with a wall-clock
125
+ fallback, Android back once Skip is allowed, `skipStyle` and `skipTextStyle`.
126
+ - The skip control is a solid black pill reading "Skip in N", then "Skip Ad"
127
+ with a skip-to-end icon.
128
+ - A small "Sponsored by Ethicly.ch" line under the call-to-action button.
129
+ - Video starts with sound by default (`interstitial.audio` `on`); `optional`
130
+ starts muted, `none` is always muted.
131
+ - `prepare` builds `lib/`, so `npm pack` gives an installable tarball.
132
+ - Example Expo app.
133
+
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,429 @@
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.1 (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. It ships no native code of its own.
10
+
11
+ | | |
12
+ |---|---|
13
+ | React Native | 0.72 or later |
14
+ | 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`) |
15
+ | iOS / Android | whatever your React Native version supports |
16
+
17
+ ## Integrate in 5 steps
18
+
19
+ 1. **Install** from npm (it ships `lib/` with CommonJS, ES modules and type
20
+ declarations, and no native code):
21
+
22
+ ```
23
+ npm install @ethicly/react-native
24
+ ```
25
+
26
+ Updates are `npm install @ethicly/react-native@latest`; every version is
27
+ listed in `CHANGELOG.md`. A tarball from Ethicly
28
+ (`npm install ./ethicly-react-native-<version>.tgz`) installs the same
29
+ package. For on-disk caching and a persistent config also have
30
+ `@react-native-async-storage/async-storage` and `expo-file-system` (most
31
+ Expo apps already do). Add `expo-video` only if you want the ready-made
32
+ screen. All three are optional peer dependencies, as is
33
+ `react-native-safe-area-context`, which the screen uses when present
34
+ (optional: without it the screen falls back to the status bar height).
35
+
36
+ Install Expo modules with `npx expo install` so the versions match your
37
+ Expo SDK. `npx expo install expo-video` also adds the `expo-video` config
38
+ plugin to your app config: an app that uses a development build or
39
+ `npx expo prebuild` needs a new native build after it (Expo Go already
40
+ includes expo-video).
41
+
42
+ 2. **Create one client at app start** and keep it for the life of the process:
43
+
44
+ ```ts
45
+ import { Linking, Platform } from 'react-native';
46
+ import AsyncStorage from '@react-native-async-storage/async-storage';
47
+ import * as FileSystem from 'expo-file-system'; // any Expo SDK 50+ ('expo-file-system/legacy' works too)
48
+ import * as Application from 'expo-application'; // npx expo install expo-application
49
+ import { createEthicly, createExpoFileCache } from '@ethicly/react-native';
50
+
51
+ export const ethicly = createEthicly({
52
+ apiKey: 'YOUR-PUBLISHER-KEY',
53
+ platform: Platform.OS === 'android' ? 'android' : 'ios',
54
+ appVersion: Application.nativeApplicationVersion ?? '0.0.0', // your app's version
55
+ adsEnabled: false, // apps with a paid tier: see step 3
56
+ storage: AsyncStorage,
57
+ fileCache: createExpoFileCache(FileSystem),
58
+ openUrl: (url) => Linking.openURL(url),
59
+ testMode: __DEV__, // ignored in a release build
60
+ logger: __DEV__ ? console : undefined,
61
+ });
62
+ ```
63
+
64
+ `appVersion` is your app's version string. `expo-application`'s
65
+ `Application.nativeApplicationVersion` reads it from the installed app;
66
+ `Constants.expoConfig?.version` from `expo-constants` is an alternative.
67
+ Two more options: `audio` sets the sound for every ad (see "Sound" below)
68
+ and `loadTimeoutMs` (default 3000) bounds how long `loadInterstitial()`
69
+ waits for a download (see step 4).
70
+
71
+ 3. **Tell it about paid users.** `adsEnabled` defaults to true and is not
72
+ stored: if your app has a paid, ad-free tier, create the client with
73
+ `adsEnabled: false`, check the user's entitlement as you do today, and call
74
+ `ethicly.setAdsEnabled(true)` only for free users (and
75
+ `setAdsEnabled(false)` again if they subscribe). Otherwise a subscriber's
76
+ app serves and downloads an ad on every cold start before your entitlement
77
+ check finishes. `setAdsEnabled(false)` stops serve requests, drops the
78
+ preloaded ad and cancels a creative download in flight. An app without a
79
+ paid tier can leave `adsEnabled` out.
80
+
81
+ 4. **Preload early, load at the break.** Call `ethicly.preload()` some time
82
+ before the ad is needed (for example when a lesson opens). At the break
83
+ ("Mark Complete"):
84
+
85
+ ```ts
86
+ const res = await ethicly.loadInterstitial();
87
+ if (res.ad) {
88
+ showMyPlayer(res.ad, res.tracker); // your existing player
89
+ } else if (res.reason !== 'ads_disabled') {
90
+ showHouseAd(); // no fill, capped...: your own house ad
91
+ } // ads_disabled: a paid user, show nothing
92
+ ```
93
+
94
+ `loadInterstitial()` returns within about `loadTimeoutMs` (default 3 s)
95
+ plus the serve request. When `preload()` already downloaded the ad it plays
96
+ from disk at once. When the download is not finished by then, the ad comes
97
+ back with the remote URL in `ad.media.videoUri` (the player streams it,
98
+ `ad.media.cached` is false) and the download carries on in the background
99
+ for next time. A download that takes longer than a minute is cancelled.
100
+
101
+ `loadInterstitial()` already applies the frequency caps
102
+ (`interstitial.max_per_session`, `interstitial.min_gap_s`) and the one hour
103
+ token lifetime. `ethicly.canShow()` answers the same question without
104
+ loading; it is false for the first moment after `createEthicly`, until the
105
+ stored frequency state has loaded (`await ethicly.ready` if you need it).
106
+
107
+ `max_per_session` counts per session, held in memory: it starts from zero
108
+ on a cold start and when the app comes back after 30 minutes or more in
109
+ the background (`SESSION_TIMEOUT_MS`, from React Native's `AppState`). The
110
+ time of the last ad is stored through `storage`, so `min_gap_s` also holds
111
+ across restarts.
112
+
113
+ 5. **Call the tracker from your player.** Play `ad.media.videoUri` (a local
114
+ file when cached, else the remote URL), show `ad.ctaLabel` on the button,
115
+ allow skipping after `ad.skipAfterMs` (always 8 to 15 seconds: the SDK
116
+ clamps the server's value), play with sound unless `ad.audio` is `none`
117
+ (always muted) or `optional` (start muted), then:
118
+
119
+ | When | Call |
120
+ |---|---|
121
+ | the ad appears on screen | `tracker.shown()` |
122
+ | every player time update (250 ms is fine) | `tracker.progress(positionMs, { visible })`, where `visible` is "on screen, app in the foreground, playing" |
123
+ | the video reaches the end | `tracker.complete()` |
124
+ | the user skips | `tracker.skipped(positionMs)` |
125
+ | playback fails | `tracker.error()` |
126
+ | the user taps the button | `tracker.clicked()` (it opens the link through `openUrl`) |
127
+ | the ad screen goes away | `tracker.closed()` |
128
+
129
+ Every tracker method is safe to call at any time and never throws. For a
130
+ still image (`ad.media.kind === 'image'`), call `progress()` only once the
131
+ image has loaded, and `tracker.error()` if it fails to load.
132
+
133
+ ### Or use the ready-made screen
134
+
135
+ ```tsx
136
+ import { useEthiclyInterstitial } from '@ethicly/react-native';
137
+ import { EthiclyInterstitial } from '@ethicly/react-native/interstitial';
138
+
139
+ const interstitial = useEthiclyInterstitial(ethicly);
140
+
141
+ async function onMarkComplete() {
142
+ if (await interstitial.show()) return; // the screen below shows the ad
143
+ if (ethicly.lastNoFillReason !== 'ads_disabled') showHouseAd(); // nothing for paid users
144
+ }
145
+
146
+ {interstitial.ad && interstitial.tracker && (
147
+ <EthiclyInterstitial
148
+ ad={interstitial.ad}
149
+ tracker={interstitial.tracker}
150
+ onClose={interstitial.dismiss}
151
+ onRemoveAds={() => { interstitial.dismiss(); navigation.navigate('Upgrade'); }}
152
+ audio="optional" // optional: overrides ad.audio for this screen
153
+ />
154
+ )}
155
+ ```
156
+
157
+ The controls stay clear of the notch, status bar and home indicator. Pass
158
+ `insets={useSafeAreaInsets()}` if you like; otherwise the screen reads
159
+ `react-native-safe-area-context` itself when the app has it (it works with or
160
+ without a `SafeAreaProvider`), and without it uses the status bar height on
161
+ Android. The 0.1 positions (56 points from the top, 44 from the bottom) are a
162
+ floor: insets only ever move the controls inward, so a phone without a notch
163
+ looks exactly as before.
164
+
165
+ The screen is a fullscreen modal: the video fills it, a small "Ad" label sits
166
+ top left, a white button shows `ctaLabel` ("Learn more" when the advertiser
167
+ set none), and either `onRemoveAds` (a "Remove ads" link) or
168
+ `renderBelowButton` fills the space under the button, above a small
169
+ "Sponsored by Ethicly.ch" line. A test-mode ad (`ad.test`) also shows a small
170
+ "Test ad" label. Sound follows `ad.audio`, or the screen's `audio` prop when
171
+ you pass one (see "Sound" below).
172
+
173
+ A still-image ad counts toward viewability only once the image has loaded. If
174
+ it fails to load the screen reports `tracker.error()`, counts nothing, and
175
+ lets the user close it at once.
176
+
177
+ The skip control is a solid black pill that reads "Skip in N", then
178
+ "Skip Ad" with a skip-to-end icon (restyle it with the `skipStyle` and `skipTextStyle` props).
179
+ Skip appears after `ad.skipAfterMs`: at least 8 seconds, at most 15. The
180
+ countdown follows playback, with foreground time on screen as a fallback, so a
181
+ stalled video never traps the user. A video shorter than that can be closed
182
+ when it ends. After the user opens the link and comes
183
+ back, Skip is available at once. Android back closes the ad only once Skip is
184
+ available. If the ad expired before it reached the screen, the screen closes
185
+ itself through `onClose` without recording an impression.
186
+
187
+ ### Sound
188
+
189
+ Ads play with sound by default. You choose, in code:
190
+
191
+ - `createEthicly({ ..., audio })` sets it for every ad, over the publisher
192
+ setting from the server. `ad.audio` is the effective value.
193
+ - `<EthiclyInterstitial audio="optional" ... />` sets it for one screen, over
194
+ `ad.audio`.
195
+
196
+ Precedence: the screen's `audio` prop, then the client's `audio` option, then
197
+ the server's `interstitial.audio`, then `'on'`.
198
+
199
+ | Value | Behaviour |
200
+ |---|---|
201
+ | `'on'` (default) | starts with sound, with a mute toggle |
202
+ | `'optional'` | starts muted, with a "Sound on" toggle |
203
+ | `'none'` | always muted, no toggle |
204
+
205
+ Know what `'on'` does on an iPhone: expo-video plays the ad's sound even when
206
+ the silent switch is on, and it pauses the user's own audio (music, a
207
+ podcast) while the ad plays. If your users often listen to something while
208
+ using the app, `'optional'` is the gentler choice.
209
+
210
+ ### The creative cache
211
+
212
+ `createExpoFileCache(FileSystem)` takes the `expo-file-system` module as your
213
+ app imports it, on any Expo SDK from 50. On SDK 54 and later
214
+ `import * as FileSystem from 'expo-file-system'` is the object API (`File`,
215
+ `Directory`, `Paths`) and the adapter uses it; before SDK 54, or from
216
+ `expo-file-system/legacy`, it uses the legacy functions. You never need to
217
+ tell it which. Given anything else it streams creatives and logs one warning
218
+ (through the `logger` argument; to the console only in development).
219
+
220
+ It keeps creatives in `<cache directory>/ethicly-ads/`
221
+ within `prefetch.max_cache_mb` and `prefetch.max_cached_creatives` (from
222
+ `/config`), least recently used first. Each file's size is checked before it
223
+ is written (a HEAD request for `Content-Length`, and the download is cancelled
224
+ once it passes the remaining budget; with the object API of expo-file-system
225
+ 19 to 54, which has no progress callback, a file that lands over the budget is
226
+ deleted at once), so an oversized video streams instead.
227
+ The cache index is saved before every download starts; on first use the SDK
228
+ deletes any file in its directory that the index does not list. With the
229
+ default in-memory `storage` the index is lost when the app exits, so the
230
+ directory is emptied at the next start: disk use stays bounded either way, but
231
+ pass `AsyncStorage` to keep creatives across launches. A custom
232
+ `FileCacheAdapter` should implement `list()` (and ideally `uriFor()`) for the
233
+ same guarantee, and `cancel()` so `setAdsEnabled(false)` and the one-minute
234
+ limit can stop a download in flight.
235
+
236
+ ## Test mode
237
+
238
+ `testMode: true` adds `test=1` to the serve request. You get real ads and run
239
+ every beacon, and the server stores nothing: no impression, no click, no
240
+ earnings. The `/impression` answer is logged as a test impression.
241
+
242
+ **A release build never runs in test mode.** In a React Native release build
243
+ (`__DEV__` false) the SDK ignores `testMode: true`: it serves and bills
244
+ normally and logs an error through `logger` and once through `console.error`,
245
+ so a forgotten flag cannot cost the publisher its earnings. Still tie it to
246
+ `__DEV__`. Where `__DEV__` is not defined at all (a Node script, or tests)
247
+ the code is not a shipped app, and test mode works as asked.
248
+
249
+ ## Reliability
250
+
251
+ - Beacon retries (timeouts, 5xx, 429) wait a random time between 0 and a
252
+ ceiling that doubles from 1 s to 60 s (full jitter), for up to one hour.
253
+ - What a rendered ad still owes the server is kept in `storage` and sent on
254
+ the next start if the app is killed first: `/impression` (same
255
+ `client_impression_id`, so the server answers with the row it already has),
256
+ `/viewable` (billed at most once) and video events (applied monotonically).
257
+ None of them can be counted twice. `/click` is never stored or retried. At
258
+ most 20 ads are kept, each for one hour after it was shown. Pass
259
+ `AsyncStorage` as `storage` for this; the default in-memory storage loses it
260
+ with the process. There is one outbox per storage object, so pass the same
261
+ `AsyncStorage` module to every client.
262
+ - Beacons of an ad that was shown are still sent after `setAdsEnabled(false)`:
263
+ the ad really was on screen. They are held back while a kill switch is on
264
+ (`app_disabled`, `sdk_unsupported`) or the key is refused, and then expire
265
+ one hour after the ad was shown.
266
+ - Storage keys are per API key (`ethicly:v1:<kind>:<key>`). A key you no
267
+ longer use leaves a few small entries behind; they are harmless.
268
+
269
+ ## API
270
+
271
+ ```ts
272
+ createEthicly(options: {
273
+ apiKey: string;
274
+ platform: 'ios' | 'android';
275
+ appVersion: string;
276
+ baseUrl?: string; // default https://ads.ethicly.ch/functions/v1/get-ad-with-geo
277
+ testMode?: boolean; // ignored in a release build
278
+ adsEnabled?: boolean; // default true; pass false until entitlement is known (paid tier)
279
+ audio?: 'on' | 'optional' | 'none'; // overrides the server's interstitial.audio for every ad
280
+ loadTimeoutMs?: number; // default 3000: longest loadInterstitial() waits for a download
281
+ storage?: KeyValueStorage; // AsyncStorage shape; default in memory
282
+ fileCache?: FileCacheAdapter; // download/exists/delete/size/list/cancel; default streams
283
+ openUrl?: (url: string) => unknown;
284
+ fetch?: FetchLike; // default global fetch
285
+ now?: () => number;
286
+ logger?: { debug?, info?, warn?, error? };
287
+ appState?: AppStateLike | null; // default React Native's AppState; null: one session per process
288
+ }): Ethicly
289
+
290
+ createExpoFileCache(fs, subdirectory = 'ethicly-ads/', logger?): FileCacheAdapter
291
+
292
+ interface Ethicly {
293
+ ready: Promise<void>;
294
+ preload(): Promise<InterstitialResult>;
295
+ loadInterstitial(): Promise<InterstitialResult>;
296
+ canShow(): boolean; // false until the stored frequency state loaded
297
+ setAdsEnabled(enabled: boolean): void;
298
+ isAdsEnabled(): boolean;
299
+ getConfig(): EthiclyConfig;
300
+ refreshConfig(): Promise<void>;
301
+ lastNoFillReason: NoFillReason | null;
302
+ sdkVersion: string;
303
+ }
304
+
305
+ type InterstitialResult =
306
+ | { ad: EthiclyAd; tracker: Tracker }
307
+ | { ad: null; tracker: null; reason: NoFillReason };
308
+
309
+ interface EthiclyAd {
310
+ id: number; ctaLabel: string; destinationUrl: string; skipAfterMs: number;
311
+ audio: 'none' | 'optional' | 'on'; title: string | null; test: boolean;
312
+ servedAt: number; expiresAt: number;
313
+ media: { kind: 'video' | 'image'; uri: string; videoUri: string | null; posterUri: string | null;
314
+ durationMs: number | null; mime: string | null; width: number; height: number; cached: boolean };
315
+ }
316
+
317
+ interface Tracker {
318
+ shown(size?: { width?: number; height?: number }): Promise<void>;
319
+ progress(positionMs: number, opts: { visible: boolean; durationMs?: number }): void;
320
+ complete(): void;
321
+ skipped(positionMs: number): void;
322
+ error(): void;
323
+ clicked(): Promise<string>; // the URL that was opened
324
+ closed(): Promise<void>;
325
+ isExpired(): boolean;
326
+ }
327
+ ```
328
+
329
+ `NoFillReason` is a server reason (`no_matching_ad`, `no_approved_ads`,
330
+ `app_disabled`, `sdk_unsupported`, `interstitial_disabled`, ...) or one of the
331
+ SDK's own: `ads_disabled`, `frequency_capped`, `unknown_key`, `invalid_key`,
332
+ `rate_limited`, `network_error`, `server_error`, `invalid_response`. Show
333
+ your house ad for every reason except `ads_disabled`: that one means a paid
334
+ user (you called `setAdsEnabled(false)`), so show nothing.
335
+
336
+ An ad whose destination is not an `http:` or `https:` URL (for example
337
+ `tel:`, `intent:`, `javascript:` or an app scheme) is refused as
338
+ `invalid_response`, and the tracker never opens such a URL.
339
+
340
+ Also exported: `useEthiclyInterstitial`, `createMemoryStorage`,
341
+ `createMemoryFileCache`, `createExpoFileCache`, `appendClickToken`,
342
+ `compareVersions`, `SDK_VERSION`, `SESSION_TIMEOUT_MS`, `DEFAULT_LOAD_TIMEOUT_MS`. The core alone is at
343
+ `@ethicly/react-native/core` (no React import).
344
+
345
+ ## What it sends, and what it never sends
346
+
347
+ The SDK sends the publisher key, `platform`, its own version, your
348
+ `appVersion`, a random UUID per rendered ad (for retry idempotency; it comes
349
+ from `crypto.randomUUID` or `crypto.getRandomValues` and falls back to
350
+ `Math.random` only when the runtime has no `crypto` at all, for example Hermes
351
+ without a polyfill such as `react-native-get-random-values`), the ad
352
+ and impression ids, and the country code the server returned. It sends no
353
+ advertising identifier, no device or vendor id, no user id and no location.
354
+ With each impression it also sends the rendered ad size, how long the ad was
355
+ visible, video progress (quartiles, complete, skip and its position, playback
356
+ error) and whether the button was tapped.
357
+
358
+ ## App Store and Google Play disclosures
359
+
360
+ This is a factual list of what the SDK and Ethicly's server handle, so you can
361
+ fill in Apple's App Privacy answers and Google Play's Data safety form. It is
362
+ not legal advice; you are responsible for your app's declarations.
363
+
364
+ **What Ethicly's server stores**, per ad shown:
365
+
366
+ - the ad id and your publisher site id, `platform`, the SDK version and your
367
+ `appVersion`;
368
+ - a random id the SDK generates for that one rendered ad (not tied to the
369
+ user or the device; a new one for every ad);
370
+ - the rendered size of the ad, whether and how long it was visible, video
371
+ progress (highest quartile, completed, skipped and the skip position,
372
+ playback error);
373
+ - whether the ad was clicked, with a random click token for conversion
374
+ reporting;
375
+ - a two-letter country code. The server derives it from the device's IP
376
+ address with its own database (no third party). The IP address itself is
377
+ used in transit (country lookup, rate limiting) and is not written to
378
+ Ethicly's database or to the ad server's own logs, except as a salted hash
379
+ combined with the ad id, used to cap clicks per IP and deleted after two
380
+ days. Request logs kept by Ethicly's hosting platform are outside this
381
+ list.
382
+
383
+ Serve and `/config` requests store nothing per request. The User-Agent header
384
+ is read in transit and not stored.
385
+
386
+ **Never collected:** no advertising identifier (IDFA or GAID), no vendor or
387
+ device identifier, no install or user id, no precise location, no contacts,
388
+ no cookies. Nothing links the data to a user or to data from other apps.
389
+
390
+ **The creative host.** The SDK downloads the ad's video, image and poster
391
+ from the URLs in the ad. Like any download, that host sees the device's IP
392
+ address and User-Agent.
393
+
394
+ **Apple (App Privacy, App Store Connect):**
395
+
396
+ - Usage Data, Product Interaction (ad views, taps, video progress), and
397
+ Usage Data, Advertising Data (which ads were shown): collected, used for
398
+ Third-Party Advertising (and Analytics, for the publisher's reports), **not
399
+ linked to the user**, **not used for tracking**.
400
+ - Country derived from the IP address: if you treat it as location, declare
401
+ Location, Coarse Location: not linked to the user, not used for tracking.
402
+ - No App Tracking Transparency prompt is needed for Ethicly: the SDK does not
403
+ read the IDFA and does not track users across apps or websites.
404
+
405
+ **Google Play (Data safety):**
406
+
407
+ - Location, Approximate location: derived from the IP address on Ethicly's
408
+ server (country only). Collected, for Advertising or marketing and
409
+ Analytics.
410
+ - App activity, App interactions (ad views, clicks, video progress):
411
+ collected, for Advertising or marketing and Analytics.
412
+ - Not used for tracking: no advertising or device identifier is read, and
413
+ the data is not linked to a user. Answer the sharing, encryption and
414
+ deletion questions for your app as a whole; ask Ethicly if you need a
415
+ statement for them.
416
+
417
+ **Children.** Ethicly is not a Google Play Families self-certified ads SDK.
418
+ Do not use it in apps primarily directed at children, or in the parts of an
419
+ app aimed at children.
420
+
421
+ ## Development
422
+
423
+ ```
424
+ npm install
425
+ npm run typecheck
426
+ npm test # jest in Node, against recorded fixtures
427
+ npm run build # lib/commonjs, lib/module, lib/typescript (also run by `prepare`)
428
+ npm pack # installable tarball
429
+ ```
@@ -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
+ }