novvy-ads-react-native 1.0.0-beta.1

package/src/index.tsx

@@ -0,0 +1,29 @@
+// Public entry point for the Novvy Ads React Native SDK.
+
+export { NovvyAds } from './NovvyAds';
+
+// Ad types
+export { NovvyAd } from './ads/NovvyAd';
+export { NovvyFullScreenAd } from './ads/NovvyFullScreenAd';
+export { NovvyInterstitialAd } from './ads/NovvyInterstitialAd';
+export { NovvyRewardedAd } from './ads/NovvyRewardedAd';
+export { NovvyMidAd } from './ads/NovvyMidAd';
+export { NovvyEndAd } from './ads/NovvyEndAd';
+export { NovvyScrollAd } from './ads/NovvyScrollAd';
+export { NovvyPauseAd } from './ads/NovvyPauseAd';
+
+// Embedded views
+export { NovvyScrollAdView } from './views/NovvyScrollAdView';
+export type { NovvyScrollAdViewProps } from './views/NovvyScrollAdView';
+export { NovvyPauseAdView } from './views/NovvyPauseAdView';
+export type { NovvyPauseAdViewProps } from './views/NovvyPauseAdView';
+
+// Data types
+export {
+  NovvyAdEvent,
+  type NovvyUserContext,
+  type NovvyContentContext,
+  type NovvyDramaRecord,
+  type NovvyGender,
+  type NovvyPlayerAdapter,
+} from './types';

package/src/spec/NativeNovvyAds.ts

@@ -0,0 +1,134 @@
+import type { TurboModule } from 'react-native';
+import { TurboModuleRegistry } from 'react-native';
+import type {
+  Int32,
+  Double,
+  EventEmitter,
+  UnsafeObject,
+} from 'react-native/Libraries/Types/CodegenTypes';
+
+/**
+ * Codegen-facing spec for the Novvy Ads TurboModule (new architecture only).
+ *
+ * Method surface mirrors the Flutter plugin's Pigeon `NovvyAdHostApi`
+ * (pigeons/novvy_ads_api.dart) one-to-one. The single `onAdEvent` emitter
+ * mirrors Pigeon's `NovvyAdsFlutterApi.onAdEvent`; each JS ad object filters
+ * this stream by its own `adObjectId`.
+ *
+ * NOTE: Codegen struct/event types must live in this file. The public,
+ * richly-documented aliases are re-exported from `../types`.
+ */
+
+// ── Data structs (codegen-facing) ───────────────────────────────────────────
+
+export type NativeDramaRecord = {
+  seriesId: string;
+  lastWatchedEpisode: Int32;
+  unlockedEpisode: Int32;
+  dramaTitle?: string | null;
+};
+
+export type NativeUserContext = {
+  userId?: string | null;
+  hashedEmail?: string | null;
+  isPaidUser?: boolean | null;
+  age?: Int32 | null;
+  /** "male" / "female" / "unknown". */
+  gender?: string | null;
+  dramaWatchHistory?: Array<NativeDramaRecord> | null;
+  maximumAdsInOneDrama?: Int32 | null;
+};
+
+export type NativeContentContext = {
+  seriesName?: string | null;
+  episodeNumber?: Int32 | null;
+  url?: string | null;
+};
+
+/**
+ * Single native→JS ad lifecycle event. `event` is one of the NovvyAdEvent
+ * string values. `remainingSeconds` is only populated for `playbackTick`
+ * (flattened from Pigeon's `data` map for codegen compatibility).
+ */
+export type NativeAdEvent = {
+  adObjectId: string;
+  adUnitId: string;
+  event: string;
+  error?: string | null;
+  remainingSeconds?: Int32 | null;
+};
+
+// ── TurboModule ─────────────────────────────────────────────────────────────
+
+export interface Spec extends TurboModule {
+  // SDK & context
+  //
+  // NOTE: context args are declared as UnsafeObject (not the typed
+  // NativeUserContext / NativeContentContext structs above) so iOS codegen
+  // produces NSDictionary * parameters instead of C++ struct references, to
+  // match the ObjC++ impl in ios/NovvyAds.mm. Android codegen already lowers
+  // typed structs to ReadableMap. The public API in NovvyAds.ts still exposes
+  // the strongly-typed NovvyUserContext / NovvyContentContext to JS callers.
+  initialize(
+    appId: string,
+    endpoint: string,
+    apiKey: string,
+    userContext?: UnsafeObject | null
+  ): Promise<boolean>;
+  setUserContext(context: UnsafeObject): void;
+  updateUserContext(partial: UnsafeObject): void;
+  setContentContext(context: UnsafeObject): void;
+  updateContentContext(partial: UnsafeObject): void;
+
+  // Interstitial
+  loadInterstitialAd(adUnitId: string, adObjectId: string): void;
+  showInterstitialAd(adObjectId: string): void;
+
+  // Rewarded
+  loadRewardedAd(adUnitId: string, adObjectId: string): void;
+  showRewardedAd(adObjectId: string): void;
+
+  // Mid-roll
+  loadMidAd(adUnitId: string, adObjectId: string): void;
+  showMidAd(adObjectId: string): void;
+
+  // End-roll
+  loadEndAd(adUnitId: string, adObjectId: string): void;
+  showEndAd(adObjectId: string): void;
+
+  // Scroll (inline feed)
+  loadScrollAd(
+    adUnitId: string,
+    adObjectId: string,
+    episodeNumber?: Int32 | null
+  ): void;
+  attachScrollAd(
+    adObjectId: string,
+    durationSeconds: Int32 | null,
+    useDefaultSwipeOverlay: boolean
+  ): void;
+  setScrollAdPlaying(adObjectId: string, playing: boolean): void;
+  detachScrollAd(adObjectId: string): void;
+
+  // Pause (realtime pause card)
+  attachPauseAd(
+    adUnitId: string,
+    adObjectId: string,
+    positionMs: Double,
+    isPlaying: boolean
+  ): void;
+  updatePauseAdPlayerState(
+    adObjectId: string,
+    positionMs: Double,
+    isPlaying: boolean
+  ): void;
+  detachPauseAd(adObjectId: string): void;
+
+  // Common
+  disposeAd(adObjectId: string): void;
+
+  // Native → JS event stream (multiplexed by adObjectId)
+  readonly onAdEvent: EventEmitter<NativeAdEvent>;
+}
+
+export default TurboModuleRegistry.getEnforcing<Spec>('NovvyAds');

