@ethicly/react-native 0.3.0 → 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 +59 -0
- package/README.md +112 -13
- package/lib/commonjs/core/cache.js +2 -0
- package/lib/commonjs/core/client.js +168 -53
- package/lib/commonjs/core/config.js +4 -1
- package/lib/commonjs/core/houseTracker.js +92 -0
- package/lib/commonjs/react/EthiclyInterstitial.js +23 -4
- package/lib/commonjs/react/useEthiclyInterstitial.js +22 -6
- package/lib/commonjs/version.js +1 -1
- package/lib/module/core/cache.js +2 -0
- package/lib/module/core/client.js +168 -53
- package/lib/module/core/config.js +4 -1
- package/lib/module/core/houseTracker.js +88 -0
- package/lib/module/react/EthiclyInterstitial.js +23 -4
- package/lib/module/react/useEthiclyInterstitial.js +22 -6
- package/lib/module/version.js +1 -1
- package/lib/typescript/core/cache.d.ts +3 -1
- package/lib/typescript/core/client.d.ts +24 -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 +44 -2
- package/lib/typescript/react/EthiclyInterstitial.d.ts +7 -0
- package/lib/typescript/react/useEthiclyInterstitial.d.ts +16 -2
- 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 +186 -55
- package/src/core/config.ts +4 -1
- package/src/core/houseTracker.ts +108 -0
- package/src/core/index.ts +1 -1
- package/src/core/types.ts +44 -2
- package/src/react/EthiclyInterstitial.tsx +26 -4
- package/src/react/useEthiclyInterstitial.ts +38 -8
- package/src/version.ts +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -5,6 +5,65 @@ 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
|
+
|
|
8
67
|
## [0.3.0] - 2026-11-21
|
|
9
68
|
|
|
10
69
|
### Added
|
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
|
|
@@ -154,8 +158,9 @@ It speaks contract v1 of the Ethicly app API. It ships no native code of its own
|
|
|
154
158
|
|
|
155
159
|
5. **Call the tracker from your player.** Play `ad.media.videoUri` (a local
|
|
156
160
|
file when cached, else the remote URL), show `ad.ctaLabel` on the button
|
|
157
|
-
with a small "Sponsored by Ethicly.ch" line under it
|
|
158
|
-
|
|
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),
|
|
159
164
|
allow skipping after `ad.skipAfterMs` (always 8 to 15 seconds: the SDK
|
|
160
165
|
clamps the server's value), play with sound unless `ad.audio` is `none`
|
|
161
166
|
(always muted) or `optional` (start muted), then:
|
|
@@ -210,7 +215,8 @@ The screen is a fullscreen modal: the video fills it, a small "Ad" label sits
|
|
|
210
215
|
top left, a white button shows `ctaLabel` ("Learn more" when the advertiser
|
|
211
216
|
set none), and either `onRemoveAds` (a "Remove ads" link) or
|
|
212
217
|
`renderBelowButton` fills the space under the button, above a small
|
|
213
|
-
"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
|
|
214
220
|
"Test ad" label. Sound follows `ad.audio`, or the screen's `audio` prop when
|
|
215
221
|
you pass one (see "Sound" below).
|
|
216
222
|
|
|
@@ -228,6 +234,85 @@ back, Skip is available at once. Android back closes the ad only once Skip is
|
|
|
228
234
|
available. If the ad expired before it reached the screen, the screen closes
|
|
229
235
|
itself through `onClose` without recording an impression.
|
|
230
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
|
+
|
|
231
316
|
### Sound
|
|
232
317
|
|
|
233
318
|
Ads play with sound by default. You choose, in code:
|
|
@@ -286,15 +371,21 @@ You, the publisher, decide how ads fit your app:
|
|
|
286
371
|
- **When:** which moments in your app call `show()` or `loadInterstitial()`.
|
|
287
372
|
- **Paid users:** `setAdsEnabled(false)` means no serves and no downloads.
|
|
288
373
|
- **Sound:** the `audio` option or prop.
|
|
289
|
-
- **Fallback:**
|
|
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.
|
|
290
381
|
- **Player:** the ready-made screen or your own player with the tracker.
|
|
291
382
|
|
|
292
383
|
Ethicly decides:
|
|
293
384
|
|
|
294
385
|
- **Which ad** is served.
|
|
295
386
|
- **The skip window:** Skip appears after 8 to 15 seconds.
|
|
296
|
-
- **The
|
|
297
|
-
|
|
387
|
+
- **The "Ad" label:** it stays visible on every ad, house ads included, also
|
|
388
|
+
in your own player.
|
|
298
389
|
- **What counts** as a billable view or a billable click.
|
|
299
390
|
- **Billing** and payouts.
|
|
300
391
|
- **Anti-abuse limits**, such as a minimum time between billable views from
|
|
@@ -350,6 +441,8 @@ createEthicly(options: {
|
|
|
350
441
|
audio?: 'on' | 'optional' | 'none'; // overrides the server's interstitial.audio for every ad
|
|
351
442
|
loadTimeoutMs?: number; // default 3000: longest loadInterstitial() waits for a download
|
|
352
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
|
|
353
446
|
storage?: KeyValueStorage; // AsyncStorage shape; default in memory
|
|
354
447
|
fileCache?: FileCacheAdapter; // download/exists/delete/size/list/cancel; default streams
|
|
355
448
|
openUrl?: (url: string) => unknown;
|
|
@@ -363,8 +456,9 @@ createExpoFileCache(fs, subdirectory = 'ethicly-ads/', logger?): FileCacheAdapte
|
|
|
363
456
|
|
|
364
457
|
interface Ethicly {
|
|
365
458
|
ready: Promise<void>;
|
|
366
|
-
preload(): Promise<InterstitialResult>;
|
|
367
|
-
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
|
|
368
462
|
canShow(): boolean; // false until the stored frequency state loaded
|
|
369
463
|
nextAdStatus(): NextAdStatus; // allowed, reason, retryAt, shownThisSession, maxPerSession, minGapSeconds
|
|
370
464
|
setFrequency(update: { maxPerSession?: number | null; minGapSeconds?: number | null }): void; // null: back to /config
|
|
@@ -385,6 +479,9 @@ interface EthiclyAd {
|
|
|
385
479
|
id: number; ctaLabel: string; destinationUrl: string; skipAfterMs: number;
|
|
386
480
|
audio: 'none' | 'optional' | 'on'; title: string | null; test: boolean;
|
|
387
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
|
|
388
485
|
media: { kind: 'video' | 'image'; uri: string; videoUri: string | null; posterUri: string | null;
|
|
389
486
|
durationMs: number | null; mime: string | null; width: number; height: number; cached: boolean };
|
|
390
487
|
}
|
|
@@ -395,7 +492,7 @@ interface Tracker {
|
|
|
395
492
|
complete(): void;
|
|
396
493
|
skipped(positionMs: number): void;
|
|
397
494
|
error(): void;
|
|
398
|
-
clicked(): Promise<string>;
|
|
495
|
+
clicked(opts?: { open?: boolean }): Promise<string>; // the URL; house ads: open false only counts the tap
|
|
399
496
|
closed(): Promise<void>;
|
|
400
497
|
isExpired(): boolean;
|
|
401
498
|
}
|
|
@@ -405,8 +502,10 @@ interface Tracker {
|
|
|
405
502
|
`app_disabled`, `sdk_unsupported`, `interstitial_disabled`, ...) or one of the
|
|
406
503
|
SDK's own: `ads_disabled`, `frequency_capped`, `unknown_key`, `invalid_key`,
|
|
407
504
|
`rate_limited`, `network_error`, `server_error`, `invalid_response`. Show
|
|
408
|
-
your
|
|
409
|
-
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.
|
|
410
509
|
|
|
411
510
|
An ad whose destination is not an `http:` or `https:` URL (for example
|
|
412
511
|
`tel:`, `intent:`, `javascript:` or an app scheme) is refused as
|
|
@@ -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));
|
|
@@ -10,6 +10,7 @@ const click_1 = require("./click");
|
|
|
10
10
|
const config_1 = require("./config");
|
|
11
11
|
const http_1 = require("./http");
|
|
12
12
|
const outbox_1 = require("./outbox");
|
|
13
|
+
const houseTracker_1 = require("./houseTracker");
|
|
13
14
|
const tracker_1 = require("./tracker");
|
|
14
15
|
const version_1 = require("../version");
|
|
15
16
|
/** How long loadInterstitial() waits for a creative download by default. */
|
|
@@ -92,6 +93,7 @@ class EthiclyClient {
|
|
|
92
93
|
this.cache = new cache_1.CreativeCache(o.fileCache || (0, adapters_1.createMemoryFileCache)(), this.storage, 'ethicly:v1:cache', this.now, this.log, o.fileCache ? (url) => this.contentLength(url) : undefined);
|
|
93
94
|
this.config = (0, config_1.defaultConfig)(this.bundled);
|
|
94
95
|
this.adsOn = o.adsEnabled !== false;
|
|
96
|
+
this.houseAdsOn = o.houseAds !== false;
|
|
95
97
|
this.audio = audioPolicy(o.audio);
|
|
96
98
|
if (o.audio !== undefined && !this.audio)
|
|
97
99
|
this.log.warn(`audio must be 'on', 'optional' or 'none': using the server's value`);
|
|
@@ -403,6 +405,25 @@ class EthiclyClient {
|
|
|
403
405
|
isAdsEnabled() {
|
|
404
406
|
return this.adsOn;
|
|
405
407
|
}
|
|
408
|
+
setHouseAds(enabled) {
|
|
409
|
+
var _a, _b;
|
|
410
|
+
this.houseAdsOn = !!enabled;
|
|
411
|
+
if (this.houseAdsOn)
|
|
412
|
+
return;
|
|
413
|
+
if ((_a = this.preloaded) === null || _a === void 0 ? void 0 : _a.result.ad.house)
|
|
414
|
+
this.preloaded = null;
|
|
415
|
+
if ((_b = this.pendingServed) === null || _b === void 0 ? void 0 : _b.house)
|
|
416
|
+
this.pendingServed = null;
|
|
417
|
+
}
|
|
418
|
+
/**
|
|
419
|
+
* Whether this call takes a house ad: the call's option, else the client's,
|
|
420
|
+
* and never while the dashboard switch (/config interstitial.house_ads) is off.
|
|
421
|
+
*/
|
|
422
|
+
wantHouse(opts) {
|
|
423
|
+
if (!this.config.interstitial.house_ads)
|
|
424
|
+
return false;
|
|
425
|
+
return typeof (opts === null || opts === void 0 ? void 0 : opts.houseAds) === 'boolean' ? opts.houseAds : this.houseAdsOn;
|
|
426
|
+
}
|
|
406
427
|
// ------------------------------------------------------------- serve
|
|
407
428
|
blockedReason() {
|
|
408
429
|
if (this.invalidKey)
|
|
@@ -422,14 +443,23 @@ class EthiclyClient {
|
|
|
422
443
|
this.log.info(`no ad: ${reason}`);
|
|
423
444
|
return { ad: null, tracker: null, reason };
|
|
424
445
|
}
|
|
425
|
-
/**
|
|
426
|
-
|
|
446
|
+
/**
|
|
447
|
+
* The served ad waiting for its download, or a new serve. One serve at a
|
|
448
|
+
* time. A house ad is a no fill for a caller that does not take one.
|
|
449
|
+
*/
|
|
450
|
+
async serveFor(houseAds) {
|
|
451
|
+
const out = await this.serveOnce(houseAds);
|
|
452
|
+
if (out.served && out.served.house && !houseAds)
|
|
453
|
+
return { noFill: this.noFill(out.served.noFillReason || 'no_matching_ad') };
|
|
454
|
+
return out;
|
|
455
|
+
}
|
|
456
|
+
serveOnce(houseAds) {
|
|
427
457
|
const p = this.pendingServed;
|
|
428
458
|
if (p && !p.consumed && this.now() < p.expiresAt)
|
|
429
459
|
return Promise.resolve({ served: p });
|
|
430
460
|
this.pendingServed = null;
|
|
431
461
|
if (!this.serveInflight) {
|
|
432
|
-
this.serveInflight = this.serve()
|
|
462
|
+
this.serveInflight = this.serve(houseAds)
|
|
433
463
|
.then((out) => {
|
|
434
464
|
if (out.served)
|
|
435
465
|
this.pendingServed = out.served;
|
|
@@ -445,16 +475,23 @@ class EthiclyClient {
|
|
|
445
475
|
s.result = s.build(uris);
|
|
446
476
|
return s.result;
|
|
447
477
|
}
|
|
448
|
-
async preload() {
|
|
478
|
+
async preload(opts) {
|
|
449
479
|
try {
|
|
450
480
|
if (!this.adsOn)
|
|
451
481
|
return this.noFill('ads_disabled');
|
|
452
|
-
|
|
453
|
-
|
|
454
|
-
|
|
482
|
+
const house = this.wantHouse(opts);
|
|
483
|
+
const p = this.preloaded;
|
|
484
|
+
if (p && !p.result.tracker.isExpired()) {
|
|
485
|
+
if (house || !p.result.ad.house)
|
|
486
|
+
return p.result;
|
|
487
|
+
// A preloaded house ad this call does not take: kept, and a paid ad may replace it.
|
|
488
|
+
}
|
|
489
|
+
else {
|
|
490
|
+
this.preloaded = null;
|
|
491
|
+
}
|
|
455
492
|
if (this.shownCount >= this.getFrequency().maxPerSession)
|
|
456
493
|
return this.noFill('frequency_capped');
|
|
457
|
-
const out = await this.
|
|
494
|
+
const out = await this.serveFor(house);
|
|
458
495
|
if (!out.served)
|
|
459
496
|
return out.noFill;
|
|
460
497
|
const s = out.served;
|
|
@@ -475,7 +512,7 @@ class EthiclyClient {
|
|
|
475
512
|
return this.noFill('network_error');
|
|
476
513
|
}
|
|
477
514
|
}
|
|
478
|
-
async loadInterstitial() {
|
|
515
|
+
async loadInterstitial(opts) {
|
|
479
516
|
var _a;
|
|
480
517
|
try {
|
|
481
518
|
await this.ready;
|
|
@@ -488,17 +525,45 @@ class EthiclyClient {
|
|
|
488
525
|
return this.noFill(blocked);
|
|
489
526
|
if (!this.canShow())
|
|
490
527
|
return this.noFill('frequency_capped');
|
|
528
|
+
const house = this.wantHouse(opts);
|
|
491
529
|
const pre = this.preloaded;
|
|
492
530
|
this.preloaded = null;
|
|
493
|
-
|
|
494
|
-
|
|
495
|
-
|
|
496
|
-
|
|
497
|
-
|
|
531
|
+
const valid = pre && !pre.result.tracker.isExpired() ? pre : null;
|
|
532
|
+
if (valid && !valid.result.ad.house)
|
|
533
|
+
return valid.result;
|
|
534
|
+
// A preloaded house ad this call does not take stays for a later one.
|
|
535
|
+
if (valid && !house)
|
|
536
|
+
this.preloaded = valid;
|
|
537
|
+
const fallback = valid && house ? valid : null;
|
|
538
|
+
const started = this.now();
|
|
539
|
+
let out;
|
|
540
|
+
if (fallback) {
|
|
541
|
+
// A preloaded house ad never blocks a paid one: ask for a paid ad
|
|
542
|
+
// first, within the load budget, and show the house ad only without one.
|
|
543
|
+
out = await this.within(this.serveFor(false), this.loadTimeoutMs);
|
|
544
|
+
if (!out || !out.served) {
|
|
545
|
+
if (!this.adsOn)
|
|
546
|
+
return this.noFill('ads_disabled');
|
|
547
|
+
// The paid-first serve may have hit the kill switch or the minimum SDK
|
|
548
|
+
// version: the server said stop, so the preloaded house ad must not show.
|
|
549
|
+
const nowBlocked = this.blockedReason();
|
|
550
|
+
if (nowBlocked)
|
|
551
|
+
return this.noFill(nowBlocked);
|
|
552
|
+
// The serve may still answer: it then waits as pendingServed for next time.
|
|
553
|
+
this.lastNoFillReason = null;
|
|
554
|
+
return fallback.result;
|
|
555
|
+
}
|
|
556
|
+
}
|
|
557
|
+
else {
|
|
558
|
+
out = await this.serveFor(house);
|
|
559
|
+
if (!out.served)
|
|
560
|
+
return out.noFill;
|
|
561
|
+
}
|
|
498
562
|
const s = out.served;
|
|
499
563
|
// The user is waiting: give the download a short budget, then stream the
|
|
500
564
|
// remote file. The download carries on in the background for next time.
|
|
501
|
-
const
|
|
565
|
+
const budget = Math.max(0, this.loadTimeoutMs - (this.now() - started));
|
|
566
|
+
const cached = await this.within(s.download, budget);
|
|
502
567
|
if (!this.adsOn)
|
|
503
568
|
return this.noFill('ads_disabled');
|
|
504
569
|
if (!cached)
|
|
@@ -510,6 +575,9 @@ class EthiclyClient {
|
|
|
510
575
|
// A preload that finished meanwhile may have stored this same ad.
|
|
511
576
|
if (((_a = this.preloaded) === null || _a === void 0 ? void 0 : _a.result) === r)
|
|
512
577
|
this.preloaded = null;
|
|
578
|
+
// The house ad that was not needed stays preloaded for next time.
|
|
579
|
+
if (fallback && !this.preloaded)
|
|
580
|
+
this.preloaded = fallback;
|
|
513
581
|
return r;
|
|
514
582
|
}
|
|
515
583
|
catch (e) {
|
|
@@ -524,8 +592,7 @@ class EthiclyClient {
|
|
|
524
592
|
return Promise.race([p, timeout]).finally(() => { if (timer)
|
|
525
593
|
clearTimeout(timer); });
|
|
526
594
|
}
|
|
527
|
-
async serve() {
|
|
528
|
-
var _a, _b;
|
|
595
|
+
async serve(houseAds) {
|
|
529
596
|
const noFill = (reason) => ({ noFill: this.noFill(reason) });
|
|
530
597
|
await this.ready;
|
|
531
598
|
if (this.configStale())
|
|
@@ -535,6 +602,8 @@ class EthiclyClient {
|
|
|
535
602
|
return noFill(blocked);
|
|
536
603
|
if (this.gate.waitMs('serve') > 0)
|
|
537
604
|
return noFill('rate_limited');
|
|
605
|
+
// The dashboard switch, read from the config just refreshed.
|
|
606
|
+
const askHouse = houseAds && this.config.interstitial.house_ads;
|
|
538
607
|
const q = [
|
|
539
608
|
`key=${encodeURIComponent(this.o.apiKey)}`,
|
|
540
609
|
'format=interstitial',
|
|
@@ -544,6 +613,9 @@ class EthiclyClient {
|
|
|
544
613
|
];
|
|
545
614
|
if (this.testMode)
|
|
546
615
|
q.push('test=1');
|
|
616
|
+
// The SDK counts a house ad itself, on show (/fallback-impression): the server must not count it at pick time.
|
|
617
|
+
if (askHouse)
|
|
618
|
+
q.push('house_ads=1', 'client_fallback_tracking=1');
|
|
547
619
|
const res = await (0, http_1.httpRequest)(this.fetchFn, `${this.serveBase()}?${q.join('&')}`, {
|
|
548
620
|
headers: this.headers(), timeoutMs: SERVE_TIMEOUT_MS,
|
|
549
621
|
});
|
|
@@ -562,52 +634,107 @@ class EthiclyClient {
|
|
|
562
634
|
if (res.status !== 200 || !res.body || typeof res.body !== 'object')
|
|
563
635
|
return noFill('server_error');
|
|
564
636
|
const body = res.body;
|
|
637
|
+
const ttlS = typeof body.token_ttl_s === 'number' && body.token_ttl_s > 0 ? body.token_ttl_s : DEFAULT_TTL_S;
|
|
565
638
|
if (!body.ad) {
|
|
566
639
|
const reason = typeof body.reason === 'string' && body.reason ? body.reason : 'no_matching_ad';
|
|
567
640
|
if (reason === 'app_disabled')
|
|
568
641
|
this.appDisabled = true;
|
|
569
642
|
if (reason === 'sdk_unsupported')
|
|
570
643
|
this.sdkUnsupported = true;
|
|
644
|
+
const h = body.house_ad;
|
|
645
|
+
// A house ad only when asked for, and never past a kill switch.
|
|
646
|
+
if (askHouse && h && typeof h === 'object' && reason !== 'app_disabled' && reason !== 'sdk_unsupported') {
|
|
647
|
+
if (!this.validAd(h, 'house ad', body.request_id))
|
|
648
|
+
return noFill(reason);
|
|
649
|
+
if (!this.adsOn)
|
|
650
|
+
return noFill('ads_disabled');
|
|
651
|
+
const fallbackId = h.id;
|
|
652
|
+
const test = this.testMode || h.test === true || body.test === true;
|
|
653
|
+
this.log.info(`no paid ad (${reason}): house ad ${fallbackId}`);
|
|
654
|
+
return {
|
|
655
|
+
served: this.makeServed({
|
|
656
|
+
wire: h, cacheKey: `house-${fallbackId}`, servedAt, ttlS, test, house: true, noFillReason: reason,
|
|
657
|
+
tracker: (ad) => new houseTracker_1.HouseTracker({
|
|
658
|
+
ctx: this.beaconCtx(), ad, fallbackId, test, openUrl: this.o.openUrl, onShown: () => this.onShown(),
|
|
659
|
+
onPress: this.o.onHouseAdPress,
|
|
660
|
+
}),
|
|
661
|
+
}),
|
|
662
|
+
};
|
|
663
|
+
}
|
|
571
664
|
return noFill(reason);
|
|
572
665
|
}
|
|
573
666
|
const ad = body.ad;
|
|
667
|
+
if (!this.validAd(ad, 'ad', body.request_id))
|
|
668
|
+
return noFill('invalid_response');
|
|
669
|
+
if (body.test === true)
|
|
670
|
+
this.log.info(`test serve: ad ${ad.id} on site ${body.publisher_site_id}`);
|
|
671
|
+
if (!this.adsOn)
|
|
672
|
+
return noFill('ads_disabled');
|
|
673
|
+
return {
|
|
674
|
+
served: this.makeServed({
|
|
675
|
+
wire: ad, cacheKey: ad.id, servedAt, ttlS, test: body.test === true, house: false,
|
|
676
|
+
tracker: (result) => new tracker_1.InterstitialTracker({
|
|
677
|
+
ctx: this.beaconCtx(),
|
|
678
|
+
ad: result,
|
|
679
|
+
serve: {
|
|
680
|
+
publisherSiteId: typeof body.publisher_site_id === 'number' && body.publisher_site_id > 0 ? body.publisher_site_id : null,
|
|
681
|
+
countryCode: typeof body.country_code === 'string' ? body.country_code : null,
|
|
682
|
+
impressionToken: typeof body.impression_token === 'string' ? body.impression_token : null,
|
|
683
|
+
},
|
|
684
|
+
viewableAfterMs: this.config.beacon.viewable_after_ms,
|
|
685
|
+
flushIntervalS: this.config.beacon.flush_interval_s,
|
|
686
|
+
platform: this.o.platform,
|
|
687
|
+
sdkVersion: version_1.SDK_VERSION,
|
|
688
|
+
appVersion: this.o.appVersion,
|
|
689
|
+
openUrl: this.o.openUrl,
|
|
690
|
+
onShown: () => this.onShown(),
|
|
691
|
+
outbox: this.outbox,
|
|
692
|
+
}),
|
|
693
|
+
}),
|
|
694
|
+
};
|
|
695
|
+
}
|
|
696
|
+
/** A paid or house ad has a numeric id, media and an http(s) destination. */
|
|
697
|
+
validAd(ad, what, requestId) {
|
|
574
698
|
const m = ad.media;
|
|
575
699
|
if (typeof ad.id !== 'number' || !m || typeof m.url !== 'string' || !m.url || typeof ad.destination_url !== 'string') {
|
|
576
|
-
this.log.warn(
|
|
577
|
-
return
|
|
700
|
+
this.log.warn(`serve answered a ${what} without media or destination`, requestId);
|
|
701
|
+
return false;
|
|
578
702
|
}
|
|
579
703
|
if (!(0, click_1.isWebUrl)(ad.destination_url)) {
|
|
580
704
|
// Only web pages are opened: never tel:, intent:, javascript: or an app scheme.
|
|
581
705
|
if (!this.badDestinationLogged) {
|
|
582
706
|
this.badDestinationLogged = true;
|
|
583
|
-
this.log.error(
|
|
707
|
+
this.log.error(`${what} ${ad.id}: destination is not an http(s) URL, ad skipped`, requestId);
|
|
584
708
|
}
|
|
585
|
-
return
|
|
709
|
+
return false;
|
|
586
710
|
}
|
|
587
|
-
|
|
588
|
-
|
|
589
|
-
|
|
590
|
-
|
|
711
|
+
return true;
|
|
712
|
+
}
|
|
713
|
+
/** Start the creative download; the ad and tracker are built later by preload() or loadInterstitial(). */
|
|
714
|
+
makeServed(a) {
|
|
715
|
+
var _a, _b;
|
|
716
|
+
const ad = a.wire;
|
|
717
|
+
// validAd() checked these.
|
|
718
|
+
const m = ad.media;
|
|
719
|
+
const mediaUrl = m.url;
|
|
720
|
+
const destinationUrl = ad.destination_url;
|
|
591
721
|
const kind = m.kind === 'video' ? 'video' : 'image';
|
|
592
722
|
const poster = kind === 'video' && typeof m.poster_url === 'string' && m.poster_url ? m.poster_url : null;
|
|
593
723
|
const pf = this.config.prefetch;
|
|
594
724
|
// Started now, awaited by preload() in full and by loadInterstitial() within loadTimeoutMs.
|
|
595
|
-
const download = this.cache.ensure(
|
|
596
|
-
const
|
|
597
|
-
const expiresAt = servedAt + ttlS * 1000;
|
|
598
|
-
const adId = ad.id;
|
|
599
|
-
const mediaUrl = m.url;
|
|
600
|
-
const destinationUrl = ad.destination_url;
|
|
725
|
+
const download = this.cache.ensure(a.cacheKey, poster ? [mediaUrl, poster] : [mediaUrl], { maxCreatives: pf.max_cached_creatives, maxBytes: pf.max_cache_mb * 1024 * 1024 }, () => this.adsOn).catch(() => ({ uris: {} }));
|
|
726
|
+
const expiresAt = a.servedAt + a.ttlS * 1000;
|
|
601
727
|
const label = typeof ad.cta_label === 'string' ? ad.cta_label.trim() : '';
|
|
602
728
|
const posInt = (v, d) => (typeof v === 'number' && v > 0 ? Math.round(v) : d);
|
|
603
729
|
// The ad's value wins over /config, kept within the same 8 to 15 s range.
|
|
604
730
|
const skipAfterMs = (_a = (0, config_1.clampSkipAfterMs)(ad.skip_after_ms)) !== null && _a !== void 0 ? _a : this.config.interstitial.skip_after_ms;
|
|
605
731
|
// The app's choice (options.audio) wins over the server's interstitial.audio.
|
|
606
732
|
const audio = (_b = this.audio) !== null && _b !== void 0 ? _b : this.config.interstitial.audio;
|
|
733
|
+
const showSponsorLabel = !a.house && this.config.interstitial.sponsor_label;
|
|
607
734
|
const build = (uris) => {
|
|
608
735
|
const uri = uris[mediaUrl] || mediaUrl;
|
|
609
736
|
const result = {
|
|
610
|
-
id:
|
|
737
|
+
id: ad.id,
|
|
611
738
|
ctaLabel: label || 'Learn more',
|
|
612
739
|
destinationUrl,
|
|
613
740
|
skipAfterMs,
|
|
@@ -624,30 +751,18 @@ class EthiclyClient {
|
|
|
624
751
|
},
|
|
625
752
|
audio,
|
|
626
753
|
title: typeof ad.title === 'string' ? ad.title : null,
|
|
627
|
-
test:
|
|
628
|
-
servedAt,
|
|
754
|
+
test: a.test,
|
|
755
|
+
servedAt: a.servedAt,
|
|
629
756
|
expiresAt,
|
|
757
|
+
house: a.house,
|
|
758
|
+
showSponsorLabel,
|
|
630
759
|
};
|
|
631
|
-
|
|
632
|
-
|
|
633
|
-
|
|
634
|
-
serve: {
|
|
635
|
-
publisherSiteId: typeof body.publisher_site_id === 'number' && body.publisher_site_id > 0 ? body.publisher_site_id : null,
|
|
636
|
-
countryCode: typeof body.country_code === 'string' ? body.country_code : null,
|
|
637
|
-
impressionToken: typeof body.impression_token === 'string' ? body.impression_token : null,
|
|
638
|
-
},
|
|
639
|
-
viewableAfterMs: this.config.beacon.viewable_after_ms,
|
|
640
|
-
flushIntervalS: this.config.beacon.flush_interval_s,
|
|
641
|
-
platform: this.o.platform,
|
|
642
|
-
sdkVersion: version_1.SDK_VERSION,
|
|
643
|
-
appVersion: this.o.appVersion,
|
|
644
|
-
openUrl: this.o.openUrl,
|
|
645
|
-
onShown: () => this.onShown(),
|
|
646
|
-
outbox: this.outbox,
|
|
647
|
-
});
|
|
648
|
-
return { ad: result, tracker };
|
|
760
|
+
if (a.house)
|
|
761
|
+
result.noFillReason = a.noFillReason;
|
|
762
|
+
return { ad: result, tracker: a.tracker(result) };
|
|
649
763
|
};
|
|
764
|
+
// An ad will show, so there is no fill reason, even for a house ad (see ad.noFillReason).
|
|
650
765
|
this.lastNoFillReason = null;
|
|
651
|
-
return {
|
|
766
|
+
return { build, download, expiresAt, consumed: false, result: null, house: a.house, noFillReason: a.noFillReason };
|
|
652
767
|
}
|
|
653
768
|
}
|
|
@@ -31,7 +31,7 @@ function defaultConfig(serveBase) {
|
|
|
31
31
|
enabled: true,
|
|
32
32
|
min_sdk: { ios: '0.0.0', android: '0.0.0' },
|
|
33
33
|
formats: ['interstitial', '300x250'],
|
|
34
|
-
interstitial: { skip_after_ms: 8000, max_per_session: 3, min_gap_s: 120, audio: 'on' },
|
|
34
|
+
interstitial: { skip_after_ms: 8000, max_per_session: 3, min_gap_s: 120, audio: 'on', sponsor_label: true, house_ads: true },
|
|
35
35
|
prefetch: { max_cached_creatives: 3, max_cache_mb: 20 },
|
|
36
36
|
beacon: { viewable_after_ms: 2000, flush_interval_s: 30 },
|
|
37
37
|
endpoints: { serve: serveBase },
|
|
@@ -80,6 +80,9 @@ function parseConfig(body, bundledBase) {
|
|
|
80
80
|
max_per_session: num(it.max_per_session, d.interstitial.max_per_session, 0, 1000),
|
|
81
81
|
min_gap_s: num(it.min_gap_s, d.interstitial.min_gap_s, 0, 86400),
|
|
82
82
|
audio,
|
|
83
|
+
// Only an explicit false hides the line.
|
|
84
|
+
sponsor_label: it.sponsor_label !== false,
|
|
85
|
+
house_ads: it.house_ads !== false,
|
|
83
86
|
},
|
|
84
87
|
prefetch: {
|
|
85
88
|
max_cached_creatives: num(pf.max_cached_creatives, d.prefetch.max_cached_creatives, 0, 100),
|