TapADN SDK Unity 接入文档

SDK 支持版本

Unity 2019.4 LTS 及以上（推荐使用 Unity 2022.3 LTS）
Android 5.0（API level 21）及以上
.NET Standard 2.0 及以上
Gradle 7.x + Android Gradle Plugin 4.0.1 及以上
Unity 集成资源：dirichlet_ad_unity_5.3.1.6.unitypackage

SDK 集成

平台版本说明

本次 5.3.0.4 更新适用于 Android。Unity iOS 工程请继续使用 5.3.0.1 UnityPackage；5.3.0.4 包的 iOS 构建脚本会请求同版本 CocoaPods，当前 iOS 发布版本仍为 5.3.0.1。

方式一：UnityPackage 导入（推荐）

下载 dirichlet_ad_unity_5.3.1.6.unitypackage
在 Unity 中依次点击 Assets → Import Package → Custom Package…
选择下载的 .unitypackage，保持所有条目勾选并导入
导入完成后确认存在以下目录：
- Assets/DirichletAd
- Assets/DirichletAd/sample（示例代码）
- Assets/Plugins/Android/DirichletAd

发布前务必删除示例代码

sample 目录包含示例代码，仅供开发调试参考。

正式发布前请务必删除 sample 目录，避免示例代码被打包到线上版本。

UnityPackage 导入后的下一步

使用 UnityPackage 导入后，可直接跳转至「SDK 初始化」章节开始接入。UnityPackage 已包含完整的 Gradle 依赖配置、AndroidManifest 权限声明及 ProGuard 混淆规则，无需手动处理。

下方「SDK 配置」章节仅适用于以下场景：

采用「方式二：手动拷贝」进行集成
项目已启用自定义 Gradle/Manifest 模板，需要与现有配置合并
构建时出现依赖冲突或 Manifest 合并错误

方式二：手动拷贝

将官方提供的 Assets/DirichletAd、Assets/Plugins/Android、Assets/Plugins/Android/DirichletAd/libs 等目录完整复制至项目
保留随包提供的 AndroidManifest.xml、mainTemplate.gradle、proguard-user.txt 等构建文件
如项目已有自定义模板，请根据下方「SDK 配置」章节合并配置

SDK 配置

适用范围

本章节仅适用于手动拷贝集成或需要自定义构建配置的场景。若使用 UnityPackage 导入且构建正常，可跳过本章节，直接阅读「运行时权限」及后续内容。

mainTemplate.gradle 依赖配置

在 Unity 中勾选 Project Settings → Player → Android → Publish Settings → Build → Custom Main Gradle Template
确认生成的 Assets/Plugins/Android/mainTemplate.gradle 中包含：
- flatDir { dirs 'libs', 'DirichletAd/libs' }
- 下列依赖声明

dependencies {
    implementation fileTree(dir: 'libs', include: ['*.jar'])

    implementation(name: "dirichlet_ad_5.3.1.6", ext: "aar")

    implementation 'com.squareup.okhttp3:okhttp:3.12.1'
}

提示

若接入方使用 EDM4U（External Dependency Manager for Unity），可保留 Assets/DirichletAd/Editor/DirichletAdDependencies.xml 以自动解析所需依赖。

AndroidManifest 权限配置

在 Custom Main Manifest 模式下编辑 Assets/Plugins/Android/AndroidManifest.xml，按需声明以下权限。SDK 的 Provider 等组件会从 AAR 的 Manifest 自动合并，无需手动添加：

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.unity3d.player">

    <!-- 必须权限 -->
    <uses-permission android:name="android.permission.INTERNET"/>
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>

    <!-- 建议权限（提高定向及下载能力，可按需裁剪） -->
    <uses-permission android:name="android.permission.READ_PHONE_STATE"/>
    <uses-permission android:name="android.permission.QUERY_ALL_PACKAGES"/>
    <uses-permission android:name="android.permission.REQUEST_INSTALL_PACKAGES"/>
    <uses-permission android:name="android.permission.BLUETOOTH"/>
    <uses-permission android:name="android.permission.BLUETOOTH_CONNECT"/>
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>
    <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/>
    <uses-permission android:name="android.permission.POST_NOTIFICATIONS"/>
</manifest>

升级后出现 tapad_ad_file_path 报错时

正常全量导入 5.3.1.6 UnityPackage 无需额外处理。该版本的 TapADFileProvider 不再使用 @xml/tapad_ad_file_path，Provider 声明会从 SDK AAR 自动合并。

若升级后构建时报 resource xml/tapad_ad_file_path not found，说明工程仍残留旧版 Manifest 配置，并非 SDK 漏包。请按以下步骤排查：