package/src/spec/NovvyPauseAdViewNativeComponent.ts

@@ -0,0 +1,20 @@
+import type { HostComponent, ViewProps } from 'react-native';
+import codegenNativeComponent from 'react-native/Libraries/Utilities/codegenNativeComponent';
+import type { DirectEventHandler } from 'react-native/Libraries/Types/CodegenTypes';
+
+/**
+ * Fabric component for an inline realtime pause-card ad container
+ * (fixed 260×90). The native view registers its container in the TurboModule
+ * keyed by `adObjectId`, then fires `onViewReady`, at which point JS issues
+ * `attachPauseAd` (there is no load step for pause ads).
+ */
+type ViewReadyEvent = Readonly<{ adObjectId: string }>;
+
+export interface NativeProps extends ViewProps {
+  adObjectId: string;
+  onViewReady?: DirectEventHandler<ViewReadyEvent>;
+}
+
+export default codegenNativeComponent<NativeProps>(
+  'NovvyPauseAdView'
+) as HostComponent<NativeProps>;

package/src/spec/NovvyScrollAdViewNativeComponent.ts

@@ -0,0 +1,21 @@
+import type { HostComponent, ViewProps } from 'react-native';
+import codegenNativeComponent from 'react-native/Libraries/Utilities/codegenNativeComponent';
+import type { DirectEventHandler } from 'react-native/Libraries/Types/CodegenTypes';
+
+/**
+ * Fabric component for an inline scroll (feed) ad container.
+ *
+ * The native view registers its container in the TurboModule keyed by
+ * `adObjectId`, then fires `onViewReady` (mirrors the Flutter plugin's
+ * `onPlatformViewCreated`), at which point JS issues `attachScrollAd`.
+ */
+type ViewReadyEvent = Readonly<{ adObjectId: string }>;
+
+export interface NativeProps extends ViewProps {
+  adObjectId: string;
+  onViewReady?: DirectEventHandler<ViewReadyEvent>;
+}
+
+export default codegenNativeComponent<NativeProps>(
+  'NovvyScrollAdView'
+) as HostComponent<NativeProps>;

package/src/spec/codegen-event-emitter.d.ts

@@ -0,0 +1,10 @@
+// RN 0.76.0 ships the codegen `EventEmitter` type in the Flow source
+// (Libraries/Types/CodegenTypes.js) — the native codegen parser recognizes it
+// — but omits it from the bundled TypeScript declarations. Augment the module
+// so `tsc` type-checks the spec. Newer RN versions declare this themselves;
+// declaration merging makes this a no-op there.
+declare module 'react-native/Libraries/Types/CodegenTypes' {
+  export type EventEmitter<T> = (handler: (event: T) => void) => {
+    remove(): void;
+  };
+}

