跳到主要内容
版本：v3

TapADN SDK 接入指南

SDK 配置​

Unity 模块是通过引入 Android 模块后增加桥接文件打包出的 .unitypackage，方便以 Unity 开发的游戏直接引入。其他引擎/平台的游戏可以通过 Android 原生的方式接入，详见 Android 接入文档。

开发环境要求：

  • Unity 2019.4 或更高版本
  • Android 5.0（API level 21）或更高版本
提示

Unity 项目可在 TapTap/TapAD/Demo 找到示例工程来了解其实现过程，注意 Demo 工程需要到真机中才能看到效果，Editor 环境并不会实际生效。

点击展开 Unity 2020.3.15 之前的版本升级 Gradle 版本

在 Project Settings -> Player -> Android Tab -> Publish Settings -> Build，然后勾选Custom Base Gradle Template

将以下更改应用于生成的这个文件: Assets/Plugins/Android/baseProjectTemplate.gradle

如果存在，请移除文件顶部的以下注释：

// GENERATED BY UNITY. REMOVE THIS COMMENT TO PREVENT OVERWRITING WHEN EXPORTING AGAIN

修改文件内容:

dependencies {
    // If you are changing the Android Gradle Plugin version, make sure it is compatible with the Gradle version preinstalled with Unity
    // See which Gradle version is preinstalled with Unity here https://docs.unity3d.com/Manual/android-gradle-overview.html
    // See official Gradle and Android Gradle Plugin compatibility table here https://developer.android.com/studio/releases/gradle-plugin#updating-gradle
    // To specify a custom Gradle version in Unity, go do "Preferences > External Tools", uncheck "Gradle Installed with Unity (recommended)" and specify a path to a custom Gradle version
    // 将 3.x.0 版本修改为 4.0.1
    //classpath 'com.android.tools.build:gradle:3.x.0'
    classpath 'com.android.tools.build:gradle:4.0.1'
}

同时，为了将 Gradle 版本和 Android Gradle Plugin 版本对应，需要更新 Gradle 版本，下载 6.1.1 版本的 Gradle，解压后放到自定义的文件夹中，同时不勾选 Unity 中的 Preferences -> External Tools-> Android -> Gradle Installed with Unity(recommend)，改为选择解压后 Gradle 文件夹的位置，如 <some path>/gradle-6.1.1。

无论 Unity 版本都添加一些原生依赖库：在 Project Settings -> Player -> Android Tab -> Publish Settings -> Build，勾选Custom Main Gradle Template

将以下更改应用于生成的这个文件: Assets/Plugins/Android/mainTemplate.gradle

如果存在，请移除文件顶部的以下注释：

// GENERATED BY UNITY. REMOVE THIS COMMENT TO PREVENT OVERWRITING WHEN EXPORTING AGAIN

修改文件内容:

