@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.
- package/CHANGELOG.md +92 -0
- package/README.md +189 -12
- package/lib/commonjs/core/cache.js +2 -0
- package/lib/commonjs/core/client.js +245 -62
- package/lib/commonjs/core/config.js +4 -1
- package/lib/commonjs/core/houseTracker.js +92 -0
- package/lib/commonjs/core/tracker.js +3 -0
- package/lib/commonjs/react/EthiclyInterstitial.js +23 -4
- package/lib/commonjs/react/useEthiclyInterstitial.js +26 -7
- package/lib/commonjs/version.js +1 -1
- package/lib/module/core/cache.js +2 -0
- package/lib/module/core/client.js +245 -62
- package/lib/module/core/config.js +4 -1
- package/lib/module/core/houseTracker.js +88 -0
- package/lib/module/core/tracker.js +3 -0
- package/lib/module/react/EthiclyInterstitial.js +23 -4
- package/lib/module/react/useEthiclyInterstitial.js +26 -7
- package/lib/module/version.js +1 -1
- package/lib/typescript/core/cache.d.ts +3 -1
- package/lib/typescript/core/client.d.ts +43 -4
- package/lib/typescript/core/houseTracker.d.ts +53 -0
- package/lib/typescript/core/index.d.ts +1 -1
- package/lib/typescript/core/types.d.ts +87 -2
- package/lib/typescript/react/EthiclyInterstitial.d.ts +7 -0
- package/lib/typescript/react/useEthiclyInterstitial.d.ts +19 -3
- package/lib/typescript/version.d.ts +1 -1
- package/package.json +1 -1
- package/src/core/cache.ts +4 -2
- package/src/core/client.ts +277 -62
- package/src/core/config.ts +4 -1
- package/src/core/houseTracker.ts +108 -0
- package/src/core/index.ts +3 -2
- package/src/core/tracker.ts +2 -0
- package/src/core/types.ts +96 -2
- package/src/react/EthiclyInterstitial.tsx +26 -4
- package/src/react/useEthiclyInterstitial.ts +45 -10
- package/src/version.ts +1 -1
package/src/core/index.ts
CHANGED
|
@@ -9,6 +9,7 @@ export { appendClickToken, CLICK_TIMEOUT_MS } from './click';
|
|
|
9
9
|
export { compareVersions, BUNDLED_BASE_URL } from './config';
|
|
10
10
|
export { SDK_VERSION } from '../version';
|
|
11
11
|
export type {
|
|
12
|
-
AudioPolicy, EthiclyAd, EthiclyAdMedia, EthiclyConfig, FetchLike, FileCacheAdapter,
|
|
13
|
-
InterstitialResult, KeyValueStorage, Logger,
|
|
12
|
+
AudioPolicy, EthiclyAd, EthiclyAdMedia, EthiclyConfig, FetchLike, FileCacheAdapter, FrequencyOptions,
|
|
13
|
+
FrequencyUpdate, InterstitialResult, KeyValueStorage, LoadOptions, Logger, NextAdReason, NextAdStatus, NoFillReason,
|
|
14
|
+
Platform, Tracker,
|
|
14
15
|
} from './types';
|
package/src/core/tracker.ts
CHANGED
|
@@ -353,6 +353,8 @@ export class InterstitialTracker implements Tracker {
|
|
|
353
353
|
const body: Record<string, unknown> = { ad_id: ad.id, impression_id: imp.id };
|
|
354
354
|
if (serve.publisherSiteId) body.publisher_site_id = serve.publisherSiteId;
|
|
355
355
|
if (serve.countryCode) body.country_code = serve.countryCode;
|
|
356
|
+
// Proof the view was served: lets the server bill a tap made before /viewable.
|
|
357
|
+
if (imp.viewableToken) body.viewable_token = imp.viewableToken;
|
|
356
358
|
// Never retried: one request, whatever happens.
|
|
357
359
|
const res = await httpRequest(ctx.fetch, `${ctx.serveBase()}/click`, {
|
|
358
360
|
method: 'POST', headers: ctx.headers(), body, timeoutMs: Math.min(remaining, BEACON_TIMEOUT_MS),
|
package/src/core/types.ts
CHANGED
|
@@ -14,6 +14,16 @@ export interface EthiclyConfig {
|
|
|
14
14
|
max_per_session: number;
|
|
15
15
|
min_gap_s: number;
|
|
16
16
|
audio: AudioPolicy;
|
|
17
|
+
/**
|
|
18
|
+
* Whether the paid-ad screen shows "Sponsored by Ethicly.ch", set in the
|
|
19
|
+
* publisher's dashboard. Absent from the server: true.
|
|
20
|
+
*/
|
|
21
|
+
sponsor_label: boolean;
|
|
22
|
+
/**
|
|
23
|
+
* The publisher's dashboard master switch for house ads. false: the SDK
|
|
24
|
+
* never asks for one. Absent from the server: true.
|
|
25
|
+
*/
|
|
26
|
+
house_ads: boolean;
|
|
17
27
|
};
|
|
18
28
|
prefetch: { max_cached_creatives: number; max_cache_mb: number };
|
|
19
29
|
beacon: { viewable_after_ms: number; flush_interval_s: number };
|
|
@@ -133,6 +143,18 @@ export interface EthiclyAd {
|
|
|
133
143
|
servedAt: number;
|
|
134
144
|
/** Epoch ms after which the ad must not be shown (served + token_ttl_s). */
|
|
135
145
|
expiresAt: number;
|
|
146
|
+
/**
|
|
147
|
+
* True for the publisher's own house ad, uploaded in the dashboard and shown
|
|
148
|
+
* when no paid ad fills. Unbilled, but it counts toward the frequency caps.
|
|
149
|
+
*/
|
|
150
|
+
house: boolean;
|
|
151
|
+
/** For a house ad: why no paid ad filled (the server's reason). Unset for a paid ad. */
|
|
152
|
+
noFillReason?: NoFillReason;
|
|
153
|
+
/**
|
|
154
|
+
* Show "Sponsored by Ethicly.ch" with this ad. false for house ads, else the
|
|
155
|
+
* dashboard setting (/config interstitial.sponsor_label, default true).
|
|
156
|
+
*/
|
|
157
|
+
showSponsorLabel: boolean;
|
|
136
158
|
}
|
|
137
159
|
|
|
138
160
|
export interface Tracker {
|
|
@@ -143,14 +165,28 @@ export interface Tracker {
|
|
|
143
165
|
complete(): void;
|
|
144
166
|
skipped(positionMs: number): void;
|
|
145
167
|
error(): void;
|
|
146
|
-
/**
|
|
147
|
-
|
|
168
|
+
/**
|
|
169
|
+
* POST /click (500 ms budget), then open the destination. Resolves with the URL opened.
|
|
170
|
+
* House ads only: `{ open: false }` counts the tap without opening anything,
|
|
171
|
+
* for an app that sends it to its own screen. A paid ad always opens the
|
|
172
|
+
* advertiser's page.
|
|
173
|
+
*/
|
|
174
|
+
clicked(opts?: { open?: boolean }): Promise<string>;
|
|
148
175
|
/** Call when the ad screen goes away. Sends queued video events. */
|
|
149
176
|
closed(): Promise<void>;
|
|
150
177
|
/** True once the ad is older than token_ttl_s: it must not be shown. */
|
|
151
178
|
isExpired(): boolean;
|
|
152
179
|
}
|
|
153
180
|
|
|
181
|
+
/** Per-call options for preload() and loadInterstitial(). */
|
|
182
|
+
export interface LoadOptions {
|
|
183
|
+
/**
|
|
184
|
+
* false treats a house ad as no fill for this call, so the app can show its
|
|
185
|
+
* own fallback. Default: the client's setting (options.houseAds, default true).
|
|
186
|
+
*/
|
|
187
|
+
houseAds?: boolean;
|
|
188
|
+
}
|
|
189
|
+
|
|
154
190
|
export type InterstitialResult =
|
|
155
191
|
| { ad: EthiclyAd; tracker: Tracker; reason?: undefined }
|
|
156
192
|
| { ad: null; tracker: null; reason: NoFillReason };
|
|
@@ -173,9 +209,15 @@ export interface WireAd {
|
|
|
173
209
|
} | null;
|
|
174
210
|
}
|
|
175
211
|
|
|
212
|
+
/** Raw house ad, sent next to `ad: null` on an interstitial no-fill when the serve asked with house_ads=1. */
|
|
213
|
+
export interface WireHouseAd extends WireAd {
|
|
214
|
+
test?: boolean;
|
|
215
|
+
}
|
|
216
|
+
|
|
176
217
|
export interface WireServe {
|
|
177
218
|
ad: WireAd | null;
|
|
178
219
|
reason?: string;
|
|
220
|
+
house_ad?: WireHouseAd | null;
|
|
179
221
|
publisher_site_id?: number;
|
|
180
222
|
country_code?: string;
|
|
181
223
|
impression_token?: string;
|
|
@@ -183,3 +225,55 @@ export interface WireServe {
|
|
|
183
225
|
test?: boolean;
|
|
184
226
|
request_id?: string;
|
|
185
227
|
}
|
|
228
|
+
|
|
229
|
+
/**
|
|
230
|
+
* How often ads may show, set in code. Each field set here wins over the
|
|
231
|
+
* dashboard value from /config (interstitial.max_per_session, min_gap_s);
|
|
232
|
+
* an unset field falls back to /config, then to the defaults (3 and 120).
|
|
233
|
+
*/
|
|
234
|
+
export interface FrequencyOptions {
|
|
235
|
+
/**
|
|
236
|
+
* Ads per session. 0 shows none. Any integer >= 0; Infinity (or a large
|
|
237
|
+
* number such as 1000000) means no session limit.
|
|
238
|
+
*/
|
|
239
|
+
maxPerSession?: number;
|
|
240
|
+
/** Seconds between two ads, kept across restarts. 0 means no gap. Finite, >= 0. */
|
|
241
|
+
minGapSeconds?: number;
|
|
242
|
+
}
|
|
243
|
+
|
|
244
|
+
/** setFrequency(): a field left out keeps its current value, null goes back to /config. */
|
|
245
|
+
export interface FrequencyUpdate {
|
|
246
|
+
maxPerSession?: number | null;
|
|
247
|
+
minGapSeconds?: number | null;
|
|
248
|
+
}
|
|
249
|
+
|
|
250
|
+
/** Why nextAdStatus() says no ad may show now. */
|
|
251
|
+
export type NextAdReason =
|
|
252
|
+
/** The gap between ads (min_gap_s) has not passed: see retryAt. */
|
|
253
|
+
| 'frequency_capped'
|
|
254
|
+
/** max_per_session ads were shown this session. */
|
|
255
|
+
| 'session_cap'
|
|
256
|
+
/** setAdsEnabled(false), for example a paid user. */
|
|
257
|
+
| 'ads_disabled'
|
|
258
|
+
/** The stored frequency state is still loading (see `ready`). */
|
|
259
|
+
| 'not_ready'
|
|
260
|
+
| 'invalid_key'
|
|
261
|
+
| 'unknown_key'
|
|
262
|
+
| 'sdk_unsupported'
|
|
263
|
+
| 'app_disabled'
|
|
264
|
+
| 'interstitial_disabled';
|
|
265
|
+
|
|
266
|
+
export interface NextAdStatus {
|
|
267
|
+
/** Same as canShow(). */
|
|
268
|
+
allowed: boolean;
|
|
269
|
+
/** Set when allowed is false. */
|
|
270
|
+
reason?: NextAdReason;
|
|
271
|
+
/** Epoch ms when the gap ends. Only with reason 'frequency_capped'. */
|
|
272
|
+
retryAt?: number;
|
|
273
|
+
/** Ads shown in the current session. */
|
|
274
|
+
shownThisSession: number;
|
|
275
|
+
/** The effective per-session limit (Infinity for none). */
|
|
276
|
+
maxPerSession: number;
|
|
277
|
+
/** The effective gap between ads, in seconds. */
|
|
278
|
+
minGapSeconds: number;
|
|
279
|
+
}
|
|
@@ -1,7 +1,9 @@
|
|
|
1
1
|
// Optional ready-made fullscreen screen. Needs expo-video (Expo SDK 52+).
|
|
2
2
|
// Layout follows a typical in-app video player: 9:16 video, a skip control that counts
|
|
3
3
|
// down then reads "Skip Ad", a white call-to-action button, an optional
|
|
4
|
-
// "Remove ads" slot and a small "Sponsored by Ethicly.ch" line under it.
|
|
4
|
+
// "Remove ads" slot and a small "Sponsored by Ethicly.ch" line under it. The
|
|
5
|
+
// line follows ad.showSponsorLabel: hidden for house ads, and for paid ads when
|
|
6
|
+
// the publisher switched it off in the dashboard.
|
|
5
7
|
// Video starts with sound unless the effective audio (the `audio` prop, else
|
|
6
8
|
// ad.audio: createEthicly's `audio` option, else /config) is 'none' or 'optional'.
|
|
7
9
|
// The controls keep clear of the notch, status bar and home indicator: see
|
|
@@ -26,6 +28,13 @@ export interface EthiclyInterstitialProps {
|
|
|
26
28
|
/** Shows a "Remove ads" link under the button that calls this. */
|
|
27
29
|
onRemoveAds?(): void;
|
|
28
30
|
removeAdsLabel?: string;
|
|
31
|
+
/**
|
|
32
|
+
* House ads only: a tap on the button counts the tap, closes the ad (as
|
|
33
|
+
* onClose does) and calls this instead of opening the house ad's link, for
|
|
34
|
+
* example to open the app's premium screen. Wins over the hook's and
|
|
35
|
+
* createEthicly's onHouseAdPress. Paid ads always open the advertiser's page.
|
|
36
|
+
*/
|
|
37
|
+
onHouseAdPress?(ad: EthiclyAd): void;
|
|
29
38
|
/** Replaces the "Remove ads" link with anything the app wants. */
|
|
30
39
|
renderBelowButton?(): React.ReactNode;
|
|
31
40
|
/** Default true: wraps the screen in a fullscreen Modal. */
|
|
@@ -160,7 +169,7 @@ interface BodyProps extends EthiclyInterstitialProps {
|
|
|
160
169
|
}
|
|
161
170
|
|
|
162
171
|
function InterstitialBody({
|
|
163
|
-
ad, tracker, onClose, onRemoveAds, removeAdsLabel, renderBelowButton, skipStyle, skipTextStyle, insets, backRef, audio: audioProp,
|
|
172
|
+
ad, tracker, onClose, onRemoveAds, removeAdsLabel, onHouseAdPress, renderBelowButton, skipStyle, skipTextStyle, insets, backRef, audio: audioProp,
|
|
164
173
|
}: BodyProps) {
|
|
165
174
|
const audio = effectiveAudio(audioProp, ad);
|
|
166
175
|
const safe = useSafeInsets(insets);
|
|
@@ -291,12 +300,25 @@ function InterstitialBody({
|
|
|
291
300
|
}, [ended, failed, isVideo, onClose, tracker]);
|
|
292
301
|
|
|
293
302
|
const onCta = useCallback(() => {
|
|
303
|
+
// A house ad the app routes to its own screen: count the tap, close the
|
|
304
|
+
// ad the normal way, then hand over. Never for a paid ad.
|
|
305
|
+
const housePress = ad.house
|
|
306
|
+
? onHouseAdPress || (tracker as { houseAdPress?: (a: EthiclyAd) => void }).houseAdPress
|
|
307
|
+
: undefined;
|
|
308
|
+
if (housePress) {
|
|
309
|
+
// A second tap before the screen unmounts must not run the handler twice.
|
|
310
|
+
if (closedRef.current) return;
|
|
311
|
+
void tracker.clicked({ open: false });
|
|
312
|
+
close();
|
|
313
|
+
try { housePress(ad); } catch { /* the app's handler must not break the screen */ }
|
|
314
|
+
return;
|
|
315
|
+
}
|
|
294
316
|
if (isVideo) player.pause();
|
|
295
317
|
// Once the user has visited the advertiser, they can always close the ad
|
|
296
318
|
// when they come back.
|
|
297
319
|
setClicked(true);
|
|
298
320
|
void tracker.clicked();
|
|
299
|
-
}, [isVideo, player, tracker]);
|
|
321
|
+
}, [ad, close, isVideo, onHouseAdPress, player, tracker]);
|
|
300
322
|
|
|
301
323
|
const toggleSound = useCallback(() => {
|
|
302
324
|
setMuted((m) => {
|
|
@@ -373,7 +395,7 @@ function InterstitialBody({
|
|
|
373
395
|
<Text style={styles.removeAds}>{removeAdsLabel || 'Remove ads'}</Text>
|
|
374
396
|
</Pressable>
|
|
375
397
|
) : null}
|
|
376
|
-
<Text style={styles.sponsor}>Sponsored by Ethicly.ch</Text>
|
|
398
|
+
{ad.showSponsorLabel ? <Text style={styles.sponsor}>Sponsored by Ethicly.ch</Text> : null}
|
|
377
399
|
</View>
|
|
378
400
|
</View>
|
|
379
401
|
);
|
|
@@ -3,18 +3,32 @@
|
|
|
3
3
|
|
|
4
4
|
import { useCallback, useEffect, useRef, useState } from 'react';
|
|
5
5
|
import type { Ethicly } from '../core/client';
|
|
6
|
-
import type { EthiclyAd, NoFillReason, Tracker } from '../core/types';
|
|
6
|
+
import type { EthiclyAd, NextAdStatus, NoFillReason, Tracker } from '../core/types';
|
|
7
7
|
|
|
8
8
|
export interface UseEthiclyInterstitialOptions {
|
|
9
9
|
/** Preload on mount and after each dismiss. Default true. */
|
|
10
10
|
preload?: boolean;
|
|
11
|
+
/**
|
|
12
|
+
* false treats a house ad as no fill, so `reason` is set and the app shows
|
|
13
|
+
* its own fallback. Default: the client's setting (createEthicly houseAds).
|
|
14
|
+
*/
|
|
15
|
+
houseAds?: boolean;
|
|
16
|
+
/**
|
|
17
|
+
* House ads only: where EthiclyInterstitial sends a tap on the button
|
|
18
|
+
* instead of opening the link (the ad closes first). Wins over
|
|
19
|
+
* createEthicly's onHouseAdPress; the screen's own prop wins over this.
|
|
20
|
+
*/
|
|
21
|
+
onHouseAdPress?: (ad: EthiclyAd) => void;
|
|
11
22
|
}
|
|
12
23
|
|
|
13
24
|
export interface EthiclyInterstitialState {
|
|
14
|
-
/** The ad to render, set by a successful show(). */
|
|
25
|
+
/** The ad to render, set by a successful show(). `ad.house` is true for the publisher's house ad. */
|
|
15
26
|
ad: EthiclyAd | null;
|
|
16
27
|
tracker: Tracker | null;
|
|
17
|
-
/**
|
|
28
|
+
/**
|
|
29
|
+
* Why the last show() found no ad: show your own fallback if you have one,
|
|
30
|
+
* except for 'ads_disabled' (a paid user). Null when a house ad was shown.
|
|
31
|
+
*/
|
|
18
32
|
reason: NoFillReason | null;
|
|
19
33
|
loading: boolean;
|
|
20
34
|
/** Load the ad to show now. Resolves true when `ad` is set, false on no fill. */
|
|
@@ -22,6 +36,8 @@ export interface EthiclyInterstitialState {
|
|
|
22
36
|
/** Close the current ad: flushes queued events and preloads the next one. */
|
|
23
37
|
dismiss(): void;
|
|
24
38
|
canShow(): boolean;
|
|
39
|
+
/** Whether an ad may show now and, when not, why and until when. Same as ethicly.nextAdStatus(). */
|
|
40
|
+
nextAdStatus(): NextAdStatus;
|
|
25
41
|
}
|
|
26
42
|
|
|
27
43
|
export function useEthiclyInterstitial(
|
|
@@ -29,6 +45,9 @@ export function useEthiclyInterstitial(
|
|
|
29
45
|
options: UseEthiclyInterstitialOptions = {},
|
|
30
46
|
): EthiclyInterstitialState {
|
|
31
47
|
const preload = options.preload !== false;
|
|
48
|
+
const houseAds = options.houseAds;
|
|
49
|
+
const housePressRef = useRef(options.onHouseAdPress);
|
|
50
|
+
housePressRef.current = options.onHouseAdPress;
|
|
32
51
|
const [current, setCurrent] = useState<{ ad: EthiclyAd; tracker: Tracker } | null>(null);
|
|
33
52
|
const [reason, setReason] = useState<NoFillReason | null>(null);
|
|
34
53
|
const [loading, setLoading] = useState(false);
|
|
@@ -38,19 +57,32 @@ export function useEthiclyInterstitial(
|
|
|
38
57
|
|
|
39
58
|
useEffect(() => {
|
|
40
59
|
mounted.current = true;
|
|
41
|
-
if (preload) void ethicly.preload();
|
|
60
|
+
if (preload) void ethicly.preload({ houseAds });
|
|
42
61
|
return () => {
|
|
43
62
|
mounted.current = false;
|
|
44
63
|
void currentRef.current?.tracker.closed();
|
|
45
64
|
};
|
|
46
|
-
}, [ethicly, preload]);
|
|
65
|
+
}, [ethicly, preload, houseAds]);
|
|
47
66
|
|
|
48
67
|
const show = useCallback(async (): Promise<boolean> => {
|
|
49
68
|
setLoading(true);
|
|
50
69
|
try {
|
|
51
|
-
const r = await ethicly.loadInterstitial();
|
|
70
|
+
const r = await ethicly.loadInterstitial({ houseAds });
|
|
52
71
|
if (!mounted.current) return false;
|
|
53
72
|
if (r.ad) {
|
|
73
|
+
if (r.ad.house) {
|
|
74
|
+
// Read at tap time: the hook's latest handler wins, else the client's
|
|
75
|
+
// (set when the ad was built), else the link opens. A handler added or
|
|
76
|
+
// removed after the ad loaded is respected.
|
|
77
|
+
const t = r.tracker as { houseAdPress?: (a: EthiclyAd) => void };
|
|
78
|
+
const clientPress = t.houseAdPress;
|
|
79
|
+
Object.defineProperty(t, 'houseAdPress', {
|
|
80
|
+
configurable: true,
|
|
81
|
+
enumerable: true,
|
|
82
|
+
get: () => housePressRef.current ?? clientPress,
|
|
83
|
+
set: () => { /* fixed for this ad: the hook resolves it */ },
|
|
84
|
+
});
|
|
85
|
+
}
|
|
54
86
|
setCurrent({ ad: r.ad, tracker: r.tracker });
|
|
55
87
|
setReason(null);
|
|
56
88
|
return true;
|
|
@@ -60,15 +92,18 @@ export function useEthiclyInterstitial(
|
|
|
60
92
|
} finally {
|
|
61
93
|
if (mounted.current) setLoading(false);
|
|
62
94
|
}
|
|
63
|
-
}, [ethicly]);
|
|
95
|
+
}, [ethicly, houseAds]);
|
|
64
96
|
|
|
65
97
|
const dismiss = useCallback(() => {
|
|
66
98
|
void currentRef.current?.tracker.closed();
|
|
67
99
|
setCurrent(null);
|
|
68
|
-
if (preload) void ethicly.preload();
|
|
69
|
-
}, [ethicly, preload]);
|
|
100
|
+
if (preload) void ethicly.preload({ houseAds });
|
|
101
|
+
}, [ethicly, preload, houseAds]);
|
|
70
102
|
|
|
71
103
|
const canShow = useCallback(() => ethicly.canShow(), [ethicly]);
|
|
104
|
+
const nextAdStatus = useCallback(() => ethicly.nextAdStatus(), [ethicly]);
|
|
72
105
|
|
|
73
|
-
return {
|
|
106
|
+
return {
|
|
107
|
+
ad: current?.ad ?? null, tracker: current?.tracker ?? null, reason, loading, show, dismiss, canShow, nextAdStatus,
|
|
108
|
+
};
|
|
74
109
|
}
|
package/src/version.ts
CHANGED
|
@@ -1,2 +1,2 @@
|
|
|
1
1
|
/** SDK version, sent as sdk_version and in X-Ethicly-SDK. Keep in step with package.json. */
|
|
2
|
-
export const SDK_VERSION = '0.
|
|
2
|
+
export const SDK_VERSION = '0.4.0';
|