@ethicly/react-native 0.2.1 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (37) hide show
  1. package/CHANGELOG.md +92 -0
  2. package/README.md +189 -12
  3. package/lib/commonjs/core/cache.js +2 -0
  4. package/lib/commonjs/core/client.js +245 -62
  5. package/lib/commonjs/core/config.js +4 -1
  6. package/lib/commonjs/core/houseTracker.js +92 -0
  7. package/lib/commonjs/core/tracker.js +3 -0
  8. package/lib/commonjs/react/EthiclyInterstitial.js +23 -4
  9. package/lib/commonjs/react/useEthiclyInterstitial.js +26 -7
  10. package/lib/commonjs/version.js +1 -1
  11. package/lib/module/core/cache.js +2 -0
  12. package/lib/module/core/client.js +245 -62
  13. package/lib/module/core/config.js +4 -1
  14. package/lib/module/core/houseTracker.js +88 -0
  15. package/lib/module/core/tracker.js +3 -0
  16. package/lib/module/react/EthiclyInterstitial.js +23 -4
  17. package/lib/module/react/useEthiclyInterstitial.js +26 -7
  18. package/lib/module/version.js +1 -1
  19. package/lib/typescript/core/cache.d.ts +3 -1
  20. package/lib/typescript/core/client.d.ts +43 -4
  21. package/lib/typescript/core/houseTracker.d.ts +53 -0
  22. package/lib/typescript/core/index.d.ts +1 -1
  23. package/lib/typescript/core/types.d.ts +87 -2
  24. package/lib/typescript/react/EthiclyInterstitial.d.ts +7 -0
  25. package/lib/typescript/react/useEthiclyInterstitial.d.ts +19 -3
  26. package/lib/typescript/version.d.ts +1 -1
  27. package/package.json +1 -1
  28. package/src/core/cache.ts +4 -2
  29. package/src/core/client.ts +277 -62
  30. package/src/core/config.ts +4 -1
  31. package/src/core/houseTracker.ts +108 -0
  32. package/src/core/index.ts +3 -2
  33. package/src/core/tracker.ts +2 -0
  34. package/src/core/types.ts +96 -2
  35. package/src/react/EthiclyInterstitial.tsx +26 -4
  36. package/src/react/useEthiclyInterstitial.ts +45 -10
  37. package/src/version.ts +1 -1
@@ -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,17 @@ 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
- return { ad: (_a = current === null || current === void 0 ? void 0 : current.ad) !== null && _a !== void 0 ? _a : null, tracker: (_b = current === null || current === void 0 ? void 0 : current.tracker) !== null && _b !== void 0 ? _b : null, reason, loading, show, dismiss, canShow };
69
+ const nextAdStatus = (0, react_1.useCallback)(() => ethicly.nextAdStatus(), [ethicly]);
70
+ return {
71
+ ad: (_a = current === null || current === void 0 ? void 0 : current.ad) !== null && _a !== void 0 ? _a : null, tracker: (_b = current === null || current === void 0 ? void 0 : current.tracker) !== null && _b !== void 0 ? _b : null, reason, loading, show, dismiss, canShow, nextAdStatus,
72
+ };
54
73
  }
@@ -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.2.1';
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. */
@@ -21,6 +22,23 @@ const DEFAULT_TTL_S = 3600;
21
22
  */
22
23
  export const SESSION_TIMEOUT_MS = 30 * 60 * 1000;
23
24
  let releaseTestModeLogged = false;
