@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.
@@ -0,0 +1,92 @@
1
+ "use strict";
2
+ // The tracker for a house ad: the publisher's own creative, shown when no paid
3
+ // ad fills. Nothing is billed, so there is no /impression, /viewable, video
4
+ // event or click token: only the unbilled /fallback-impression and
5
+ // /fallback-click counters, fire-and-forget, and none of them in test mode.
6
+ Object.defineProperty(exports, "__esModule", { value: true });
7
+ exports.HouseTracker = void 0;
8
+ const beacons_1 = require("./beacons");
9
+ const click_1 = require("./click");
10
+ const http_1 = require("./http");
11
+ class HouseTracker {
12
+ constructor(d) {
13
+ this.d = d;
14
+ this.shownOnce = false;
15
+ this.clickedOnce = false;
16
+ this.pending = new Set();
17
+ this.houseAdPress = d.onPress;
18
+ }
19
+ /** Resolves when every counter in flight has settled. For tests. */
20
+ async settle() {
21
+ while (this.pending.size)
22
+ await Promise.all(Array.from(this.pending)).catch(() => undefined);
23
+ }
24
+ isExpired() {
25
+ return this.d.ctx.now() >= this.d.ad.expiresAt;
26
+ }
27
+ /**
28
+ * One POST to a house-ad counter, never retried, never awaited by the
29
+ * caller. The answer (200, 400 or 429) changes nothing. Never rejects.
30
+ */
31
+ send(route) {
32
+ const { ctx } = this.d;
33
+ if (this.d.test)
34
+ return;
35
+ const p = (0, http_1.httpRequest)(ctx.fetch, `${ctx.serveBase()}/${route}`, {
36
+ method: 'POST', headers: ctx.headers(), body: { fallback_id: this.d.fallbackId }, timeoutMs: beacons_1.BEACON_TIMEOUT_MS,
37
+ }).then((res) => {
38
+ if (res.status !== 200)
39
+ ctx.log.debug(`/${route} answered ${res.status || 'nothing'}`);
40
+ }).catch((e) => ctx.log.debug(`/${route} failed`, e));
41
+ this.pending.add(p);
42
+ p.finally(() => this.pending.delete(p)).catch(() => undefined);
43
+ }
44
+ shown() {
45
+ if (this.shownOnce)
46
+ return Promise.resolve();
47
+ this.shownOnce = true;
48
+ if (this.isExpired()) {
49
+ this.d.ctx.log.error(`house ad ${this.d.fallbackId} expired before it was shown; load a new one`);
50
+ return Promise.resolve();
51
+ }
52
+ try {
53
+ this.d.onShown();
54
+ }
55
+ catch { /* never throw */ }
56
+ this.send('fallback-impression');
57
+ return Promise.resolve();
58
+ }
59
+ progress(_positionMs, _opts) { }
60
+ complete() { }
61
+ skipped(_positionMs) { }
62
+ error() { }
63
+ /**
64
+ * Counts the tap once (fire-and-forget) and opens the destination right
65
+ * away. `{ open: false }` only counts it: the app shows its own screen.
66
+ */
67
+ async clicked(opts) {
68
+ const url = this.d.ad.destinationUrl;
69
+ if (!this.clickedOnce) {
70
+ this.clickedOnce = true;
71
+ this.send('fallback-click');
72
+ }
73
+ if ((opts === null || opts === void 0 ? void 0 : opts.open) === false)
74
+ return url;
75
+ if (!(0, click_1.isWebUrl)(url)) {
76
+ this.d.ctx.log.error(`house ad ${this.d.fallbackId}: destination is not an http(s) URL, not opened`);
77
+ return url;
78
+ }
79
+ try {
80
+ if (this.d.openUrl)
81
+ await this.d.openUrl(url);
82
+ else
83
+ this.d.ctx.log.warn('no openUrl adapter: the host must open the returned URL');
84
+ }
85
+ catch (e) {
86
+ this.d.ctx.log.error('openUrl failed', e);
87
+ }
88
+ return url;
89
+ }
90
+ async closed() { }
91
+ }
92
+ exports.HouseTracker = HouseTracker;
@@ -29,7 +29,9 @@ const jsx_runtime_1 = require("react/jsx-runtime");
29
29
  // Optional ready-made fullscreen screen. Needs expo-video (Expo SDK 52+).
30
30
  // Layout follows a typical in-app video player: 9:16 video, a skip control that counts
31
31
  // down then reads "Skip Ad", a white call-to-action button, an optional
