@ezoic/react-native-sdk 1.3.0 → 1.4.0

package/src/EzoicInstreamAd.ts

@@ -0,0 +1,110 @@
+import NativeEzoicAds from './NativeEzoicAds';
+
+/** Options for {@link EzoicInstreamAd.load}. */
+export interface EzoicInstreamLoadOptions {
+  /**
+   * The URL of the video the host is currently playing. When supplied it is
+   * added to the VAST ad tag as `url`/`description_url` for contextual
+   * targeting. Omit it when the content URL is unknown.
+   */
+  contentUrl?: string;
+}
+
+/** Options for {@link EzoicInstreamAd.reportImpression}. */
+export interface EzoicInstreamImpressionOptions {
+  /**
+   * The publisher-reported revenue (USD) for this impression, if known. Folded
+   * into the Ezoic impression-event pixel. Omit it when no revenue is known.
+   */
+  revenueUsd?: number;
+}
+
+/**
+ * An instream video ad controller. Instream video runs inside the host app's
+ * OWN video content: **the host owns the video player and the Google IMA SDK**.
+ * Unlike the banner/native/outstream views, this controller renders nothing and
+ * holds no view — its sole deliverable is a GAM VAST ad-tag URL string the host
+ * feeds to its own IMA `AdsRequest`.
+ *
+ * Usage:
+ *
+ * ```ts
+ * const instream = new EzoicInstreamAd('12345');
+ * const tagUrl = await instream.load({ contentUrl: playingVideoUrl });
+ * // hand tagUrl to your IMA AdsLoader / AdsRequest.
+ *
+ * // On an IMA ad error, walk down the floor waterfall:
+ * const next = await instream.getNextAdTagUrl();
+ * if (next) { /* request IMA again with next *\/ }
+ *
+ * // On the IMA STARTED event, record the Ezoic impression:
+ * await instream.reportImpression({ revenueUsd: 0.42 });
+ *
+ * // When finished with the ad unit:
+ * await instream.destroy();
+ * ```
+ *
+ * Mirrors the native `EzoicInstreamAd` load pipeline on both platforms. Unlike
+ * the interstitial/rewarded ads, the controller is **multi-use** and NOT
+ * auto-destroying: the native controller is prefetchable and reused across
+ * loads for the same id, so the same instance can be loaded again after a
+ * previous load resolves. Call {@link destroy} when the unit is no longer
+ * needed. There is no event emitter — every result settles the returned
+ * promise directly from the native listener/delegate.
+ */
+export class EzoicInstreamAd {
+  /** The Ezoic ad unit identifier this controller was created for. */
+  readonly adUnitIdentifier: number;
+
+  /**
+   * @param adUnitIdentifier the Ezoic ad unit id (numeric). A string is coerced
+   * to a number so callers can pass either; a non-numeric string yields `NaN`,
+   * which the native side rejects.
+   */
+  constructor(adUnitIdentifier: string | number) {
+    this.adUnitIdentifier = Number(adUnitIdentifier);
+  }
+
+  /**
+   * Loads the instream config, runs optional Prebid demand, and resolves with
+   * the GAM VAST ad-tag URL for the host's IMA player. Rejects on no fill, an
+   * uninitialized SDK, or an overlapping load already in flight for this id.
+   * Safe to call again after a previous load resolves (multi-use).
+   */
+  load(options?: EzoicInstreamLoadOptions): Promise<string> {
+    return NativeEzoicAds.loadInstreamAd(
+      this.adUnitIdentifier,
+      options?.contentUrl ?? null
+    );
+  }
+
+  /**
+   * Pops the current head off the floor waterfall and resolves with the ad tag
+   * rebuilt against the next `eb_br` hash, or `null` once the waterfall is
+   * exhausted (or before a successful {@link load} / after {@link destroy}).
+   * Call this on an IMA ad error to try the next floor.
+   */
+  getNextAdTagUrl(): Promise<string | null> {
+    return NativeEzoicAds.getInstreamNextAdTagUrl(this.adUnitIdentifier);
+  }
+
+  /**
+   * Fires the Ezoic impression-event pixel for the most recently delivered tag.
+   * Call this on the IMA `STARTED` event. No-op natively when no tag has been
+   * delivered or after {@link destroy}.
+   */
+  reportImpression(options?: EzoicInstreamImpressionOptions): Promise<void> {
+    return NativeEzoicAds.reportInstreamImpression(
+      this.adUnitIdentifier,
+      options?.revenueUsd ?? null
+    );
+  }
+
+  /**
+   * Cancels any in-flight load and releases the native controller for this id.
+   * A load in flight rejects. Safe to call multiple times.
+   */
+  destroy(): Promise<void> {
+    return NativeEzoicAds.destroyInstreamAd(this.adUnitIdentifier);
+  }
+}

package/src/EzoicOutstreamAdViewNativeComponent.ts

