@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 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 house ad
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 (required, as on the
158
- ready-made screen),
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. A test-mode ad (`ad.test`) also shows a small
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:** what to show when no Ethicly ad is available (your house ad).
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 ad labels:** the "Ad" label and the "Sponsored by Ethicly.ch" line
297
- under the button stay visible, also in your own player.
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>; // the URL that was opened
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 house ad for every reason except `ads_disabled`: that one means a paid
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
- /** The served ad waiting for its download, or a new serve. One serve at a time. */
426
- serveOnce() {
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
- if (this.preloaded && !this.preloaded.result.tracker.isExpired())
453
- return this.preloaded.result;
454
- this.preloaded = null;
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.serveOnce();
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
- if (pre && !pre.result.tracker.isExpired())
494
- return pre.result;
495
- const out = await this.serveOnce();
496
- if (!out.served)
497
- return out.noFill;
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 cached = await this.within(s.download, this.loadTimeoutMs);
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('serve answered an ad without media or destination', body.request_id);
577
- return noFill('invalid_response');
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(`ad ${ad.id}: destination is not an http(s) URL, ad skipped`, body.request_id);
707
+ this.log.error(`${what} ${ad.id}: destination is not an http(s) URL, ad skipped`, requestId);
584
708
  }
585
- return noFill('invalid_response');
709
+ return false;
586
710
  }
587
- if (body.test === true)
588
- this.log.info(`test serve: ad ${ad.id} on site ${body.publisher_site_id}`);
589
- if (!this.adsOn)
590
- return noFill('ads_disabled');
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(ad.id, poster ? [m.url, poster] : [m.url], { maxCreatives: pf.max_cached_creatives, maxBytes: pf.max_cache_mb * 1024 * 1024 }, () => this.adsOn).catch(() => ({ uris: {} }));
596
- const ttlS = typeof body.token_ttl_s === 'number' && body.token_ttl_s > 0 ? body.token_ttl_s : DEFAULT_TTL_S;
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: adId,
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: body.test === true,
628
- servedAt,
754
+ test: a.test,
755
+ servedAt: a.servedAt,
629
756
  expiresAt,
757
+ house: a.house,
758
+ showSponsorLabel,
630
759
  };
631
- const tracker = new tracker_1.InterstitialTracker({
632
- ctx: this.beaconCtx(),
633
- ad: result,
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 { served: { build, download, expiresAt, consumed: false, result: null } };
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),