@ethicly/react-native 0.2.0 → 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 (42) hide show
  1. package/CHANGELOG.md +59 -1
  2. package/README.md +168 -53
  3. package/lib/commonjs/core/adapters.js +44 -5
  4. package/lib/commonjs/core/cache.js +60 -5
  5. package/lib/commonjs/core/click.js +10 -0
  6. package/lib/commonjs/core/client.js +160 -64
  7. package/lib/commonjs/core/config.js +17 -2
  8. package/lib/commonjs/core/index.js +2 -1
  9. package/lib/commonjs/core/tracker.js +5 -0
  10. package/lib/commonjs/react/EthiclyInterstitial.js +46 -13
  11. package/lib/commonjs/version.js +1 -1
  12. package/lib/module/core/adapters.js +44 -5
  13. package/lib/module/core/cache.js +59 -4
  14. package/lib/module/core/click.js +9 -0
  15. package/lib/module/core/client.js +160 -64
  16. package/lib/module/core/config.js +15 -1
  17. package/lib/module/core/index.js +1 -1
  18. package/lib/module/core/tracker.js +6 -1
  19. package/lib/module/react/EthiclyInterstitial.js +45 -13
  20. package/lib/module/version.js +1 -1
  21. package/lib/typescript/core/adapters.d.ts +2 -1
  22. package/lib/typescript/core/cache.d.ts +20 -2
  23. package/lib/typescript/core/click.d.ts +5 -0
  24. package/lib/typescript/core/client.d.ts +23 -3
  25. package/lib/typescript/core/config.d.ts +9 -0
  26. package/lib/typescript/core/index.d.ts +1 -1
  27. package/lib/typescript/core/types.d.ts +5 -0
  28. package/lib/typescript/react/EthiclyInterstitial.d.ts +13 -1
  29. package/lib/typescript/react/useEthiclyInterstitial.d.ts +1 -1
  30. package/lib/typescript/version.d.ts +1 -1
  31. package/package.json +2 -2
  32. package/src/core/adapters.ts +33 -5
  33. package/src/core/cache.ts +48 -3
  34. package/src/core/click.ts +10 -0
  35. package/src/core/client.ts +186 -68
  36. package/src/core/config.ts +14 -1
  37. package/src/core/index.ts +1 -1
  38. package/src/core/tracker.ts +6 -1
  39. package/src/core/types.ts +5 -0
  40. package/src/react/EthiclyInterstitial.tsx +62 -16
  41. package/src/react/useEthiclyInterstitial.ts +1 -1
  42. package/src/version.ts +1 -1
package/CHANGELOG.md CHANGED
@@ -3,7 +3,65 @@
3
3
  All notable changes to `@ethicly/react-native` are recorded here. The format
4
4
  follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the
5
5
  package uses [Semantic Versioning](https://semver.org/). Every version speaks
6
- contract v1 of the Ethicly app API (`docs/APP_API_V1.md`).
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.
7
65
 
8
66
  ## [0.2.0] - 2026-11-15
9
67
 
package/README.md CHANGED
@@ -1,13 +1,12 @@
1
1
  # @ethicly/react-native
2
2
 
3
- Fullscreen video ads from Ethicly for React Native and Expo apps. Version 0.2 (see `CHANGELOG.md`).
3
+ Fullscreen video ads from Ethicly for React Native and Expo apps. Version 0.2.1 (see `CHANGELOG.md`).
4
4
 
5
5
  The core is **headless**: it fetches the ad, downloads the video, and does all
6
6
  the tracking, while your app keeps its own player and its own house ads. A
7
7
  ready-made fullscreen screen is available as a separate, optional entry.
8
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.
9
+ It speaks contract v1 of the Ethicly app API. It ships no native code of its own.
11
10
 
12
11
  | | |
13
12
  |---|---|
@@ -31,7 +30,14 @@ Ethicly repo). It ships no native code of its own.
31
30
  `@react-native-async-storage/async-storage` and `expo-file-system` (most
32
31
  Expo apps already do). Add `expo-video` only if you want the ready-made
33
32
  screen. All three are optional peer dependencies, as is