全工程搜索 tapad_ad_file_path，重点检查 Assets/Plugins/Android/DirichletAd/AndroidManifest.xml 和 Assets/Plugins/Android/AndroidManifest.xml
删除旧 Provider 中引用该资源的 <meta-data>；若整个 TapADFileProvider 都是手动添加的，请删除完整的 <provider> 节点
确保工程中没有旧版 dirichlet_ad_*.aar 共存
删除 Unity 生成缓存 Library/Bee/Android，然后执行 Clean Build

不要修改报错路径中的 packaged_manifests，该目录由构建过程生成；也不要自行创建同名 XML。

ProGuard 混淆配置

SDK 已内置 R8/ProGuard 混淆规则（通过 consumerProguardFiles 自动合并），通常无需手动添加配置。

如遇混淆相关问题，可在 Assets/Plugins/Android/proguard-user.txt 中增加以下规则：

-dontwarn okhttp3.**
-dontwarn okio.**
-dontwarn com.tapsdk.tapad.**
-keeppackagenames com.tapsdk.tapad.**
-keepclassmembers class * {
    @android.webkit.JavascriptInterface <methods>;
}
-keepclassmembers class * extends com.tapsdk.tapad.protobuf.GeneratedMessageLite {
    <fields>;
}
-keepnames class * extends com.tapsdk.tapad.protobuf.GeneratedMessageLite

运行时权限

Unity 侧可在合适时机请求 SDK 所需权限：

using Dirichlet.Ad;

public void RequestPermissionsIfNeeded()
{
    DirichletAdSdk.RequestPermissionIfNecessary();
}

SDK 初始化

创建配置

using Dirichlet.Ad;

var config = new DirichletAdConfig.Builder()
    .WithMediaId(YourMediaId)
    .WithMediaKey("your-media-key")
    .WithMediaName("YourGame")
    .EnableDebug(false)      // 开发阶段可设为 true
    .ShakeEnabled(true)
    .Build();

参数	类型	必填	说明
`MediaId`	`long`	✅	Dirichlet 后台分配的媒体 ID
`MediaKey`	`string`	✅	媒体密钥
`MediaName`	`string`	❌	用于日志及后台展示
`EnableDebug`	`bool`	❌	是否输出调试日志，正式发布前建议关闭
`ShakeEnabled`	`bool`	❌	是否开启摇一摇交互
`CustomConfigJson`	`string`	❌	透传自定义配置 JSON

初始化 SDK

DirichletAdSdk.Init(
    config,
    onSuccess: result => {
        Debug.Log($"Dirichlet 初始化成功: {result.Message}");
    },
    onFailure: error => {
        Debug.LogError($"Dirichlet 初始化失败: {error.Code} / {error.Message}");
    }
);

if (!DirichletAdSdk.IsInitialized)
{
    Debug.LogWarning("TapADN SDK 尚未初始化完成");
}

获取 SDK 版本

string version = DirichletAdSdk.GetVersion();
Debug.Log($"TapADN SDK Version: {version}");

广告通用流程

创建或复用 DirichletAdNative：var adNative = DirichletAdManager.CreateAdNative();
使用 DirichletAdRequest.Builder 配置 SpaceId、UserId、Reward 等参数
调用 Load*Ad 接口并在成功回调中注册 Shown、Clicked、Closed 等事件
调用 Show() 展示广告，完成后可调用 Destroy() 释放资源

广告类型示例

激励视频（Reward Video）

自动加载展示（推荐，Android only）

4.2.0.1 新增

ShowRewardVideoAutoAd 接口将加载和展示合并为一次调用，内部自动管理广告缓存。若有可用缓存则立即展示，否则自动加载后展示。

public class MyRewardVideoAutoAdListener : IDirichletRewardVideoAutoAdListener
{
    public void OnError(DirichletError error)
    {
        Debug.LogError($"激励视频加载/展示失败: {error.Code} {error.Message}");
    }

    public void OnAdShow()
    {
        Debug.Log("激励视频展示");
    }

    public void OnAdClose()
    {
        Debug.Log("激励视频关闭");
    }

    public void OnRewardVerify(DirichletRewardVerificationEventArgs args)
    {
        if (args.IsVerified)
        {
            GrantReward(args.RewardAmount, args.RewardName);
        }
    }

    public void OnAdClick()
    {
        Debug.Log("激励视频点击");
    }
}

// 调用方式
adNative.ShowRewardVideoAutoAd(request, new MyRewardVideoAutoAdListener());

手动加载展示

private DirichletRewardVideoAd rewardAd;

public void LoadRewardAd(DirichletAdNative adNative, DirichletAdRequest request)
{
    adNative.LoadRewardVideoAd(
        request,
        onLoaded: ad => {
            rewardAd = ad;
            rewardAd.Shown += () => Debug.Log("激励视频展示");
            rewardAd.RewardVerified += args => {
                if (args.IsVerified)
                {
                    GrantReward(args.RewardAmount, args.RewardName);
                }
            };
            rewardAd.Closed += () => {
                rewardAd.Destroy();
                rewardAd = null;
            };
        },
        onFailure: error => Debug.LogError($"激励视频加载失败 {error.Code}:{error.Message}")
    );
}

