react-native-tencent-gdt

腾讯优量汇广告 SDK for React Native

支持 TurboModule 新架构 | TypeScript 类型安全

English | 简体中文

📖 项目简介

react-native-tencent-gdt 是一个现代化的 React Native 库,为腾讯优量汇(Tencent GDT/Youlianghui)广告平台提供完整的 SDK 封装。

🎯 项目目标

• ✅ 使用最新技术栈 - 基于 React Native 新架构 (TurboModule + Codegen)
• ✅ 完整的 TypeScript 支持 - 提供完整的类型定义和智能提示
• ✅ 持续更新 - 跟进腾讯优量汇 SDK 最新版本
• ✅ 开箱即用 - 简单的 API 设计,快速集成
• ✅ 生产就绪 - 完善的错误处理和事件回调
• ✅ 开源社区驱动 - 欢迎贡献和反馈

🌟 为什么选择这个库?

| 特性 | 本库 | 其他方案 | | ---------------- | ----------------- | ------------- | | TurboModule 支持 | ✅ | ❌ | | TypeScript | ✅ 完整类型 | ⚠️ 部分支持 | | 维护状态 | ✅ 活跃维护 | ⚠️ 长期未更新 | | SDK 版本 | ✅ 最新 (4.6x+) | ⚠️ 旧版本 | | 文档 | ✅ 中英文完整文档 | ⚠️ 文档缺失 |

🚀 快速开始

安装

# 使用 npm
npm install react-native-tencent-gdt

# 使用 yarn
yarn add react-native-tencent-gdt

# 使用 pnpm
pnpm add react-native-tencent-gdt

安装依赖

iOS

cd ios
pod install
cd ..

Android

Android 端会自动链接,无需额外配置。

配置原生项目

Android 配置

1. 确保 android/build.gradle 中的 minSdkVersion >= 21
2. 库已自动配置腾讯优量汇 SDK 依赖和必要权限

iOS 配置

1. 确保 ios/Podfile 中的 platform :ios >= '12.0'
2. 运行 pod install 后会自动安装腾讯优量汇 SDK

运行项目

# iOS
npx react-native run-ios

# Android
npx react-native run-android

📱 支持的广告类型

✅ 已实现

• 🎬 开屏广告 (Splash Ad) - 应用启动时展示,支持跳过按钮
• 🎁 激励视频广告 (Rewarded Video Ad) - 观看视频获得奖励,支持服务端验证
• 🖼️ 插屏全屏广告 (Interstitial Ad) - 支持图文/视频/激励三种形式
• 🎯 插屏半屏广告 (Half Screen Interstitial Ad) - 半屏插屏

🚧 计划中

• 📰 Banner 广告 (Banner Ad) - 页面顶部/底部横幅
• 📱 信息流广告 (Native Express Ad) - 原生信息流

💡 基本用法

初始化 SDK

import TencentGdt from 'react-native-tencent-gdt';
import { Platform } from 'react-native';

// 在应用启动时初始化
await TencentGdt.initialize({
  appId: Platform.OS === 'ios' ? 'YOUR_IOS_APP_ID' : 'YOUR_ANDROID_APP_ID',
  debug: __DEV__, // 开发环境启用调试
});

开屏广告

import { SplashAd } from 'react-native-tencent-gdt';

const result = await SplashAd.show({
  posId: 'YOUR_SPLASH_AD_POS_ID',
  skipDelay: 3, // 跳过按钮延迟时间(秒)
  showDownloadInfo: true, // 是否显示下载信息
  onAdPresent: () => console.log('广告展示'),
  onAdDismiss: () => console.log('广告关闭'),
  onAdFailed: (error) => console.error('广告失败', error),
  onAdClicked: () => console.log('广告被点击'),
});

if (result.success) {
  console.log('开屏广告展示成功');
}

激励视频广告

import { RewardedVideoAd } from 'react-native-tencent-gdt';

const result = await RewardedVideoAd.show({
  posId: 'YOUR_REWARDED_VIDEO_POS_ID',
  userId: 'user_123', // 可选,用于服务端验证
  customData: 'custom_data', // 可选,用于服务端验证
  onRewarded: (reward) => {
    console.log('获得奖励!', reward);
    // 发放奖励给用户
  },
  onAdDismiss: () => console.log('广告关闭'),
  onAdFailed: (error) => console.error('广告失败', error),
});