34
- `react-native-safe-area-context`, which the screen uses when present.
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).
35
41
 
36
42
  2. **Create one client at app start** and keep it for the life of the process:
37
43
 
@@ -39,12 +45,14 @@ Ethicly repo). It ships no native code of its own.
39
45
  import { Linking, Platform } from 'react-native';
40
46
  import AsyncStorage from '@react-native-async-storage/async-storage';
41
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
42
49
  import { createEthicly, createExpoFileCache } from '@ethicly/react-native';
43
50
 
44
51
  export const ethicly = createEthicly({
45
52
  apiKey: 'YOUR-PUBLISHER-KEY',
46
53
  platform: Platform.OS === 'android' ? 'android' : 'ios',
47
- appVersion: '4.2.0', // your app's version
54
+ appVersion: Application.nativeApplicationVersion ?? '0.0.0', // your app's version
55
+ adsEnabled: false, // apps with a paid tier: see step 3
48
56
  storage: AsyncStorage,
49
57
  fileCache: createExpoFileCache(FileSystem),
50
58
  openUrl: (url) => Linking.openURL(url),
@@ -53,9 +61,22 @@ Ethicly repo). It ships no native code of its own.
53
61
  });
54
62
  ```
55
63
 
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`.
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.
59
80
 
60
81
  4. **Preload early, load at the break.** Call `ethicly.preload()` some time
61
82
  before the ad is needed (for example when a lesson opens). At the break
@@ -63,13 +84,20 @@ Ethicly repo). It ships no native code of its own.
63
84
 
64
85
  ```ts
65
86
  const res = await ethicly.loadInterstitial();
66
- if (!res.ad) {
67
- showHouseAd(); // res.reason says why: no fill, capped, disabled...
68
- } else {
87
+ if (res.ad) {
69
88
  showMyPlayer(res.ad, res.tracker); // your existing player
70
- }
89
+ } else if (res.reason !== 'ads_disabled') {
90
+ showHouseAd(); // no fill, capped...: your own house ad
91
+ } // ads_disabled: a paid user, show nothing
71
92
  ```
72
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
+
73
101
  `loadInterstitial()` already applies the frequency caps
74
102
  (`interstitial.max_per_session`, `interstitial.min_gap_s`) and the one hour
75
103
  token lifetime. `ethicly.canShow()` answers the same question without
@@ -83,9 +111,10 @@ Ethicly repo). It ships no native code of its own.
83
111
  across restarts.
84
112
 
85
113
  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:
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:
89
118
 
90
119
  | When | Call |
91
120
  |---|---|
@@ -97,7 +126,9 @@ Ethicly repo). It ships no native code of its own.
97
126
  | the user taps the button | `tracker.clicked()` (it opens the link through `openUrl`) |
98
127
  | the ad screen goes away | `tracker.closed()` |
99
128
 
100
- Every tracker method is safe to call at any time and never throws.
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.
101
132
 
102
133
  ### Or use the ready-made screen
103
134
 
@@ -108,7 +139,8 @@ import { EthiclyInterstitial } from '@ethicly/react-native/interstitial';
108
139
  const interstitial = useEthiclyInterstitial(ethicly);
109
140
 
110
141
  async function onMarkComplete() {
111
- if (!(await interstitial.show())) showHouseAd();
142
+ if (await interstitial.show()) return; // the screen below shows the ad
143
+ if (ethicly.lastNoFillReason !== 'ads_disabled') showHouseAd(); // nothing for paid users
112
144
  }
113
145
 