public void ShowRewardAd()
{
    if (rewardAd != null && rewardAd.IsLoaded)
    {
        rewardAd.Show();
    }
}

插屏（Interstitial）

自动加载展示（推荐，Android only）

4.2.2.0 新增

ShowInterstitialAutoAd 接口将加载和展示合并为一次调用，内部自动管理广告缓存。若有可用缓存则立即展示，否则自动加载后展示。

public class MyInterstitialAutoAdListener : IDirichletInterstitialAutoAdListener
{
    public void OnError(DirichletError error)
    {
        Debug.LogError($"插屏加载/展示失败: {error.Code} {error.Message}");
    }

    public void OnAdShow()
    {
        Debug.Log("插屏展示");
    }

    public void OnAdClick()
    {
        Debug.Log("插屏点击");
    }

    public void OnAdClose()
    {
        Debug.Log("插屏关闭");
    }
}

// 调用方式
adNative.ShowInterstitialAutoAd(request, new MyInterstitialAutoAdListener());

手动加载展示

adNative.LoadInterstitialAd(
    request,
    onLoaded: ad => {
        ad.Shown += () => Debug.Log("插屏展示");
        ad.Closed += () => ad.Destroy();
        ad.Show();
    },
    onFailure: error => Debug.LogWarning($"插屏加载失败 {error.Code}:{error.Message}")
);

自动加载展示（推荐，Android only）

4.2.2.0 新增

ShowBannerAutoAd 接口将加载和展示合并为一次调用，内部自动管理广告缓存与轮播刷新。开发者只需指定容器，SDK 自动完成加载、展示和定时刷新。

public class MyBannerAutoAdListener : IDirichletBannerAutoAdListener
{
    public void OnError(DirichletError error)
    {
        Debug.LogError($"Banner 加载/展示失败: {error.Code} {error.Message}");
    }

    public void OnAdShow()
    {
        Debug.Log("Banner 展示");
    }

    public void OnAdClick()
    {
        Debug.Log("Banner 点击");
    }

    public void OnAdClose()
    {
        Debug.Log("Banner 关闭");
    }
}

// 调用方式，slideInterval 为轮播间隔（秒），取值范围 30~120，默认 30
var request = new DirichletAdRequest.Builder()
    .WithSpaceId(BannerSlotId)
    .WithSlideInterval(30)
    .Build();

adNative.ShowBannerAutoAd(request, new MyBannerAutoAdListener());

手动加载展示

adNative.LoadBannerAd(
    request,
    onLoaded: ad => {
        ad.Shown += () => Debug.Log("Banner 展示");
        ad.Closed += () => ad.Destroy();

        ad.Show(new DirichletAdShowOptions {
            BannerAlignment = DirichletBannerAlignment.Bottom,
            BannerOffset = 0
        });
    },
    onFailure: error => Debug.LogError($"Banner 加载失败 {error.Message}")
);

开屏（Splash）

自动加载展示（推荐，Android only）

4.2.2.0 新增

ShowSplashAutoAd 接口将加载和展示合并为一次调用，内部自动管理广告缓存。若有可用缓存则立即展示，否则自动加载后展示。

public class MySplashAutoAdListener : IDirichletSplashAutoAdListener
{
    public void OnError(DirichletError error)
    {
        Debug.LogError($"开屏加载/展示失败: {error.Code} {error.Message}");
        GoToMainScene();
    }

    public void OnAdShow()
    {
        Debug.Log("开屏展示");
    }

    public void OnAdClick()
    {
        Debug.Log("开屏点击");
    }

    public void OnAdClose()
    {
        Debug.Log("开屏关闭");
        GoToMainScene();
    }
}

// 调用方式
var splashRequest = new DirichletAdRequest.Builder()
    .WithSpaceId(SplashSlotId)
    .WithExpressViewSize(Screen.width, Screen.height)
    .Build();

adNative.ShowSplashAutoAd(splashRequest, new MySplashAutoAdListener());

手动加载展示

var splashRequest = new DirichletAdRequest.Builder()
    .WithSpaceId(SplashSlotId)
    .WithExpressViewSize(Screen.width, Screen.height)
    .Build();

adNative.LoadSplashAd(
    splashRequest,
    onLoaded: ad => {
        ad.Shown += () => Debug.Log("开屏展示");
        ad.Closed += () => GoToMainScene();
        ad.Show();
    },
    onFailure: error => {
        Debug.LogWarning($"开屏加载失败 {error.Code}:{error.Message}");
        GoToMainScene();
    });

