@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.
- package/CHANGELOG.md +133 -0
- package/LICENSE +21 -0
- package/README.md +428 -2
- package/core/package.json +6 -0
- package/interstitial/package.json +6 -0
- package/lib/commonjs/core/adapters.js +326 -0
- package/lib/commonjs/core/beacons.js +70 -0
- package/lib/commonjs/core/cache.js +261 -0
- package/lib/commonjs/core/click.js +29 -0
- package/lib/commonjs/core/client.js +585 -0
- package/lib/commonjs/core/config.js +128 -0
- package/lib/commonjs/core/http.js +115 -0
- package/lib/commonjs/core/index.js +21 -0
- package/lib/commonjs/core/outbox.js +192 -0
- package/lib/commonjs/core/tracker.js +379 -0
- package/lib/commonjs/core/types.js +4 -0
- package/lib/commonjs/index.js +22 -0
- package/lib/commonjs/interstitial.js +7 -0
- package/lib/commonjs/react/EthiclyInterstitial.js +319 -0
- package/lib/commonjs/react/useEthiclyInterstitial.js +54 -0
- package/lib/commonjs/version.js +5 -0
- package/lib/module/core/adapters.js +315 -0
- package/lib/module/core/beacons.js +64 -0
- package/lib/module/core/cache.js +257 -0
- package/lib/module/core/click.js +24 -0
- package/lib/module/core/client.js +581 -0
- package/lib/module/core/config.js +118 -0
- package/lib/module/core/http.js +105 -0
- package/lib/module/core/index.js +6 -0
- package/lib/module/core/outbox.js +186 -0
- package/lib/module/core/tracker.js +375 -0
- package/lib/module/core/types.js +3 -0
- package/lib/module/index.js +4 -0
- package/lib/module/interstitial.js +3 -0
- package/lib/module/react/EthiclyInterstitial.js +292 -0
- package/lib/module/react/useEthiclyInterstitial.js +51 -0
- package/lib/module/version.js +2 -0
- package/lib/typescript/core/adapters.d.ts +139 -0
- package/lib/typescript/core/beacons.d.ts +32 -0
- package/lib/typescript/core/cache.d.ts +71 -0
- package/lib/typescript/core/click.d.ts +13 -0
- package/lib/typescript/core/client.d.ts +78 -0
- package/lib/typescript/core/config.d.ts +33 -0
- package/lib/typescript/core/http.d.ts +34 -0
- package/lib/typescript/core/index.d.ts +8 -0
- package/lib/typescript/core/outbox.d.ts +56 -0
- package/lib/typescript/core/tracker.d.ts +95 -0
- package/lib/typescript/core/types.d.ts +175 -0
- package/lib/typescript/index.d.ts +3 -0
- package/lib/typescript/interstitial.d.ts +2 -0
- package/lib/typescript/react/EthiclyInterstitial.d.ts +51 -0
- package/lib/typescript/react/useEthiclyInterstitial.d.ts +20 -0
- package/lib/typescript/version.d.ts +2 -0
- package/package.json +101 -4
- package/src/core/adapters.ts +365 -0
- package/src/core/beacons.ts +81 -0
- package/src/core/cache.ts +261 -0
- package/src/core/click.ts +26 -0
- package/src/core/client.ts +665 -0
- package/src/core/config.ts +124 -0
- package/src/core/http.ts +115 -0
- package/src/core/index.ts +14 -0
- package/src/core/outbox.ts +193 -0
- package/src/core/tracker.ts +376 -0
- package/src/core/types.ts +185 -0
- package/src/index.ts +5 -0
- package/src/interstitial.ts +4 -0
- package/src/react/EthiclyInterstitial.tsx +432 -0
- package/src/react/useEthiclyInterstitial.ts +74 -0
- 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
|
-
#
|
|
1
|
+
# @ethicly/react-native
|
|
2
2
|
|
|
3
|
-
|
|
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
|
+
```
|