提示
  • TapADN SDK 从 3.16.3.10 版本开始更新了 glide 的依赖，glide 版本从 4.0.0 更新到了 4.9.0。
  • 3.16.3.17 加入 Android Dependencies 文件（位于 TapAD/Editor/TapAdDependencies.xml) 方便接入 EDM4U(https://github.com/googlesamples/unity-jar-resolver) 的项目方解决 Android 依赖。
dependencies {
    implementation fileTree(dir: 'libs', include: ['*.jar'])
// 加入的依赖库-开始
    implementation 'io.reactivex.rxjava2:rxandroid:2.0.1'
    implementation 'io.reactivex.rxjava2:rxjava:2.0.1'
    implementation 'com.squareup.okhttp3:okhttp:3.12.1'
    implementation "com.android.support:appcompat-v7:28.0.0"
    implementation "com.android.support:support-annotations:28.0.0"
    implementation "com.android.support:support-v4:28.0.0"
    implementation "com.github.bumptech.glide:glide:4.9.0"
    implementation 'com.android.support:recyclerview-v7:28.0.0'
// 加入的依赖库-结束
// 下面这行是 Unity 的 mainTemplate.gradle 自带的，帮助定位插入位置
// **DEPS**
}

权限申请​

无论 Unity 版本都需加入 Android 相关权限申请，在 Project Settings -> Player -> Android Tab -> Publish Settings -> Build，勾选Custom Main Manifest。

将以下更改应用于生成的这个文件: Assets/Plugins/Android/AndroidManifest.xml

如果存在，请移除文件顶部的以下注释：

// GENERATED BY UNITY. REMOVE THIS COMMENT TO PREVENT OVERWRITING WHEN EXPORTING AGAIN

修改文件内容:

<?xml version="1.0" encoding="utf-8"?>
<manifest
    xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.unity3d.player"
    xmlns:tools="http://schemas.android.com/tools">

    <!-- TapAd 必须的权限-开始  -->
    <!-- TargetVersion 31 及以上 通过时，需要该权限) deviceName 和下面的 BLUETOOTEH 互斥-->
    <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"/>
    <!-- IMEI 、序列号、MEID 、IMSI 、 ICCID 等信息。TargetSdkVersion 4 以及更高需要申请 -->
    <uses-permission android:name="android.permission.READ_PHONE_STATE"/>
    <!-- TapAd 必须的权限-结束  -->
    
    <!-- TapAd 可选择权限-开始   -->
    <!-- 获取网络状态信息   -->
    <uses-permission android:name="android.permission.ACCESS_WIFI_STATE"/> 
    <!-- 获取安装应用列表  Android 11 及以上版本才需声明，Android 11 以下版本无需申请 -->
    <uses-permission android:name="android.permission.QUERY_ALL_PACKAGES"/>
    <!-- （targetVersion 31 以下）deviceName 和上面的 BLUETOOTH_CONNECT 互斥-->
    <uses-permission android:name="android.permission.BLUETOOTH"/>
    <!-- 允许应用请求安装软件包 -->
    <uses-permission android:name="android.permission.REQUEST_INSTALL_PACKAGES"/>
    <!-- TapAd 可选择权限-结束   -->
    ...

获取广告权限​

在获取 imei 地理位置时，需要用户授予权限。建议先询问权限，再进行初始化工作。

using TapTap.TapAd
TapAdSdk.RequestPermissionIfNecessary();

初始化​

using TapTap.TapAd

TapAdConfig config = new TapAdConfig.Builder()
                .MediaId(your_media_id)             // 必选参数，为 TapADN 注册的媒体 ID
                .MediaName(your_media_name)         // 必选参数，为 TapADN 注册的媒体名称
                .MediaKey(your_media_key)           // 必选参数，媒体密钥，可以在 TapADN 后台查看（用于传输数据的解密）
                .MediaVersion("1")                  // 必选参数，默认值 "1"
                .Channel(your__channel)             // 必选参数，渠道
                .TapClientId(your_tap_client_id)    // 可选参数，TapTap 开发者中心的游戏 Client ID 
                .EnableDebugLog(false)              // 可选参数，是否打开原生 debug 调试信息输出：true 打开、false 关闭。默认 false 关闭
                .ShakeEnabled(false)                // 可选参数，是否开启摇一摇: true 打开、false 关闭。
                .Build();

// CustomControllerWrapper 为实现了 TapTap.TapAd.ICustomController 的类
// onInitedCallback 为可选回调函数，类型是 System.Action，
TapAdSdk.Init(config, new CustomControllerWrapper(this), onInitedCallback);

// ICustomController 接口说明
public interface ICustomController
{
    // 是否允许 SDK 主动使用地理位置信息
    bool CanUseLocation { get; }

    // 当 isCanUseLocation=false 时，可传入地理位置信息，TapAd 使用您传入的地理位置信息
    TapAdLocation GetTapAdLocation { get; }

    // 是否允许 SDK 主动使用手机硬件参数，如 imei
    bool CanUsePhoneState { get; }

    // 当 isCanUsePhoneState=false 时，可传入 imei 信息，TapAd 使用您传入的 imei 信息
    string GetDevImei { get; }

    // 是否允许 SDK 主动使用 ACCESS_WIFI_STATE 权限
    bool CanUseWifiState { get; }

    // 是否允许 SDK 主动使用 WRITE_EXTERNAL_STORAGE 权限
    bool CanUseWriteExternal { get; }

