@ethicly/react-native 0.2.1 → 0.4.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 +92 -0
- package/README.md +189 -12
- package/lib/commonjs/core/cache.js +2 -0
- package/lib/commonjs/core/client.js +245 -62
- package/lib/commonjs/core/config.js +4 -1
- package/lib/commonjs/core/houseTracker.js +92 -0
- package/lib/commonjs/core/tracker.js +3 -0
- package/lib/commonjs/react/EthiclyInterstitial.js +23 -4
- package/lib/commonjs/react/useEthiclyInterstitial.js +26 -7
- package/lib/commonjs/version.js +1 -1
- package/lib/module/core/cache.js +2 -0
- package/lib/module/core/client.js +245 -62
- package/lib/module/core/config.js +4 -1
- package/lib/module/core/houseTracker.js +88 -0
- package/lib/module/core/tracker.js +3 -0
- package/lib/module/react/EthiclyInterstitial.js +23 -4
- package/lib/module/react/useEthiclyInterstitial.js +26 -7
- package/lib/module/version.js +1 -1
- package/lib/typescript/core/cache.d.ts +3 -1
- package/lib/typescript/core/client.d.ts +43 -4
- package/lib/typescript/core/houseTracker.d.ts +53 -0
- package/lib/typescript/core/index.d.ts +1 -1
- package/lib/typescript/core/types.d.ts +87 -2
- package/lib/typescript/react/EthiclyInterstitial.d.ts +7 -0
- package/lib/typescript/react/useEthiclyInterstitial.d.ts +19 -3
- package/lib/typescript/version.d.ts +1 -1
- package/package.json +1 -1
- package/src/core/cache.ts +4 -2
- package/src/core/client.ts +277 -62
- package/src/core/config.ts +4 -1
- package/src/core/houseTracker.ts +108 -0
- package/src/core/index.ts +3 -2
- package/src/core/tracker.ts +2 -0
- package/src/core/types.ts +96 -2
- package/src/react/EthiclyInterstitial.tsx +26 -4
- package/src/react/useEthiclyInterstitial.ts +45 -10
- package/src/version.ts +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -5,6 +5,98 @@ 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
6
|
contract v1 of the Ethicly app API.
|
|
7
7
|
|
|
8
|
+
## [0.4.0] - 2026-11-22
|
|
9
|
+
|
|
10
|
+
Needs the server change that sends `house_ad` on an interstitial no-fill and
|
|
11
|
+
adds `/fallback-impression` and `interstitial.sponsor_label`. Against an
|
|
12
|
+
older server the SDK behaves exactly like 0.3.0.
|
|
13
|
+
|
|
14
|
+
### Added
|
|
15
|
+
|
|
16
|
+
- House ads. When no paid ad fills, the serve answer may carry the
|
|
17
|
+
publisher's house ad (uploaded in the dashboard). The SDK returns it as a
|
|
18
|
+
normal ad with `ad.house: true` and the server's reason in
|
|
19
|
+
`ad.noFillReason`; `lastNoFillReason` stays null because an ad is shown.
|
|
20
|
+
It is validated like a paid ad (media, http(s)-only destination), cached
|
|
21
|
+
under its own key (`house-<id>`, so it never collides with a paid ad id),
|
|
22
|
+
unbilled, and counted toward `maxPerSession` and the gap between ads.
|
|
23
|
+
- House-ad counters: `tracker.shown()` sends `POST /fallback-impression` and
|
|
24
|
+
`tracker.clicked()` sends `POST /fallback-click` (body `{ fallback_id }`),
|
|
25
|
+
once each, fire-and-forget; the link opens at once. No `/impression`,
|
|
26
|
+
`/viewable`, video events or click token for house ads, and no counters in
|
|
27
|
+
test mode. Serve requests that take a house ad send `house_ads=1` with
|
|
28
|
+
`client_fallback_tracking=1`, so the server does not also count the view at
|
|
29
|
+
pick time.
|
|
30
|
+
- `houseAds` on `createEthicly` (default true: the dashboard upload is the
|
|
31
|
+
opt-in), `setHouseAds(enabled)`, `{ houseAds }` on `preload()` and
|
|
32
|
+
`loadInterstitial()`, and a `houseAds` option on `useEthiclyInterstitial`.
|
|
33
|
+
`false` treats a house ad as no fill so the app can show its own.
|
|
34
|
+
- `onHouseAdPress(ad)` on `EthiclyInterstitial`, `useEthiclyInterstitial` and
|
|
35
|
+
`createEthicly` (prop wins over hook, hook over client). For a house ad, a
|
|
36
|
+
tap on the button counts the tap, closes the ad the same way as `onClose`,
|
|
37
|
+
then calls the handler instead of opening the link: for example the app's
|
|
38
|
+
premium screen. Paid ads always open the advertiser's page.
|
|
39
|
+
- `tracker.clicked({ open: false })` counts a house ad tap without opening
|
|
40
|
+
anything, for headless players. Paid ads ignore it.
|
|
41
|
+
- `/config` `interstitial.house_ads` (the dashboard master switch, absent
|
|
42
|
+
means true): while false the SDK sends neither `house_ads=1` nor
|
|
43
|
+
`client_fallback_tracking=1`, ignores a `house_ad` and never shows a
|
|
44
|
+
preloaded one.
|
|
45
|
+
- `ad.showSponsorLabel`: whether "Sponsored by Ethicly.ch" shows. False for
|
|
46
|
+
house ads; for paid ads the dashboard setting from `/config`
|
|
47
|
+
`interstitial.sponsor_label` (absent means true). `EthiclyConfig` gains
|
|
48
|
+
`interstitial.sponsor_label`.
|
|
49
|
+
- README and INTEGRATING: "House ads" and "Remove ads" sections.
|
|
50
|
+
- Example app: house ads show like any ad, the status line reads
|
|
51
|
+
"House ad (no paid ad: <reason>)", "Remove ads" opens an alert, and a house
|
|
52
|
+
ad tap opens an "Open premium screen" alert through `onHouseAdPress`.
|
|
53
|
+
|
|
54
|
+
### Changed
|
|
55
|
+
|
|
56
|
+
- A preloaded house ad never stands in for a paid ad: `loadInterstitial()`
|
|
57
|
+
first asks for a paid ad within `loadTimeoutMs` and shows the house ad only
|
|
58
|
+
if none fills. A paid ad that answers after the budget waits for the next
|
|
59
|
+
show.
|
|
60
|
+
- `EthiclyInterstitial` shows the sponsor line only when
|
|
61
|
+
`ad.showSponsorLabel` is true. The "Ad" label, the button (`ad.ctaLabel`)
|
|
62
|
+
and the "Remove ads" link are unchanged, also on house ads.
|
|
63
|
+
- Docs: the sponsor line is a publisher dashboard setting, no longer
|
|
64
|
+
described as required. In your own player, show it when
|
|
65
|
+
`ad.showSponsorLabel` is true.
|
|
66
|
+
|
|
67
|
+
## [0.3.0] - 2026-11-21
|
|
68
|
+
|
|
69
|
+
### Added
|
|
70
|
+
|
|
71
|
+
- `/click` now carries the impression's `viewable_token`, so the server can
|
|
72
|
+
bill a tap made before the view was confirmed and refuse unproven clicks.
|
|
73
|
+
- `frequency: { maxPerSession?, minGapSeconds? }` on `createEthicly`. The
|
|
74
|
+
publisher decides how often ads show: each field set in code wins over the
|
|
75
|
+
dashboard values from `/config` (`interstitial.max_per_session`,
|
|
76
|
+
`min_gap_s`); a field left out falls back to `/config`, then the defaults.
|
|
77
|
+
Any value 0 or above is accepted: `maxPerSession: 0` shows no ads,
|
|
78
|
+
`Infinity` or a large number means no session limit, `minGapSeconds: 0`
|
|
79
|
+
means no gap. Negative values count as 0; non-numbers are ignored with a
|
|
80
|
+
warning.
|
|
81
|
+
- `setFrequency(update)` changes the frequency at runtime (after an
|
|
82
|
+
entitlement check or an A/B test). A field left out keeps its value; `null`
|
|
83
|
+
goes back to `/config`. `getFrequency()` returns the values in effect.
|
|
84
|
+
- `nextAdStatus()` on the client and on `useEthiclyInterstitial`: whether an
|
|
85
|
+
ad may show now and, when not, the reason (`frequency_capped` with
|
|
86
|
+
`retryAt`, `session_cap`, `ads_disabled`, `not_ready` or a server gate) plus
|
|
87
|
+
`shownThisSession`, `maxPerSession` and `minGapSeconds`.
|
|
88
|
+
- README and INTEGRATING: "What you control and what Ethicly controls". Ads
|
|
89
|
+
shown beyond Ethicly's anti-abuse limits still play but are not billed.
|
|
90
|
+
- Example app: a status line under the buttons explains every no-ad case,
|
|
91
|
+
with a live countdown to the next allowed ad, and a "Demo: no frequency
|
|
92
|
+
limit" toggle.
|
|
93
|
+
|
|
94
|
+
### Changed
|
|
95
|
+
|
|
96
|
+
- `canShow()` is now `nextAdStatus().allowed`; its answers are unchanged.
|
|
97
|
+
Without `frequency`, behaviour is identical to 0.2.x. Billing and the event
|
|
98
|
+
outbox are unchanged.
|
|
99
|
+
|
|
8
100
|
## [0.2.1] - 2026-11-21
|
|
9
101
|
|
|
10
102
|
### Fixed
|
package/README.md
CHANGED
|
@@ -85,12 +85,16 @@ It speaks contract v1 of the Ethicly app API. It ships no native code of its own
|
|
|
85
85
|
```ts
|
|
86
86
|
const res = await ethicly.loadInterstitial();
|
|
87
87
|
if (res.ad) {
|
|
88
|
-
showMyPlayer(res.ad, res.tracker); // your existing player
|
|
88
|
+
showMyPlayer(res.ad, res.tracker); // your existing player (ad.house: the publisher's house ad)
|
|
89
89
|
} else if (res.reason !== 'ads_disabled') {
|
|
90
|
-
showHouseAd(); // no fill, capped...: your own
|
|
90
|
+
showHouseAd(); // no fill, capped...: your own fallback
|
|
91
91
|
} // ads_disabled: a paid user, show nothing
|
|
92
92
|
```
|
|
93
93
|
|
|
94
|
+
When no paid ad fills and you uploaded a house ad in the dashboard,
|
|
95
|
+
`res.ad` is that house ad (`res.ad.house` is true): play it like any other
|
|
96
|
+
ad. See "House ads" below.
|
|
97
|
+
|
|
94
98
|
`loadInterstitial()` returns within about `loadTimeoutMs` (default 3 s)
|
|
95
99
|
plus the serve request. When `preload()` already downloaded the ad it plays
|
|
96
100
|
from disk at once. When the download is not finished by then, the ad comes
|
|
@@ -110,8 +114,53 @@ It speaks contract v1 of the Ethicly app API. It ships no native code of its own
|
|
|
110
114
|
time of the last ad is stored through `storage`, so `min_gap_s` also holds
|
|
111
115
|
across restarts.
|
|
112
116
|
|
|
117
|
+
**You decide how often.** The dashboard values are only the starting point.
|
|
118
|
+
Set them in code and they win for this client:
|
|
119
|
+
|
|
120
|
+
```ts
|
|
121
|
+
const ethicly = createEthicly({
|
|
122
|
+
// ...
|
|
123
|
+
frequency: { maxPerSession: 5, minGapSeconds: 60 },
|
|
124
|
+
});
|
|
125
|
+
// Later, for example after an A/B test or an entitlement check:
|
|
126
|
+
ethicly.setFrequency({ minGapSeconds: 30 }); // maxPerSession stays 5
|
|
127
|
+
ethicly.setFrequency({ maxPerSession: null }); // back to the dashboard value
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
Each field you set wins over `/config`; a field you leave out uses the
|
|
131
|
+
dashboard value, then the defaults (3 per session, 120 s). Any number 0 or
|
|
132
|
+
above works: `maxPerSession: 0` shows no ads, `maxPerSession: Infinity` (or
|
|
133
|
+
a large number such as `1_000_000`) means no session limit,
|
|
134
|
+
`minGapSeconds: 0` means no gap. A negative value counts as 0; anything
|
|
135
|
+
that is not a number is ignored with a warning. Without `frequency` the SDK
|
|
136
|
+
behaves exactly as 0.2.x. `ethicly.getFrequency()` returns the values in
|
|
137
|
+
effect.
|
|
138
|
+
|
|
139
|
+
**Tell the user when the next ad may show.** `ethicly.nextAdStatus()` (also
|
|
140
|
+
on the hook) says whether an ad may show now and, when not, why:
|
|
141
|
+
|
|
142
|
+
```ts
|
|
143
|
+
const s = ethicly.nextAdStatus();
|
|
144
|
+
// { allowed: false, reason: 'frequency_capped', retryAt: 1763730000000,
|
|
145
|
+
// shownThisSession: 1, maxPerSession: 3, minGapSeconds: 120 }
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
| `reason` | Meaning |
|
|
149
|
+
|---|---|
|
|
150
|
+
| `frequency_capped` | the gap between ads is running; `retryAt` (epoch ms) is when it ends |
|
|
151
|
+
| `session_cap` | `maxPerSession` ads were shown this session; no `retryAt` (a new session starts after 30 minutes in the background) |
|
|
152
|
+
| `ads_disabled` | `setAdsEnabled(false)`, a paid user |
|
|
153
|
+
| `not_ready` | the stored frequency state is still loading |
|
|
154
|
+
| `invalid_key`, `unknown_key`, `sdk_unsupported`, `app_disabled`, `interstitial_disabled` | the same gates `loadInterstitial()` reports |
|
|
155
|
+
|
|
156
|
+
`canShow()` is `nextAdStatus().allowed`. `loadInterstitial()` still
|
|
157
|
+
reports both caps as `frequency_capped`, as in 0.2.x.
|
|
158
|
+
|
|
113
159
|
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
|
|
160
|
+
file when cached, else the remote URL), show `ad.ctaLabel` on the button
|
|
161
|
+
with a small "Sponsored by Ethicly.ch" line under it when
|
|
162
|
+
`ad.showSponsorLabel` is true (the publisher's dashboard setting, on by
|
|
163
|
+
default, and always false for house ads),
|
|
115
164
|
allow skipping after `ad.skipAfterMs` (always 8 to 15 seconds: the SDK
|
|
116
165
|
clamps the server's value), play with sound unless `ad.audio` is `none`
|
|
117
166
|
(always muted) or `optional` (start muted), then:
|
|
@@ -166,7 +215,8 @@ The screen is a fullscreen modal: the video fills it, a small "Ad" label sits
|
|
|
166
215
|
top left, a white button shows `ctaLabel` ("Learn more" when the advertiser
|
|
167
216
|
set none), and either `onRemoveAds` (a "Remove ads" link) or
|
|
168
217
|
`renderBelowButton` fills the space under the button, above a small
|
|
169
|
-
"Sponsored by Ethicly.ch" line
|
|
218
|
+
"Sponsored by Ethicly.ch" line when `ad.showSponsorLabel` is true (see
|
|
219
|
+
"House ads" and "What you control" below). A test-mode ad (`ad.test`) also shows a small
|
|
170
220
|
"Test ad" label. Sound follows `ad.audio`, or the screen's `audio` prop when
|
|
171
221
|
you pass one (see "Sound" below).
|
|
172
222
|
|
|
@@ -184,6 +234,85 @@ back, Skip is available at once. Android back closes the ad only once Skip is
|
|
|
184
234
|
available. If the ad expired before it reached the screen, the screen closes
|
|
185
235
|
itself through `onClose` without recording an impression.
|
|
186
236
|
|
|
237
|
+
### Remove ads
|
|
238
|
+
|
|
239
|
+
Pass `onRemoveAds` to show a "Remove ads" link under the button. Open your
|
|
240
|
+
premium or upgrade screen there, and dismiss the ad first:
|
|
241
|
+
|
|
242
|
+
```tsx
|
|
243
|
+
<EthiclyInterstitial
|
|
244
|
+
ad={interstitial.ad}
|
|
245
|
+
tracker={interstitial.tracker}
|
|
246
|
+
onClose={interstitial.dismiss}
|
|
247
|
+
onRemoveAds={() => { interstitial.dismiss(); navigation.navigate('Premium'); }}
|
|
248
|
+
removeAdsLabel="Go ad-free" // optional: renames the link
|
|
249
|
+
/>
|
|
250
|
+
```
|
|
251
|
+
|
|
252
|
+
The link works the same on paid ads and house ads. Once the user pays, call
|
|
253
|
+
`ethicly.setAdsEnabled(false)` so no ad of either kind shows again. For a
|
|
254
|
+
completely different control, pass `renderBelowButton` instead.
|
|
255
|
+
|
|
256
|
+
### House ads
|
|
257
|
+
|
|
258
|
+
A house ad is the publisher's own fullscreen creative (a video or a still,
|
|
259
|
+
with its own button label and link), uploaded in the Ethicly dashboard. When
|
|
260
|
+
no paid ad fills, the server sends it with the no-fill and the SDK returns it
|
|
261
|
+
as a normal ad with `ad.house: true` and the real reason in
|
|
262
|
+
`ad.noFillReason` (`no_approved_ads`, `no_matching_ad`, `publisher_paused` or
|
|
263
|
+
`publisher_blackout`). `ethicly.lastNoFillReason` stays null, since an ad is
|
|
264
|
+
shown.
|
|
265
|
+
|
|
266
|
+
- **Opt-in by upload.** `houseAds` defaults to true, but nothing changes until
|
|
267
|
+
a house ad is uploaded in the dashboard. The dashboard also has a master
|
|
268
|
+
switch for house ads (`/config` `interstitial.house_ads`, on by default):
|
|
269
|
+
while it is off the SDK never asks for one.
|
|
270
|
+
- **Unbilled.** Nothing is billed or paid out. The SDK only counts views and
|
|
271
|
+
taps for your dashboard (`/fallback-impression` on `tracker.shown()`,
|
|
272
|
+
`/fallback-click` on `tracker.clicked()`), never in test mode.
|
|
273
|
+
- **Counted.** A house ad is a fullscreen interruption, so it counts toward
|
|
274
|
+
`maxPerSession` and the gap between ads, like a paid ad.
|
|
275
|
+
- **Never in the way of a paid ad.** When the preloaded ad is a house ad,
|
|
276
|
+
`loadInterstitial()` first asks for a paid ad, within `loadTimeoutMs`, and
|
|
277
|
+
shows the house ad only if none fills.
|
|
278
|
+
- **No sponsor line.** `ad.showSponsorLabel` is false: the ready-made screen
|
|
279
|
+
hides "Sponsored by Ethicly.ch" and keeps the "Ad" label, the button
|
|
280
|
+
(`ad.ctaLabel`) and the "Remove ads" link.
|
|
281
|
+
- **Optional.** To show the app's own fallback instead, pass
|
|
282
|
+
`houseAds: false` to `createEthicly`, call `ethicly.setHouseAds(false)`, or
|
|
283
|
+
pass `{ houseAds: false }` to one `loadInterstitial()` / `preload()` call
|
|
284
|
+
(or `useEthiclyInterstitial(ethicly, { houseAds: false })`). A house ad is
|
|
285
|
+
then a no fill with its reason, as in 0.3.
|
|
286
|
+
|
|
287
|
+
**Send the tap to your own screen.** By default the button opens the house
|
|
288
|
+
ad's link. To open the app's premium screen (or any screen) instead, pass
|
|
289
|
+
`onHouseAdPress`:
|
|
290
|
+
|
|
291
|
+
```tsx
|
|
292
|
+
<EthiclyInterstitial
|
|
293
|
+
ad={interstitial.ad}
|
|
294
|
+
tracker={interstitial.tracker}
|
|
295
|
+
onClose={interstitial.dismiss}
|
|
296
|
+
onHouseAdPress={() => navigation.navigate('Premium')}
|
|
297
|
+
/>
|
|
298
|
+
```
|
|
299
|
+
|
|
300
|
+
The tap is still counted, the ad closes the same way as `onClose`, and then
|
|
301
|
+
the handler runs; the link is not opened. The same option exists on
|
|
302
|
+
`useEthiclyInterstitial(ethicly, { onHouseAdPress })` and on
|
|
303
|
+
`createEthicly({ onHouseAdPress })`: the screen's prop wins over the hook's,
|
|
304
|
+
which wins over the client's. Paid ads are never routed to it: they always
|
|
305
|
+
open the advertiser's page.
|
|
306
|
+
|
|
307
|
+
A headless app branches on `ad.house` if it wants to treat house ads
|
|
308
|
+
differently; the tracker calls are the same. To count a tap without opening
|
|
309
|
+
the link, call `tracker.clicked({ open: false })`, close your player, then
|
|
310
|
+
show your own screen (paid ads ignore `open: false`).
|
|
311
|
+
|
|
312
|
+
**No paid ad and no house ad** (none uploaded, the dashboard switch off, or
|
|
313
|
+
`houseAds: false`): `loadInterstitial()` returns no ad with the reason, nothing
|
|
314
|
+
is shown, and the app shows its own fallback or nothing.
|
|
315
|
+
|
|
187
316
|
### Sound
|
|
188
317
|
|
|
189
318
|
Ads play with sound by default. You choose, in code:
|
|
@@ -233,6 +362,39 @@ pass `AsyncStorage` to keep creatives across launches. A custom
|
|
|
233
362
|
same guarantee, and `cancel()` so `setAdsEnabled(false)` and the one-minute
|
|
234
363
|
limit can stop a download in flight.
|
|
235
364
|
|
|
365
|
+
## What you control and what Ethicly controls
|
|
366
|
+
|
|
367
|
+
You, the publisher, decide how ads fit your app:
|
|
368
|
+
|
|
369
|
+
- **How often:** the `frequency` option or `setFrequency()` in code, or the
|
|
370
|
+
dashboard values when you set nothing.
|
|
371
|
+
- **When:** which moments in your app call `show()` or `loadInterstitial()`.
|
|
372
|
+
- **Paid users:** `setAdsEnabled(false)` means no serves and no downloads.
|
|
373
|
+
- **Sound:** the `audio` option or prop.
|
|
374
|
+
- **Fallback:** your house ad, uploaded in the dashboard and shown when no
|
|
375
|
+
paid ad fills, or with `houseAds: false` your app's own fallback.
|
|
376
|
+
- **The sponsor line:** whether "Sponsored by Ethicly.ch" shows under the
|
|
377
|
+
button on paid ads, a dashboard setting (on by default). The SDK passes it as
|
|
378
|
+
`ad.showSponsorLabel`; in your own player, show the line when it is true.
|
|
379
|
+
- **Remove ads:** the `onRemoveAds` link (renamed with `removeAdsLabel`)
|
|
380
|
+
opens your premium screen.
|
|
381
|
+
- **Player:** the ready-made screen or your own player with the tracker.
|
|
382
|
+
|
|
383
|
+
Ethicly decides:
|
|
384
|
+
|
|
385
|
+
- **Which ad** is served.
|
|
386
|
+
- **The skip window:** Skip appears after 8 to 15 seconds.
|
|
387
|
+
- **The "Ad" label:** it stays visible on every ad, house ads included, also
|
|
388
|
+
in your own player.
|
|
389
|
+
- **What counts** as a billable view or a billable click.
|
|
390
|
+
- **Billing** and payouts.
|
|
391
|
+
- **Anti-abuse limits**, such as a minimum time between billable views from
|
|
392
|
+
the same app.
|
|
393
|
+
- **The kill switch** and the **minimum SDK version**.
|
|
394
|
+
|
|
395
|
+
Ads you show beyond Ethicly's anti-abuse limits still play, but they are not
|
|
396
|
+
billed. Showing ads more often than those limits allow does not earn more.
|
|
397
|
+
|
|
236
398
|
## Test mode
|
|
237
399
|
|
|
238
400
|
`testMode: true` adds `test=1` to the serve request. You get real ads and run
|
|
@@ -278,6 +440,9 @@ createEthicly(options: {
|
|
|
278
440
|
adsEnabled?: boolean; // default true; pass false until entitlement is known (paid tier)
|
|
279
441
|
audio?: 'on' | 'optional' | 'none'; // overrides the server's interstitial.audio for every ad
|
|
280
442
|
loadTimeoutMs?: number; // default 3000: longest loadInterstitial() waits for a download
|
|
443
|
+
frequency?: { maxPerSession?: number; minGapSeconds?: number }; // wins over /config; unset: /config
|
|
444
|
+
houseAds?: boolean; // default true: the dashboard house ad on no fill; false: never
|
|
445
|
+
onHouseAdPress?: (ad: EthiclyAd) => void; // EthiclyInterstitial: a house ad tap goes here instead of its link
|
|
281
446
|
storage?: KeyValueStorage; // AsyncStorage shape; default in memory
|
|
282
447
|
fileCache?: FileCacheAdapter; // download/exists/delete/size/list/cancel; default streams
|
|
283
448
|
openUrl?: (url: string) => unknown;
|
|
@@ -291,9 +456,13 @@ createExpoFileCache(fs, subdirectory = 'ethicly-ads/', logger?): FileCacheAdapte
|
|
|
291
456
|
|
|
292
457
|
interface Ethicly {
|
|
293
458
|
ready: Promise<void>;
|
|
294
|
-
preload(): Promise<InterstitialResult>;
|
|
295
|
-
loadInterstitial(): Promise<InterstitialResult>;
|
|
459
|
+
preload(opts?: { houseAds?: boolean }): Promise<InterstitialResult>;
|
|
460
|
+
loadInterstitial(opts?: { houseAds?: boolean }): Promise<InterstitialResult>; // houseAds false: a house ad is a no fill
|
|
461
|
+
setHouseAds(enabled: boolean): void; // false also drops a preloaded house ad
|
|
296
462
|
canShow(): boolean; // false until the stored frequency state loaded
|
|
463
|
+
nextAdStatus(): NextAdStatus; // allowed, reason, retryAt, shownThisSession, maxPerSession, minGapSeconds
|
|
464
|
+
setFrequency(update: { maxPerSession?: number | null; minGapSeconds?: number | null }): void; // null: back to /config
|
|
465
|
+
getFrequency(): { maxPerSession: number; minGapSeconds: number };
|
|
297
466
|
setAdsEnabled(enabled: boolean): void;
|
|
298
467
|
isAdsEnabled(): boolean;
|
|
299
468
|
getConfig(): EthiclyConfig;
|
|
@@ -310,6 +479,9 @@ interface EthiclyAd {
|
|
|
310
479
|
id: number; ctaLabel: string; destinationUrl: string; skipAfterMs: number;
|
|
311
480
|
audio: 'none' | 'optional' | 'on'; title: string | null; test: boolean;
|
|
312
481
|
servedAt: number; expiresAt: number;
|
|
482
|
+
house: boolean; // the publisher's house ad: unbilled, counted toward the caps
|
|
483
|
+
noFillReason?: NoFillReason; // house ads only: why no paid ad filled
|
|
484
|
+
showSponsorLabel: boolean; // show "Sponsored by Ethicly.ch": false for house ads, else the dashboard setting
|
|
313
485
|
media: { kind: 'video' | 'image'; uri: string; videoUri: string | null; posterUri: string | null;
|
|
314
486
|
durationMs: number | null; mime: string | null; width: number; height: number; cached: boolean };
|
|
315
487
|
}
|
|
@@ -320,7 +492,7 @@ interface Tracker {
|
|
|
320
492
|
complete(): void;
|
|
321
493
|
skipped(positionMs: number): void;
|
|
322
494
|
error(): void;
|
|
323
|
-
clicked(): Promise<string>;
|
|
495
|
+
clicked(opts?: { open?: boolean }): Promise<string>; // the URL; house ads: open false only counts the tap
|
|
324
496
|
closed(): Promise<void>;
|
|
325
497
|
isExpired(): boolean;
|
|
326
498
|
}
|
|
@@ -330,8 +502,10 @@ interface Tracker {
|
|
|
330
502
|
`app_disabled`, `sdk_unsupported`, `interstitial_disabled`, ...) or one of the
|
|
331
503
|
SDK's own: `ads_disabled`, `frequency_capped`, `unknown_key`, `invalid_key`,
|
|
332
504
|
`rate_limited`, `network_error`, `server_error`, `invalid_response`. Show
|
|
333
|
-
your
|
|
334
|
-
user (you called `setAdsEnabled(false)`), so show nothing.
|
|
505
|
+
your own fallback for every reason except `ads_disabled`: that one means a
|
|
506
|
+
paid user (you called `setAdsEnabled(false)`), so show nothing. When the
|
|
507
|
+
dashboard house ad was returned there is no reason: `res.ad.house` is true and
|
|
508
|
+
`res.ad.noFillReason` holds it.
|
|
335
509
|
|
|
336
510
|
An ad whose destination is not an `http:` or `https:` URL (for example
|
|
337
511
|
`tel:`, `intent:`, `javascript:` or an app scheme) is refused as
|
|
@@ -375,9 +549,12 @@ not legal advice; you are responsible for your app's declarations.
|
|
|
375
549
|
- a two-letter country code. The server derives it from the device's IP
|
|
376
550
|
address with its own database (no third party). The IP address itself is
|
|
377
551
|
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
|
|
379
|
-
combined with the ad id, used to cap clicks
|
|
380
|
-
|
|
552
|
+
Ethicly's database or to the ad server's own logs, except as two salted
|
|
553
|
+
hashes used against fraud: one combined with the ad id, used to cap clicks
|
|
554
|
+
per IP and deleted after two days; and one combined with your site and the
|
|
555
|
+
day, used to cap billable views per network and deleted after about two
|
|
556
|
+
hours. Neither identifies a device or links data across apps. Request logs
|
|
557
|
+
kept by Ethicly's hosting platform are outside this
|
|
381
558
|
list.
|
|
382
559
|
|
|
383
560
|
Serve and `/config` requests store nothing per request. The User-Agent header
|
|
@@ -161,6 +161,8 @@ class CreativeCache {
|
|
|
161
161
|
* `allowed()` is checked before every download so setAdsEnabled(false)
|
|
162
162
|
* stops a download that has not started yet; cancel() also stops the one in
|
|
163
163
|
* flight when the adapter supports it.
|
|
164
|
+
* `adId` keys the entry and names the files: house ads pass `house-<id>`
|
|
165
|
+
* because their ids can collide with paid ad ids.
|
|
164
166
|
*/
|
|
165
167
|
ensure(adId, urls, limits, allowed) {
|
|
166
168
|
const run = this.chain.then(() => this.ensureNow(adId, urls, limits, allowed));
|