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