    // 开发者可以传入 oaid
    // 信通院 OAID 的相关采集——如何获取 OAID：
    // 1. 移动安全联盟官网 http://www.msa-alliance.cn/
    // 2. 信通院统一 SDK 下载 http://msa-alliance.cn/col.jsp?id=120
    string GetDevOaid { get; }

    // 是否允许 SDK 主动获取设备上应用安装列表的采集权限
    bool Alist { get; }

    // 是否允许 SDK 主动获取 ANDROID_ID
    bool CanUseAndroidId { get; }

    // 用户信息（为了提高广告的推送效率，开发者可以帮助传入一些用户的画像信息）
    CustomUser ProvideCustomer();
}

// 地理位置说明
public sealed class TapAdLocation 
{
    // 纬度
    public double latitude;

    // 经度
    public double longitude;

    // 精度
    public double accuracy;
    
    // 设置经纬度
    public TapAdLocation(double latitude, double longitude, double accuracy)
    {
        //...
    }
}

// 用户信息
public sealed class CustomUser
{
    public int realAge;
    // 0.男;1.女
    public int realSex;
    // 角色性别 0.男;1.女
    public int avatarSex;
    // 角色等级
    public int avatarLevel;
    // 是否新玩家 0.否;1.是
    public int newUserStatus;
    // 是否为付费用户 0.否;1.是
    public int payedUserStatus;
    // 是否通过新手教程 0.否;1.是
    public int beginMissionFinished;
    // 角色当前付费道具数量
    public int avatarPayedToolCnt;
}

上报用户行为​

为了获取更优质的广告内容，需要游戏额外提供一些玩家在游戏中的行为数据作为补充。

using TapTap.TapAd
var userActions = new UserAction[3];
var jan1st1970 = new DateTime
    (1970, 1, 1, 0, 0, 0, DateTimeKind.Utc);
for (int i = 0 ; i < 3; i ++) {
    var tmp = new UserAction(actionType: i, actionTime: (long)(DateTime.UtcNow - jan1st1970).TotalMilliseconds,
                amount: i * 1000, winStatus: i % 2);
    userActions[i] = tmp;
}
// CustomUserAction 为实现了 IUserAction 的类
TapAdSdk.UploadUserAction(userActions, new CustomUserAction(this));
// 用户行为数据类说明
public class UserAction
{
    // 行为动作类型,可自定义
    public int ActionType { get; }

    // 行为发生时间（单位：秒）
    public long ActionTime { get; }

    // 付费金额
    public int Amount{ get; }

    // 是否胜利.0-失败;1-胜利
    public int WinStatus{ get; }
    public UserAction(int actionType, long actionTime, int amount, int winStatus) 
    {
        ...
    }
}
// 上报接口说明
public interface IUserAction
{
    // 上报成功
    void OnSuccess();

    // 上报失败
    void OnError(int code, string message);
}

开屏广告​

开屏广告为用户在进入 App 时展示的全屏广告。开屏广告为一个 View，宽高默认为 match_parent。

信息

竖屏开屏广告 view 要求 width = 屏幕宽，height 需要 >= 75% 屏幕高，否则会影响计费。

横屏开屏广告 view 要求 width = 屏幕宽，height 需要 = 屏幕高，否则会影响计费。

建议业务逻辑：

  1. 每次启动应用的时候调用 SDK 接口请求开屏广告。
  2. SDK 会根据一定规则从候选队列里选取一个返回给游戏，获取成功就可以展示，获取失败的话本次不展示广告。

获取广告​

using TapTap.TapAd
TapSplashAd _tapSplashAd = null;
if (TapAdSdk.IsInited == false)
{
    Debug.Log("TapAd 需要先初始化!");
    return;
}
// 释放之前的广告
if (_tapSplashAd != null)
{
    _tapSplashAd.Dispose();
    _tapSplashAd = null;
}
int adId = YOUR_AD_ID;
// create AdRequest
var request = new TapAdRequest.Builder()
    .SpaceId(adId)
    .Build();
