react-native-menta-ads-global

Menta 广告 SDK 的 React Native 桥接层，支持 开屏 / 插屏 / 激励视频 / Banner / 信息流模板 五种广告类型。

其中开屏、插屏、激励视频是命令式全屏广告（new XxxAd(...) → load() → show()）； Banner 与信息流模板是嵌入式广告，组件放进布局后需 ref.load() 手动拉取（可选 autoLoad）。

• 架构：New Architecture / TurboModule + Fabric 组件 + codegen（RN 0.79+）
• 原生：iOS Objective-C++ · Android Kotlin
• 基线：RN 0.81.5 / React 19（对齐 Expo SDK 54）
• Expo：提供 config plugin，支持 prebuild / dev-client

一、安装（下游 App 对接）

npm install react-native-menta-ads-global
# 或
yarn add react-native-menta-ads-global

裸 RN 工程

cd ios && pod install

新架构默认开启（RN 0.76+），无需额外配置。

iOS 接入真实 Menta SDK：本包 iOS 端依赖 MentaMediationGlobal（含 MentaBaseGlobal）。 这些库已发布到 CocoaPods 公共 trunk 源，下游 App 直接在 ios/Podfile 引用即可 （示例固定 1.0.30，并接入 Menta 的全局广告网络：MentaVlionGlobal + MentaVlionGlobalAdapter）：

pod 'MentaBaseGlobal',         '1.0.30'
pod 'MentaMediationGlobal',    '1.0.30'
pod 'MentaVlionGlobal',        '1.0.30'
pod 'MentaVlionGlobalAdapter', '1.0.30'

若某广告位在服务端配置了其他网络（DIO/TPN/TradPlus/TaurusX/MAX），再按需增补对应 Menta*Adapter 公共库。Menta 为 static_framework，需以 framework 方式链接：

USE_FRAMEWORKS=static bundle exec pod install

初始化需传 appId 与 appKey： await MentaAds.initialize({ appId: 'A0004', appKey: '510cc...' });

Android 接入真实 Vlion SDK：本包 Android 端依赖 cn.vlion.ad:vlionad。 下游 App 需在其 android/build.gradle 的 allprojects.repositories（或 settings 的 dependencyResolutionManagement.repositories）中加入 Menta 的 maven 源（HTTP，需 allowInsecureProtocol = true）：

maven { url 'http://sdk.mentamob.com/repository/vlion/'; allowInsecureProtocol = true }

并在 AndroidManifest.xml 加上 INTERNET / ACCESS_NETWORK_STATE / com.google.android.gms.permission.AD_ID 权限。

注意：iOS 与 Android 的 appId/appKey 与广告位 ID 均不同，下游需按平台分别传参（见 example/src/adConfig.ts 用 Platform.select 的写法）。

Expo 工程（SDK 54，RN 0.81.5）

本包含原生代码，不能用于 Expo Go，需 expo prebuild 或 dev-client：

// app.json
{
  "expo": {
    "plugins": [
      ["react-native-menta-ads-global", {
        "iosAppId": "your-ios-app-id",
        "androidAppId": "your-android-app-id"
      }]
    ]
  }
}

npx expo prebuild
npx expo run:ios     # 或 run:android

二、快速上手

import {
  MentaAds,
  SplashAd,
  InterstitialAd,
  RewardedAd,
} from 'react-native-menta-ads-global';

// 1. App 启动时初始化一次
await MentaAds.initialize({ appId: 'your-app-id', appKey: 'your-app-key' });

// 2. 加载 + 展示（以激励视频为例）
const ad = new RewardedAd(
  { placementId: 'your-placement-id' },
  {
    onLoaded: () => ad.show(),          // 就绪后展示
    onRewarded: (r) => grant(r.amount), // 发放激励
    onClosed: () => console.log('closed'),
    onError: (e) => console.warn(e.code, e.message),
  }
);
ad.load();

开屏、插屏用法相同，把 RewardedAd 换成 SplashAd / InterstitialAd 即可（无 onRewarded）。

Banner 与信息流模板是嵌入式广告：把组件放进布局，在合适时机调用 ref.load() 拉取并渲染（无全屏 show() 一步）。

import { useRef } from 'react';
import { BannerAd, NativeExpressAd, type AdViewHandle } from 'react-native-menta-ads-global';