32
- // "Remove ads" slot and a small "Sponsored by Ethicly.ch" line under it.
32
+ // "Remove ads" slot and a small "Sponsored by Ethicly.ch" line under it. The
33
+ // line follows ad.showSponsorLabel: hidden for house ads, and for paid ads when
34
+ // the publisher switched it off in the dashboard.
33
35
  // Video starts with sound unless the effective audio (the `audio` prop, else
34
36
  // ad.audio: createEthicly's `audio` option, else /config) is 'none' or 'optional'.
35
37
  // The controls keep clear of the notch, status bar and home indicator: see
@@ -123,7 +125,7 @@ function useAppActive() {
123
125
  }, []);
124
126
  return active;
125
127
  }
126
- function InterstitialBody({ ad, tracker, onClose, onRemoveAds, removeAdsLabel, renderBelowButton, skipStyle, skipTextStyle, insets, backRef, audio: audioProp, }) {
128
+ function InterstitialBody({ ad, tracker, onClose, onRemoveAds, removeAdsLabel, onHouseAdPress, renderBelowButton, skipStyle, skipTextStyle, insets, backRef, audio: audioProp, }) {
127
129
  const audio = effectiveAudio(audioProp, ad);
128
130
  const safe = useSafeInsets(insets);
129
131
  const isVideo = ad.media.kind === 'video' && !!ad.media.videoUri;
@@ -252,13 +254,30 @@ function InterstitialBody({ ad, tracker, onClose, onRemoveAds, removeAdsLabel, r
252
254
  onClose();
253
255
  }, [ended, failed, isVideo, onClose, tracker]);
254
256
  const onCta = (0, react_1.useCallback)(() => {
257
+ // A house ad the app routes to its own screen: count the tap, close the
258
+ // ad the normal way, then hand over. Never for a paid ad.
259
+ const housePress = ad.house
260
+ ? onHouseAdPress || tracker.houseAdPress
261
+ : undefined;
262
+ if (housePress) {
263
+ // A second tap before the screen unmounts must not run the handler twice.
264
+ if (closedRef.current)
265
+ return;
266
+ void tracker.clicked({ open: false });
267
+ close();
268
+ try {
269
+ housePress(ad);
270
+ }
271
+ catch { /* the app's handler must not break the screen */ }
272
+ return;
273
+ }
255
274
  if (isVideo)
256
275
  player.pause();
257
276
  // Once the user has visited the advertiser, they can always close the ad
258
277
  // when they come back.
259
278
  setClicked(true);
260
279
  void tracker.clicked();
261
- }, [isVideo, player, tracker]);
280
+ }, [ad, close, isVideo, onHouseAdPress, player, tracker]);
262
281
  const toggleSound = (0, react_1.useCallback)(() => {
263
282
  setMuted((m) => {
264
283
  player.muted = !m;
@@ -270,7 +289,7 @@ function InterstitialBody({ ad, tracker, onClose, onRemoveAds, removeAdsLabel, r
270
289
  backRef.current = canSkip ? close : null;
271
290
  return ((0, jsx_runtime_1.jsxs)(react_native_1.View, { style: styles.root, children: [isVideo ? ((0, jsx_runtime_1.jsxs)(jsx_runtime_1.Fragment, { children: [ad.media.posterUri ? (0, jsx_runtime_1.jsx)(react_native_1.Image, { source: { uri: ad.media.posterUri }, style: react_native_1.StyleSheet.absoluteFill, resizeMode: "cover" }) : null, (0, jsx_runtime_1.jsx)(expo_video_1.VideoView, { player: player, style: react_native_1.StyleSheet.absoluteFill, contentFit: "cover", nativeControls: false, allowsPictureInPicture: false })] })) : ((0, jsx_runtime_1.jsx)(react_native_1.Image, { source: { uri: ad.media.uri }, style: react_native_1.StyleSheet.absoluteFill, resizeMode: "cover", onLoad: onImageLoad, onError: onImageError })), (0, jsx_runtime_1.jsxs)(react_native_1.View, { style: [styles.topRow, { top: Math.max(safe.top + TOP_GAP, MIN_TOP), left: safe.left + SIDE_GAP_TOP, right: safe.right + SIDE_GAP_TOP }], pointerEvents: "box-none", children: [(0, jsx_runtime_1.jsxs)(react_native_1.View, { style: styles.leftGroup, children: [(0, jsx_runtime_1.jsx)(react_native_1.Text, { style: styles.adLabel, accessibilityRole: "text", children: "Ad" }), ad.test ? (0, jsx_runtime_1.jsx)(react_native_1.Text, { style: [styles.adLabel, styles.testLabel], accessibilityRole: "text", children: "Test ad" }) : null, isVideo && audio !== 'none' ? ((0, jsx_runtime_1.jsx)(react_native_1.Pressable, { onPress: toggleSound, style: styles.soundButton, accessibilityRole: "button", accessibilityLabel: muted ? 'Turn sound on' : 'Mute', hitSlop: 8, children: (0, jsx_runtime_1.jsx)(react_native_1.Text, { style: styles.soundText, children: muted ? 'Sound off' : 'Sound on' }) })) : null] }), (0, jsx_runtime_1.jsx)(react_native_1.Pressable, { onPress: canSkip ? close : undefined, disabled: !canSkip, style: [styles.skip, skipStyle], accessibilityRole: "button", accessibilityLabel: canSkip ? 'Skip ad' : `Skip in ${remainingS} seconds`, hitSlop: 8, children: canSkip ? ((0, jsx_runtime_1.jsxs)(react_native_1.View, { style: styles.skipRow, children: [(0, jsx_runtime_1.jsx)(react_native_1.Text, { style: [styles.skipText, skipTextStyle], children: "Skip Ad" }), (0, jsx_runtime_1.jsx)(SkipIcon, {})] })) : ((0, jsx_runtime_1.jsx)(react_native_1.Text, { style: [styles.skipText, styles.skipTextWaiting, skipTextStyle], children: `Skip in ${remainingS}` })) })] }), (0, jsx_runtime_1.jsxs)(react_native_1.View, { style: [styles.bottom, {
272
291
  bottom: Math.max(safe.bottom + BOTTOM_GAP, MIN_BOTTOM), left: safe.left + SIDE_GAP_BOTTOM, right: safe.right + SIDE_GAP_BOTTOM,
273
- }], pointerEvents: "box-none", children: [(0, jsx_runtime_1.jsx)(react_native_1.Pressable, { onPress: onCta, style: ({ pressed }) => [styles.cta, pressed && styles.ctaPressed], accessibilityRole: "link", children: (0, jsx_runtime_1.jsx)(react_native_1.Text, { style: styles.ctaText, numberOfLines: 1, children: ad.ctaLabel || 'Learn more' }) }), renderBelowButton ? renderBelowButton() : onRemoveAds ? ((0, jsx_runtime_1.jsx)(react_native_1.Pressable, { onPress: onRemoveAds, accessibilityRole: "button", hitSlop: 8, children: (0, jsx_runtime_1.jsx)(react_native_1.Text, { style: styles.removeAds, children: removeAdsLabel || 'Remove ads' }) })) : null, (0, jsx_runtime_1.jsx)(react_native_1.Text, { style: styles.sponsor, children: "Sponsored by Ethicly.ch" })] })] }));
292
+ }], pointerEvents: "box-none", children: [(0, jsx_runtime_1.jsx)(react_native_1.Pressable, { onPress: onCta, style: ({ pressed }) => [styles.cta, pressed && styles.ctaPressed], accessibilityRole: "link", children: (0, jsx_runtime_1.jsx)(react_native_1.Text, { style: styles.ctaText, numberOfLines: 1, children: ad.ctaLabel || 'Learn more' }) }), renderBelowButton ? renderBelowButton() : onRemoveAds ? ((0, jsx_runtime_1.jsx)(react_native_1.Pressable, { onPress: onRemoveAds, accessibilityRole: "button", hitSlop: 8, children: (0, jsx_runtime_1.jsx)(react_native_1.Text, { style: styles.removeAds, children: removeAdsLabel || 'Remove ads' }) })) : null, ad.showSponsorLabel ? (0, jsx_runtime_1.jsx)(react_native_1.Text, { style: styles.sponsor, children: "Sponsored by Ethicly.ch" }) : null] })] }));
274
293
  }
