Bidding Android iOS JS Media API 常见问题

激励广告

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

简介

激励视频广告是指将短视频融入到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

方法名 方法介绍
public RewardVideoAD(final Context context, final String posID, final RewardVideoADListener rewardVideoADListener, final boolean volumeOn) 激励视频广告构造函数,可指定播放时是否有声音;context 是指上下文环境,推荐传入开发者的 Activity,posID 是广告位 ID,rewardVideoADListener 指定广告状态回调接口,volumeOn为true表示有声播放,false表示静音播放。
public RewardVideoAD(final Context context, final String posID, final RewardVideoADListener rewardVideoADListener) 激励视频广告构造函数,有声播放;参数含义同上
loadAD() 加载激励视频广告,加载成功则调用回调RewardVideoADListener.onADLoad(),加载失败则会调用RewardVideoADListener.onError(AdError error)
showAD() 展示激励视频广告,展示成功则调用回调RewardVideoADListener.onADShow(),展示失败则会调用RewardVideoADListener.onError(AdError error)
getECPMLevel() 获取本条广告实时的eCMP价格层级标签,每个层级标签对应线下预定的eCPM价格范围,成功返回一个包含数字的字符串,比如“1”,无权限调用该接口或后台异常会返回空字符串
getECPM() 获取本条广告实时的eCPM价格,单位是分
hasShown() 判断拉取的广告是否已经展示过,一次广告请求只能展示一次。RewardVideoADListener.onADShow()回调成功调用后返回true,其他情况下返回false
isValid() 广告是否有效,无效广告将无法展示
getVideoDuration() 获取视频素材时长,单位毫秒
setServerSideVerificationOptions(ServerSideVerificationOptions options) 设置服务端校验需要透传的参数,服务端校验功能介绍请参照 ServerSideVerificationOptions API 介绍
getExtraInfo() (4.410.1280新增)获取本条广告一些额外信息

RewardVideoADListener

方法名 方法介绍
onADLoad() 广告加载成功,可在此回调后进行广告展示,展示前请使用isValid()判断广告是否有效,若无效则广告将无法展示
onVideoCached() 视频素材缓存成功,可在此回调后进行广告展示
onADShow() 激励视频广告页面展示,此后RewardVideoAD.hasShown()返回true
onADExpose() 激励视频广告曝光
onReward(Map map) 激励视频广告激励发放,若选择了服务端验证,可以通过 ServerSideVerificationOptions#TRANS_ID 键从 map 中获取此次交易的 id;若未选择服务端验证,则不需关注 map 参数。
onADClick() 激励视频广告被点击
onVideoComplete() 广告视频素材播放完毕
onADClose() 激励视频广告被关闭
onError(AdError error) 广告加载或展示过程中出错,AdError中包了含错误码和错误描述,具体错误码内容可参考错误码部分

ServerSideVerificationOptions

方法名 方法介绍
getCustomData() 获取设置的自定义数据
getUserId() 获取设置的用户 ID
Builder.setCustomData(String customData) 设置自定义数据
Builder.setUserId(String userId) 设置的用户 ID
Builder.build() 生成 ServerSideVerificationOptions 实例

服务端验证说明

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

服务端回调说明

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

pid=%s&appid=%s&transid=%s&userid=%s&extrainfo=%s&sig=%s
字段定义 字段名称 字段类型 备注
pid 广告位ID string 签名
appid APP ID string
transid 交易id string 完成观看的唯一交易ID
userid 用户id string 调用SDK透传,应用对用户的唯一标识
extrainfo 其他信息 string 调用SDK传入并透传,如无需要则为空
sig 签名 string 签名

具体示例:

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();
}

 文档反馈

腾讯公司 版权所有