_tapSplashAd = new TapSplashAd(request);
// SplashAdLoadListener 为实现了 ISplashAdLoadListener 的类
_tapSplashAd.SetLoadListener(new SplashAdLoadListener(this));
_tapSplashAd.Load();
// Splash 加载接口说明
public interface ISplashAdLoadListener : ICommonLoadListener
{
    // 当 Splash 加载完毕
    void OnSplashAdLoad(TapSplashAd ad);
}
// 通用加载接口说明
public interface ICommonLoadListener
{
    // 加载出错回调
    void OnError(int code, string message);
}

播放​

using TapTap.TapAd
if (TapAdSdk.IsInited == false)
{
    Debug.Log("TapAd 需要先初始化!");
    return;
}
if (_tapSplashAd != null)
{
    // SplashInteractionListener 为实现了 ISplashAdInteractionListener 的类
    _tapSplashAd.SetInteractionListener(new SplashInteractionListener(this));
    _tapSplashAd.Show();
}
else
{
    Debug.LogErrorFormat($"[Unity::AD] 未加载好视频，无法播放!");
}
// Splash 播放回调接口说明
public interface ISplashAdInteractionListener : ICommonInteractionListener
{
    // 点击跳过
    void OnAdSkip(TapSplashAd ad);

    // 广告时间到
    void OnAdTimeOver(TapSplashAd ad);

    // 点击广告回调 3.16.3.30 新增
    void OnAdClick();
}
// 通用播放回调接口说明
public interface ICommonInteractionListener
{
    
}

关闭开屏广告​

提示

注意 3.16.3.23 版本开始 开屏广告移除了自动关闭逻辑，需要媒体手动关闭。

using TapTap.TapAd
// 场景 1 媒体直接关闭开屏广告
if (_tapSplashAd != null)
{
    _tapSplashAd.Dispose();
}

// 场景 2 在收到开屏广告交互事件后选择关闭
public void OnAdSkip(TapSplashAd ad) {
    if (ad != null) ad.Dispose();
}

public void OnAdTimeOver(TapSplashAd ad) {
    if (ad != null) ad.Dispose();
}
...

激励视频广告​

激励视频是一种全屏播放的视频广告，用户可以在观看完整的视频后获取奖励,视频广告播放结束后会显示结束页面，引导用户进行后续动作。目前激励视频广告的表现形式为：视频播放完展示 Endcard 页面。

使用场景包括但不限于：

  1. 游戏等应用内观看视频广告获得游戏内金币等。
  2. 积分类应用接入。
支持的广告尺寸
  • 全屏横屏（宽高比 16:9）
  • 全屏竖屏（宽高比 9:16）
  • Android 端暂不支持重力旋转。

获取广告​

using TapTap.TapAd
TapRewardVideoAd _tapRewardAd = null;
if (TapAdSdk.IsInited == false)
{
    Debug.Log("TapAd 需要先初始化!");
    return;
}
if (_tapRewardAd != null)
{
    _tapRewardAd.Dispose();
    _tapRewardAd = null;
}
int adId = YOUR_AD_ID;
// create AdRequest
var request = new TapAdRequest.Builder()
    .SpaceId(adId)
    .RewardName("your_reward_name")
    .RewardCount(your_reward_count)
    .Build();
_tapRewardAd = new TapRewardVideoAd(request);
// RewardVideoAdLoadListener 为实现了 IRewardVideoAdLoadListener 的类
_tapRewardAd.SetLoadListener(new RewardVideoAdLoadListener(this));
_tapRewardAd.Load();
// 激励视频广告加载回调接口说明
public interface IRewardVideoAdLoadListener : ICommonLoadListener
{
    // 当激励视频被 Cache 完毕
    void OnRewardVideoAdCached(TapRewardVideoAd ad);

    // 当激励视频被 Load 完毕
    void OnRewardVideoAdLoad(TapRewardVideoAd ad);
}
// 通用广告加载回调接口说明
public interface ICommonLoadListener
{
    // 加载出错回调
    void OnError(int code, string message);
}

播放​