const bannerRef = useRef<AdViewHandle>(null);
const feedRef = useRef<AdViewHandle>(null);

// Banner：高度自己给（不写默认 60）；默认不自动拉取、不自动刷新
<BannerAd
  ref={bannerRef}
  placementId="your-banner-id"
  style={{ width: '100%', height: 60 }}
  onLoaded={(info) => console.log('eCPM', info.ecpm)}
/>
// 用户进入页面或点击按钮时：
bannerRef.current?.load();

// 信息流模板：高度由素材决定，原生量好回传，组件自动撑开，别写死 height
<NativeExpressAd ref={feedRef} placementId="your-native-id" style={{ width: '100%' }} />
feedRef.current?.load();

三、API 参考

MentaAds

| 方法 | 说明 | | --- | --- | | initialize(config): Promise<boolean> | 初始化 SDK，需传 appId 与 appKey | | setLogLevel(level) | 'off' \| 'error' \| 'info' \| 'debug' | | isInitialized(): boolean | 是否已初始化 |

广告类 SplashAd / InterstitialAd / RewardedAd

new XxxAd(options: AdLoadOptions, listeners: AdListeners)

| 方法 | 说明 | | --- | --- | | load() | 加载广告 | | show() | 展示（需在 onLoaded 后） | | isReady(): boolean | 是否就绪 | | destroy() | 释放资源 | | getState(): AdState | 当前状态机 |

回调 AdListeners

onLoaded · onError(e) · onShown · onClicked · onClosed 激励视频额外：onRewarded(reward)

广告组件 BannerAd / NativeExpressAd

| Prop | 说明 | | --- | --- | | placementId | 广告位 ID（必填） | | style | 容器样式，给了 height 就以它为准 | | autoLoad | 挂载后是否自动拉取，默认 false（需 ref.load()） | | refreshInterval | 定时刷新间隔（秒），默认 0（不刷新） | | onLoaded(info) | 渲染成功，info 含 ecpm / width / height | | onError · onShown · onClicked · onClosed | 同 AdListeners | | hideCloseButton（仅 Banner） | 隐藏关闭按钮，默认 false | | autoHeight（仅信息流） | 按原生回传高度撑开容器，默认 true |

通过 ref 拿到 AdViewHandle，调 load() 或 reload() 拉取/换一条广告。

Mock 行为控制（仅模拟阶段生效）

new SplashAd({
  placementId: 'xxx',
  mock: {
    loadDelayMs: 800,  // 加载耗时
    failRate: 0.3,     // 失败概率 0~1
    displayMs: 3000,   // 展示时长
    autoClick: true,   // 展示后自动触发点击
  },
});

四、运行 Demo

yarn
yarn example ios       # 或 yarn example android

Demo 演示五种广告的完整流程与事件日志：三种全屏广告的加载/展示， 以及内嵌在页面里的 Banner 与信息流模板。

五、架构

src/
├─ NativeMentaAds.ts              TurboModule codegen spec（全屏广告的薄契约层）
├─ MentaAdViewNativeComponent.ts  Fabric 组件 codegen spec（嵌入式广告）
├─ core/MentaAds.ts               SDK 顶层入口（初始化/配置）
├─ ads/                           SplashAd / InterstitialAd / RewardedAd（命令式）
│                                 BannerAd / NativeExpressAd（组件，共用 AdView）
├─ internal/AdEventHub.ts         原生单通道事件 → 按 requestId 路由到实例
ios/     MentaAds.mm（TurboModule） + MentaAdView.mm（Fabric 视图）
         Menta*Adapter.m —— 各广告类型封装真实 SDK 的唯一一层
android/ MentaAdsModule.kt（TurboModule） + MentaAdViewManager.kt（Fabric 视图）
         Menta*Adapter.kt —— 同上

两条通道、同一套事件语义：

• 全屏广告走 TurboModule，JS 生成 requestId，原生按 id 维护实例， 事件统一从 onAdEvent 回流，再由 AdEventHub 分发到对应实例。
• 嵌入式广告走 Fabric 组件，事件同样收敛成一个 onAdEvent， 由 AdView 扇出成 onLoaded / onError / ...。

换网络、换 SDK 只需要改 Menta*Adapter：主模块、ViewManager、JS/TS 全层 以及下游对接代码都不受影响。