@ethicly/react-native 0.2.0 → 0.3.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 (44) hide show
  1. package/CHANGELOG.md +92 -1
  2. package/README.md +246 -53
  3. package/lib/commonjs/core/adapters.js +44 -5
  4. package/lib/commonjs/core/cache.js +60 -5
  5. package/lib/commonjs/core/click.js +10 -0
  6. package/lib/commonjs/core/client.js +237 -73
  7. package/lib/commonjs/core/config.js +17 -2
  8. package/lib/commonjs/core/index.js +2 -1
  9. package/lib/commonjs/core/tracker.js +8 -0
  10. package/lib/commonjs/react/EthiclyInterstitial.js +46 -13
  11. package/lib/commonjs/react/useEthiclyInterstitial.js +4 -1
  12. package/lib/commonjs/version.js +1 -1
  13. package/lib/module/core/adapters.js +44 -5
  14. package/lib/module/core/cache.js +59 -4
  15. package/lib/module/core/click.js +9 -0
  16. package/lib/module/core/client.js +237 -73
  17. package/lib/module/core/config.js +15 -1
  18. package/lib/module/core/index.js +1 -1
  19. package/lib/module/core/tracker.js +9 -1
  20. package/lib/module/react/EthiclyInterstitial.js +45 -13
  21. package/lib/module/react/useEthiclyInterstitial.js +4 -1
  22. package/lib/module/version.js +1 -1
  23. package/lib/typescript/core/adapters.d.ts +2 -1
  24. package/lib/typescript/core/cache.d.ts +20 -2
  25. package/lib/typescript/core/click.d.ts +5 -0
  26. package/lib/typescript/core/client.d.ts +42 -3
  27. package/lib/typescript/core/config.d.ts +9 -0
  28. package/lib/typescript/core/index.d.ts +2 -2
  29. package/lib/typescript/core/types.d.ts +48 -0
  30. package/lib/typescript/react/EthiclyInterstitial.d.ts +13 -1
  31. package/lib/typescript/react/useEthiclyInterstitial.d.ts +4 -2
  32. package/lib/typescript/version.d.ts +1 -1
  33. package/package.json +2 -2
  34. package/src/core/adapters.ts +33 -5
  35. package/src/core/cache.ts +48 -3
  36. package/src/core/click.ts +10 -0
  37. package/src/core/client.ts +278 -76
  38. package/src/core/config.ts +14 -1
  39. package/src/core/index.ts +4 -3
  40. package/src/core/tracker.ts +8 -1
  41. package/src/core/types.ts +57 -0
  42. package/src/react/EthiclyInterstitial.tsx +62 -16
  43. package/src/react/useEthiclyInterstitial.ts +8 -3
  44. package/src/version.ts +1 -1
@@ -2,7 +2,8 @@
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
4
  // "Remove ads" slot and a small "Sponsored by Ethicly.ch" line under it.
5
- // Video starts with sound unless interstitial.audio is 'none' or 'optional'.
5
+ // Video starts with sound unless the effective audio (the `audio` prop, else
6
+ // ad.audio: createEthicly's `audio` option, else /config) is 'none' or 'optional'.
6
7
  // The controls keep clear of the notch, status bar and home indicator: see
7
8
  // useSafeInsets below.
8
9
 
@@ -12,7 +13,7 @@ import {
12
13
  type AppStateStatus, type StyleProp, type TextStyle, type ViewStyle,
13
14
  } from 'react-native';
14
15
  import { useVideoPlayer, VideoView } from 'expo-video';
15
- import type { EthiclyAd, Tracker } from '../core/types';
16
+ import type { AudioPolicy, EthiclyAd, Tracker } from '../core/types';
16
17
 
17
18
  /** Safe-area insets in points, as react-native-safe-area-context reports them. */
18
19
  export interface EthiclyInsets { top: number; bottom: number; left: number; right: number }
@@ -44,6 +45,20 @@ export interface EthiclyInterstitialProps {
44
45
  * only move them inward.
45
46
  */
46
47
  insets?: EthiclyInsets;
48
+ /**
49
+ * Sound for this screen, over `ad.audio` (createEthicly's `audio` option,
50
+ * else the server's interstitial.audio, else 'on'). 'on' plays with sound,
51
+ * 'optional' starts muted with a sound toggle, 'none' plays muted with no toggle.
52
+ * With expo-video on iPhone, sound plays even with the silent switch on and
53
+ * pauses the user's own audio.
54
+ */
55
+ audio?: AudioPolicy;
56
+ }
57
+
58
+ /** The sound a screen plays with: the prop, else ad.audio, else 'on'. */
59
+ export function effectiveAudio(prop: AudioPolicy | undefined, ad: { audio?: AudioPolicy }): AudioPolicy {
60
+ for (const v of [prop, ad.audio]) if (v === 'on' || v === 'optional' || v === 'none') return v;
61
+ return 'on';
47
62
  }