using TapTap.TapAd
if (TapAdSdk.IsInited == false)
{
    Debug.Log("TapAd 需要先初始化!");
    return;
}
if (_tapRewardAd != null)
{
    // RewardVideoInteractionListener 为实现了 IRewardVideoInteractionListener 的类
    _tapRewardAd.SetInteractionListener(new RewardVideoInteractionListener(this));
    _tapRewardAd.Show();
}
else
{
    Debug.LogErrorFormat($"[Unity::AD] 未加载好视频,无法播放!");
}
// 激励视频广告播放回调接口说明
public interface IRewardVideoInteractionListener : ICommonInteractionListener
{
    // 当广告出现
    void OnAdShow(TapRewardVideoAd ad);
    
    // 当广告关闭
    void OnAdClose(TapRewardVideoAd ad);

    // 当视频完成
    void OnVideoComplete(TapRewardVideoAd ad);

    // 视频出错
    void OnVideoError(TapRewardVideoAd ad);

    // 视频播放完毕，奖励确认可以发放
    void OnRewardVerify(TapRewardVideoAd ad, bool rewardVerify, int rewardAmount, string rewardName, int code, string msg);

    // 当跳过视频
    void OnSkippedVideo(TapRewardVideoAd ad);

    // 点击事件
    void OnAdClick(TapRewardVideoAd ad);
}
// 通用广告播放回调接口说明
public interface ICommonInteractionListener
{
    
}

模版渲染 Banner：开发者不用自行对广告样式进行编辑和渲染，可直接调用相关接口进行广告展示。

提示

不支持开发者在 view 添加按钮及对广告拦截处理。

获取广告​

using TapTap.TapAd

TapBannerAd _tapBannerAd = null;
if (TapAdSdk.IsInited == false)
{
    Debug.Log("TapAd 需要先初始化!");
    return;
}
if (_tapBannerAd != null)
{
    _tapBannerAd.Dispose();
    _tapBannerAd = null;
}
int adId = YOUR_AD_ID;
// create AdRequest
var request = new TapAdRequest.Builder()
    .SpaceId(adId)
    .Build();
_tapBannerAd = new TapBannerAd(request);
// BannerAdLoadListener 为实现了 IBannerAdLoadListener 的类
_tapBannerAd.SetLoadListener(new BannerAdLoadListener(this));
_tapBannerAd.Load();
// banner 广告加载回调接口说明
public interface IBannerAdLoadListener : ICommonLoadListener
{
    // 当 Banner 加载完毕
    void OnBannerAdLoad(TapBannerAd ad);
}
// 通用广告加载回调接口说明
public interface ICommonLoadListener
{
    // 加载出错回调
    void OnError(int code, string message);
}

播放​

using TapTap.TapAd
if (TapAdSdk.IsInited == false)
{
    Debug.Log("TapAd 需要先初始化!");
    return;
}
// BannerInteractionListener 为实现了 IBannerAdInteractionListener 的类
if (_tapBannerAd != null)
{
    _tapBannerAd.SetInteractionListener(new BannerInteractionListener(this));
    _tapBannerAd.Show();
}
else
{
    Debug.LogErrorFormat($"[Unity::AD] 未加载好视频,无法播放!");
}
// banner 广告播放回调接口说明
public interface IBannerAdInteractionListener : ICommonInteractionListener
{
    // 当广告曝光
    void OnAdShow(TapBannerAd ad);

    // 当广告关闭
    void OnAdClose(TapBannerAd ad);

    // 当点击广告
    void OnAdClick(TapBannerAd ad);

    // 当点击下载
    void OnDownloadClick(TapBannerAd ad);
}
// 通用广告播放回调接口说明
public interface ICommonInteractionListener
{
    
}

自渲染信息流广告​

提示
  • TapADN SDK 从 3.16.3.28 版本开始自渲染信息流视频广告对外暴露视频控制接口。

为可自定义布局的信息流广告，包含大图和视频两种基本样式类型，应用下载、跳转到落地页和跳转到浏览器三种交互类型。

提示

支持的广告尺寸：

  • 大图(宽高比：1.78 的图片)
  • 视频(宽高比：1.78 的视频)

获取广告​

// 暂不支持

广告行为监听​

信息

AdInteractionListener 涉及到广告计费，必须正确调用，convertView 必须使用 ViewGroup。