25
+ /** Same ceiling as the dashboard's gap between ads (24 hours). */
26
+ const MAX_MIN_GAP_S = 86400;
27
+ /**
28
+ * A frequency value from code: undefined when not a usable number, else >= 0.
29
+ * Infinity only where `allowInfinity`.
30
+ */
31
+ function frequencyValue(v, name, allowInfinity, log) {
32
+ if (typeof v !== 'number' || Number.isNaN(v) || (v === Infinity && !allowInfinity) || v === -Infinity) {
33
+ log.warn(`frequency.${name} must be a number >= 0${allowInfinity ? ' or Infinity' : ''}: using the dashboard value`);
34
+ return undefined;
35
+ }
36
+ if (v < 0) {
37
+ log.warn(`frequency.${name} below 0: using 0`);
38
+ return 0;
39
+ }
40
+ return v;
41
+ }
24
42
  function audioPolicy(v) {
25
43
  return v === 'on' || v === 'optional' || v === 'none' ? v : null;
26
44
  }
@@ -48,6 +66,9 @@ class EthiclyClient {
48
66
  this.shownCount = 0;
49
67
  this.lastShownAt = null;
50
68
  this.frequencyLoaded = false;
69
+ /** Frequency set in code, null where /config decides. */
70
+ this.maxPerSessionOverride = null;
71
+ this.minGapSOverride = null;
51
72
  /** When the app left the foreground, null while it is in it. */
52
73
  this.backgroundSince = null;
53
74
  this.preloaded = null;
@@ -68,12 +89,15 @@ class EthiclyClient {
68
89
  this.cache = new CreativeCache(o.fileCache || createMemoryFileCache(), this.storage, 'ethicly:v1:cache', this.now, this.log, o.fileCache ? (url) => this.contentLength(url) : undefined);
69
90
  this.config = defaultConfig(this.bundled);
70
91
  this.adsOn = o.adsEnabled !== false;
92
+ this.houseAdsOn = o.houseAds !== false;
71
93
  this.audio = audioPolicy(o.audio);
72
94
  if (o.audio !== undefined && !this.audio)
73
95
  this.log.warn(`audio must be 'on', 'optional' or 'none': using the server's value`);
74
96
  this.loadTimeoutMs = typeof o.loadTimeoutMs === 'number' && Number.isFinite(o.loadTimeoutMs) && o.loadTimeoutMs >= 0
75
97
  ? o.loadTimeoutMs
76
98
  : DEFAULT_LOAD_TIMEOUT_MS;
99
+ if (o.frequency)
100
+ this.setFrequency(o.frequency);
77
101
  this.testMode = !!o.testMode && !isReleaseBuild();
78
102
  if (o.testMode && !this.testMode)
79
103
  this.reportReleaseTestMode();
@@ -300,15 +324,61 @@ class EthiclyClient {
300
324
  this.log.warn(`config fetch failed (${res.status || 'network'}), keeping the last known config`);
301
325
  }
302
326
  // ------------------------------------------------------------- frequency
303
- canShow() {
327
+ getFrequency() {
328
+ var _a, _b;
304
329
  const it = this.config.interstitial;
305
- if (!this.adsOn || !this.frequencyLoaded || this.blockedReason())
306
- return false;
307
- if (this.shownCount >= it.max_per_session)
308
- return false;
309
- if (this.lastShownAt !== null && this.now() - this.lastShownAt < it.min_gap_s * 1000)
310
- return false;
311
- return true;
330
+ return {
331
+ maxPerSession: (_a = this.maxPerSessionOverride) !== null && _a !== void 0 ? _a : it.max_per_session,
332
+ minGapSeconds: (_b = this.minGapSOverride) !== null && _b !== void 0 ? _b : it.min_gap_s,
333
+ };
334
+ }
335
+ setFrequency(update) {
336
+ if (!update || typeof update !== 'object')
337
+ return;
338
+ if (update.maxPerSession === null)
339
+ this.maxPerSessionOverride = null;
340
+ else if (update.maxPerSession !== undefined) {
341
+ const v = frequencyValue(update.maxPerSession, 'maxPerSession', true, this.log);
342
+ if (v !== undefined) {
343
+ const whole = Math.floor(v);
344
+ if (whole !== v)
345
+ this.log.warn(`frequency.maxPerSession ${v} is not a whole number: using ${whole}${whole === 0 ? ' (no ads)' : ''}`);
346
+ this.maxPerSessionOverride = whole;
347
+ }
348
+ }
349
+ if (update.minGapSeconds === null)
350
+ this.minGapSOverride = null;
351
+ else if (update.minGapSeconds !== undefined) {
352
+ const v = frequencyValue(update.minGapSeconds, 'minGapSeconds', false, this.log);
353
+ if (v !== undefined) {
354
+ if (v > MAX_MIN_GAP_S)
355
+ this.log.warn(`frequency.minGapSeconds above ${MAX_MIN_GAP_S}: using ${MAX_MIN_GAP_S}`);
356
+ this.minGapSOverride = Math.min(v, MAX_MIN_GAP_S);
357
+ }
358
+ }
359
+ }
360
+ nextAdStatus() {
361
+ const { maxPerSession, minGapSeconds } = this.getFrequency();
362
+ const base = { shownThisSession: this.shownCount, maxPerSession, minGapSeconds };
363
+ const no = (reason, retryAt) => (retryAt === undefined ? { ...base, allowed: false, reason } : { ...base, allowed: false, reason, retryAt });
364
+ if (!this.adsOn)
365
+ return no('ads_disabled');
366
+ if (!this.frequencyLoaded)
367
+ return no('not_ready');
368
+ const blocked = this.blockedReason();
369
+ if (blocked)
370
+ return no(blocked);
371
+ if (this.shownCount >= maxPerSession)
372
+ return no('session_cap');
373
+ if (this.lastShownAt !== null) {
374
+ const retryAt = this.lastShownAt + minGapSeconds * 1000;
375
+ if (this.now() < retryAt)
376
+ return no('frequency_capped', retryAt);
377
+ }
378
+ return { ...base, allowed: true };
379
+ }
380
+ canShow() {
381
+ return this.nextAdStatus().allowed;
312
382
  }
313
383
  onShown() {
314
384
  this.shownCount += 1;
@@ -331,6 +401,25 @@ class EthiclyClient {
331
401
  isAdsEnabled() {
332
402
  return this.adsOn;
333
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
+ }
334
423
  // ------------------------------------------------------------- serve
335
424
  blockedReason() {
336
425
  if (this.invalidKey)
@@ -350,14 +439,23 @@ class EthiclyClient {
350
439
  this.log.info(`no ad: ${reason}`);
351
440
  return { ad: null, tracker: null, reason };
352
441
  }
353
- /** The served ad waiting for its download, or a new serve. One serve at a time. */
354
- 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) {
355
453
  const p = this.pendingServed;
356
454
  if (p && !p.consumed && this.now() < p.expiresAt)
357
455
  return Promise.resolve({ served: p });
358
456
  this.pendingServed = null;
359
457
  if (!this.serveInflight) {
360
- this.serveInflight = this.serve()
458
+ this.serveInflight = this.serve(houseAds)
361
459
  .then((out) => {
362
460
  if (out.served)
363
461
  this.pendingServed = out.served;
@@ -373,16 +471,23 @@ class EthiclyClient {
373
471
  s.result = s.build(uris);
374
472
  return s.result;
375
473
  }
376
- async preload() {
474
+ async preload(opts) {
377
475
  try {
378
476
  if (!this.adsOn)
379
477
  return this.noFill('ads_disabled');
380
- if (this.preloaded && !this.preloaded.result.tracker.isExpired())
381
- return this.preloaded.result;
382
- this.preloaded = null;
383
- if (this.shownCount >= this.config.interstitial.max_per_session)
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
+ }
488
+ if (this.shownCount >= this.getFrequency().maxPerSession)
384
489
  return this.noFill('frequency_capped');
385
- const out = await this.serveOnce();
490
+ const out = await this.serveFor(house);
386
491
  if (!out.served)
387
492
  return out.noFill;
388
493
  const s = out.served;
@@ -403,7 +508,7 @@ class EthiclyClient {
403
508
  return this.noFill('network_error');
404
509
  }
405
510
  }
406
- async loadInterstitial() {
511
+ async loadInterstitial(opts) {
407
512
  var _a;
408
513
  try {
409
514
  await this.ready;
@@ -416,17 +521,45 @@ class EthiclyClient {
416
521
  return this.noFill(blocked);
417
522
  if (!this.canShow())
418
523
  return this.noFill('frequency_capped');
524
+ const house = this.wantHouse(opts);
419
525
  const pre = this.preloaded;
420
526
  this.preloaded = null;
421
- if (pre && !pre.result.tracker.isExpired())
422
- return pre.result;
423
- const out = await this.serveOnce();
424
- if (!out.served)
425
- 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
+ }
426
558
  const s = out.served;
427
559
  // The user is waiting: give the download a short budget, then stream the
428
560
  // remote file. The download carries on in the background for next time.
429
- 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);
430
563
  if (!this.adsOn)
431
564
  return this.noFill('ads_disabled');
432
565
  if (!cached)
@@ -438,6 +571,9 @@ class EthiclyClient {
438
571
  // A preload that finished meanwhile may have stored this same ad.
439
572
  if (((_a = this.preloaded) === null || _a === void 0 ? void 0 : _a.result) === r)
440
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;
441
577
  return r;
442
578
  }
443
579
  catch (e) {
@@ -452,8 +588,7 @@ class EthiclyClient {
452
588
  return Promise.race([p, timeout]).finally(() => { if (timer)
453
589
  clearTimeout(timer); });
454
590
  }
455
- async serve() {
456
- var _a, _b;
591
+ async serve(houseAds) {
457
592
  const noFill = (reason) => ({ noFill: this.noFill(reason) });
458
593
  await this.ready;
459
594
  if (this.configStale())
@@ -463,6 +598,8 @@ class EthiclyClient {
463
598
  return noFill(blocked);
464
599
  if (this.gate.waitMs('serve') > 0)
465
600
  return noFill('rate_limited');
601
+ // The dashboard switch, read from the config just refreshed.
602
+ const askHouse = houseAds && this.config.interstitial.house_ads;
466
603
  const q = [
467
604
  `key=${encodeURIComponent(this.o.apiKey)}`,
468
605
  'format=interstitial',
@@ -472,6 +609,9 @@ class EthiclyClient {
472
609
  ];
473
610
  if (this.testMode)
474
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');
475
615
  const res = await httpRequest(this.fetchFn, `${this.serveBase()}?${q.join('&')}`, {
476
616
  headers: this.headers(), timeoutMs: SERVE_TIMEOUT_MS,
477
617
  });
@@ -490,52 +630,107 @@ class EthiclyClient {
490
630
  if (res.status !== 200 || !res.body || typeof res.body !== 'object')
491
631
  return noFill('server_error');
492
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;
493
634
  if (!body.ad) {
494
635
  const reason = typeof body.reason === 'string' && body.reason ? body.reason : 'no_matching_ad';
495
636
  if (reason === 'app_disabled')
496
637
  this.appDisabled = true;
497
638
  if (reason === 'sdk_unsupported')
498
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
+ }
499
660
  return noFill(reason);
500
661
  }
501
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) {
502
694
  const m = ad.media;
503
695
  if (typeof ad.id !== 'number' || !m || typeof m.url !== 'string' || !m.url || typeof ad.destination_url !== 'string') {
504
- this.log.warn('serve answered an ad without media or destination', body.request_id);
505
- return noFill('invalid_response');
696
+ this.log.warn(`serve answered a ${what} without media or destination`, requestId);
697
+ return false;
506
698
  }
507
699
  if (!isWebUrl(ad.destination_url)) {
508
700
  // Only web pages are opened: never tel:, intent:, javascript: or an app scheme.
509
701
  if (!this.badDestinationLogged) {
510
702
  this.badDestinationLogged = true;
511
- 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);
512
704
  }
513
- return noFill('invalid_response');
705
+ return false;
514
706
  }
515
- if (body.test === true)
516
- this.log.info(`test serve: ad ${ad.id} on site ${body.publisher_site_id}`);
517
- if (!this.adsOn)
518
- 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;
519
717
  const kind = m.kind === 'video' ? 'video' : 'image';
520
718
  const poster = kind === 'video' && typeof m.poster_url === 'string' && m.poster_url ? m.poster_url : null;
521
719
  const pf = this.config.prefetch;
522
720
  // Started now, awaited by preload() in full and by loadInterstitial() within loadTimeoutMs.
523
- 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: {} }));
524
- const ttlS = typeof body.token_ttl_s === 'number' && body.token_ttl_s > 0 ? body.token_ttl_s : DEFAULT_TTL_S;
525
- const expiresAt = servedAt + ttlS * 1000;
526
- const adId = ad.id;
527
- const mediaUrl = m.url;
528
- 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;
529
723
  const label = typeof ad.cta_label === 'string' ? ad.cta_label.trim() : '';
530
724
  const posInt = (v, d) => (typeof v === 'number' && v > 0 ? Math.round(v) : d);
531
725
  // The ad's value wins over /config, kept within the same 8 to 15 s range.
532
726
  const skipAfterMs = (_a = clampSkipAfterMs(ad.skip_after_ms)) !== null && _a !== void 0 ? _a : this.config.interstitial.skip_after_ms;
533
727
  // The app's choice (options.audio) wins over the server's interstitial.audio.
534
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;
535
730
  const build = (uris) => {
536
731
  const uri = uris[mediaUrl] || mediaUrl;
537
732
  const result = {
538
- id: adId,
733
+ id: ad.id,
539
734
  ctaLabel: label || 'Learn more',
540
735
  destinationUrl,
541
736
  skipAfterMs,
@@ -552,30 +747,18 @@ class EthiclyClient {
552
747
  },
553
748
  audio,
554
749
  title: typeof ad.title === 'string' ? ad.title : null,
555
- test: body.test === true,
556
- servedAt,
750
+ test: a.test,
751
+ servedAt: a.servedAt,
557
752
  expiresAt,
753
+ house: a.house,
754
+ showSponsorLabel,
558
755
  };
559
- const tracker = new InterstitialTracker({
560
- ctx: this.beaconCtx(),
561
- ad: result,
562
- serve: {
563
- publisherSiteId: typeof body.publisher_site_id === 'number' && body.publisher_site_id > 0 ? body.publisher_site_id : null,
564
- countryCode: typeof body.country_code === 'string' ? body.country_code : null,
565
- impressionToken: typeof body.impression_token === 'string' ? body.impression_token : null,
566
- },
567
- viewableAfterMs: this.config.beacon.viewable_after_ms,
568
- flushIntervalS: this.config.beacon.flush_interval_s,
569
- platform: this.o.platform,
570
- sdkVersion: SDK_VERSION,
571
- appVersion: this.o.appVersion,
572
- openUrl: this.o.openUrl,
573
- onShown: () => this.onShown(),
574
- outbox: this.outbox,
575
- });
576
- return { ad: result, tracker };
756
+ if (a.house)
757
+ result.noFillReason = a.noFillReason;
758
+ return { ad: result, tracker: a.tracker(result) };
577
759
  };
760
+ // An ad will show, so there is no fill reason, even for a house ad (see ad.noFillReason).
578
761
  this.lastNoFillReason = null;
579
- return { served: { build, download, expiresAt, consumed: false, result: null } };
762
+ return { build, download, expiresAt, consumed: false, result: null, house: a.house, noFillReason: a.noFillReason };
580
763
  }
581
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),
@@ -0,0 +1,88 @@
1
+ // The tracker for a house ad: the publisher's own creative, shown when no paid
2
+ // ad fills. Nothing is billed, so there is no /impression, /viewable, video
3
+ // event or click token: only the unbilled /fallback-impression and
4
+ // /fallback-click counters, fire-and-forget, and none of them in test mode.
5
+ import { BEACON_TIMEOUT_MS } from './beacons';
6
+ import { isWebUrl } from './click';
7
+ import { httpRequest } from './http';
8
+ export class HouseTracker {
9
+ constructor(d) {
10
+ this.d = d;
11
+ this.shownOnce = false;
12
+ this.clickedOnce = false;
13
+ this.pending = new Set();
14
+ this.houseAdPress = d.onPress;
15
+ }
16
+ /** Resolves when every counter in flight has settled. For tests. */
17
+ async settle() {
18
+ while (this.pending.size)
19
+ await Promise.all(Array.from(this.pending)).catch(() => undefined);
20
+ }
21
+ isExpired() {
22
+ return this.d.ctx.now() >= this.d.ad.expiresAt;
23
+ }
24
+ /**
25
+ * One POST to a house-ad counter, never retried, never awaited by the
26
+ * caller. The answer (200, 400 or 429) changes nothing. Never rejects.
27
+ */
28
+ send(route) {
29
+ const { ctx } = this.d;
30
+ if (this.d.test)
31
+ return;
32
+ const p = httpRequest(ctx.fetch, `${ctx.serveBase()}/${route}`, {
33
+ method: 'POST', headers: ctx.headers(), body: { fallback_id: this.d.fallbackId }, timeoutMs: BEACON_TIMEOUT_MS,
34
+ }).then((res) => {
35
+ if (res.status !== 200)
36
+ ctx.log.debug(`/${route} answered ${res.status || 'nothing'}`);
37
+ }).catch((e) => ctx.log.debug(`/${route} failed`, e));
38
+ this.pending.add(p);
39
+ p.finally(() => this.pending.delete(p)).catch(() => undefined);
40
+ }
41
+ shown() {
42
+ if (this.shownOnce)
43
+ return Promise.resolve();
44
+ this.shownOnce = true;
45
+ if (this.isExpired()) {
46
+ this.d.ctx.log.error(`house ad ${this.d.fallbackId} expired before it was shown; load a new one`);
47
+ return Promise.resolve();
48
+ }
49
+ try {
50
+ this.d.onShown();
51
+ }
52
+ catch { /* never throw */ }
53
+ this.send('fallback-impression');
54
+ return Promise.resolve();
55
+ }
56
+ progress(_positionMs, _opts) { }
57
+ complete() { }
58
+ skipped(_positionMs) { }
59
+ error() { }
60
+ /**
61
+ * Counts the tap once (fire-and-forget) and opens the destination right
62
+ * away. `{ open: false }` only counts it: the app shows its own screen.
63
+ */
64
+ async clicked(opts) {
65
+ const url = this.d.ad.destinationUrl;
66
+ if (!this.clickedOnce) {
67
+ this.clickedOnce = true;
68
+ this.send('fallback-click');
69
+ }
70
+ if ((opts === null || opts === void 0 ? void 0 : opts.open) === false)
71
+ return url;
72
+ if (!isWebUrl(url)) {
73
+ this.d.ctx.log.error(`house ad ${this.d.fallbackId}: destination is not an http(s) URL, not opened`);
74
+ return url;
75
+ }
76
+ try {
77
+ if (this.d.openUrl)
78
+ await this.d.openUrl(url);
79
+ else
80
+ this.d.ctx.log.warn('no openUrl adapter: the host must open the returned URL');
81
+ }
82
+ catch (e) {
83
+ this.d.ctx.log.error('openUrl failed', e);
84
+ }
85
+ return url;
86
+ }
87
+ async closed() { }
88
+ }