@@ -0,0 +1,23 @@
+import { codegenNativeComponent } from 'react-native';
+import type { CodegenTypes, HostComponent, ViewProps } from 'react-native';
+
+type LoadEvent = Readonly<{}>;
+type ErrorEvent = Readonly<{ message: string; code: CodegenTypes.Int32 }>;
+
+export interface NativeProps extends ViewProps {
+  adUnitIdentifier: string;
+  onLoad?: CodegenTypes.BubblingEventHandler<LoadEvent> | null;
+  onError?: CodegenTypes.BubblingEventHandler<ErrorEvent> | null;
+  onImpression?: CodegenTypes.BubblingEventHandler<LoadEvent> | null;
+  // `onClick` is reserved by core ViewProps (a gesture handler), so the native
+  // outstream-click event is exposed as `onAdClick`. The public
+  // `EzoicOutstreamAdView` component maps the user-facing `onClick` prop onto
+  // this.
+  onAdClick?: CodegenTypes.BubblingEventHandler<LoadEvent> | null;
+  onOpen?: CodegenTypes.BubblingEventHandler<LoadEvent> | null;
+  onClose?: CodegenTypes.BubblingEventHandler<LoadEvent> | null;
+}
+
+export default codegenNativeComponent<NativeProps>(
+  'EzoicOutstreamAdView'
+) as HostComponent<NativeProps>;

package/src/NativeEzoicAds.ts

@@ -32,6 +32,24 @@ export interface Spec extends TurboModule {
   showRewardedAd(adUnitIdentifier: string): Promise<EzoicRewardResult>;
   loadInterstitialAd(adUnitIdentifier: string): Promise<void>;
   showInterstitialAd(adUnitIdentifier: string): Promise<void>;
+  // Instream video: the native `EzoicInstreamAd` renders nothing — its sole
+  // deliverable is a GAM VAST ad-tag URL the host feeds to its own IMA player.
+  // The id is numeric here (matches the native controller's `Int`/`Int`
+  // adUnitId) and multi-use: a controller is created-or-reused per id and is
+  // NOT auto-destroyed. `contentUrl`/`revenueUsd` are nullable unions —
+  // codegen maps them to nullable native args (String?/NSString*, Double?/
+  // NSNumber*) — because there is no optional-arg precedent for instream on
+  // this spec and the native `load`/`reportImpression` accept optionals.
+  loadInstreamAd(
+    adUnitIdentifier: number,
+    contentUrl: string | null
+  ): Promise<string>;
+  getInstreamNextAdTagUrl(adUnitIdentifier: number): Promise<string | null>;
+  reportInstreamImpression(
+    adUnitIdentifier: number,
+    revenueUsd: number | null
+  ): Promise<void>;
+  destroyInstreamAd(adUnitIdentifier: number): Promise<void>;
   // Required by NativeEventEmitter for the ad lifecycle events.
   addListener(eventName: string): void;
   removeListeners(count: number): void;

package/src/index.tsx

@@ -2,6 +2,7 @@ import type { StyleProp, ViewStyle } from 'react-native';
 import NativeEzoicAds, { type EzoicConfig } from './NativeEzoicAds';
 import EzoicBannerNative from './EzoicBannerViewNativeComponent';
 import EzoicNativeAdNative from './EzoicNativeAdViewNativeComponent';
+import EzoicOutstreamNative from './EzoicOutstreamAdViewNativeComponent';
 import { coerceAdUnitId, normalizeConfig, normalizeSize } from './helpers';
 
 export type { EzoicConfig };
@@ -14,6 +15,11 @@ export {
   EzoicInterstitialAd,
   type EzoicInterstitialAdListeners,
 } from './EzoicInterstitialAd';
+export {
+  EzoicInstreamAd,
+  type EzoicInstreamLoadOptions,
+  type EzoicInstreamImpressionOptions,
+} from './EzoicInstreamAd';
 
 export const EzoicAds = {
   initialize(config: EzoicConfig): Promise<void> {
@@ -122,3 +128,50 @@ export function EzoicNativeAdView(props: EzoicNativeAdViewProps) {
     />
   );
 }
+
+export interface EzoicOutstreamAdError {
+  message: string;
+  code: number;
+}
+
+export interface EzoicOutstreamAdViewProps {
+  adUnitIdentifier: string | number;
+  style?: StyleProp<ViewStyle>;
+  onLoad?: () => void;
+  onError?: (error: EzoicOutstreamAdError) => void;
+  onImpression?: () => void;
+  onClick?: () => void;
+  onOpen?: () => void;
+  onClose?: () => void;
+}
+
+/**
+ * Renders an outstream video ad in an SDK-built player. Outstream video runs on
+ * its own (not inside host video content), so the SDK owns the player and this
+ * component only needs a size. Fills the bounds it is given by its RN style, so
+ * size it with `style` (e.g. `{ width: '100%', height: 200 }`).
+ */
+export function EzoicOutstreamAdView(props: EzoicOutstreamAdViewProps) {
+  const {
+    adUnitIdentifier,
+    onLoad,
+    onError,
+    onImpression,
+    onClick,
+    onOpen,
+    onClose,
+    ...rest
+  } = props;
+  return (
+    <EzoicOutstreamNative
+      {...rest}
+      adUnitIdentifier={coerceAdUnitId(adUnitIdentifier)}
+      onLoad={onLoad ? () => onLoad() : undefined}
+      onError={onError ? (e) => onError(e.nativeEvent) : undefined}
+      onImpression={onImpression ? () => onImpression() : undefined}
+      onAdClick={onClick ? () => onClick() : undefined}
+      onOpen={onOpen ? () => onOpen() : undefined}
+      onClose={onClose ? () => onClose() : undefined}
+    />
+  );
+}