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

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) NovvyAI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,210 @@
+# novvy-ads-react-native
+
+React Native SDK for **Novvy Ads** — short-drama vertical-video ad formats
+(interstitial, rewarded, mid, end, scroll, pause). It wraps the native Novvy
+Android & iOS SDKs behind a single TypeScript API, mirroring the design of the
+official Flutter plugin.
+
+- **New Architecture only** (TurboModule + Fabric). Requires **React Native ≥ 0.76**.
+- **Framework-agnostic** — plain RN native module, **zero Expo runtime dependency**.
+- Ships an **optional Expo config plugin** (build-time only) for Expo hosts.
+
+---
+
+## Installation
+
+```sh
+npm install novvy-ads-react-native
+# or
+yarn add novvy-ads-react-native
+```
+
+### iOS
+
+```sh
+cd ios && pod install
+```
+
+- The podspec downloads `NovvyAds.xcframework` (currently pinned to **1.1.0**) from the [NovvyAds cocoapods release](https://github.com/NovvyAI/novvy-ads-cocoapods/releases) automatically — no manual binary integration.
+- Minimum deployment target **iOS 13.0**. Raise your Podfile's `platform :ios` to 13.0+ if it's lower.
+- **No AdMob / Google-Mobile-Ads-SDK dependency** (removed in 1.1.0).
+- The vendored framework ships **arm64 simulator only** (x86_64 simulator is excluded), so simulator builds require an **Apple Silicon Mac**. Intel Macs can only build for physical devices.
+- Local development against an unreleased NovvyAds iOS SDK: set `NOVVY_ADS_LOCAL_XCFRAMEWORK=<path>` before `pod install` and the podspec will skip the download and use that path instead.
+
+### Android
+
+No extra steps — autolinking wires it up.
+
+- The native SDK **`ai.novvy.android:sdk:1.1.0`** is pulled from **Maven Central**. Make sure `mavenCentral()` is in your root `build.gradle`'s `allprojects.repositories` (default in RN templates).
+- Minimum **`minSdkVersion 24`** (Android 7.0). Raise `android/build.gradle`'s `minSdkVersion` if it's lower.
+- Compiles with **JDK 17**; `compileSdkVersion` 34+ recommended.
+
+### Expo (optional)
+
+For managed / CNG (prebuild) Expo apps, add the config plugin. It only runs at
+build time and adds **no** runtime dependency. Non-Expo hosts do **not** need it.
+
+```json
+{
+  "expo": {
+    "plugins": [
+      ["novvy-ads-react-native", {
+        "iosDeploymentTarget": "13.0",
+        "androidMinSdkVersion": 24,
+        "userTrackingUsageDescription": "We use your data to show relevant ads."
+      }]
+    ]
+  }
+}
+```
+
+Then run `npx expo prebuild`. All options are optional:
+
+| Option | Type | Default | Effect |
+| ------ | ------ | ------ | ------ |
+| `iosDeploymentTarget` | `string` | `"13.0"` | Raises `Podfile.properties`'s `ios.deploymentTarget` to at least this value |
+| `androidMinSdkVersion` | `number` | `24` | Raises `gradle.properties`'s `android.minSdkVersion` to at least this value |
+| `userTrackingUsageDescription` | `string` | — | If set, injects `NSUserTrackingUsageDescription` into `Info.plist` (iOS ATT copy) |
+
+> New Architecture must be enabled (default on RN 0.76+). For Expo, ensure
+> `newArchEnabled` is true.
+
+---
+
+## Quick start
+
+```ts
+import {
+  NovvyAds,
+  NovvyRewardedAd,
+} from 'novvy-ads-react-native';
+
+// 1. Initialize once at app startup.
+const ok = await NovvyAds.initialize({
+  appId: 'YOUR_APP_ID',
+  endpoint: 'https://bid.novvy.ai',
+  apiKey: 'YOUR_API_KEY',
+  userContext: { userId: 'u_123', isPaidUser: false },
+});
+
+// 2. Set content context before requesting ads (required for drama fill).
+NovvyAds.setContentContext({ seriesName: 'My Drama', episodeNumber: 3 });
+
+// 3. Create an ad, wire callbacks, load & show.
+const ad = new NovvyRewardedAd('YOUR_AD_UNIT_ID');
+let earned = false;
+ad.onAdLoaded = () => ad.show();
+ad.onUserEarnedReward = () => { earned = true; };
+ad.onAdDismissed = () => { if (earned) grantReward(); };
+ad.onAdFailedToLoad = (e) => console.warn('load failed', e);
+ad.load();
+```
+
+---
+
+## Ad formats
+
+| Class | Kind | Lifecycle |
+| --- | --- | --- |
+| `NovvyInterstitialAd` | full-screen | `load()` → `onAdLoaded` → `show()` → `onAdDismissed` |
+| `NovvyRewardedAd` | rewarded video | `load()` → `show()` → `onUserEarnedReward` → `onAdDismissed` |
+| `NovvyMidAd` | full-screen (mid-roll) | `load()` → `show()` → `onAdDismissed` |
+| `NovvyEndAd` | full-screen (end-roll) | `load()` → `show()` → `onAdDismissed` |
+| `NovvyScrollAd` | inline feed video | `load()` → `<NovvyScrollAdView>` → `setPlaying()` |
+| `NovvyPauseAd` | realtime pause card (260×90) | `<NovvyPauseAdView>` (no `load()`) |
+
+> There is **no banner / native / app-open** format, and **no click callback**.
+> `NovvyRewardedAd` grants a parameterless reward (no amount/type payload).
+
+### Full-screen (interstitial / mid / end)
+
+```ts
+import { NovvyInterstitialAd } from 'novvy-ads-react-native';
+
+const ad = new NovvyInterstitialAd('AD_UNIT_ID');
+ad.onAdLoaded = () => ad.show();
+ad.onAdShowed = () => {};
+ad.onAdDismissed = () => {}; // ad auto-destroys after dismiss
+ad.onAdFailedToLoad = (e) => {};
+ad.load();
+```
+
+### Scroll (inline feed) ad
+
+```tsx
+import { NovvyScrollAd, NovvyScrollAdView } from 'novvy-ads-react-native';
+
+const ad = useMemo(() => new NovvyScrollAd('AD_UNIT_ID', /* episodeNumber */ 3), []);
+
+useEffect(() => {
+  ad.onAdLoaded = () => ad.setPlaying(true);
+  ad.onAdPlaybackTick = (remaining) => {/* update your skip UI */};
+  ad.load();
+  return () => ad.destroy();
+}, [ad]);
+
+// Give the view a fixed height in your feed item:
+<View style={{ height: 640 }}>
+  <NovvyScrollAdView ad={ad} durationSeconds={5} useDefaultSwipeOverlay />
+</View>
+
+// Toggle playback from viewport visibility:
+// ad.setPlaying(true)  // scrolled into view
+// ad.setPlaying(false) // scrolled out
+```
+
+### Pause card ad
+
+`NovvyPauseAd` has **no load step** — mounting `<NovvyPauseAdView>` issues the
+request. You must supply a `NovvyPlayerAdapter` that reports your video player's
+position; the SDK uses it to detect resume and hide the card.
+
+```tsx
+import { NovvyPauseAd, NovvyPauseAdView, type NovvyPlayerAdapter } from 'novvy-ads-react-native';
+
+// Adapter backed by your player's current state (read live each access):
+const player: NovvyPlayerAdapter = {
+  get currentPositionMs() { return videoRef.current?.positionMs ?? 0; },
+  get isPlaying() { return videoRef.current?.isPlaying ?? false; },
+};
+
+const ad = useMemo(() => new NovvyPauseAd('AD_UNIT_ID'), []);
+useEffect(() => {
+  ad.onAdShowed = () => {};
+  ad.onAdHidden = () => ad.destroy(); // resumed
+  return () => ad.destroy();
+}, [ad]);
+
+// Position within your player overlay (fixed 260×90):
+<NovvyPauseAdView ad={ad} player={player} />
+```
+
+---
+
+## SDK API (`NovvyAds`)
+
+| Method | Description |
+| --- | --- |
+| `initialize(opts)` | `Promise<boolean>` — init with `appId` / `endpoint` / `apiKey` / optional `userContext`. |
+| `setUserContext(ctx)` / `updateUserContext(partial)` | Replace / merge user targeting context. |
+| `setContentContext(ctx)` / `updateContentContext(partial)` | Replace / merge series/episode context. Call before requesting drama ads. |
+| `helperHashEmail(email)` | SHA-256 of the trimmed/lowercased email (pure JS). |
+
+### Privacy / consent
+
+There is no explicit GDPR/CCPA consent API. Privacy targeting is expressed
+through `NovvyUserContext` / `NovvyContentContext`. On iOS, present the ATT
+prompt yourself (the config plugin can add `NSUserTrackingUsageDescription`).
+
+---
+
+## How it works
+
+A single native → JS event (`onAdEvent`, carrying `adObjectId`) multiplexes
+every ad's lifecycle; each ad object filters the stream by its own id, exactly
+like the Flutter plugin. `adObjectId`s are generated JS-side. Inline formats use
+Fabric view components that register a native container keyed by `adObjectId`.
+
+## License
+
+MIT

package/android/build.gradle

@@ -0,0 +1,84 @@
+buildscript {
+  ext.getExtOrDefault = { name ->
+    return rootProject.ext.has(name) ? rootProject.ext.get(name) : project.properties["NovvyAds_" + name]
+  }
+
+  repositories {
+    google()
+    mavenCentral()
+  }
+
+  dependencies {
+    classpath "com.android.tools.build:gradle:8.6.0"
+    classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:${getExtOrDefault('kotlinVersion')}"
+  }
+}
+
+def reactNativeArchitectures() {
+  def value = rootProject.getProperties().get("reactNativeArchitectures")
+  return value ? value.split(",") : ["armeabi-v7a", "x86", "x86_64", "arm64-v8a"]
+}
+
+def isNewArchitectureEnabled() {
+  return rootProject.hasProperty("newArchEnabled") && rootProject.getProperty("newArchEnabled") == "true"
+}
+
+apply plugin: "com.android.library"
+apply plugin: "kotlin-android"
+
+if (isNewArchitectureEnabled()) {
+  apply plugin: "com.facebook.react"
+}
+
+def getExtOrIntegerDefault = { name ->
+  return rootProject.ext.has(name) ? rootProject.ext.get(name) : (project.properties["NovvyAds_" + name]).toInteger()
+}
+
+android {
+  namespace "ai.novvy.reactnative"
+
+  compileSdkVersion getExtOrIntegerDefault("compileSdkVersion")
+
+  defaultConfig {
+    minSdkVersion getExtOrIntegerDefault("minSdkVersion")
+    targetSdkVersion getExtOrIntegerDefault("targetSdkVersion")
+  }
+
+  buildFeatures {
+    buildConfig true
+  }
+
+  compileOptions {
+    sourceCompatibility JavaVersion.VERSION_17
+    targetCompatibility JavaVersion.VERSION_17
+  }
+
+  kotlinOptions {
+    jvmTarget = "17"
+  }
+
+  sourceSets {
+    main {
+      if (isNewArchitectureEnabled()) {
+        java.srcDirs += ["generated/java", "generated/jni"]
+      }
+    }
+  }
+}
+
+repositories {
+  google()
+  mavenCentral()
+}
+
+dependencies {
+  implementation "com.facebook.react:react-android"
+
+  // Novvy native Android ad SDK (published to Maven Central).
+  implementation "ai.novvy.android:sdk:1.1.0"
+  // For publishing the host Activity as a ViewTreeLifecycleOwner on the ad
+  // container so the SDK's inline host can observe background/foreground (pauses
+  // a VIDEO creative on click-through). Provided at runtime by RN + the Novvy
+  // SDK, so compileOnly avoids forcing a version.
+  compileOnly "androidx.lifecycle:lifecycle-runtime-ktx:2.8.7"
+}

package/android/gradle.properties

@@ -0,0 +1,4 @@
+NovvyAds_kotlinVersion=1.9.24
+NovvyAds_minSdkVersion=24
+NovvyAds_targetSdkVersion=34
+NovvyAds_compileSdkVersion=35

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,4 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+  <!-- Permissions (INTERNET, ACCESS_NETWORK_STATE, AD_ID) are declared by the
+       underlying ai.novvy.android:sdk manifest and merged automatically. -->
+</manifest>

package/android/src/main/java/ai/novvy/reactnative/NovvyAdContainerView.kt

@@ -0,0 +1,63 @@
+package ai.novvy.reactnative
+
+import android.widget.FrameLayout
+import androidx.lifecycle.LifecycleOwner
+import androidx.lifecycle.setViewTreeLifecycleOwner
+import com.facebook.react.uimanager.ThemedReactContext
+
+/**
+ * Container [FrameLayout] that hosts an SDK-rendered ad creative.
+ *
+ * Two RN/New-Arch integration gaps are patched here:
+ *
+ * 1. **Layout of imperatively-added children.** Fabric only measures/lays out
+ *    views in the JS shadow tree, and RN-managed ViewGroups swallow normal
+ *    `requestLayout()` propagation. The Novvy SDK mounts its creative (video /
+ *    image / native) via `addView` at runtime — that child is NOT in the shadow
+ *    tree, so it never gets measured and stays 0×0 (blank/black slot; a VIDEO's
+ *    ExoPlayer still decodes audio). [requestLayout] is overridden to post a
+ *    manual measure + layout of our own subtree (the standard react-native-video
+ *    / -webview / google-mobile-ads workaround). Converges rather than
+ *    busy-looping because the SDK only re-fits on bounds *change*.
+ *
+ * 2. **Activity for click-through.** The SDK resolves the Activity used to open
+ *    a creative's `cta_url` via `container.context as? Activity` (see
+ *    `NovvyPlacementAd.attach` / `ClickOpenPipeline`). Under RN the view's
+ *    context is a [ThemedReactContext], never an Activity, so that cast returns
+ *    null and every click silently no-ops. `View.getContext()` is final and
+ *    cannot be overridden, so we construct the view with the current Activity as
+ *    its base context — `getContext()` then returns the Activity and the cast
+ *    (and CTA open) works. RN-side event dispatch must read [reactContext]
+ *    instead of `getContext()`, which is no longer the ReactContext.
+ */
+class NovvyAdContainerView(
+  /** The RN context. Kept separately because getContext() now returns the Activity. */
+  val reactContext: ThemedReactContext,
+) : FrameLayout(reactContext.currentActivity ?: reactContext) {
+
+  init {
+    // RN does not reliably expose a ViewTreeLifecycleOwner on its view tree, so
+    // the SDK's inline host's `container.findViewTreeLifecycleOwner()` returns
+    // null and it never registers its onStop/onStart observer — meaning a VIDEO
+    // creative keeps playing (audio included) when a click-through opens the
+    // browser on top. Publish the host Activity (a LifecycleOwner) on this
+    // container so the SDK can observe background/foreground and pause/resume.
+    (reactContext.currentActivity as? LifecycleOwner)?.let { setViewTreeLifecycleOwner(it) }
+  }
+
+  private val measureAndLayout = Runnable {
+    measure(
+      MeasureSpec.makeMeasureSpec(width, MeasureSpec.EXACTLY),
+      MeasureSpec.makeMeasureSpec(height, MeasureSpec.EXACTLY),
+    )
+    layout(left, top, right, bottom)
+  }
+
+  override fun requestLayout() {
+    super.requestLayout()
+    // React Native won't lay out children that aren't in the shadow tree, so
+    // force a measure + layout pass; without it the SDK's imperatively-added
+    // creative stays 0×0 and the slot renders as a blank (black) container.
+    post(measureAndLayout)
+  }
+}