@ethicly/react-native 0.0.0-stage → 0.2.1
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 +133 -0
- package/LICENSE +21 -0
- package/README.md +428 -2
- package/core/package.json +6 -0
- package/interstitial/package.json +6 -0
- package/lib/commonjs/core/adapters.js +326 -0
- package/lib/commonjs/core/beacons.js +70 -0
- package/lib/commonjs/core/cache.js +261 -0
- package/lib/commonjs/core/click.js +29 -0
- package/lib/commonjs/core/client.js +585 -0
- package/lib/commonjs/core/config.js +128 -0
- package/lib/commonjs/core/http.js +115 -0
- package/lib/commonjs/core/index.js +21 -0
- package/lib/commonjs/core/outbox.js +192 -0
- package/lib/commonjs/core/tracker.js +379 -0
- package/lib/commonjs/core/types.js +4 -0
- package/lib/commonjs/index.js +22 -0
- package/lib/commonjs/interstitial.js +7 -0
- package/lib/commonjs/react/EthiclyInterstitial.js +319 -0
- package/lib/commonjs/react/useEthiclyInterstitial.js +54 -0
- package/lib/commonjs/version.js +5 -0
- package/lib/module/core/adapters.js +315 -0
- package/lib/module/core/beacons.js +64 -0
- package/lib/module/core/cache.js +257 -0
- package/lib/module/core/click.js +24 -0
- package/lib/module/core/client.js +581 -0
- package/lib/module/core/config.js +118 -0
- package/lib/module/core/http.js +105 -0
- package/lib/module/core/index.js +6 -0
- package/lib/module/core/outbox.js +186 -0
- package/lib/module/core/tracker.js +375 -0
- package/lib/module/core/types.js +3 -0
- package/lib/module/index.js +4 -0
- package/lib/module/interstitial.js +3 -0
- package/lib/module/react/EthiclyInterstitial.js +292 -0
- package/lib/module/react/useEthiclyInterstitial.js +51 -0
- package/lib/module/version.js +2 -0
- package/lib/typescript/core/adapters.d.ts +139 -0
- package/lib/typescript/core/beacons.d.ts +32 -0
- package/lib/typescript/core/cache.d.ts +71 -0
- package/lib/typescript/core/click.d.ts +13 -0
- package/lib/typescript/core/client.d.ts +78 -0
- package/lib/typescript/core/config.d.ts +33 -0
- package/lib/typescript/core/http.d.ts +34 -0
- package/lib/typescript/core/index.d.ts +8 -0
- package/lib/typescript/core/outbox.d.ts +56 -0
- package/lib/typescript/core/tracker.d.ts +95 -0
- package/lib/typescript/core/types.d.ts +175 -0
- package/lib/typescript/index.d.ts +3 -0
- package/lib/typescript/interstitial.d.ts +2 -0
- package/lib/typescript/react/EthiclyInterstitial.d.ts +51 -0
- package/lib/typescript/react/useEthiclyInterstitial.d.ts +20 -0
- package/lib/typescript/version.d.ts +2 -0
- package/package.json +101 -4
- package/src/core/adapters.ts +365 -0
- package/src/core/beacons.ts +81 -0
- package/src/core/cache.ts +261 -0
- package/src/core/click.ts +26 -0
- package/src/core/client.ts +665 -0
- package/src/core/config.ts +124 -0
- package/src/core/http.ts +115 -0
- package/src/core/index.ts +14 -0
- package/src/core/outbox.ts +193 -0
- package/src/core/tracker.ts +376 -0
- package/src/core/types.ts +185 -0
- package/src/index.ts +5 -0
- package/src/interstitial.ts +4 -0
- package/src/react/EthiclyInterstitial.tsx +432 -0
- package/src/react/useEthiclyInterstitial.ts +74 -0
- package/src/version.ts +2 -0
|
@@ -0,0 +1,261 @@
|
|
|
1
|
+
// Creative cache: downloads the video and poster of a served ad (doc
|
|
2
|
+
// "Lifecycle and timing" step 3) within prefetch.max_cache_mb and
|
|
3
|
+
// prefetch.max_cached_creatives, evicting least recently used first.
|
|
4
|
+
//
|
|
5
|
+
// Disk use stays bounded even if the app dies mid-download or the index is
|
|
6
|
+
// lost (for example with the default in-memory storage):
|
|
7
|
+
// - a file's size is checked before it is written (HEAD Content-Length, and
|
|
8
|
+
// the adapter aborts a download that grows past the remaining budget);
|
|
9
|
+
// - the index records each file name as pending BEFORE its download starts,
|
|
10
|
+
// and is written again as soon as the download lands;
|
|
11
|
+
// - on first use every pending file, and every file in the SDK's cache
|
|
12
|
+
// directory that the index does not list, is deleted.
|
|
13
|
+
|
|
14
|
+
import type { FileCacheAdapter, KeyValueStorage, Logger } from './types';
|
|
15
|
+
|
|
16
|
+
interface CachedFile { url: string; uri: string; bytes: number }
|
|
17
|
+
interface Entry { key: string; files: CachedFile[]; lastUsed: number }
|
|
18
|
+
interface Index { entries: Entry[]; pending?: string[] }
|
|
19
|
+
|
|
20
|
+
export interface CacheLimits { maxCreatives: number; maxBytes: number }
|
|
21
|
+
|
|
22
|
+
export interface CachedMedia {
|
|
23
|
+
/** remote URL -> local uri, for the files that are cached. */
|
|
24
|
+
uris: Record<string, string>;
|
|
25
|
+
}
|
|
26
|
+
|
|
27
|
+
/**
|
|
28
|
+
* The longest one creative file may take to download. A slower (trickling)
|
|
29
|
+
* download is cancelled when the adapter supports it, else abandoned: the
|
|
30
|
+
* creative streams and later downloads are not held up behind it. A file it
|
|
31
|
+
* still writes afterwards is not indexed, so the next launch's sweep deletes it.
|
|
32
|
+
*/
|
|
33
|
+
export const DOWNLOAD_TIMEOUT_MS = 60000;
|
|
34
|
+
|
|
35
|
+
/** Content-Length of a URL, or null when unknown. */
|
|
36
|
+
export type SizeProbe = (url: string) => Promise<number | null>;
|
|
37
|
+
|
|
38
|
+
function hash(s: string): string {
|
|
39
|
+
let h = 5381;
|
|
40
|
+
for (let i = 0; i < s.length; i++) h = ((h << 5) + h + s.charCodeAt(i)) >>> 0;
|
|
41
|
+
return h.toString(36);
|
|
42
|
+
}
|
|
43
|
+
|
|
44
|
+
function extOf(url: string, fallback: string): string {
|
|
45
|
+
const m = /\.([a-z0-9]{2,5})(?:[?#]|$)/i.exec(url);
|
|
46
|
+
return m ? m[1].toLowerCase() : fallback;
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
function baseName(uri: string): string {
|
|
50
|
+
return uri.replace(/[?#].*$/, '').split('/').pop() || uri;
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
export class CreativeCache {
|
|
54
|
+
private entries: Entry[] = [];
|
|
55
|
+
/** File names whose download has started but not landed. */
|
|
56
|
+
private pending: string[] = [];
|
|
57
|
+
private loaded: Promise<void> | null = null;
|
|
58
|
+
private chain: Promise<unknown> = Promise.resolve();
|
|
59
|
+
/** Bumped by cancel(): a download started before it no longer counts. */
|
|
60
|
+
private generation = 0;
|
|
61
|
+
|
|
62
|
+
constructor(
|
|
63
|
+
private files: FileCacheAdapter,
|
|
64
|
+
private storage: KeyValueStorage,
|
|
65
|
+
private storageKey: string,
|
|
66
|
+
private now: () => number,
|
|
67
|
+
private log: Required<Logger>,
|
|
68
|
+
private probeSize: SizeProbe = async () => null,
|
|
69
|
+
private downloadTimeoutMs: number = DOWNLOAD_TIMEOUT_MS,
|
|
70
|
+
) {}
|
|
71
|
+
|
|
72
|
+
/**
|
|
73
|
+
* Stop the download in flight, when the adapter can (FileCacheAdapter.cancel),
|
|
74
|
+
* and skip the files not started yet. For setAdsEnabled(false).
|
|
75
|
+
*/
|
|
76
|
+
cancel(): void {
|
|
77
|
+
this.generation += 1;
|
|
78
|
+
try { this.files.cancel?.(); } catch (e) { this.log.warn('could not cancel the creative download', e); }
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
/** The adapter's download, given up on after downloadTimeoutMs. */
|
|
82
|
+
private async downloadWithin(url: string, name: string, maxBytes: number): Promise<{ uri: string; bytes?: number }> {
|
|
83
|
+
let timer: ReturnType<typeof setTimeout> | undefined;
|
|
84
|
+
const timeout = new Promise<never>((_, reject) => {
|
|
85
|
+
timer = setTimeout(() => {
|
|
86
|
+
try { this.files.cancel?.(); } catch { /* best effort */ }
|
|
87
|
+
reject(new Error(`download took longer than ${this.downloadTimeoutMs} ms`));
|
|
88
|
+
}, this.downloadTimeoutMs);
|
|
89
|
+
});
|
|
90
|
+
const dl = this.files.download(url, name, { maxBytes });
|
|
91
|
+
// A late rejection of an abandoned download must not go unhandled.
|
|
92
|
+
dl.catch(() => undefined);
|
|
93
|
+
try {
|
|
94
|
+
return await Promise.race([dl, timeout]);
|
|
95
|
+
} finally {
|
|
96
|
+
if (timer) clearTimeout(timer);
|
|
97
|
+
}
|
|
98
|
+
}
|
|
99
|
+
|
|
100
|
+
private load(): Promise<void> {
|
|
101
|
+
if (!this.loaded) this.loaded = this.loadNow();
|
|
102
|
+
return this.loaded;
|
|
103
|
+
}
|
|
104
|
+
|
|
105
|
+
private async loadNow(): Promise<void> {
|
|
106
|
+
let pending: string[] = [];
|
|
107
|
+
try {
|
|
108
|
+
const raw = await this.storage.getItem(this.storageKey);
|
|
109
|
+
const parsed = raw ? JSON.parse(raw) : null;
|
|
110
|
+
if (Array.isArray(parsed)) this.entries = parsed as Entry[]; // 0.1.0 pre-release shape
|
|
111
|
+
else if (parsed && Array.isArray(parsed.entries)) {
|
|
112
|
+
this.entries = (parsed as Index).entries;
|
|
113
|
+
pending = Array.isArray(parsed.pending) ? (parsed as Index).pending! : [];
|
|
114
|
+
}
|
|
115
|
+
} catch {
|
|
116
|
+
this.entries = [];
|
|
117
|
+
}
|
|
118
|
+
await this.sweep(pending);
|
|
119
|
+
}
|
|
120
|
+
|
|
121
|
+
/**
|
|
122
|
+
* Delete the downloads a previous run left unfinished, and every file in the
|
|
123
|
+
* cache directory that the index does not list.
|
|
124
|
+
*/
|
|
125
|
+
private async sweep(pending: string[]): Promise<void> {
|
|
126
|
+
const known = new Set<string>();
|
|
127
|
+
for (const e of this.entries) for (const f of e.files) known.add(baseName(f.uri));
|
|
128
|
+
// The directory listing below covers these too; this also works for an
|
|
129
|
+
// adapter that cannot list its directory.
|
|
130
|
+
if (this.files.uriFor) {
|
|
131
|
+
for (const name of pending) {
|
|
132
|
+
if (!known.has(name)) await this.files.delete(this.files.uriFor(name)).catch(() => undefined);
|
|
133
|
+
}
|
|
134
|
+
}
|
|
135
|
+
let listed: string[] = [];
|
|
136
|
+
try {
|
|
137
|
+
listed = this.files.list ? await this.files.list() : [];
|
|
138
|
+
} catch (e) {
|
|
139
|
+
this.log.warn('could not list the creative cache', e);
|
|
140
|
+
}
|
|
141
|
+
for (const uri of listed) {
|
|
142
|
+
if (!known.has(baseName(uri))) {
|
|
143
|
+
await this.files.delete(uri).catch(() => undefined);
|
|
144
|
+
this.log.debug(`swept unindexed file ${baseName(uri)}`);
|
|
145
|
+
}
|
|
146
|
+
}
|
|
147
|
+
await this.persist();
|
|
148
|
+
}
|
|
149
|
+
|
|
150
|
+
private persist(): Promise<void> {
|
|
151
|
+
const index: Index = { entries: this.entries, pending: this.pending };
|
|
152
|
+
return this.storage.setItem(this.storageKey, JSON.stringify(index)).catch(() => undefined);
|
|
153
|
+
}
|
|
154
|
+
|
|
155
|
+
/** Number of cached creatives and their total size, for tests and debugging. */
|
|
156
|
+
async stats(): Promise<{ creatives: number; bytes: number; keys: string[] }> {
|
|
157
|
+
await this.load();
|
|
158
|
+
return {
|
|
159
|
+
creatives: this.entries.length,
|
|
160
|
+
bytes: this.entries.reduce((n, e) => n + this.size(e), 0),
|
|
161
|
+
keys: this.entries.map((e) => e.key),
|
|
162
|
+
};
|
|
163
|
+
}
|
|
164
|
+
|
|
165
|
+
/**
|
|
166
|
+
* Make sure the files of one creative are on disk. Never throws: a file that
|
|
167
|
+
* cannot be cached is simply left out of the result and streamed instead.
|
|
168
|
+
* `allowed()` is checked before every download so setAdsEnabled(false)
|
|
169
|
+
* stops a download that has not started yet; cancel() also stops the one in
|
|
170
|
+
* flight when the adapter supports it.
|
|
171
|
+
*/
|
|
172
|
+
ensure(adId: number, urls: string[], limits: CacheLimits, allowed: () => boolean): Promise<CachedMedia> {
|
|
173
|
+
const run = this.chain.then(() => this.ensureNow(adId, urls, limits, allowed));
|
|
174
|
+
this.chain = run.catch(() => undefined);
|
|
175
|
+
return run;
|
|
176
|
+
}
|
|
177
|
+
|
|
178
|
+
private async ensureNow(adId: number, urls: string[], limits: CacheLimits, allowed: () => boolean): Promise<CachedMedia> {
|
|
179
|
+
await this.load();
|
|
180
|
+
if (limits.maxCreatives <= 0 || limits.maxBytes <= 0) return { uris: {} };
|
|
181
|
+
const key = `${adId}:${hash(urls.join('|'))}`;
|
|
182
|
+
|
|
183
|
+
let entry = this.entries.find((e) => e.key === key);
|
|
184
|
+
if (entry) {
|
|
185
|
+
const present = await Promise.all(entry.files.map((f) => this.files.exists(f.uri).catch(() => false)));
|
|
186
|
+
entry.files = entry.files.filter((_, i) => present[i]);
|
|
187
|
+
} else {
|
|
188
|
+
entry = { key, files: [], lastUsed: 0 };
|
|
189
|
+
this.entries.push(entry);
|
|
190
|
+
}
|
|
191
|
+
entry.lastUsed = this.now();
|
|
192
|
+
const generation = this.generation;
|
|
193
|
+
const go = () => allowed() && generation === this.generation;
|
|
194
|
+
|
|
195
|
+
for (const url of urls) {
|
|
196
|
+
if (entry.files.some((f) => f.url === url)) continue;
|
|
197
|
+
if (!go()) break;
|
|
198
|
+
// One creative may use the whole budget (older ones are evicted), never more.
|
|
199
|
+
const budget = limits.maxBytes - this.size(entry);
|
|
200
|
+
const known = await this.probeSize(url).catch(() => null);
|
|
201
|
+
if (known !== null && known > budget) {
|
|
202
|
+
this.log.info(`${url} is ${known} bytes, over the cache budget: it will stream`);
|
|
203
|
+
continue;
|
|
204
|
+
}
|
|
205
|
+
// Known size: make room first, so the disk never holds more than the budget.
|
|
206
|
+
if (known !== null) await this.evict(limits, entry, known);
|
|
207
|
+
const name = `ethicly-${adId}-${hash(url)}.${extOf(url, 'bin')}`;
|
|
208
|
+
this.pending = [name];
|
|
209
|
+
await this.persist();
|
|
210
|
+
try {
|
|
211
|
+
const res = await this.downloadWithin(url, name, budget);
|
|
212
|
+
const bytes = typeof res.bytes === 'number' && res.bytes > 0 ? res.bytes : await this.files.size(res.uri).catch(() => 0);
|
|
213
|
+
if (bytes > budget) {
|
|
214
|
+
await this.files.delete(res.uri).catch(() => undefined);
|
|
215
|
+
this.log.info(`${url} is over the cache budget: it will stream`);
|
|
216
|
+
} else if (!go()) {
|
|
217
|
+
// Cancelled while it was landing: keep nothing for a paid user.
|
|
218
|
+
await this.files.delete(res.uri).catch(() => undefined);
|
|
219
|
+
} else {
|
|
220
|
+
entry.files.push({ url, uri: res.uri, bytes });
|
|
221
|
+
}
|
|
222
|
+
} catch (e) {
|
|
223
|
+
this.log.warn(`could not cache ${url}, it will stream`, e);
|
|
224
|
+
}
|
|
225
|
+
this.pending = [];
|
|
226
|
+
// Persist right after each file lands, so the index never lags the disk
|
|
227
|
+
// by more than the download in flight (which the sweep covers).
|
|
228
|
+
await this.evict(limits, entry);
|
|
229
|
+
await this.persist();
|
|
230
|
+
}
|
|
231
|
+
|
|
232
|
+
if (entry.files.length === 0) this.entries = this.entries.filter((e) => e !== entry);
|
|
233
|
+
await this.evict(limits, entry);
|
|
234
|
+
await this.persist();
|
|
235
|
+
|
|
236
|
+
const uris: Record<string, string> = {};
|
|
237
|
+
for (const f of this.entries.includes(entry) ? entry.files : []) uris[f.url] = f.uri;
|
|
238
|
+
return { uris };
|
|
239
|
+
}
|
|
240
|
+
|
|
241
|
+
private size(e: Entry): number {
|
|
242
|
+
return e.files.reduce((n, f) => n + f.bytes, 0);
|
|
243
|
+
}
|
|
244
|
+
|
|
245
|
+
/**
|
|
246
|
+
* LRU eviction, leaving room for `incoming` more bytes. The current entry
|
|
247
|
+
* goes last, and only if it alone is too big.
|
|
248
|
+
*/
|
|
249
|
+
private async evict(limits: CacheLimits, current: Entry, incoming = 0): Promise<void> {
|
|
250
|
+
const total = () => this.entries.reduce((n, e) => n + this.size(e), 0) + incoming;
|
|
251
|
+
const victims = () => this.entries.filter((e) => e !== current).sort((a, b) => a.lastUsed - b.lastUsed);
|
|
252
|
+
while (this.entries.length > limits.maxCreatives || total() > limits.maxBytes) {
|
|
253
|
+
if (incoming > 0 && victims().length === 0) break;
|
|
254
|
+
const v = victims()[0] || (this.entries.includes(current) ? current : undefined);
|
|
255
|
+
if (!v) break;
|
|
256
|
+
this.entries = this.entries.filter((e) => e !== v);
|
|
257
|
+
for (const f of v.files) await this.files.delete(f.uri).catch(() => undefined);
|
|
258
|
+
this.log.debug(`evicted creative ${v.key}`);
|
|
259
|
+
}
|
|
260
|
+
}
|
|
261
|
+
}
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
// Doc "Click handling" step 3, the same rule as trackClickAndNavigate in
|
|
2
|
+
// frontend/public/ethicly.js.
|
|
3
|
+
|
|
4
|
+
/**
|
|
5
|
+
* Append ethicly_click=<token> to the destination. The separator is "&" when
|
|
6
|
+
* the URL already contains a "?" anywhere, otherwise "?". The token is
|
|
7
|
+
* percent-encoded and nothing else in the URL changes.
|
|
8
|
+
*/
|
|
9
|
+
export function appendClickToken(destinationUrl: string, clickToken: string | null | undefined): string {
|
|
10
|
+
if (typeof clickToken !== 'string' || clickToken === '') return destinationUrl;
|
|
11
|
+
const sep = destinationUrl.indexOf('?') >= 0 ? '&' : '?';
|
|
12
|
+
return `${destinationUrl}${sep}ethicly_click=${encodeURIComponent(clickToken)}`;
|
|
13
|
+
}
|
|
14
|
+
|
|
15
|
+
/** The /click budget: the website snippet aborts at exactly 500 ms. */
|
|
16
|
+
export const CLICK_TIMEOUT_MS = 500;
|
|
17
|
+
|
|
18
|
+
/**
|
|
19
|
+
* True for an absolute http: or https: URL with a host. Anything else (tel:,
|
|
20
|
+
* intent:, javascript:, a custom app scheme, a relative path) is never opened.
|
|
21
|
+
*/
|
|
22
|
+
export function isWebUrl(url: unknown): url is string {
|
|
23
|
+
return typeof url === 'string'
|
|
24
|
+
&& /^https?:\/\/[^\s/?#@]+(?:[/?#]|$)/i.test(url)
|
|
25
|
+
&& !/[\s\u0000-\u001f\u007f]/.test(url);
|
|
26
|
+
}
|