48
63
 
49
64
  const TICK_MS = 250;
@@ -145,8 +160,9 @@ interface BodyProps extends EthiclyInterstitialProps {
145
160
  }
146
161
 
147
162
  function InterstitialBody({
148
- ad, tracker, onClose, onRemoveAds, removeAdsLabel, renderBelowButton, skipStyle, skipTextStyle, insets, backRef,
163
+ ad, tracker, onClose, onRemoveAds, removeAdsLabel, renderBelowButton, skipStyle, skipTextStyle, insets, backRef, audio: audioProp,
149
164
  }: BodyProps) {
165
+ const audio = effectiveAudio(audioProp, ad);
150
166
  const safe = useSafeInsets(insets);
151
167
  const isVideo = ad.media.kind === 'video' && !!ad.media.videoUri;
152
168
  const appActive = useAppActive();
@@ -156,16 +172,22 @@ function InterstitialBody({
156
172
  const [positionMs, setPositionMs] = useState(0);
157
173
  const [ended, setEnded] = useState(false);
158
174
  const [failed, setFailed] = useState(false);
159
- const [muted, setMuted] = useState(ad.audio !== 'on');
175
+ const [muted, setMuted] = useState(audio !== 'on');
176
+ /**
177
+ * A still image counts as visible only once it has loaded: an image that
178
+ * never arrives is never billed as viewable.
179
+ */
180
+ const imageLoadedRef = useRef(false);
160
181
  /** Wall-clock time on screen with the app in the foreground. */
161
182
  const [onScreenMs, setOnScreenMs] = useState(0);
162
183
  const [clicked, setClicked] = useState(false);
163
184
  const positionRef = useRef(0);
164
185
  const closedRef = useRef(false);
186
+ const failedRef = useRef(false);
165
187
 
166
188
  const player = useVideoPlayer(isVideo ? ad.media.videoUri : null, (p) => {
167
189
  p.loop = false;
168
- p.muted = ad.audio !== 'on';
190
+ p.muted = audio !== 'on';
169
191
  p.timeUpdateEventInterval = TICK_MS / 1000;
170
192
  p.play();
171
193
  });
@@ -202,7 +224,8 @@ function InterstitialBody({
202
224
  tracker.complete();
203
225
  }),
204
226
  player.addListener('statusChange', ({ status }) => {
205
- if (status === 'error') {
227
+ if (status === 'error' && !failedRef.current) {
228
+ failedRef.current = true;
206
229
  setFailed(true);
207
230
  tracker.error();
208
231
  }
@@ -211,22 +234,35 @@ function InterstitialBody({
211
234
  return () => subs.forEach((s) => s.remove());
212
235
  }, [isVideo, player, tracker]);
213
236
 
214
- // Time on screen while the app is in the foreground. For a still image it is
215
- // the playback position; for a video it is the skip countdown's fallback, so
216
- // Skip still appears after skipAfterMs if the video stalls or never starts.
237
+ // Time on screen while the app is in the foreground: the skip countdown, so
238
+ // Skip appears after skipAfterMs even if the video stalls or the image never
239
+ // loads. For a still image, the time since it loaded is the playback position.
217
240
  useEffect(() => {
218
241
  let shownMs = 0;
242
+ let loadedMs = 0;
219
243
  const id = setInterval(() => {
220
244
  if (activeRef.current) shownMs += TICK_MS;
221
245
  setOnScreenMs(shownMs);
222
- if (isVideo) return;
223
- positionRef.current = shownMs;
224
- setPositionMs(shownMs);
225
- tracker.progress(shownMs, { visible: activeRef.current });
246
+ if (isVideo || !imageLoadedRef.current || failedRef.current) return;
247
+ if (activeRef.current) loadedMs += TICK_MS;
248
+ positionRef.current = loadedMs;
249
+ setPositionMs(loadedMs);
250
+ tracker.progress(loadedMs, { visible: activeRef.current });
226
251
  }, TICK_MS);
227
252
  return () => clearInterval(id);
228
253
  }, [isVideo, tracker]);
229
254
 
255
+ const onImageLoad = useCallback(() => {
256
+ imageLoadedRef.current = true;
257
+ }, []);
258
+
259
+ const onImageError = useCallback(() => {
260
+ if (failedRef.current) return;
261
+ failedRef.current = true;
262
+ setFailed(true);
263
+ tracker.error();
264
+ }, [tracker]);
265
+
230
266
  useEffect(() => {
231
267
  if (!isVideo) return;
232
268
  if (appActive && !ended) player.play();
@@ -237,6 +273,7 @@ function InterstitialBody({
237
273
  // waiting for the next player tick (which may never come while paused).
238
274
  useEffect(() => {
239
275
  if (appActive) return;
276
+ if (!isVideo && (!imageLoadedRef.current || failedRef.current)) return;
240
277
  const durationMs = isVideo && player.duration > 0 ? player.duration * 1000 : undefined;
241
278
  tracker.progress(positionRef.current, { visible: false, durationMs });
242
279
  }, [appActive, isVideo, player, tracker]);
@@ -277,10 +314,17 @@ function InterstitialBody({
277
314
  {isVideo ? (
278
315
  <>
279
316
  {ad.media.posterUri ? <Image source={{ uri: ad.media.posterUri }} style={StyleSheet.absoluteFill} resizeMode="cover" /> : null}
280
- <VideoView player={player} style={StyleSheet.absoluteFill} contentFit="cover" nativeControls={false} allowsFullscreen={false} allowsPictureInPicture={false} />
317
+ {/* No native controls, so no fullscreen button: no fullscreen prop is needed (allowsFullscreen is deprecated). */}
318
+ <VideoView player={player} style={StyleSheet.absoluteFill} contentFit="cover" nativeControls={false} allowsPictureInPicture={false} />
281
319
  </>
282
320
  ) : (
283
- <Image source={{ uri: ad.media.uri }} style={StyleSheet.absoluteFill} resizeMode="cover" />
321
+ <Image
322
+ source={{ uri: ad.media.uri }}
323
+ style={StyleSheet.absoluteFill}
324
+ resizeMode="cover"
325
+ onLoad={onImageLoad}
326
+ onError={onImageError}
327
+ />
284
328
  )}
285
329
 
286
330
  <View
@@ -289,7 +333,8 @@ function InterstitialBody({
289
333
  >
290
334
  <View style={styles.leftGroup}>
291
335
  <Text style={styles.adLabel} accessibilityRole="text">Ad</Text>
292
- {isVideo && ad.audio !== 'none' ? (
336
+ {ad.test ? <Text style={[styles.adLabel, styles.testLabel]} accessibilityRole="text">Test ad</Text> : null}
337
+ {isVideo && audio !== 'none' ? (
293
338
  <Pressable onPress={toggleSound} style={styles.soundButton} accessibilityRole="button" accessibilityLabel={muted ? 'Turn sound on' : 'Mute'} hitSlop={8}>
294
339
  <Text style={styles.soundText}>{muted ? 'Sound off' : 'Sound on'}</Text>
295
340
  </Pressable>
@@ -355,6 +400,7 @@ const styles = StyleSheet.create({
355
400
  color: '#fff', fontSize: 11, fontWeight: '600', letterSpacing: 0.5,
356
401
  backgroundColor: 'rgba(0,0,0,0.45)', paddingHorizontal: 6, paddingVertical: 2, borderRadius: 4, overflow: 'hidden',
357
402
  },
403
+ testLabel: { marginLeft: 8, backgroundColor: 'rgba(196,120,0,0.85)' },
358
404
  soundButton: { marginLeft: 8, backgroundColor: 'rgba(0,0,0,0.45)', paddingHorizontal: 8, paddingVertical: 4, borderRadius: 6 },
359
405
  soundText: { color: '#fff', fontSize: 12, fontWeight: '500' },
360
406
  // Solid black, no blur or translucency. The faint hairline keeps the edge
@@ -3,7 +3,7 @@
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. */
@@ -14,7 +14,7 @@ export interface EthiclyInterstitialState {
14
14
  /** The ad to render, set by a successful show(). */
15
15
  ad: EthiclyAd | null;
16
16
  tracker: Tracker | null;
17
- /** Why the last show() found no ad (show your house ad). */
17
+ /** Why the last show() found no ad: show your house ad, except for 'ads_disabled' (a paid user). */
18
18
  reason: NoFillReason | null;
19
19
  loading: boolean;
20
20
  /** Load the ad to show now. Resolves true when `ad` is set, false on no fill. */
@@ -22,6 +22,8 @@ export interface EthiclyInterstitialState {
22
22
  /** Close the current ad: flushes queued events and preloads the next one. */
23
23
  dismiss(): void;
24
24
  canShow(): boolean;
25
+ /** Whether an ad may show now and, when not, why and until when. Same as ethicly.nextAdStatus(). */
26
+ nextAdStatus(): NextAdStatus;
25
27
  }
26
28
 
27
29
  export function useEthiclyInterstitial(
@@ -69,6 +71,9 @@ export function useEthiclyInterstitial(
69
71
  }, [ethicly, preload]);
70
72
 
71
73
  const canShow = useCallback(() => ethicly.canShow(), [ethicly]);
74
+ const nextAdStatus = useCallback(() => ethicly.nextAdStatus(), [ethicly]);
72
75
 
73
- return { ad: current?.ad ?? null, tracker: current?.tracker ?? null, reason, loading, show, dismiss, canShow };
76
+ return {
77
+ ad: current?.ad ?? null, tracker: current?.tracker ?? null, reason, loading, show, dismiss, canShow, nextAdStatus,
78
+ };
74
79
  }
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.0';
2
+ export const SDK_VERSION = '0.3.0';