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