@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.
Files changed (70) hide show
  1. package/CHANGELOG.md +133 -0
  2. package/LICENSE +21 -0
  3. package/README.md +428 -2
  4. package/core/package.json +6 -0
  5. package/interstitial/package.json +6 -0
  6. package/lib/commonjs/core/adapters.js +326 -0
  7. package/lib/commonjs/core/beacons.js +70 -0
  8. package/lib/commonjs/core/cache.js +261 -0
  9. package/lib/commonjs/core/click.js +29 -0
  10. package/lib/commonjs/core/client.js +585 -0
  11. package/lib/commonjs/core/config.js +128 -0
  12. package/lib/commonjs/core/http.js +115 -0
  13. package/lib/commonjs/core/index.js +21 -0
  14. package/lib/commonjs/core/outbox.js +192 -0
  15. package/lib/commonjs/core/tracker.js +379 -0
  16. package/lib/commonjs/core/types.js +4 -0
  17. package/lib/commonjs/index.js +22 -0
  18. package/lib/commonjs/interstitial.js +7 -0
  19. package/lib/commonjs/react/EthiclyInterstitial.js +319 -0
  20. package/lib/commonjs/react/useEthiclyInterstitial.js +54 -0
  21. package/lib/commonjs/version.js +5 -0
  22. package/lib/module/core/adapters.js +315 -0
  23. package/lib/module/core/beacons.js +64 -0
  24. package/lib/module/core/cache.js +257 -0
  25. package/lib/module/core/click.js +24 -0
  26. package/lib/module/core/client.js +581 -0
  27. package/lib/module/core/config.js +118 -0
  28. package/lib/module/core/http.js +105 -0
  29. package/lib/module/core/index.js +6 -0
  30. package/lib/module/core/outbox.js +186 -0
  31. package/lib/module/core/tracker.js +375 -0
  32. package/lib/module/core/types.js +3 -0
  33. package/lib/module/index.js +4 -0
  34. package/lib/module/interstitial.js +3 -0
  35. package/lib/module/react/EthiclyInterstitial.js +292 -0
  36. package/lib/module/react/useEthiclyInterstitial.js +51 -0
  37. package/lib/module/version.js +2 -0
  38. package/lib/typescript/core/adapters.d.ts +139 -0
  39. package/lib/typescript/core/beacons.d.ts +32 -0
  40. package/lib/typescript/core/cache.d.ts +71 -0
  41. package/lib/typescript/core/click.d.ts +13 -0
  42. package/lib/typescript/core/client.d.ts +78 -0
  43. package/lib/typescript/core/config.d.ts +33 -0
  44. package/lib/typescript/core/http.d.ts +34 -0
  45. package/lib/typescript/core/index.d.ts +8 -0
  46. package/lib/typescript/core/outbox.d.ts +56 -0
  47. package/lib/typescript/core/tracker.d.ts +95 -0
  48. package/lib/typescript/core/types.d.ts +175 -0
  49. package/lib/typescript/index.d.ts +3 -0
  50. package/lib/typescript/interstitial.d.ts +2 -0
  51. package/lib/typescript/react/EthiclyInterstitial.d.ts +51 -0
  52. package/lib/typescript/react/useEthiclyInterstitial.d.ts +20 -0
  53. package/lib/typescript/version.d.ts +2 -0
  54. package/package.json +101 -4
  55. package/src/core/adapters.ts +365 -0
  56. package/src/core/beacons.ts +81 -0
  57. package/src/core/cache.ts +261 -0
  58. package/src/core/click.ts +26 -0
  59. package/src/core/client.ts +665 -0
  60. package/src/core/config.ts +124 -0
  61. package/src/core/http.ts +115 -0
  62. package/src/core/index.ts +14 -0
  63. package/src/core/outbox.ts +193 -0
  64. package/src/core/tracker.ts +376 -0
  65. package/src/core/types.ts +185 -0
  66. package/src/index.ts +5 -0
  67. package/src/interstitial.ts +4 -0
  68. package/src/react/EthiclyInterstitial.tsx +432 -0
  69. package/src/react/useEthiclyInterstitial.ts +74 -0
  70. package/src/version.ts +2 -0