275
294
  /** Skip-to-end mark (a play triangle against a bar), drawn so it never depends on a font glyph. */
276
295
  function SkipIcon() {
@@ -7,6 +7,9 @@ const react_1 = require("react");
7
7
  function useEthiclyInterstitial(ethicly, options = {}) {
8
8
  var _a, _b;
9
9
  const preload = options.preload !== false;
10
+ const houseAds = options.houseAds;
11
+ const housePressRef = (0, react_1.useRef)(options.onHouseAdPress);
12
+ housePressRef.current = options.onHouseAdPress;
10
13
  const [current, setCurrent] = (0, react_1.useState)(null);
11
14
  const [reason, setReason] = (0, react_1.useState)(null);
12
15
  const [loading, setLoading] = (0, react_1.useState)(false);
@@ -16,20 +19,33 @@ function useEthiclyInterstitial(ethicly, options = {}) {
16
19
  (0, react_1.useEffect)(() => {
17
20
  mounted.current = true;
18
21
  if (preload)
19
- void ethicly.preload();
22
+ void ethicly.preload({ houseAds });
20
23
  return () => {
21
24
  var _a;
22
25
  mounted.current = false;
23
26
  void ((_a = currentRef.current) === null || _a === void 0 ? void 0 : _a.tracker.closed());
24
27
  };
25
- }, [ethicly, preload]);
28
+ }, [ethicly, preload, houseAds]);
26
29
  const show = (0, react_1.useCallback)(async () => {
27
30
  setLoading(true);
28
31
  try {
29
- const r = await ethicly.loadInterstitial();
32
+ const r = await ethicly.loadInterstitial({ houseAds });
30
33
  if (!mounted.current)
31
34
  return false;
32
35
  if (r.ad) {
36
+ if (r.ad.house) {
37
+ // Read at tap time: the hook's latest handler wins, else the client's
38
+ // (set when the ad was built), else the link opens. A handler added or
39
+ // removed after the ad loaded is respected.
40
+ const t = r.tracker;
41
+ const clientPress = t.houseAdPress;
42
+ Object.defineProperty(t, 'houseAdPress', {
43
+ configurable: true,
44
+ enumerable: true,
45
+ get: () => { var _a; return (_a = housePressRef.current) !== null && _a !== void 0 ? _a : clientPress; },
46
+ set: () => { },
47
+ });
48
+ }
33
49
  setCurrent({ ad: r.ad, tracker: r.tracker });
34
50
  setReason(null);
35
51
  return true;
@@ -41,14 +57,14 @@ function useEthiclyInterstitial(ethicly, options = {}) {
41
57
  if (mounted.current)
42
58
  setLoading(false);
43
59
  }
44
- }, [ethicly]);
60
+ }, [ethicly, houseAds]);
45
61
  const dismiss = (0, react_1.useCallback)(() => {
46
62
  var _a;
47
63
  void ((_a = currentRef.current) === null || _a === void 0 ? void 0 : _a.tracker.closed());
48
64
  setCurrent(null);
49
65
  if (preload)
50
- void ethicly.preload();
51
- }, [ethicly, preload]);
66
+ void ethicly.preload({ houseAds });
67
+ }, [ethicly, preload, houseAds]);
52
68
  const canShow = (0, react_1.useCallback)(() => ethicly.canShow(), [ethicly]);