114
146
  {interstitial.ad && interstitial.tracker && (
@@ -117,6 +149,7 @@ async function onMarkComplete() {
117
149
  tracker={interstitial.tracker}
118
150
  onClose={interstitial.dismiss}
119
151
  onRemoveAds={() => { interstitial.dismiss(); navigation.navigate('Upgrade'); }}
152
+ audio="optional" // optional: overrides ad.audio for this screen
120
153
  />
121
154
  )}
122
155
  ```
@@ -133,19 +166,47 @@ The screen is a fullscreen modal: the video fills it, a small "Ad" label sits
133
166
  top left, a white button shows `ctaLabel` ("Learn more" when the advertiser
134
167
  set none), and either `onRemoveAds` (a "Remove ads" link) or
135
168
  `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.
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.
140
176
 
141
177
  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
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
143
180
  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
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
145
183
  back, Skip is available at once. Android back closes the ad only once Skip is
146
184
  available. If the ad expired before it reached the screen, the screen closes
147
185
  itself through `onClose` without recording an impression.
148
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
+
149
210
  ### The creative cache
150
211
 
151
212
  `createExpoFileCache(FileSystem)` takes the `expo-file-system` module as your
@@ -153,7 +214,8 @@ app imports it, on any Expo SDK from 50. On SDK 54 and later
153
214
  `import * as FileSystem from 'expo-file-system'` is the object API (`File`,
154
215
  `Directory`, `Paths`) and the adapter uses it; before SDK 54, or from
155
216
  `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.
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).
157
219
 
158
220
  It keeps creatives in `<cache directory>/ethicly-ads/`
159
221
  within `prefetch.max_cache_mb` and `prefetch.max_cached_creatives` (from
@@ -168,7 +230,8 @@ default in-memory `storage` the index is lost when the app exits, so the
168
230
  directory is emptied at the next start: disk use stays bounded either way, but
169
231
  pass `AsyncStorage` to keep creatives across launches. A custom
170
232
  `FileCacheAdapter` should implement `list()` (and ideally `uriFor()`) for the
171
- same guarantee.
233
+ same guarantee, and `cancel()` so `setAdsEnabled(false)` and the one-minute
234
+ limit can stop a download in flight.
172
235
 
173
236
  ## Test mode
174
237
 
@@ -180,9 +243,8 @@ earnings. The `/impression` answer is logged as a test impression.
180
243
  (`__DEV__` false) the SDK ignores `testMode: true`: it serves and bills
181
244
  normally and logs an error through `logger` and once through `console.error`,
182
245
  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.
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.
186
248
 
187
249
  ## Reliability
188
250
 
@@ -213,9 +275,11 @@ createEthicly(options: {
213
275
  appVersion: string;
214
276
  baseUrl?: string; // default https://ads.ethicly.ch/functions/v1/get-ad-with-geo
215
277
  testMode?: boolean; // ignored in a release build
216
- adsEnabled?: boolean; // default true
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
217
281
  storage?: KeyValueStorage; // AsyncStorage shape; default in memory
218
- fileCache?: FileCacheAdapter; // download/exists/delete/size/list; default streams
282
+ fileCache?: FileCacheAdapter; // download/exists/delete/size/list/cancel; default streams
219
283
  openUrl?: (url: string) => unknown;
220
284
  fetch?: FetchLike; // default global fetch
221
285
  now?: () => number;
@@ -265,12 +329,17 @@ interface Tracker {
265
329
  `NoFillReason` is a server reason (`no_matching_ad`, `no_approved_ads`,
266
330
  `app_disabled`, `sdk_unsupported`, `interstitial_disabled`, ...) or one of the
267
331
  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".
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.
270
339
 
271
340
  Also exported: `useEthiclyInterstitial`, `createMemoryStorage`,
272
341
  `createMemoryFileCache`, `createExpoFileCache`, `appendClickToken`,
273
- `compareVersions`, `SDK_VERSION`, `SESSION_TIMEOUT_MS`. The core alone is at
342
+ `compareVersions`, `SDK_VERSION`, `SESSION_TIMEOUT_MS`, `DEFAULT_LOAD_TIMEOUT_MS`. The core alone is at
274
343
  `@ethicly/react-native/core` (no React import).
275
344
 
276
345
  ## What it sends, and what it never sends
@@ -282,7 +351,72 @@ from `crypto.randomUUID` or `crypto.getRandomValues` and falls back to
282
351
  without a polyfill such as `react-native-get-random-values`), the ad
283
352
  and impression ids, and the country code the server returned. It sends no
284
353
  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`.
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.
286
420
 
287
421
  ## Development
288
422
 
@@ -290,25 +424,6 @@ The server's full inventory is in "Data collected" in `docs/APP_API_V1.md`.
290
424
  npm install
291
425
  npm run typecheck
292
426
  npm test # jest in Node, against recorded fixtures
293
- npm run test:live # one test-mode run against production (stores nothing)
294
427
  npm run build # lib/commonjs, lib/module, lib/typescript (also run by `prepare`)
295
428
  npm pack # installable tarball
296
429
  ```
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`).
@@ -73,7 +73,8 @@ function isLegacyFs(fs) {
73
73
  * A file cache over either expo-file-system API: the object API of SDK 54+
74
74
  * (`File`, `Directory`, `Paths`), else the legacy functions (`getInfoAsync`,
75
75
  * `downloadAsync`, ...). Anything else gets the streaming cache, which writes
76
- * nothing to disk, and one warning through `logger` (default `console`).
76
+ * nothing to disk, and one warning through `logger` (default `console` in
77
+ * development, nothing in a release build).
77
78
  */
78
79
  function createExpoFileCache(fs, subdirectory = exports.DEFAULT_CACHE_SUBDIRECTORY, logger) {
79
80
  const sub = safeCacheSubdirectory(subdirectory);
@@ -81,7 +82,8 @@ function createExpoFileCache(fs, subdirectory = exports.DEFAULT_CACHE_SUBDIRECTO
81
82
  return modernFileCache(fs, sub);
82
83
  if (isLegacyFs(fs))
83
84
  return legacyFileCache(fs, sub);
84
- safeLogger(logger || consoleLogger()).warn('createExpoFileCache: not an expo-file-system module (no File/Directory/Paths, no cacheDirectory); creatives will stream');
85
+ // console only in development: a release build stays quiet unless the app passes a logger.
86
+ safeLogger(logger || (isReleaseBuild() ? undefined : consoleLogger())).warn('createExpoFileCache: not an expo-file-system module (no File/Directory/Paths, no cacheDirectory); creatives will stream');
85
87
  return createMemoryFileCache();
86
88
  }
87
89
  function consoleLogger() {
@@ -91,6 +93,8 @@ function consoleLogger() {
91
93
  function legacyFileCache(fs, sub) {
92
94
  const dir = `${fs.cacheDirectory}${sub}`;
93
95
  let made = null;
96
+ /** Cancels for the downloads in flight (only resumable downloads can be cancelled). */
97
+ const inflight = new Set();
94
98
  const sizeOf = async (uri) => {
95
99
  const info = await fs.getInfoAsync(uri, { size: true });
96
100
  return info.exists && typeof info.size === 'number' ? info.size : 0;
@@ -106,15 +110,22 @@ function legacyFileCache(fs, sub) {
106
110
  let tooBig = false;
107
111
  if (max !== undefined && fs.createDownloadResumable) {
108
112
  // Stop as soon as the server announces, or we have written, more than the budget.
113
+ const stop = () => { void (dl.cancelAsync ? dl.cancelAsync() : dl.pauseAsync()).catch(() => undefined); };
109
114
  const dl = fs.createDownloadResumable(url, target, {}, (p) => {
110
115
  if (tooBig)
111
116
  return;
112
117
  if (p.totalBytesExpectedToWrite > max || p.totalBytesWritten > max) {
113
118
  tooBig = true;
114
- void (dl.cancelAsync ? dl.cancelAsync() : dl.pauseAsync()).catch(() => undefined);
119
+ stop();
115
120
  }
116
121
  });
117
- res = await dl.downloadAsync().catch(() => undefined);
122
+ inflight.add(stop);
123
+ try {
124
+ res = await dl.downloadAsync().catch(() => undefined);
125
+ }
126
+ finally {
127
+ inflight.delete(stop);
128
+ }
118
129
  }
119
130
  else {
120
131
  res = await fs.downloadAsync(url, target);
@@ -129,6 +140,12 @@ function legacyFileCache(fs, sub) {
129
140
  async delete(uri) { await fs.deleteAsync(uri, { idempotent: true }); },
130
141
  size: sizeOf,
131
142
  uriFor: (fileName) => dir + fileName,
143
+ cancel() {
144
+ inflight.forEach((stop) => { try {
145
+ stop();
146
+ }
147
+ catch { /* already settled */ } });
148
+ },
132
149
  async list() {
133
150
  if (!fs.readDirectoryAsync)
134
151
  return [];
@@ -163,6 +180,7 @@ function modernFileCache(fs, sub) {
163
180
  return f.exists && typeof f.size === 'number' && f.size > 0 ? f.size : 0;
164
181
  };
165
182
  let made = false;
183
+ const inflight = new Set();
166
184
  return {
167
185
  async download(url, fileName, opts) {
168
186
  if (!made) {
@@ -174,6 +192,7 @@ function modernFileCache(fs, sub) {
174
192
  const target = dir() + fileName;
175
193
  const max = opts === null || opts === void 0 ? void 0 : opts.maxBytes;
176
194
  let tooBig = false;
195
+ let cancelled = false;
177
196
  try {
178
197
  remove(target);
179
198
  const createTask = fs.File.createDownloadTask;
@@ -190,7 +209,14 @@ function modernFileCache(fs, sub) {
190
209
  catch { /* already settled */ }
191
210
  },
192
211
  });
193
- await task.downloadAsync();
212
+ const handle = { cancel: () => { cancelled = true; task.cancel(); } };
213
+ inflight.add(handle);
214
+ try {
215
+ await task.downloadAsync();
216
+ }
217
+ finally {
218
+ inflight.delete(handle);
219
+ }
194
220
  }
195
221
  else {
196
222
  await fs.File.downloadFileAsync(url, file(target), { idempotent: true });
@@ -206,6 +232,13 @@ function modernFileCache(fs, sub) {
206
232
  // Without a progress callback the whole file lands first: check it now
207
233
  // and delete it if it is over the budget.
208
234
  const bytes = await sizeOf(target);
235
+ if (cancelled) {
236
+ try {
237
+ remove(target);
238
+ }
239
+ catch { /* ignore */ }
240
+ throw new Error('download cancelled');
241
+ }
209
242
  if (tooBig || (max !== undefined && bytes > max)) {
210
243
  try {
211
244
  remove(target);
@@ -219,6 +252,12 @@ function modernFileCache(fs, sub) {
219
252
  async delete(uri) { remove(uri); },
220
253
  size: sizeOf,
221
254
  uriFor: (fileName) => dir() + fileName,
255
+ cancel() {
256
+ inflight.forEach((t) => { try {
257
+ t.cancel();
258
+ }
259
+ catch { /* already settled */ } });
260
+ },
222
261
  async list() {
223
262
  const d = new fs.Directory(dir());
224
263
  if (!d.exists)
@@ -12,7 +12,14 @@
12
12
  // - on first use every pending file, and every file in the SDK's cache
13
13
  // directory that the index does not list, is deleted.
14
14
  Object.defineProperty(exports, "__esModule", { value: true });
15
- exports.CreativeCache = void 0;
15
+ exports.CreativeCache = exports.DOWNLOAD_TIMEOUT_MS = void 0;
16
+ /**
17
+ * The longest one creative file may take to download. A slower (trickling)
18
+ * download is cancelled when the adapter supports it, else abandoned: the
19
+ * creative streams and later downloads are not held up behind it. A file it
20
+ * still writes afterwards is not indexed, so the next launch's sweep deletes it.
21
+ */
22
+ exports.DOWNLOAD_TIMEOUT_MS = 60000;
16
23
  function hash(s) {
17
24
  let h = 5381;
18
25
  for (let i = 0; i < s.length; i++)
@@ -27,18 +34,59 @@ function baseName(uri) {
27
34
  return uri.replace(/[?#].*$/, '').split('/').pop() || uri;
28
35
  }
29
36
  class CreativeCache {
30
- constructor(files, storage, storageKey, now, log, probeSize = async () => null) {
37
+ constructor(files, storage, storageKey, now, log, probeSize = async () => null, downloadTimeoutMs = exports.DOWNLOAD_TIMEOUT_MS) {
31
38
  this.files = files;
32
39
  this.storage = storage;
33
40
  this.storageKey = storageKey;
34
41
  this.now = now;
35
42
  this.log = log;
36
43
  this.probeSize = probeSize;
44
+ this.downloadTimeoutMs = downloadTimeoutMs;
37
45
  this.entries = [];
38
46
  /** File names whose download has started but not landed. */
39
47
  this.pending = [];
40
48
  this.loaded = null;
41
49
  this.chain = Promise.resolve();
50
+ /** Bumped by cancel(): a download started before it no longer counts. */
51
+ this.generation = 0;
52
+ }
53
+ /**
54
+ * Stop the download in flight, when the adapter can (FileCacheAdapter.cancel),
55
+ * and skip the files not started yet. For setAdsEnabled(false).
56
+ */
57
+ cancel() {
58
+ var _a, _b;
59
+ this.generation += 1;
60
+ try {
61
+ (_b = (_a = this.files).cancel) === null || _b === void 0 ? void 0 : _b.call(_a);
62
+ }
63
+ catch (e) {
64
+ this.log.warn('could not cancel the creative download', e);
65
+ }
66
+ }
67
+ /** The adapter's download, given up on after downloadTimeoutMs. */
68
+ async downloadWithin(url, name, maxBytes) {
69
+ let timer;
70
+ const timeout = new Promise((_, reject) => {
71
+ timer = setTimeout(() => {
72
+ var _a, _b;
73
+ try {
74
+ (_b = (_a = this.files).cancel) === null || _b === void 0 ? void 0 : _b.call(_a);
75
+ }
76
+ catch { /* best effort */ }
77
+ reject(new Error(`download took longer than ${this.downloadTimeoutMs} ms`));
78
+ }, this.downloadTimeoutMs);
79
+ });
80
+ const dl = this.files.download(url, name, { maxBytes });
81
+ // A late rejection of an abandoned download must not go unhandled.
82
+ dl.catch(() => undefined);
83
+ try {
84
+ return await Promise.race([dl, timeout]);
85
+ }
86
+ finally {
87
+ if (timer)
88
+ clearTimeout(timer);
89
+ }
42
90
  }
43
91
  load() {
44
92
  if (!this.loaded)
@@ -111,7 +159,8 @@ class CreativeCache {
111
159
  * Make sure the files of one creative are on disk. Never throws: a file that
112
160
  * cannot be cached is simply left out of the result and streamed instead.
113
161
  * `allowed()` is checked before every download so setAdsEnabled(false)
114
- * stops a download that has not started yet.
162
+ * stops a download that has not started yet; cancel() also stops the one in
163
+ * flight when the adapter supports it.
115
164
  */
116
165
  ensure(adId, urls, limits, allowed) {
117
166
  const run = this.chain.then(() => this.ensureNow(adId, urls, limits, allowed));
@@ -133,10 +182,12 @@ class CreativeCache {
133
182
  this.entries.push(entry);
134
183
  }
135
184
  entry.lastUsed = this.now();
185
+ const generation = this.generation;
186
+ const go = () => allowed() && generation === this.generation;
136
187
  for (const url of urls) {
137
188
  if (entry.files.some((f) => f.url === url))
138
189
  continue;
139
- if (!allowed())
190
+ if (!go())
140
191
  break;
141
192
  // One creative may use the whole budget (older ones are evicted), never more.
142
193
  const budget = limits.maxBytes - this.size(entry);
@@ -152,12 +203,16 @@ class CreativeCache {
152
203
  this.pending = [name];
153
204
  await this.persist();
154
205
  try {
155
- const res = await this.files.download(url, name, { maxBytes: budget });
206
+ const res = await this.downloadWithin(url, name, budget);
156
207
  const bytes = typeof res.bytes === 'number' && res.bytes > 0 ? res.bytes : await this.files.size(res.uri).catch(() => 0);
157
208
  if (bytes > budget) {
158
209
  await this.files.delete(res.uri).catch(() => undefined);
159
210
  this.log.info(`${url} is over the cache budget: it will stream`);
160
211
  }
212
+ else if (!go()) {
213
+ // Cancelled while it was landing: keep nothing for a paid user.
214
+ await this.files.delete(res.uri).catch(() => undefined);
215
+ }
161
216
  else {
162
217
  entry.files.push({ url, uri: res.uri, bytes });
163
218
  }