在加载到信息流广告后，接入方需要注册在信息流广告中可以点击的 View，即 TapFeedAd.registerViewForInteraction() 方法，以实现广告的功能交互及计。包含图文点击区域的注册，附加创意按钮点击区域的注册，隐私协议区域的注册，应用权限的注册。点击附加创意区域会进行应用下载操作。

注意： 如果需要点击图文区域也能进行下载，请将图文区域的 view 传入 creativeViews。示例代码如下：

// 暂不支持

广告下载事件监听​

// 暂不支持

Feed 流广告启动/暂停​

信息

如果 Feed 流是在 Activity 中使用，需要在 Activity 的 onResume 和 onPause 调用相关方法；

如果 Feed 流是在Fragment中使用，除了要考虑 onResume 和 onPause 的系统回调，还要注意 Fragment 的 setUserVisibleHint 回调。

// 暂不支持

Feed 流广告销毁​

信息

如果是在 Activity 中创建，请在 Activity 中调用销毁方法

如果是在 Fragment 中创建，请在 Fragment 中调用销毁方法

// 暂不支持

模板染信息流广告​

支持图文和视频样式，开发者不用自行对广告样式进行编辑和渲染，可直接调用相关接口获取广告view去进行展示, 开发者可以随时对 TapADN 平台上勾选的模板进行样式上的调整。降低了接入成本的前提下，不会影响cpm的水平，仍然可以保持高的竞争力。

信息

支持的广告样式：开发者在 TapADN 平台上可以进行多模板的勾选。模板渲染信息流广告支持开发者调整、编辑。注意：不允许开发者在view添加按钮及对广告拦截处理。

获取广告​

// 暂不支持

广告行为监听​

在加载到模板渲染信息流广告后，接入方需要调用 TapFeedAd.render() 接口进行模版广告的绘制 同时注册广告交互接口 TapFeedAd.setExpressRenderListener() 方法，以实现广告渲染以及其它广告行为的监听。

// 暂不支持

插屏广告​

插屏广告：支持「全屏视频广告」、「全屏图文广告」和「半屏图文广告」等形式，具体广告展示形式在后台配置。

提示

插屏广告分横竖屏形式，强烈建议在后台配置后正确使用横屏或竖屏广告，若用错配置的 orientation，可能会出现 UI 兼容异常问题。

获取广告​

if (TapAdSdk.IsInited == false){
    ShowText("TapAd 没有初始化!将自动初始化");
    Init();
    while (TapAdSdk.IsInited == false){
        await Task.Yield();
    }
    ShowText("TapAd 初始化完毕");
}
if (_tapInterstitialAd != null){
    _tapInterstitialAd.Dispose();
    _tapInterstitialAd = null;
}

int adId = isHorizontal ? LANDSCAPE_INTERSTITIAL_ID : PORTRAIT_INTERSTITIAL_ID;
// create AdRequest
var request = new TapAdRequest.Builder()
            .SpaceId(adId)
            .Build();
_tapInterstitialAd = new TapInterstitialAd(request);
_tapInterstitialAd.SetLoadListener(new InterstitialAdLoadListener(this));
_tapInterstitialAd.Load();

播放​

if (TapAdSdk.IsInited == false)
{
    ShowText("TapAd 需要先初始化!");
    return;
}
if (_tapInterstitialAd != null)
{
    _tapInterstitialAd.SetInteractionListener(new InterstitialAdInteractionListener(this));
    _tapInterstitialAd.Show();
}
else
{
    Debug.LogErrorFormat($"[Unity::AD] 未加载好视频,无法播放!");
}

Android 代码混淆​

为了保证 SDK 在代码混淆后能正常运作，需要将如下防混淆代码添加到混淆文件中：

提示

Android 原生项目混淆文件位于 app/proguard-rules.pro，Unity 项目需要先通过 Project Settings -> Player -> Publishing Settings -> 勾选 Custom Proguard File, 然后混淆文件位于项目该路径下 Assets/Plugins/Android/proguard-user.txt

-dontwarn com.tapadn.**
-keep class com.tapadn.** { *;}
-dontshrink

激励视频奖励发放说明​

奖励发放条件​

一般视频总时长为 10~60s，30s 以上的视频播放到 30s 时会显示“跳过”按钮。低于30s的激励视频观看达到 90% 即会回调奖励验证接口，高于 30s 激励视频观看到第 27s 的时候即会回调奖励验证接口。