package/src/types.ts

@@ -0,0 +1,82 @@
+/**
+ * Public types for the Novvy Ads React Native SDK.
+ *
+ * These mirror the Flutter plugin's Pigeon data classes
+ * (pigeons/novvy_ads_api.dart). At runtime they are structurally identical to
+ * the codegen structs in `spec/NativeNovvyAds.ts`, so instances pass straight
+ * through the TurboModule with no conversion.
+ */
+
+/** A single drama-watch history entry used for ad targeting. */
+export interface NovvyDramaRecord {
+  seriesId: string;
+  lastWatchedEpisode: number;
+  unlockedEpisode: number;
+  dramaTitle?: string | null;
+}
+
+/** User gender values accepted by the SDK. */
+export type NovvyGender = 'male' | 'female' | 'unknown';
+
+/**
+ * User identity and subscription context.
+ *
+ * Pass to {@link NovvyAds.setUserContext} (full replace) or
+ * {@link NovvyAds.updateUserContext} (incremental merge).
+ */
+export interface NovvyUserContext {
+  userId?: string | null;
+  /** SHA-256 of the trimmed/lowercased email. Use {@link NovvyAds.helperHashEmail}. */
+  hashedEmail?: string | null;
+  isPaidUser?: boolean | null;
+  age?: number | null;
+  gender?: NovvyGender | null;
+  /** Watched-drama records used for targeting. */
+  dramaWatchHistory?: NovvyDramaRecord[] | null;
+  /** Frequency cap: maximum ads shown within a single drama. */
+  maximumAdsInOneDrama?: number | null;
+}
+
+/**
+ * Content and episode context used for ad targeting.
+ *
+ * Pass to {@link NovvyAds.setContentContext} (full replace) or
+ * {@link NovvyAds.updateContentContext} (incremental merge).
+ */
+export interface NovvyContentContext {
+  seriesName?: string | null;
+  episodeNumber?: number | null;
+  url?: string | null;
+}
+
+/** Ad lifecycle event names (mirror Pigeon's `NovvyAdEvent` enum). */
+export enum NovvyAdEvent {
+  /** Ad and creative are ready to show (not emitted for Pause — realtime). */
+  Loaded = 'loaded',
+  /** Ad failed to load / request. */
+  FailedToLoad = 'failedToLoad',
+  /** Ad was shown (full-screen) or became visible (Scroll / Pause). */
+  Showed = 'showed',
+  /** Full-screen ad was closed by the user (Rewarded / Interstitial / Mid / End). */
+  Dismissed = 'dismissed',
+  /** Inline ad was hidden / removed (Scroll onAdHidden, Pause hidden). */
+  Hidden = 'hidden',
+  /** Rewarded ad earned a reward. Carries no data payload. */
+  EarnedReward = 'earnedReward',
+  /** Scroll ad playback tick. Carries `remainingSeconds`. */
+  PlaybackTick = 'playbackTick',
+}
+
+/**
+ * Interface for a media player that a {@link NovvyPauseAd} monitors.
+ *
+ * Implement this to bridge your video/audio player so the SDK can detect
+ * playback position and resumption. Mirrors the Flutter plugin's
+ * `NovvyPlayerAdapter`.
+ */
+export interface NovvyPlayerAdapter {
+  /** Current playback position in milliseconds. */
+  readonly currentPositionMs: number;
+  /** Whether the player is currently playing (not paused/buffering). */
+  readonly isPlaying: boolean;
+}

package/src/views/NovvyPauseAdView.tsx