53
69
  const nextAdStatus = (0, react_1.useCallback)(() => ethicly.nextAdStatus(), [ethicly]);
54
70
  return {
@@ -2,4 +2,4 @@
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
3
  exports.SDK_VERSION = void 0;
4
4
  /** SDK version, sent as sdk_version and in X-Ethicly-SDK. Keep in step with package.json. */
5
- exports.SDK_VERSION = '0.3.0';
5
+ exports.SDK_VERSION = '0.4.0';
@@ -158,6 +158,8 @@ export class CreativeCache {
158
158
  * `allowed()` is checked before every download so setAdsEnabled(false)
159
159
  * stops a download that has not started yet; cancel() also stops the one in
160
160
  * flight when the adapter supports it.
161
+ * `adId` keys the entry and names the files: house ads pass `house-<id>`
162
+ * because their ids can collide with paid ad ids.
161
163
  */
162
164
  ensure(adId, urls, limits, allowed) {
163
165
  const run = this.chain.then(() => this.ensureNow(adId, urls, limits, allowed));
@@ -6,6 +6,7 @@ import { isWebUrl } from './click';
6
6
  import { BUNDLED_BASE_URL, clampSkipAfterMs, cleanServeBase, defaultConfig, isBelowMinSdk, maxAgeSeconds, parseConfig } from './config';
7
7
  import { httpRequest, RouteGate } from './http';
8
8
  import { outboxFor, replayRecord } from './outbox';
9
+ import { HouseTracker } from './houseTracker';
9
10
  import { InterstitialTracker } from './tracker';
10
11
  import { SDK_VERSION } from '../version';
11
12
  /** How long loadInterstitial() waits for a creative download by default. */
@@ -88,6 +89,7 @@ class EthiclyClient {
88
89
  this.cache = new CreativeCache(o.fileCache || createMemoryFileCache(), this.storage, 'ethicly:v1:cache', this.now, this.log, o.fileCache ? (url) => this.contentLength(url) : undefined);
89
90
  this.config = defaultConfig(this.bundled);
90
91
  this.adsOn = o.adsEnabled !== false;
92
+ this.houseAdsOn = o.houseAds !== false;
91
93
  this.audio = audioPolicy(o.audio);
92
94
  if (o.audio !== undefined && !this.audio)
93
95
  this.log.warn(`audio must be 'on', 'optional' or 'none': using the server's value`);
@@ -399,6 +401,25 @@ class EthiclyClient {
399
401
  isAdsEnabled() {
400
402
  return this.adsOn;
401
403
  }
404
+ setHouseAds(enabled) {
405
+ var _a, _b;
406
+ this.houseAdsOn = !!enabled;
407
+ if (this.houseAdsOn)
408
+ return;
409
+ if ((_a = this.preloaded) === null || _a === void 0 ? void 0 : _a.result.ad.house)
410
+ this.preloaded = null;
411
+ if ((_b = this.pendingServed) === null || _b === void 0 ? void 0 : _b.house)
412
+ this.pendingServed = null;
413
+ }
414
+ /**
415
+ * Whether this call takes a house ad: the call's option, else the client's,
416
+ * and never while the dashboard switch (/config interstitial.house_ads) is off.
417
+ */
418
+ wantHouse(opts) {
419
+ if (!this.config.interstitial.house_ads)
420
+ return false;
421
+ return typeof (opts === null || opts === void 0 ? void 0 : opts.houseAds) === 'boolean' ? opts.houseAds : this.houseAdsOn;
422
+ }
402
423
  // ------------------------------------------------------------- serve
403
424
  blockedReason() {
404
425
  if (this.invalidKey)
@@ -418,14 +439,23 @@ class EthiclyClient {
418
439
  this.log.info(`no ad: ${reason}`);
419
440
  return { ad: null, tracker: null, reason };
420
441
  }
421
- /** The served ad waiting for its download, or a new serve. One serve at a time. */
422
- serveOnce() {
442
+ /**
443
+ * The served ad waiting for its download, or a new serve. One serve at a
444
+ * time. A house ad is a no fill for a caller that does not take one.
445
+ */
446
+ async serveFor(houseAds) {
447
+ const out = await this.serveOnce(houseAds);
448
+ if (out.served && out.served.house && !houseAds)
449
+ return { noFill: this.noFill(out.served.noFillReason || 'no_matching_ad') };
450
+ return out;
451
+ }
452
+ serveOnce(houseAds) {
423
453
  const p = this.pendingServed;
424
454
  if (p && !p.consumed && this.now() < p.expiresAt)
425
455
  return Promise.resolve({ served: p });
426
456
  this.pendingServed = null;
427
457
  if (!this.serveInflight) {
428
- this.serveInflight = this.serve()
458
+ this.serveInflight = this.serve(houseAds)
429
459
  .then((out) => {
430
460
  if (out.served)
431
461
  this.pendingServed = out.served;
@@ -441,16 +471,23 @@ class EthiclyClient {
441
471
  s.result = s.build(uris);
442
472
  return s.result;
443
473
  }
444
- async preload() {
474
+ async preload(opts) {
445
475
  try {
446
476
  if (!this.adsOn)
447
477
  return this.noFill('ads_disabled');
448
- if (this.preloaded && !this.preloaded.result.tracker.isExpired())
449
- return this.preloaded.result;
450
- this.preloaded = null;
478
+ const house = this.wantHouse(opts);
479
+ const p = this.preloaded;
480
+ if (p && !p.result.tracker.isExpired()) {
481
+ if (house || !p.result.ad.house)
482
+ return p.result;
483
+ // A preloaded house ad this call does not take: kept, and a paid ad may replace it.
484
+ }
485
+ else {
486
+ this.preloaded = null;
487
+ }
451
488
  if (this.shownCount >= this.getFrequency().maxPerSession)
452
489
  return this.noFill('frequency_capped');
453
- const out = await this.serveOnce();
490
+ const out = await this.serveFor(house);
454
491
  if (!out.served)
455
492
  return out.noFill;
456
493
  const s = out.served;
@@ -471,7 +508,7 @@ class EthiclyClient {
471
508
  return this.noFill('network_error');
472
509
  }
473
510
  }
474
- async loadInterstitial() {
511
+ async loadInterstitial(opts) {
475
512
  var _a;
476
513
  try {
477
514
  await this.ready;
@@ -484,17 +521,45 @@ class EthiclyClient {
484
521
  return this.noFill(blocked);
485
522
  if (!this.canShow())
486
523
  return this.noFill('frequency_capped');
524
+ const house = this.wantHouse(opts);
487
525
  const pre = this.preloaded;
488
526
  this.preloaded = null;
489
- if (pre && !pre.result.tracker.isExpired())
490
- return pre.result;
491
- const out = await this.serveOnce();
492
- if (!out.served)
493
- return out.noFill;
527
+ const valid = pre && !pre.result.tracker.isExpired() ? pre : null;
528
+ if (valid && !valid.result.ad.house)
529
+ return valid.result;
530
+ // A preloaded house ad this call does not take stays for a later one.
531
+ if (valid && !house)
532
+ this.preloaded = valid;
533
+ const fallback = valid && house ? valid : null;
534
+ const started = this.now();
535
+ let out;
536
+ if (fallback) {
537
+ // A preloaded house ad never blocks a paid one: ask for a paid ad
538
+ // first, within the load budget, and show the house ad only without one.
539
+ out = await this.within(this.serveFor(false), this.loadTimeoutMs);
540
+ if (!out || !out.served) {
541
+ if (!this.adsOn)
542
+ return this.noFill('ads_disabled');
543
+ // The paid-first serve may have hit the kill switch or the minimum SDK
544
+ // version: the server said stop, so the preloaded house ad must not show.
545
+ const nowBlocked = this.blockedReason();
546
+ if (nowBlocked)
547
+ return this.noFill(nowBlocked);
548
+ // The serve may still answer: it then waits as pendingServed for next time.
549
+ this.lastNoFillReason = null;
550
+ return fallback.result;
551
+ }
552
+ }
553
+ else {
554
+ out = await this.serveFor(house);
555
+ if (!out.served)
556
+ return out.noFill;
557
+ }
494
558
  const s = out.served;
495
559
  // The user is waiting: give the download a short budget, then stream the
496
560
  // remote file. The download carries on in the background for next time.
497
- const cached = await this.within(s.download, this.loadTimeoutMs);
561
+ const budget = Math.max(0, this.loadTimeoutMs - (this.now() - started));
562
+ const cached = await this.within(s.download, budget);
498
563
  if (!this.adsOn)
499
564
  return this.noFill('ads_disabled');
500
565
  if (!cached)
@@ -506,6 +571,9 @@ class EthiclyClient {
506
571
  // A preload that finished meanwhile may have stored this same ad.
507
572
  if (((_a = this.preloaded) === null || _a === void 0 ? void 0 : _a.result) === r)
508
573
  this.preloaded = null;
574
+ // The house ad that was not needed stays preloaded for next time.
575
+ if (fallback && !this.preloaded)
576
+ this.preloaded = fallback;
509
577
  return r;
510
578
  }
511
579
  catch (e) {
@@ -520,8 +588,7 @@ class EthiclyClient {
520
588
  return Promise.race([p, timeout]).finally(() => { if (timer)
521
589
  clearTimeout(timer); });
522
590
  }
523
- async serve() {
524
- var _a, _b;
591
+ async serve(houseAds) {
525
592
  const noFill = (reason) => ({ noFill: this.noFill(reason) });
526
593
  await this.ready;
527
594
  if (this.configStale())
@@ -531,6 +598,8 @@ class EthiclyClient {
531
598
  return noFill(blocked);
532
599
  if (this.gate.waitMs('serve') > 0)
533
600
  return noFill('rate_limited');
601
+ // The dashboard switch, read from the config just refreshed.
602
+ const askHouse = houseAds && this.config.interstitial.house_ads;
534
603
  const q = [
535
604
  `key=${encodeURIComponent(this.o.apiKey)}`,
536
605
  'format=interstitial',
@@ -540,6 +609,9 @@ class EthiclyClient {
540
609
  ];
541
610
  if (this.testMode)
542
611
  q.push('test=1');
612
+ // The SDK counts a house ad itself, on show (/fallback-impression): the server must not count it at pick time.
613
+ if (askHouse)
614
+ q.push('house_ads=1', 'client_fallback_tracking=1');
543
615
  const res = await httpRequest(this.fetchFn, `${this.serveBase()}?${q.join('&')}`, {
544
616
  headers: this.headers(), timeoutMs: SERVE_TIMEOUT_MS,
545
617
  });
@@ -558,52 +630,107 @@ class EthiclyClient {
558
630
  if (res.status !== 200 || !res.body || typeof res.body !== 'object')
559
631
  return noFill('server_error');
560
632
  const body = res.body;
633
+ const ttlS = typeof body.token_ttl_s === 'number' && body.token_ttl_s > 0 ? body.token_ttl_s : DEFAULT_TTL_S;
561
634
  if (!body.ad) {
562
635
  const reason = typeof body.reason === 'string' && body.reason ? body.reason : 'no_matching_ad';
563
636
  if (reason === 'app_disabled')
564
637
  this.appDisabled = true;
565
638
  if (reason === 'sdk_unsupported')
566
639
  this.sdkUnsupported = true;
640
+ const h = body.house_ad;
641
+ // A house ad only when asked for, and never past a kill switch.
642
+ if (askHouse && h && typeof h === 'object' && reason !== 'app_disabled' && reason !== 'sdk_unsupported') {
643
+ if (!this.validAd(h, 'house ad', body.request_id))
644
+ return noFill(reason);
645
+ if (!this.adsOn)
646
+ return noFill('ads_disabled');
647
+ const fallbackId = h.id;
648
+ const test = this.testMode || h.test === true || body.test === true;
649
+ this.log.info(`no paid ad (${reason}): house ad ${fallbackId}`);
650
+ return {
651
+ served: this.makeServed({
652
+ wire: h, cacheKey: `house-${fallbackId}`, servedAt, ttlS, test, house: true, noFillReason: reason,
653
+ tracker: (ad) => new HouseTracker({
654
+ ctx: this.beaconCtx(), ad, fallbackId, test, openUrl: this.o.openUrl, onShown: () => this.onShown(),
655
+ onPress: this.o.onHouseAdPress,
656
+ }),
657
+ }),
658
+ };
659
+ }
567
660
  return noFill(reason);
568
661
  }
569
662
  const ad = body.ad;
663
+ if (!this.validAd(ad, 'ad', body.request_id))
664
+ return noFill('invalid_response');
665
+ if (body.test === true)
666
+ this.log.info(`test serve: ad ${ad.id} on site ${body.publisher_site_id}`);
667
+ if (!this.adsOn)
668
+ return noFill('ads_disabled');
669
+ return {
670
+ served: this.makeServed({
671
+ wire: ad, cacheKey: ad.id, servedAt, ttlS, test: body.test === true, house: false,
672
+ tracker: (result) => new InterstitialTracker({
673
+ ctx: this.beaconCtx(),
674
+ ad: result,
675
+ serve: {
676
+ publisherSiteId: typeof body.publisher_site_id === 'number' && body.publisher_site_id > 0 ? body.publisher_site_id : null,
677
+ countryCode: typeof body.country_code === 'string' ? body.country_code : null,
678
+ impressionToken: typeof body.impression_token === 'string' ? body.impression_token : null,
679
+ },
680
+ viewableAfterMs: this.config.beacon.viewable_after_ms,
681
+ flushIntervalS: this.config.beacon.flush_interval_s,
682
+ platform: this.o.platform,
683
+ sdkVersion: SDK_VERSION,
684
+ appVersion: this.o.appVersion,
685
+ openUrl: this.o.openUrl,
686
+ onShown: () => this.onShown(),
687
+ outbox: this.outbox,
688
+ }),
689
+ }),
690
+ };
691
+ }
692
+ /** A paid or house ad has a numeric id, media and an http(s) destination. */
693
+ validAd(ad, what, requestId) {
570
694
  const m = ad.media;
571
695
  if (typeof ad.id !== 'number' || !m || typeof m.url !== 'string' || !m.url || typeof ad.destination_url !== 'string') {
572
- this.log.warn('serve answered an ad without media or destination', body.request_id);
573
- return noFill('invalid_response');
696
+ this.log.warn(`serve answered a ${what} without media or destination`, requestId);
697
+ return false;
574
698
  }
575
699
  if (!isWebUrl(ad.destination_url)) {
576
700
  // Only web pages are opened: never tel:, intent:, javascript: or an app scheme.
577
701
  if (!this.badDestinationLogged) {
578
702
  this.badDestinationLogged = true;
579
- this.log.error(`ad ${ad.id}: destination is not an http(s) URL, ad skipped`, body.request_id);
703
+ this.log.error(`${what} ${ad.id}: destination is not an http(s) URL, ad skipped`, requestId);
580
704
  }
581
- return noFill('invalid_response');
705
+ return false;
582
706
  }
583
- if (body.test === true)
584
- this.log.info(`test serve: ad ${ad.id} on site ${body.publisher_site_id}`);
585
- if (!this.adsOn)
586
- return noFill('ads_disabled');
707
+ return true;
708
+ }
709
+ /** Start the creative download; the ad and tracker are built later by preload() or loadInterstitial(). */
710
+ makeServed(a) {
711
+ var _a, _b;
712
+ const ad = a.wire;
713
+ // validAd() checked these.
714
+ const m = ad.media;
715
+ const mediaUrl = m.url;
716
+ const destinationUrl = ad.destination_url;
587
717
  const kind = m.kind === 'video' ? 'video' : 'image';
588
718
  const poster = kind === 'video' && typeof m.poster_url === 'string' && m.poster_url ? m.poster_url : null;
589
719
  const pf = this.config.prefetch;
590
720
  // Started now, awaited by preload() in full and by loadInterstitial() within loadTimeoutMs.
591
- 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: {} }));
592
- const ttlS = typeof body.token_ttl_s === 'number' && body.token_ttl_s > 0 ? body.token_ttl_s : DEFAULT_TTL_S;
593
- const expiresAt = servedAt + ttlS * 1000;
594
- const adId = ad.id;
595
- const mediaUrl = m.url;
596
- const destinationUrl = ad.destination_url;
721
+ 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: {} }));
722
+ const expiresAt = a.servedAt + a.ttlS * 1000;
597
723
  const label = typeof ad.cta_label === 'string' ? ad.cta_label.trim() : '';
598
724
  const posInt = (v, d) => (typeof v === 'number' && v > 0 ? Math.round(v) : d);
599
725
  // The ad's value wins over /config, kept within the same 8 to 15 s range.
600
726
  const skipAfterMs = (_a = clampSkipAfterMs(ad.skip_after_ms)) !== null && _a !== void 0 ? _a : this.config.interstitial.skip_after_ms;
601
727
  // The app's choice (options.audio) wins over the server's interstitial.audio.
602
728
  const audio = (_b = this.audio) !== null && _b !== void 0 ? _b : this.config.interstitial.audio;
729
+ const showSponsorLabel = !a.house && this.config.interstitial.sponsor_label;
603
730
  const build = (uris) => {
604
731
  const uri = uris[mediaUrl] || mediaUrl;
605
732
  const result = {
606
- id: adId,
733
+ id: ad.id,
607
734
  ctaLabel: label || 'Learn more',
608
735
  destinationUrl,
609
736
  skipAfterMs,
@@ -620,30 +747,18 @@ class EthiclyClient {
620
747
  },
621
748
  audio,
622
749
  title: typeof ad.title === 'string' ? ad.title : null,
623
- test: body.test === true,
624
- servedAt,
750
+ test: a.test,
751
+ servedAt: a.servedAt,
625
752
  expiresAt,
753
+ house: a.house,
754
+ showSponsorLabel,
626
755
  };
627
- const tracker = new InterstitialTracker({
628
- ctx: this.beaconCtx(),
629
- ad: result,
630
- serve: {
631
- publisherSiteId: typeof body.publisher_site_id === 'number' && body.publisher_site_id > 0 ? body.publisher_site_id : null,
632
- countryCode: typeof body.country_code === 'string' ? body.country_code : null,
633
- impressionToken: typeof body.impression_token === 'string' ? body.impression_token : null,
634
- },
635
- viewableAfterMs: this.config.beacon.viewable_after_ms,
636
- flushIntervalS: this.config.beacon.flush_interval_s,
637
- platform: this.o.platform,
638
- sdkVersion: SDK_VERSION,
639
- appVersion: this.o.appVersion,
640
- openUrl: this.o.openUrl,
641
- onShown: () => this.onShown(),
642
- outbox: this.outbox,
643
- });
644
- return { ad: result, tracker };
756
+ if (a.house)
757
+ result.noFillReason = a.noFillReason;
758
+ return { ad: result, tracker: a.tracker(result) };
645
759
  };
760
+ // An ad will show, so there is no fill reason, even for a house ad (see ad.noFillReason).
646
761
  this.lastNoFillReason = null;
647
- return { served: { build, download, expiresAt, consumed: false, result: null } };
762
+ return { build, download, expiresAt, consumed: false, result: null, house: a.house, noFillReason: a.noFillReason };
648
763
  }
649
764
  }
@@ -21,7 +21,7 @@ export function defaultConfig(serveBase) {
21
21
  enabled: true,
22
22
  min_sdk: { ios: '0.0.0', android: '0.0.0' },
23
23
  formats: ['interstitial', '300x250'],
24
- interstitial: { skip_after_ms: 8000, max_per_session: 3, min_gap_s: 120, audio: 'on' },
24
+ interstitial: { skip_after_ms: 8000, max_per_session: 3, min_gap_s: 120, audio: 'on', sponsor_label: true, house_ads: true },
25
25
  prefetch: { max_cached_creatives: 3, max_cache_mb: 20 },
26
26
  beacon: { viewable_after_ms: 2000, flush_interval_s: 30 },
27
27
  endpoints: { serve: serveBase },
@@ -70,6 +70,9 @@ export function parseConfig(body, bundledBase) {
70
70
  max_per_session: num(it.max_per_session, d.interstitial.max_per_session, 0, 1000),
71
71
  min_gap_s: num(it.min_gap_s, d.interstitial.min_gap_s, 0, 86400),
72
72
  audio,
73
+ // Only an explicit false hides the line.
74
+ sponsor_label: it.sponsor_label !== false,
75
+ house_ads: it.house_ads !== false,
73
76
  },
74
77
  prefetch: {
75
78
  max_cached_creatives: num(pf.max_cached_creatives, d.prefetch.max_cached_creatives, 0, 100),