@@ -0,0 +1,78 @@
1
+ import { type AppStateLike } from './adapters';
2
+ import type { AudioPolicy, EthiclyConfig, FetchLike, FileCacheAdapter, InterstitialResult, KeyValueStorage, Logger, NoFillReason, Platform } from './types';
3
+ export interface EthiclyOptions {
4
+ /** Publisher API key (UUID). */
5
+ apiKey: string;
6
+ /** The OS the app runs on. Never "rn": the server ignores unknown platforms. */
7
+ platform: Platform;
8
+ /** The host app's version, sent as app_version. */
9
+ appVersion: string;
10
+ /** The bundled URL /config is fetched from. Default https://ads.ethicly.ch/functions/v1/get-ad-with-geo */
11
+ baseUrl?: string;
12
+ /**
13
+ * Adds test=1 to serve. Ignored in a React Native release build
14
+ * (`__DEV__` false), where the SDK serves and bills normally and logs an error.
15
+ */
16
+ testMode?: boolean;
17
+ /**
18
+ * Initial state of the ads switch, default true. Apps with a paid tier: pass
19
+ * false until you know the user's entitlement, then setAdsEnabled(true) for
20
+ * free users, so a subscriber never serves or downloads an ad.
21
+ */
22
+ adsEnabled?: boolean;
23
+ /**
24
+ * Sound for every ad, over the server's interstitial.audio: 'on' plays with
25
+ * sound, 'optional' starts muted with a sound toggle, 'none' plays muted with
26
+ * no toggle. Unset: the server's value, which defaults to 'on'. `ad.audio`
27
+ * is the effective value. EthiclyInterstitial's `audio` prop overrides it per screen.
28
+ */
29
+ audio?: AudioPolicy;
30
+ /**
31
+ * The longest loadInterstitial() waits for the creative download when no
32
+ * preloaded ad is ready, in ms. Default 3000 (DEFAULT_LOAD_TIMEOUT_MS). After
33
+ * it the ad comes back with the remote URL, so the player streams, and the
34
+ * download carries on in the background for next time.
35
+ */
36
+ loadTimeoutMs?: number;
37
+ storage?: KeyValueStorage;
38
+ fileCache?: FileCacheAdapter;
39
+ openUrl?: (url: string) => unknown;
40
+ fetch?: FetchLike;
41
+ now?: () => number;
42
+ logger?: Logger;
43
+ /**
44
+ * App foreground and background changes, for sessions. Defaults to React
45
+ * Native's AppState; null turns sessions off (one session per process).
46
+ */
47
+ appState?: AppStateLike | null;
48
+ }
49
+ export interface Ethicly {
50
+ /** Resolves when the stored config is loaded and the first /config fetch settled. Never rejects. */
51
+ readonly ready: Promise<void>;
52
+ /** Serve and download an interstitial ahead of time. Does not consume it. */
53
+ preload(): Promise<InterstitialResult>;
54
+ /** The ad to show now: the preloaded one if still valid, else a fresh serve. Consumes it. */
55
+ loadInterstitial(): Promise<InterstitialResult>;
56
+ /**
57
+ * Frequency caps, the ads switch and the kill switch, checked client-side.
58
+ * false until the stored frequency state has loaded (see `ready`).
59
+ */
60
+ canShow(): boolean;
61
+ /** false for paid users: stops serves, drops the preloaded ad and cancels a download in flight. */
62
+ setAdsEnabled(enabled: boolean): void;
63
+ isAdsEnabled(): boolean;
64
+ getConfig(): EthiclyConfig;
65
+ /** Refetch /config now (subject to Retry-After). */
66
+ refreshConfig(): Promise<void>;
67
+ /** Why the last load returned no ad. */
68
+ readonly lastNoFillReason: NoFillReason | null;
69
+ readonly sdkVersion: string;
70
+ }
71
+ /** How long loadInterstitial() waits for a creative download by default. */
72
+ export declare const DEFAULT_LOAD_TIMEOUT_MS = 3000;
73
+ /**
74
+ * A new session (interstitial.max_per_session counts from zero again) starts
75
+ * when the app comes back after at least this long in the background.
76
+ */
77
+ export declare const SESSION_TIMEOUT_MS: number;
78
+ export declare function createEthicly(options: EthiclyOptions): Ethicly;
@@ -0,0 +1,33 @@
1
+ import type { EthiclyConfig } from './types';
2
+ export declare const BUNDLED_BASE_URL = "https://ads.ethicly.ch/functions/v1/get-ad-with-geo";
3
+ export declare const DEFAULT_MAX_AGE_S = 300;
4
+ /**
5
+ * The skip delay is kept within these bounds, from /config and from the ad:
6
+ * the video is watched for at least 8 s before Skip appears (it still
7
+ * unlocks earlier when the video ends or after the call to action).
8
+ */
9
+ export declare const MIN_SKIP_AFTER_MS = 8000;
10
+ export declare const MAX_SKIP_AFTER_MS = 15000;
11
+ /** A skip delay in ms within MIN_SKIP_AFTER_MS..MAX_SKIP_AFTER_MS, or null when not a number. */
12
+ export declare function clampSkipAfterMs(v: unknown): number | null;
13
+ /** The defaults shown in the doc. Used when no config was ever fetched. */
14
+ export declare function defaultConfig(serveBase: string): EthiclyConfig;
15
+ /** An https URL, without a trailing slash, or null. */
16
+ export declare function cleanServeBase(v: unknown): string | null;
17
+ /**
18
+ * Read a /config body leniently: every field is validated and falls back to
19
+ * the default, unknown fields are ignored. Returns null when the body is not a
20
+ * config at all.
21
+ */
22
+ export declare function parseConfig(body: unknown, bundledBase: string): EthiclyConfig | null;
23
+ /** max-age from Cache-Control, default 300 s. */
24
+ export declare function maxAgeSeconds(cacheControl: string | null): number;
25
+ /**
26
+ * Doc "Versioning > Comparison": leading dot-separated numeric components,
27
+ * everything from the first other character ignored. -1, 0, 1, or null when
28
+ * either side has no leading number. Mirrors compareVersions in the server's
29
+ * appConfig.ts.
30
+ */
31
+ export declare function compareVersions(a: unknown, b: unknown): number | null;
32
+ /** True only when `sdk` parses and is below `min`. */
33
+ export declare function isBelowMinSdk(sdk: string, min: string): boolean;
@@ -0,0 +1,34 @@
1
+ import type { FetchLike, ImpressionId } from './types';
2
+ export interface HttpResult {
3
+ /** 0 for a network error or timeout. */
4
+ status: number;
5
+ body: any;
6
+ /** Seconds from Retry-After, null when absent or unparseable. */
7
+ retryAfterS: number | null;
8
+ cacheControl: string | null;
9
+ timedOut: boolean;
10
+ }
11
+ /**
12
+ * impression_id is a 64-bit integer. JSON.parse would round anything above
13
+ * 2^53, so long ids are read as strings and written back as bare numbers.
14
+ */
15
+ export declare function parseJson(text: string): unknown;
16
+ export declare function stringifyJson(value: unknown): string;
17
+ export declare function asImpressionId(v: unknown): ImpressionId | null;
18
+ export declare function parseRetryAfter(v: string | null): number | null;
19
+ export declare function httpRequest(fetchFn: FetchLike, url: string, opts: {
20
+ method?: string;
21
+ headers: Record<string, string>;
22
+ body?: unknown;
23
+ timeoutMs: number;
24
+ }): Promise<HttpResult>;
25
+ /** On a 429 the route is closed until Retry-After has passed. */
26
+ export declare class RouteGate {
27
+ private now;
28
+ private until;
29
+ constructor(now: () => number);
30
+ block(route: string, retryAfterS: number | null): void;
31
+ /** Milliseconds until the route opens, 0 when open. */
32
+ waitMs(route: string): number;
33
+ }
34
+ export declare function sleep(ms: number): Promise<void>;
@@ -0,0 +1,8 @@
1
+ export { createEthicly, DEFAULT_LOAD_TIMEOUT_MS, SESSION_TIMEOUT_MS } from './client';
2
+ export type { Ethicly, EthiclyOptions } from './client';
3
+ export { createMemoryStorage, createMemoryFileCache, createExpoFileCache, uuidv4, } from './adapters';
4
+ export type { AppStateLike, ExpoFileSystemLike, ExpoFileSystemModernLike } from './adapters';
5
+ export { appendClickToken, CLICK_TIMEOUT_MS } from './click';
6
+ export { compareVersions, BUNDLED_BASE_URL } from './config';
7
+ export { SDK_VERSION } from '../version';
8
+ export type { AudioPolicy, EthiclyAd, EthiclyAdMedia, EthiclyConfig, FetchLike, FileCacheAdapter, InterstitialResult, KeyValueStorage, Logger, NoFillReason, Platform, Tracker, } from './types';
@@ -0,0 +1,56 @@
1
+ import { type BeaconContext } from './beacons';
2
+ import type { ImpressionId, KeyValueStorage, Logger } from './types';
3
+ export declare const MAX_OUTBOX_RECORDS = 20;
4
+ export interface OutboxEvent {
5
+ event: string;
6
+ ms: number | null;
7
+ }
8
+ /** One rendered ad's unsent beacons. */
9
+ export interface OutboxRecord {
10
+ /** client_impression_id. */
11
+ cid: string;
12
+ /** Epoch ms the ad was shown. Every beacon below is dropped one hour later. */
13
+ shownAt: number;
14
+ /** The /impression body while it has no answer. */
15
+ impression?: Record<string, unknown>;
16
+ /** Known once /impression answered. */
17
+ impressionId?: ImpressionId;
18
+ viewableToken?: string | null;
19
+ /** viewable_ms of a /viewable still to send. */
20
+ viewableMs?: number;
21
+ events: OutboxEvent[];
22
+ }
23
+ export declare function outboxFor(storage: KeyValueStorage, apiKey: string, log: Required<Logger>): Outbox;
24
+ export declare class Outbox {
25
+ private storage;
26
+ private key;
27
+ private log;
28
+ private records;
29
+ /** Records a tracker or a replay in this runtime is already sending. */
30
+ private owned;
31
+ private loaded;
32
+ private dirty;
33
+ private writing;
34
+ constructor(storage: KeyValueStorage, key: string, log: Required<Logger>);
35
+ /** Read what a previous run left. Never rejects. */
36
+ load(): Promise<void>;
37
+ /** Save or replace a record owned by this runtime. */
38
+ put(rec: OutboxRecord): void;
39
+ remove(cid: string): void;
40
+ /**
41
+ * Unexpired records nobody in this runtime is sending, now owned by the
42
+ * caller. Expired ones are dropped.
43
+ */
44
+ claimOrphans(now: number): OutboxRecord[];
45
+ /** Coalesced write of the whole outbox, after the stored one was read. Never rejects. */
46
+ private save;
47
+ /** Resolves when nothing is waiting to be written. For tests. */
48
+ flushed(): Promise<void>;
49
+ }
50
+ /**
51
+ * Send what a previous run left for one ad, with the live tracker's rules:
52
+ * /impression first (same client_impression_id), then /viewable, then the
53
+ * video events. Anything the server refuses, or that is past one hour, is
54
+ * dropped. Never throws.
55
+ */
56
+ export declare function replayRecord(ctx: BeaconContext, outbox: Outbox, rec: OutboxRecord): Promise<void>;
@@ -0,0 +1,95 @@
1
+ import { type BeaconContext } from './beacons';
2
+ import type { Outbox } from './outbox';
3
+ import type { EthiclyAd, ImpressionId, Tracker } from './types';
4
+ export interface ServeContext {
5
+ publisherSiteId: number | null;
6
+ countryCode: string | null;
7
+ impressionToken: string | null;
8
+ }
9
+ export interface TrackerDeps {
10
+ ctx: BeaconContext;
11
+ ad: EthiclyAd;
12
+ serve: ServeContext;
13
+ viewableAfterMs: number;
14
+ flushIntervalS: number;
15
+ platform: string;
16
+ sdkVersion: string;
17
+ appVersion: string;
18
+ openUrl?: (url: string) => unknown;
19
+ /** Called once when the ad is shown, for the frequency caps. */
20
+ onShown(): void;
21
+ /** Keeps unsent beacons in storage so they survive the app being killed. */
22
+ outbox?: Outbox;
23
+ }
24
+ /** Doc "Still-image interstitials": /viewable after 1000 ms on screen. */
25
+ export declare const STILL_VIEWABLE_MS = 1000;
26
+ /**
27
+ * A wall-clock gap between two progress() calls longer than this breaks
28
+ * "continuous" playback: a host player that stops ticking while the app is in
29
+ * the background must not count the time it was away.
30
+ */
31
+ export declare const MAX_TICK_GAP_MS = 1500;
32
+ interface Impression {
33
+ id: ImpressionId;
34
+ viewableToken: string | null;
35
+ at: number;
36
+ }
37
+ export declare class InterstitialTracker implements Tracker {
38
+ private d;
39
+ /** Exposed for tests and debug logs. */
40
+ clientImpressionId: string | null;
41
+ impression: Impression | null;
42
+ /** True when the impression can never bill (doc lifecycle rule 5, or a refused beacon). */
43
+ unbillable: boolean;
44
+ private impressionDone;
45
+ private viewableSent;
46
+ private continuousMs;
47
+ /** viewable_ms as measured when the threshold was crossed. */
48
+ private viewableMs;
49
+ private last;
50
+ private sentOnce;
51
+ private queue;
52
+ private timer;
53
+ private isClosed;
54
+ private clickUrl;
55
+ private pending;
56
+ private flushChain;
57
+ private shownAt;
58
+ /** The /impression body until it has an answer. */
59
+ private impressionBody;
60
+ /** viewable_ms of a /viewable not yet answered. */
61
+ private viewablePending;
62
+ /** Video events queued or in flight. */
63
+ private unsent;
64
+ constructor(d: TrackerDeps);
65
+ private get isVideo();
66
+ private track;
67
+ /** Resolves when every beacon in flight has settled. For tests and shutdown. */
68
+ settle(): Promise<void>;
69
+ isExpired(): boolean;
70
+ shown(size?: {
71
+ width?: number;
72
+ height?: number;
73
+ }): Promise<void>;
74
+ /**
75
+ * Mirror what this ad still owes the server into the outbox, or drop it
76
+ * there once nothing is owed. Never throws.
77
+ */
78
+ private persist;
79
+ private sendImpression;
80
+ progress(positionMs: number, opts: {
81
+ visible: boolean;
82
+ durationMs?: number;
83
+ }): void;
84
+ private sendViewable;
85
+ private enqueueOnce;
86
+ complete(): void;
87
+ skipped(positionMs: number): void;
88
+ error(): void;
89
+ /** Send every queued video event, one request each (there is no batch route). */
90
+ flush(): Promise<void>;
91
+ clicked(): Promise<string>;
92
+ private resolveClickUrl;
93
+ closed(): Promise<void>;
94
+ }
95
+ export {};
@@ -0,0 +1,175 @@
1
+ export type Platform = 'ios' | 'android';
2
+ export type AudioPolicy = 'none' | 'optional' | 'on';
3
+ /** The /config body (doc "GET /config"). Unknown fields are ignored. */
4
+ export interface EthiclyConfig {
5
+ enabled: boolean;
6
+ min_sdk: {
7
+ ios: string;
8
+ android: string;
9
+ };
10
+ formats: string[];
11
+ interstitial: {
12
+ skip_after_ms: number;
13
+ max_per_session: number;
14
+ min_gap_s: number;
15
+ audio: AudioPolicy;
16
+ };
17
+ prefetch: {
18
+ max_cached_creatives: number;
19
+ max_cache_mb: number;
20
+ };
21
+ beacon: {
22
+ viewable_after_ms: number;
23
+ flush_interval_s: number;
24
+ };
25
+ endpoints: {
26
+ serve: string;
27
+ };
28
+ }
29
+ /** AsyncStorage-shaped key-value store. */
30
+ export interface KeyValueStorage {
31
+ getItem(key: string): Promise<string | null>;
32
+ setItem(key: string, value: string): Promise<void>;
33
+ removeItem?(key: string): Promise<void>;
34
+ }
35
+ /** expo-file-system-shaped creative store. */
36
+ export interface FileCacheAdapter {
37
+ /**
38
+ * Download `url` into the cache under `fileName`; resolve the local uri.
39
+ * Should abort (reject, leaving no file) once more than `maxBytes` would be written.
40
+ */
41
+ download(url: string, fileName: string, opts?: {
42
+ maxBytes?: number;
43
+ }): Promise<{
44
+ uri: string;
45
+ bytes?: number;
46
+ }>;
47
+ exists(uri: string): Promise<boolean>;
48
+ delete(uri: string): Promise<void>;
49
+ /** Size in bytes, 0 when unknown. */
50
+ size(uri: string): Promise<number>;
51
+ /** Every file in the SDK's cache directory. Lets the cache sweep files it no longer indexes. */
52
+ list?(): Promise<string[]>;
53
+ /** The uri `download(url, fileName)` writes to, so an unfinished download can be deleted. */
54
+ uriFor?(fileName: string): string;
55
+ /**
56
+ * Abort every download in flight: each rejects and leaves no file. Optional;
57
+ * used by setAdsEnabled(false) and for a download that takes too long.
58
+ */
59
+ cancel?(): void;
60
+ }
61
+ export interface Logger {
62
+ debug?(message: string, ...rest: unknown[]): void;
63
+ info?(message: string, ...rest: unknown[]): void;
64
+ warn?(message: string, ...rest: unknown[]): void;
65
+ error?(message: string, ...rest: unknown[]): void;
66
+ }
67
+ /** The subset of a fetch Response the SDK reads. */
68
+ export interface ResponseLike {
69
+ status: number;
70
+ headers: {
71
+ get(name: string): string | null;
72
+ };
73
+ text(): Promise<string>;
74
+ }
75
+ export interface RequestInitLike {
76
+ method?: string;
77
+ headers?: Record<string, string>;
78
+ body?: string;
79
+ signal?: unknown;
80
+ }
81
+ export type FetchLike = (url: string, init?: RequestInitLike) => Promise<ResponseLike>;
82
+ /** 64-bit impression id. A string when the value is beyond 2^53. */
83
+ export type ImpressionId = number | string;
84
+ /** Server no-ad reasons (doc "No-ad responses") plus the SDK's own. */
85
+ export type NoFillReason = 'publisher_not_approved' | 'publisher_paused' | 'publisher_blackout' | 'app_disabled' | 'sdk_unsupported' | 'interstitial_disabled' | 'classic_disabled' | 'no_approved_ads' | 'ads_query_error' | 'no_matching_ad' | 'publisher_mix' | 'test_unavailable' | 'ads_disabled' | 'frequency_capped' | 'unknown_key' | 'invalid_key' | 'rate_limited' | 'network_error' | 'server_error' | 'invalid_response' | (string & {});
86
+ export interface EthiclyAdMedia {
87
+ kind: 'video' | 'image';
88
+ /** The file to show: local file when cached, else the remote URL. */
89
+ uri: string;
90
+ /** Same as `uri` for a video, null for a still. */
91
+ videoUri: string | null;
92
+ /** Local or remote poster, null when the ad has none. */
93
+ posterUri: string | null;
94
+ durationMs: number | null;
95
+ mime: string | null;
96
+ width: number;
97
+ height: number;
98
+ /** True when `uri` points at a local cached file. */
99
+ cached: boolean;
100
+ }
101
+ export interface EthiclyAd {
102
+ id: number;
103
+ /** Button text: ad.cta_label, or "Learn more" when the server sends none. */
104
+ ctaLabel: string;
105
+ destinationUrl: string;
106
+ /** When the skip control may appear. The ad's value wins over /config. */
107
+ skipAfterMs: number;
108
+ media: EthiclyAdMedia;
109
+ /** interstitial.audio from /config. */
110
+ audio: AudioPolicy;
111
+ title: string | null;
112
+ /** True for a test-mode serve: nothing is stored or billed. */
113
+ test: boolean;
114
+ /** Epoch ms when the serve response arrived. */
115
+ servedAt: number;
116
+ /** Epoch ms after which the ad must not be shown (served + token_ttl_s). */
117
+ expiresAt: number;
118
+ }
119
+ export interface Tracker {
120
+ /** Call the moment the ad is rendered. Sends /impression immediately. */
121
+ shown(size?: {
122
+ width?: number;
123
+ height?: number;
124
+ }): Promise<void>;
125
+ /** Call on every player time update. */
126
+ progress(positionMs: number, opts: {
127
+ visible: boolean;
128
+ durationMs?: number;
129
+ }): void;
130
+ complete(): void;
131
+ skipped(positionMs: number): void;
132
+ error(): void;
133
+ /** POST /click (500 ms budget), then open the destination. Resolves with the URL opened. */
134
+ clicked(): Promise<string>;
135
+ /** Call when the ad screen goes away. Sends queued video events. */
136
+ closed(): Promise<void>;
137
+ /** True once the ad is older than token_ttl_s: it must not be shown. */
138
+ isExpired(): boolean;
139
+ }
140
+ export type InterstitialResult = {
141
+ ad: EthiclyAd;
142
+ tracker: Tracker;
143
+ reason?: undefined;
144
+ } | {
145
+ ad: null;
146
+ tracker: null;
147
+ reason: NoFillReason;
148
+ };
149
+ /** Raw serve-response ad (only the fields the SDK reads). */
150
+ export interface WireAd {
151
+ id: number;
152
+ title?: string | null;
153
+ destination_url?: string | null;
154
+ skip_after_ms?: number | null;
155
+ cta_label?: string | null;
156
+ media?: {
157
+ kind?: string;
158
+ url?: string | null;
159
+ poster_url?: string | null;
160
+ duration_ms?: number | null;
161
+ width?: number | null;
162
+ height?: number | null;
163
+ mime?: string | null;
164
+ } | null;
165
+ }
166
+ export interface WireServe {
167
+ ad: WireAd | null;
168
+ reason?: string;
169
+ publisher_site_id?: number;
170
+ country_code?: string;
171
+ impression_token?: string;
172
+ token_ttl_s?: number;
173
+ test?: boolean;
174
+ request_id?: string;
175
+ }
@@ -0,0 +1,3 @@
1
+ export * from './core';
2
+ export { useEthiclyInterstitial } from './react/useEthiclyInterstitial';
3
+ export type { EthiclyInterstitialState, UseEthiclyInterstitialOptions } from './react/useEthiclyInterstitial';
@@ -0,0 +1,2 @@
1
+ export { EthiclyInterstitial } from './react/EthiclyInterstitial';
2
+ export type { EthiclyInsets, EthiclyInterstitialProps } from './react/EthiclyInterstitial';
@@ -0,0 +1,51 @@
1
+ import React from 'react';
2
+ import { type StyleProp, type TextStyle, type ViewStyle } from 'react-native';
3
+ import type { AudioPolicy, EthiclyAd, Tracker } from '../core/types';
4
+ /** Safe-area insets in points, as react-native-safe-area-context reports them. */
5
+ export interface EthiclyInsets {
6
+ top: number;
7
+ bottom: number;
8
+ left: number;
9
+ right: number;
10
+ }
11
+ export interface EthiclyInterstitialProps {
12
+ ad: EthiclyAd;
13
+ tracker: Tracker;
14
+ /** Called after the ad is skipped or closed. Hide the screen here. */
15
+ onClose(): void;
16
+ /** Shows a "Remove ads" link under the button that calls this. */
17
+ onRemoveAds?(): void;
18
+ removeAdsLabel?: string;
19
+ /** Replaces the "Remove ads" link with anything the app wants. */
20
+ renderBelowButton?(): React.ReactNode;
21
+ /** Default true: wraps the screen in a fullscreen Modal. */
22
+ modal?: boolean;
23
+ /**
24
+ * Overrides for the skip control, merged over the default: a solid black
25
+ * pill reading "Skip in N", then "Skip Ad" with a skip-to-end icon.
26
+ */
27
+ skipStyle?: StyleProp<ViewStyle>;
28
+ /** Overrides for the skip label (default white, "Skip in N" then "Skip Ad"). */
29
+ skipTextStyle?: StyleProp<TextStyle>;
30
+ /**
31
+ * Safe-area insets, for example `useSafeAreaInsets()`. Optional: without
32
+ * them the screen reads react-native-safe-area-context itself when the app
33
+ * has it, else the status bar height on Android. The controls never sit
34
+ * higher or lower than in 0.1 (56 from the top, 44 from the bottom); insets
35
+ * only move them inward.
36
+ */
37
+ insets?: EthiclyInsets;
38
+ /**
39
+ * Sound for this screen, over `ad.audio` (createEthicly's `audio` option,
40
+ * else the server's interstitial.audio, else 'on'). 'on' plays with sound,
41
+ * 'optional' starts muted with a sound toggle, 'none' plays muted with no toggle.
42
+ * With expo-video on iPhone, sound plays even with the silent switch on and
43
+ * pauses the user's own audio.
44
+ */
45
+ audio?: AudioPolicy;
46
+ }
47
+ /** The sound a screen plays with: the prop, else ad.audio, else 'on'. */
48
+ export declare function effectiveAudio(prop: AudioPolicy | undefined, ad: {
49
+ audio?: AudioPolicy;
50
+ }): AudioPolicy;
51
+ export declare function EthiclyInterstitial(props: EthiclyInterstitialProps): React.ReactElement;
@@ -0,0 +1,20 @@
1
+ import type { Ethicly } from '../core/client';
2
+ import type { EthiclyAd, NoFillReason, Tracker } from '../core/types';
3
+ export interface UseEthiclyInterstitialOptions {
4
+ /** Preload on mount and after each dismiss. Default true. */
5
+ preload?: boolean;
6
+ }
7
+ export interface EthiclyInterstitialState {
8
+ /** The ad to render, set by a successful show(). */
9
+ ad: EthiclyAd | null;
10
+ tracker: Tracker | null;
11
+ /** Why the last show() found no ad: show your house ad, except for 'ads_disabled' (a paid user). */
12
+ reason: NoFillReason | null;
13
+ loading: boolean;
14
+ /** Load the ad to show now. Resolves true when `ad` is set, false on no fill. */
15
+ show(): Promise<boolean>;
16
+ /** Close the current ad: flushes queued events and preloads the next one. */
17
+ dismiss(): void;
18
+ canShow(): boolean;
19
+ }
20
+ export declare function useEthiclyInterstitial(ethicly: Ethicly, options?: UseEthiclyInterstitialOptions): EthiclyInterstitialState;
@@ -0,0 +1,2 @@
1
+ /** SDK version, sent as sdk_version and in X-Ethicly-SDK. Keep in step with package.json. */
2
+ export declare const SDK_VERSION = "0.2.1";
package/package.json CHANGED
@@ -1,6 +1,103 @@
1
1
  {
2
2
  "name": "@ethicly/react-native",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.2.1",
4
+ "description": "Ethicly fullscreen video ads for React Native and Expo. Headless core plus an optional ready-made screen.",
5
+ "license": "MIT",
6
+ "homepage": "https://ethicly.ch",
7
+ "publishConfig": {
8
+ "access": "public",
9
+ "registry": "https://registry.npmjs.org/"
10
+ },
11
+ "main": "lib/commonjs/index.js",
12
+ "module": "lib/module/index.js",
13
+ "types": "lib/typescript/index.d.ts",
14
+ "react-native": "src/index.ts",
15
+ "source": "src/index.ts",
16
+ "exports": {
17
+ ".": {
18
+ "types": "./lib/typescript/index.d.ts",
19
+ "react-native": "./src/index.ts",
20
+ "import": "./lib/module/index.js",
21
+ "require": "./lib/commonjs/index.js"
22
+ },
23
+ "./core": {
24
+ "types": "./lib/typescript/core/index.d.ts",
25
+ "react-native": "./src/core/index.ts",
26
+ "import": "./lib/module/core/index.js",
27
+ "require": "./lib/commonjs/core/index.js"
28
+ },
29
+ "./interstitial": {
30
+ "types": "./lib/typescript/interstitial.d.ts",
31
+ "react-native": "./src/interstitial.ts",
32
+ "import": "./lib/module/interstitial.js",
33
+ "require": "./lib/commonjs/interstitial.js"
34
+ },
35
+ "./package.json": "./package.json"
36
+ },
37
+ "files": [
38
+ "src",
39
+ "lib",
40
+ "core",
41
+ "interstitial",
42
+ "CHANGELOG.md",
43
+ "LICENSE",
44
+ "!src/**/__tests__"
45
+ ],
46
+ "sideEffects": false,
47
+ "scripts": {
48
+ "typecheck": "tsc --noEmit -p tsconfig.json",
49
+ "test": "jest",
50
+ "test:live": "npm run build && node scripts/live-test.mjs",
51
+ "prepack": "npm run build",
52
+ "build": "node scripts/clean.mjs && tsc -p tsconfig.build.json --module commonjs --outDir lib/commonjs && tsc -p tsconfig.build.json --module es2020 --outDir lib/module && tsc -p tsconfig.build.json --emitDeclarationOnly --declaration --outDir lib/typescript"
53
+ },
54
+ "peerDependencies": {
55
+ "@react-native-async-storage/async-storage": ">=1.17.0",
56
+ "expo-file-system": ">=16.0.0",
57
+ "expo-video": ">=2.0.0",
58
+ "react": ">=18.2.0",
59
+ "react-native": ">=0.72.0",
60
+ "react-native-safe-area-context": ">=4.0.0"
61
+ },
62
+ "peerDependenciesMeta": {
63
+ "@react-native-async-storage/async-storage": {
64
+ "optional": true
65
+ },
66
+ "expo-file-system": {
67
+ "optional": true
68
+ },
69
+ "expo-video": {
70
+ "optional": true
71
+ },
72
+ "react-native-safe-area-context": {
73
+ "optional": true
74
+ }
75
+ },
76
+ "engines": {
77
+ "node": ">=18"
78
+ },
79
+ "devDependencies": {
80
+ "@types/jest": "^29.5.14",
81
+ "@types/node": "^20.17.6",
82
+ "@types/react": "^18.3.12",
83
+ "@types/react-dom": "^18.3.1",
84
+ "expo-modules-core": "^2.2.3",
85
+ "expo-video": "^2.0.6",
86
+ "jest": "^29.7.0",
87
+ "jest-environment-jsdom": "^29.7.0",
88
+ "react": "^18.3.1",
89
+ "react-dom": "^18.3.1",
90
+ "react-native": "^0.76.9",
91
+ "ts-jest": "^29.2.5",
92
+ "typescript": "^5.6.3"
93
+ },
94
+ "keywords": [
95
+ "react-native",
96
+ "expo",
97
+ "ads",
98
+ "interstitial",
99
+ "video",
100
+ "privacy",
101
+ "ethicly"
102
+ ]
103
+ }