@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.
- package/CHANGELOG.md +59 -1
- package/README.md +168 -53
- package/lib/commonjs/core/adapters.js +44 -5
- package/lib/commonjs/core/cache.js +60 -5
- package/lib/commonjs/core/click.js +10 -0
- package/lib/commonjs/core/client.js +160 -64
- package/lib/commonjs/core/config.js +17 -2
- package/lib/commonjs/core/index.js +2 -1
- package/lib/commonjs/core/tracker.js +5 -0
- package/lib/commonjs/react/EthiclyInterstitial.js +46 -13
- package/lib/commonjs/version.js +1 -1
- package/lib/module/core/adapters.js +44 -5
- package/lib/module/core/cache.js +59 -4
- package/lib/module/core/click.js +9 -0
- package/lib/module/core/client.js +160 -64
- package/lib/module/core/config.js +15 -1
- package/lib/module/core/index.js +1 -1
- package/lib/module/core/tracker.js +6 -1
- package/lib/module/react/EthiclyInterstitial.js +45 -13
- package/lib/module/version.js +1 -1
- package/lib/typescript/core/adapters.d.ts +2 -1
- package/lib/typescript/core/cache.d.ts +20 -2
- package/lib/typescript/core/click.d.ts +5 -0
- package/lib/typescript/core/client.d.ts +23 -3
- package/lib/typescript/core/config.d.ts +9 -0
- package/lib/typescript/core/index.d.ts +1 -1
- package/lib/typescript/core/types.d.ts +5 -0
- package/lib/typescript/react/EthiclyInterstitial.d.ts +13 -1
- package/lib/typescript/react/useEthiclyInterstitial.d.ts +1 -1
- package/lib/typescript/version.d.ts +1 -1
- package/package.json +2 -2
- package/src/core/adapters.ts +33 -5
- package/src/core/cache.ts +48 -3
- package/src/core/click.ts +10 -0
- package/src/core/client.ts +186 -68
- package/src/core/config.ts +14 -1
- package/src/core/index.ts +1 -1
- package/src/core/tracker.ts +6 -1
- package/src/core/types.ts +5 -0
- package/src/react/EthiclyInterstitial.tsx +62 -16
- package/src/react/useEthiclyInterstitial.ts +1 -1
- 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
|
|
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
|
|
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: '
|
|
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
|
-
|
|
57
|
-
|
|
58
|
-
`
|
|
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 (
|
|
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,
|
|
87
|
-
`ad.skipAfterMs
|
|
88
|
-
|
|
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 (
|
|
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.
|
|
137
|
-
`
|
|
138
|
-
|
|
139
|
-
|
|
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).
|
|
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.
|
|
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
|
|
184
|
-
|
|
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`.
|
|
269
|
-
every
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
119
|
+
stop();
|
|
115
120
|
}
|
|
116
121
|
});
|
|
117
|
-
|
|
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
|
-
|
|
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 (!
|
|
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.
|
|
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
|
}
|