奖励发放主要流程​

  • 客户端回调的优势：对接简单、高效，通过接口回调结果在客户端完成奖励是否发放即可。
  • 服务端回调的优势：开发者可在服务端进行二次校验，保证广告有效性后做出奖励发放，反作弊能力强。

奖励验证服务端回调 (S2S 验证)​

提示

S2S 验证需要开发者提供奖励发放的回调 URL，Security Key 由 TapADN 服务端生成并提供给开发者，现阶段通过 KA 单点对接提供

  • 服务器回调模式不是必须的，只是增加了一次第三方服务器的验证判断。具体的奖励发放由客户端完成。
  • 服务端回调逻辑：TapADN 根据“奖励发放条件“，先通过 “TapADN 服务端”访问“开发者媒体服务端”向开发者确认是否进行奖励发放，再依据“开发者服务端”返回的 true/false，在客户端给出是/否发放奖励的回调。
  • TapADN 服务端只是透传验证请求，不会在中间过程添加校验逻辑。为了保障开发者利益和用户体验，开发者可以在验证环节增加自己的校验逻辑。

SDK 奖励发放回调接口​

接口说明​
//视频播放完成后，奖励验证回调，rewardVerify：是否有效，code：错误码，msg：错误信息
void onRewardVerify(boolean rewardVerify, int rewardAmount, String rewardName,int code,String msg)
透传参数​

SDK 传给 TapADN 服务端

字段名称字段定义字段类型备注
user_id用户idstring调用SDK透传，应用对用户的唯一标识
extra其他信息string调用SDK传入并透传，如无需要则为空

奖励验证方式​

  1. 同步验证
    1. 满足“奖励发放条件”
    2. 调用“奖励验证回调接口”，并等待返回
    3. 调用onRewardVerify
      1. rewardVerify=回调接口返回的isValid
      2. code=回调接口异常时的错误码
      3. msg=回调接口异常时的错误信息
    4. 开发者可根据rewardVerify决定是否发放奖励
  2. 异步验证
    1. 满足“奖励发放条件”
    2. 调用“奖励验证回调接口”，不等待返回
    3. 调用onRewardVerify
      1. rewardVerify=true（满足“奖励发放条件”）
      2. trans_id
    4. 开发者可通过trans_id查询服务端结果，决定是否发放奖励

奖励验证回调接口​

接口请求方式​
  • 接口请求方式: GET
  • 服务端会以 GET 方式请求第三方服务的回调链接，并拼接以下参数回传：
pid=%s&user_id=%s&trans_id=%s&extra=%s&sign=%s
请求参数定义​
字段名称字段定义字段类型备注
pid广告位 IDstring
user_id用户 IDstring调用 SDK 透传，应用对用户的唯一标识
trans_id交易 IDstring完成观看的唯一交易 ID，唯一标识该次激励广告
extra其他信息string调用 SDK 传入并透传，如无需要则为空
sign签名string签名
签名生成方式​
  • 获得 SecurityKey，在申请配置激励广告位页面，设置服务端验证回调接口时获取
  • 将 trans_id 和 SecurityKey 用 ':' 符号连接
  • 使用 sha256 生成签名，用小写 16 进制
sign = fmt.Sprintf("%x", sha256.Sum256(trans_id:SecurityKey))
返回值约定​
  • 返回值格式: json
  • 返回示例:
{"isValid":true}
返回值定义​
字段名称字段定义字段类型备注
isValid校验结果bool判定结果，是否发放奖励

SDK 常见错误码汇总​

错误码错误信息原因
3001初始化错误SDK 未初始化,或者初始化异常
3002网络异常错误
3003插屏广告应用横竖方向参数与广告位支持方向不匹配插屏广告设置的横竖屏与设置的方向不一致
9999未获取到广告素材:未知错误
9000内部错误错误信息和内部错误码一般会上报
10003Request MediaInfo Miss
10004Request AppInfo Miss
10005Request AdnSdkInfo Miss
10007Request AdSpace Miss
10008Request AdSpace Not Match
10009Request Invalid DeviceId