if (result.success && result.reward?.rewarded) {
  // 用户观看完整视频,发放奖励
  console.log('用户已获得奖励');
}

插屏全屏广告

import { InterstitialAd } from 'react-native-tencent-gdt';

const result = await InterstitialAd.show({
  posId: 'YOUR_INTERSTITIAL_AD_POS_ID',
  onAdDismiss: () => console.log('广告关闭'),
  onAdFailed: (error) => console.error('广告失败', error),
});

if (result.success) {
  console.log('插屏广告展示成功');
}

注意: 插屏全屏广告支持三种形式:

• 插屏全屏图文 - 5秒后展示关闭按钮,支持上滑交互
• 插屏全屏视频 - 全屏视频广告
• 奖励式插屏视频 - 完成观看可获得奖励

SDK 会根据广告位配置自动返回相应类型,无需额外配置。

插屏半屏广告

import { HalfScreenInterstitialAd } from 'react-native-tencent-gdt';

const result = await HalfScreenInterstitialAd.show({
  posId: 'YOUR_HALF_SCREEN_INTERSTITIAL_AD_POS_ID',
  onAdDismiss: () => console.log('广告关闭'),
  onAdFailed: (error) => console.error('广告失败', error),
});

if (result.success) {
  console.log('插屏半屏广告展示成功');
}

🏗️ 技术架构

TurboModule 新架构

本库基于 React Native 新架构构建,使用 TurboModule 和 Codegen:

• 更快的启动速度 - 懒加载原生模块
• 类型安全 - 自动生成类型定义
• 更好的性能 - 直接 JSI 调用,无需 Bridge
• 面向未来 - 与 React Native 0.68+ 完美兼容

项目结构

react-native-tencent-gdt/
├── android/              # Android 原生代码 (Kotlin)
│   └── src/
│       └── main/
│           └── java/com/tencentgdt/
├── ios/                  # iOS 原生代码 (Objective-C)
│   ├── TencentGdt.h
│   └── TencentGdt.mm
├── src/                  # TypeScript 源码
│   ├── NativeTencentGdt.ts    # TurboModule 接口定义
│   ├── index.tsx              # 主入口
│   ├── types.ts               # 类型定义
│   └── components/            # React 组件
├── plugin/               # Expo Config Plugin
│   └── src/
│       └── withTencentGdt.ts
└── example/              # 示例应用 (Expo)

🔧 开发计划

当前状态

• [x] 项目脚手架搭建
• [x] TurboModule 基础架构
• [x] Android SDK 集成
• [x] iOS SDK 集成
• [x] 开屏广告实现
• [ ] Banner 广告实现
• [x] 插屏广告实现
• [x] 激励视频广告实现
• [ ] 信息流广告实现
• [ ] 完整文档
• [ ] 示例应用
• [ ] 单元测试
• [ ] 发布到 npm

Roadmap

v0.1.0 (MVP)

• 基础 SDK 初始化
• 开屏广告
• Banner 广告

v0.2.0

• 插屏广告
• 激励视频广告
• 完整的事件回调

v0.3.0

• 信息流广告
• 全屏视频广告
• Expo Config Plugin

v1.0.0

• 生产就绪
• 完整测试覆盖
• 性能优化

📚 文档

• 完整 API 文档 (待完成)
• 集成指南 (待完成)
• Expo 使用指南 (待完成)
• 常见问题 (待完成)
• 更新日志

🤝 贡献

欢迎贡献代码、报告问题或提出建议!

请查看 贡献指南 了解详情。

开发环境设置

# 克隆仓库
git clone https://github.com/qcwl/react-native-tencent-gdt.git
cd react-native-tencent-gdt

# 安装依赖
yarn install

# 运行示例应用
yarn example android
# 或
yarn example ios

# 运行测试
yarn test

# 代码检查
yarn lint

# 类型检查
yarn typecheck

📄 许可证

MIT License - 详见 LICENSE 文件

🙏 致谢

• 腾讯优量汇 - 提供广告 SDK
• React Native - 跨平台框架
• Expo - 开发工具链
• 所有贡献者和使用者

📞 联系方式

• 问题反馈: GitHub Issues
• 功能建议: GitHub Discussions
• 邮件: [email protected]

⭐ Star History

如果这个项目对您有帮助,请给我们一个 Star ⭐️

用 ❤️ 打造 | Made with ❤️

GitHub • npm • 文档