@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/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, NoFillReason, Platform, Tracker,
12
+ AudioPolicy, EthiclyAd, EthiclyAdMedia, EthiclyConfig, FetchLike, FileCacheAdapter, FrequencyOptions,
13
+ FrequencyUpdate, InterstitialResult, KeyValueStorage, LoadOptions, Logger, NextAdReason, NextAdStatus, NoFillReason,
14
+ Platform, Tracker,
14
15
  } from './types';
@@ -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
- /** POST /click (500 ms budget), then open the destination. Resolves with the URL opened. */
147
- clicked(): Promise<string>;
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
- /** Why the last show() found no ad: show your house ad, except for 'ads_disabled' (a paid user). */
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 { ad: current?.ad ?? null, tracker: current?.tracker ?? null, reason, loading, show, dismiss, canShow };
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.1';
2
+ export const SDK_VERSION = '0.4.0';