激励广告

激励广告接入方式参考下方内容。

简介

激励视频广告是指将短视频融入到app场景当中，成为app“任务”之一，用户观看短视频广告后可以得到一些应用内奖励

权限等级：开放

适用场景：常见于游戏内的广告样式，多出现在游戏的复活、登录等位置，或者网服类app的一些增值服务场景。建议开发者在分析媒体属性和功能的基础上，判断是否嵌入。

分类：激励视频广告样式有横版竖版之分，您可以根据需要创建对应的广告位：

竖版	横版

接入注意事项：

1. AndroidManifest 文件中需要新增配置

        <activity
            android:name="com.qq.e.ads.PortraitADActivity"
            android:screenOrientation="portrait"
            android:configChanges="keyboard|keyboardHidden|orientation|screenSize" />
        <activity
            android:name="com.qq.e.ads.LandscapeADActivity"
            android:screenOrientation="landscape"
            android:configChanges="keyboard|keyboardHidden|orientation|screenSize" />
   

2. SDK给开发者的回调（RewardVideoADListener）全部执行在主线程中（异步回调）。
3. 后台会考虑根据广告请求时App横竖屏状态返回相关视频素材，而激励视频广告页面的页面横竖屏设置与展示广告时App当前页面的横竖屏设置保持一致，所以开发者需要尽量保证激励视频广告请求和广告展示两个时刻App的横竖屏状态相同，以让用户获得较好的广告体验。
4. 激励视频广告一次成功拉取的广告数据只允许展示一次。
5. 激励视频广告有过期时间，您可以选择预加载激励视频（提前调用RewardVideoAD的loadAD方法可以实现广告数据和视频素材的预加载），但是您进行广告展示时务必判断下广告数据是否已经过期，判断方法请参考 GDTUnionDemo 工程
6. SDK不会持有广告实例（RewardVideoAD）和回调实例（RewardVideoADListener），所以需要开发者保证广告结束之前广告实例不会被回收掉，以避免回调丢失的情况

主要 API

RewardVideoAD

• com.qq.e.ads.rewardvideo.RewardVideoAD:
  激励视频广告入口，用于初始化广告，加载广告数据并展示广告。

RewardVideoADListener

• com.qq.e.ads.rewardvideo.RewardVideoADListener：
  激励视频广告加载、展示整个广告流程的回调,SDK保证所有回调均在主线程中被调用（异步回调）。

ServerSideVerificationOptions

• com.qq.e.ads.rewardvideo.ServerSideVerificationOptions：
  服务端验证配置项，用于流量设置需要透传的参数

服务端验证说明

当选择需要服务端验证时，开发者需要按照以上接口进行开发，并在开发者平台上填写回调URL。服务端回调是指在用户看完视频达到奖励条件时，优量汇服务端会向开发者服务端发送一个验证请求，同时客户端会给出 onReward 回调，开发者根据回调进行奖励发放，因为奖励回调和服务端验证请求是同时发送的，开发者后台收到验证请求可能会有延迟或网络原因上的失败，开发者需要平衡用户体验与奖励验证。

服务端回调说明

优量汇服务器会以GET方式请求您在开发者平台上注册的服务器回调链接，并拼接以下参数进行回传：

pid=%s&appid=%s&transid=%s&userid=%s&extrainfo=%s&sig=%s

具体示例：

https://sdk.e.qq.com/s2s?placementId=%s&appid=%s&transid=%s&userid=%s&extrainfo=%s&Fsig=%s

补充：
优量汇后台向上述URL发起请求后，您会在服务端收到某个transid的请求，如果签名验证正确，那么此transid对应的曝光为有效曝光
如果拼接的回调URL无法正常请求您的服务端，优量汇后台会进行两次重试，每次重试间隔200ms

签名生成方式：

sig = sha256(transid:secret)

其中transid为交易id，secret为您在优量汇媒体平台输入服务端URL时获取到的密钥。

接入代码示例

// 仅展示部分代码，完整代码请参考 Demo 工程
// 1.加载广告，先设置加载上下文环境和条件
// 如果想静音播放，请使用5个参数的构造函数，且volumeOn传false即可
rewardVideoAD = new RewardVideoAD(this, getPosID(), this); // 有声播放
rewardVideoAD.loadAD();

// 2.设置监听器，监听广告状态
/**
 * 广告加载成功，可在此回调后进行广告展示
 **/
@Override
public void onADLoad() {
  adLoaded = true;
  String msg = "load ad success ! ";
  Toast.makeText(this, msg, Toast.LENGTH_LONG).show();
}

/**
 * 视频素材缓存成功，可在此回调后进行广告展示
 */
@Override
public void onVideoCached() {
  videoCached = true;
  Log.i(TAG, "onVideoCached");
}

/**
 * 激励视频广告页面展示
 */
@Override
public void onADShow() {
  Log.i(TAG, "onADShow");
}

/**
 * 激励视频广告曝光
 */
@Override
public void onADExpose() {
  Log.i(TAG, "onADExpose");
}

/**
 * 激励视频触发激励（观看视频大于一定时长或者视频播放完毕）
 *
 * @param map 若选择了服务端验证，可以通过 ServerSideVerificationOptions#TRANS_ID 键从 map 中获取此次交易的 id；若未选择服务端验证，则不需关注 map 参数。
 */
@Override
public void onReward(Map<String, Object> map) {
    Log.i(TAG, "onReward " + map.get(ServerSideVerificationOptions.TRANS_ID));  // 获取服务端验证的唯一 ID
}

/**
 * 激励视频广告被点击
 */
@Override
public void onADClick() {
  Log.i(TAG, "onADClick");
}

/**
 * 激励视频播放完毕
 */
@Override
public void onVideoComplete() {
  Log.i(TAG, "onVideoComplete");
}

/**
 * 激励视频广告被关闭
 */
@Override
public void onADClose() {
  Log.i(TAG, "onADClose");
}

/**
 * 广告流程出错
 */
@Override
public void onError(AdError adError) {
  String msg = String.format(Locale.getDefault(), "onError, error code: %d, error msg: %s",
      adError.getErrorCode(), adError.getErrorMsg());
  Toast.makeText(this, msg, Toast.LENGTH_LONG).show();
}

// 3.展示广告
if (adLoaded) {//广告展示检查1：广告成功加载，此处也可以使用videoCached来实现视频预加载完成后再展示激励视频广告的逻辑
  if (!rewardVideoAD.hasShown()) {//广告展示检查2：当前广告数据还没有展示过
    //广告展示检查3：展示广告前判断广告数据未过期
    if (rewardVideoAD.isValid()) {
      rewardVideoAD.showAD();
    } else {
      Toast.makeText(this, "激励视频广告已过期，请再次请求广告后进行广告展示！", Toast.LENGTH_LONG).show();
    }
  } else {
    Toast.makeText(this, "此条广告已经展示过，请再次请求广告后进行广告展示！", Toast.LENGTH_LONG).show();
  }
} else {
  Toast.makeText(this, "成功加载广告后再进行广告展示！", Toast.LENGTH_LONG).show();
}