资源管理与最佳实践

统一管理 DirichletAdNative，避免在多个场景重复创建
广告展示后调用 Destroy()，并重新发起加载
仅在激励广告 RewardVerified 且 IsVerified = true 时发放奖励
开发阶段可开启 EnableDebug(true)，发布包务必关闭
针对关键节点（关卡结束、登录完成）提前预加载广告以降低等待时间

常见问题

问题	排查建议
初始化失败	核对 `MediaId/MediaKey`，确认网络可用，查看调试日志
广告加载失败	确认 `SpaceId` 正常投放，依赖与权限是否完整
横幅不展示	检查宿主 Activity 是否常驻，确保未频繁销毁 Banner 句柄
奖励未发放	必须在 `RewardVerified` 且 `IsVerified` 为 true 后发奖

更新记录

5.3.1.6（2026-10-23）

【优化】 完善 Android 隐私采集控制与宿主兼容性，统一广告额外点击区域控制

5.2.1.9（2026-09-10）

【优化】 提升稳定性

5.2.1.5（2026-08-31）

【优化】 提升稳定性

5.1.2.3（2026-08-12）

【优化】 提升稳定性

5.1.1.1（2026-08-06）

【优化】 广告样式优化
【优化】 提升 SDK 整体稳定性及兼容性

4.2.8.3（2026-07-28）

【优化】 提升 SDK 整体稳定性及兼容性

4.2.4.8（2026-05-06）

【优化】 稳定性提升

4.2.4.3（2026-04-08）

【优化】 广告样式完善，提升点击率；稳定性提升

4.2.3.3（2026-03-16）

【优化】 稳定性提升

4.2.2.0（2026-03-09）

【优化】 稳定性提升

4.2.1.1（2026-02-28）

【优化】 广告样式优化，提升点击率；稳定性提升

4.2.0.8（2026-01-15）

【优化】 稳定性提升

4.2.0.7（2026-01-14）

【优化】 稳定性提升

4.2.0.2（2026-01-09）

【优化】 提升 SDK 整体稳定性及运行时性能表现

SDK 支持版本​

SDK 集成​

方式一：UnityPackage 导入（推荐）​

方式二：手动拷贝​

SDK 配置​

mainTemplate.gradle 依赖配置​

AndroidManifest 权限配置​

ProGuard 混淆配置​

运行时权限​

SDK 初始化​

创建配置​

初始化 SDK​

获取 SDK 版本​

广告通用流程​

广告类型示例​

激励视频（Reward Video）​

自动加载展示（推荐，Android only）​

手动加载展示​

插屏（Interstitial）​

自动加载展示（推荐，Android only）​

手动加载展示​

横幅（Banner）​

自动加载展示（推荐，Android only）​

手动加载展示​

开屏（Splash）​

自动加载展示（推荐，Android only）​

手动加载展示​

资源管理与最佳实践​

常见问题​

更新记录​

5.3.1.6（2026-10-23）​

5.2.1.9（2026-09-10）​

5.2.1.5（2026-08-31）​

5.1.2.3（2026-08-12）​

5.1.1.1（2026-08-06）​

4.2.8.3（2026-07-28）​

4.2.4.8（2026-05-06）​

4.2.4.3（2026-04-08）​

4.2.3.3（2026-03-16）​

4.2.2.0（2026-03-09）​

4.2.1.1（2026-02-28）​

4.2.0.8（2026-01-15）​

4.2.0.7（2026-01-14）​

4.2.0.2（2026-01-09）​

SDK 支持版本

SDK 集成

方式一：UnityPackage 导入（推荐）

方式二：手动拷贝

SDK 配置

mainTemplate.gradle 依赖配置

AndroidManifest 权限配置

ProGuard 混淆配置

运行时权限

SDK 初始化

创建配置

初始化 SDK

获取 SDK 版本

广告通用流程

广告类型示例

激励视频（Reward Video）

自动加载展示（推荐，Android only）

手动加载展示

插屏（Interstitial）

自动加载展示（推荐，Android only）

手动加载展示

横幅（Banner）

自动加载展示（推荐，Android only）

手动加载展示

开屏（Splash）

自动加载展示（推荐，Android only）

手动加载展示

资源管理与最佳实践

常见问题

更新记录

5.3.1.6（2026-10-23）

5.2.1.9（2026-09-10）

5.2.1.5（2026-08-31）

5.1.2.3（2026-08-12）

5.1.1.1（2026-08-06）

4.2.8.3（2026-07-28）

4.2.4.8（2026-05-06）

4.2.4.3（2026-04-08）

4.2.3.3（2026-03-16）

4.2.2.0（2026-03-09）

4.2.1.1（2026-02-28）

4.2.0.8（2026-01-15）

4.2.0.7（2026-01-14）

4.2.0.2（2026-01-09）