@@ -0,0 +1,80 @@
+import React, { useEffect, useRef, useState } from 'react';
+import { StyleSheet, View, type ViewStyle, type StyleProp } from 'react-native';
+
+import { NovvyPauseAd } from '../ads/NovvyPauseAd';
+import type { NovvyPlayerAdapter } from '../types';
+import NativePauseView from '../spec/NovvyPauseAdViewNativeComponent';
+
+export interface NovvyPauseAdViewProps {
+  /** The pause ad instance (no load step — attach happens on mount). */
+  ad: NovvyPauseAd;
+  /** Player adapter the SDK monitors to detect resumption. */
+  player: NovvyPlayerAdapter;
+  style?: StyleProp<ViewStyle>;
+}
+
+/**
+ * Embeds a {@link NovvyPauseAd} as a native view. Fixed to
+ * {@link NovvyPauseAd.cardWidth} × {@link NovvyPauseAd.cardHeight}; position it
+ * within your own layout. Mirrors the Flutter plugin's `NovvyPauseAdView`.
+ *
+ * Touch passthrough / opacity follow the card's shown state so the view is
+ * transparent and non-interactive until the ad actually appears.
+ */
+export function NovvyPauseAdView({
+  ad,
+  player,
+  style,
+}: NovvyPauseAdViewProps): React.ReactElement {
+  const attached = useRef(false);
+  const [shown, setShown] = useState(false);
+
+  useEffect(() => {
+    const prev = ad.onShownChanged;
+    ad.onShownChanged = (isShown) => {
+      setShown(isShown);
+      prev?.(isShown);
+    };
+    return () => {
+      ad.onShownChanged = prev;
+      if (attached.current) {
+        ad.detach();
+      }
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  return (
+    <View
+      style={[styles.container, style]}
+      pointerEvents={shown ? 'auto' : 'none'}
+      // Claim the RN JS responder while the card is shown so an outer
+      // Pressable/Touchable in the host layout can't also fire onPress on
+      // the same tap and race with the SDK's CTA (which would resume the
+      // video and destroy the ad before the browser opens). The SDK's
+      // native tap handling is unaffected: on Android JSTouchDispatcher
+      // runs in parallel to native dispatch, and on iOS RCTTouchHandler
+      // uses cancelsTouchesInView=NO so native touches still reach the
+      // ad view's own gesture recognizer.
+      onStartShouldSetResponder={shown ? () => true : undefined}
+    >
+      <NativePauseView
+        style={[StyleSheet.absoluteFill, { opacity: shown ? 1 : 0 }]}
+        adObjectId={ad.adObjectId}
+        onViewReady={() => {
+          if (!attached.current) {
+            attached.current = true;
+            ad.attach(player);
+          }
+        }}
+      />
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  container: {
+    width: NovvyPauseAd.cardWidth,
+    height: NovvyPauseAd.cardHeight,
+  },
+});

package/src/views/NovvyScrollAdView.tsx

@@ -0,0 +1,71 @@
+import React, { useEffect, useRef } from 'react';
+import { StyleSheet, View, type ViewStyle, type StyleProp } from 'react-native';
+
+import type { NovvyScrollAd } from '../ads/NovvyScrollAd';
+import NativeScrollView from '../spec/NovvyScrollAdViewNativeComponent';
+
+export interface NovvyScrollAdViewProps {
+  /** The scroll ad instance (load it first via `ad.load()`). */
+  ad: NovvyScrollAd;
+  /** Swipe-unlock wait time passed to the native attach call. */
+  durationSeconds?: number | null;
+  /** Whether the SDK renders its built-in "Swipe to skip" pill. */
+  useDefaultSwipeOverlay?: boolean;
+  style?: StyleProp<ViewStyle>;
+}
+
+/**
+ * Embeds a {@link NovvyScrollAd} as a native view. Wrap it in a container with
+ * the desired height for your feed item. Mirrors the Flutter plugin's
+ * `NovvyScrollAdView`.
+ *
+ * A black backdrop paints immediately so the previous page can't show through
+ * the slot while the native view is created.
+ */
+export function NovvyScrollAdView({
+  ad,
+  durationSeconds,
+  useDefaultSwipeOverlay = true,
+  style,
+}: NovvyScrollAdViewProps): React.ReactElement {
+  const attached = useRef(false);
+
+  useEffect(() => {
+    return () => {
+      if (attached.current) {
+        ad.detach();
+      }
+    };
+    // Detach only on unmount; `ad` identity is stable for the view's lifetime.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  return (
+    <View
+      style={[styles.container, style]}
+      // Claim the RN JS responder for taps so an outer Pressable/Touchable
+      // in the host layout can't also fire onPress and race with the SDK's
+      // CTA. Only onStart is claimed — a subsequent move gesture can still
+      // migrate to an ancestor ScrollView/FlatList via the normal responder
+      // negotiation, so vertical feed swiping is preserved.
+      onStartShouldSetResponder={() => true}
+    >
+      <NativeScrollView
+        style={StyleSheet.absoluteFill}
+        adObjectId={ad.adObjectId}
+        onViewReady={() => {
+          if (!attached.current) {
+            attached.current = true;
+            ad.attach(durationSeconds, useDefaultSwipeOverlay);
+          }
+        }}
+      />
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  container: {
+    backgroundColor: '#000000',
+  },
+});