开屏广告

开屏包含 开屏广告 与 开屏V+广告，下面分别介绍两种形态的接入文档。

开屏广告

开屏广告简介

开屏广告以App启动作为曝光时机，提供5s的可感知广告展示。用户可以点击广告跳转到目标页面；或者点击右上角的“跳过”按钮，跳转到app内容首页。

权限等级：开放

适用场景：开屏广告会在您的应用开启时加载，拥有固定展示时间（一般为5秒），展示完毕后自动关闭并进入您的应用主界面。

分类：开屏广告分为全屏和半屏广告，开屏全屏广告有更沉浸的广告播放体验，变现效果更佳：

全屏	半屏

奖励式开屏简介

奖励式开屏，是优量汇最新推出的广告形态。

奖励式开屏在原有交互基础上，开屏外层额外提示可「领惊喜奖励」，用户触发交互行为后，在落地页浏览满5秒，即可获得对应奖励。

（1）用户如感兴趣，在落地页浏览满5秒：开发者需针对满足浏览的用户，派发额外的奖励，如系统内的金币，生命值等。

（2）用户如不感兴趣，在落地页浏览未满5秒：可随时点击关闭按钮，退出广告。

接入效果：奖励式开屏，可增加开屏点击吸引力，提升该广告位eCPM和整体收益。

权限等级：请联系优量汇运营同学申请接入

备注说明：选中该样式时，您务必针对满足浏览的用户，派发额外奖励，如系统内的金币，生命值等。

支持版本：Android SDK 4.470.1340 及以上

其他功能：当前样式同激励视频一样，支持奖励回调判断。

全屏	落地页

主要 API

SplashAD

• com.qq.e.ads.splash.SplashAD:

SplashADListener

• com.qq.e.ads.splash.SplashADListener:
  开屏广告回调接口

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时获取到的密钥。

接入注意事项

• 1.开屏全屏广告的显示区域其高度要与设备高度一致，开发者可通过 setDeveloperLogo 接口提供媒体logo，用以随开屏广告展示。
• 2.开屏半屏广告的显示区域其高度要大于设备高度的75%（建议值大于80%），最小高度要大于400dp，开屏广告默认只在竖屏展示，横屏一般不满足尺寸要求。
• 3.开发者如果需要展示半开屏广告，即在开屏中保留部分区域显示其他信息，如 LOGO，可以参考 demo 设置其他单独的容器来展示该信息，但展示广告的容器请一定要满足注意事项中描述的条件，否则影响曝光。
• 4.开屏广告接入api变化，原有方式将SplashAD的构造和广告的拉取展示耦合起来，新版SDK将广告的拉取和展示独立出来。因此需要开发者适配这一情况，调用fetchAndShowIn进行广告的拉取和展示。
• 5.开屏广告传入的展示广告的container中会显示跳过、倒计时等元素，container不要占用刘海等会被挡住的区域，可以参考demo里的示例。

接入代码示例

public class SplashActivity extends Activity implements SplashADListener {

  private SplashAD splashAD;
  private ViewGroup container;
  private ImageView splashHolder;

  public boolean canJump = false;
  private boolean needStartDemoList = true;

  /**
    * 为防止无广告时造成视觉上类似于"闪退"的情况，设定无广告时页面跳转根据需要延迟一定时间，demo
    * 给出的延时逻辑是从拉取广告开始算开屏最少持续多久，仅供参考，开发者可自定义延时逻辑，如果开发者采用demo
    * 中给出的延时逻辑，也建议开发者考虑自定义minSplashTimeWhenNoAD的值（单位ms）
    **/
  private int minSplashTimeWhenNoAD = 2000;
  /**
    * 记录拉取广告的时间
    */
  private long fetchSplashADTime = 0;
  private Handler handler = new Handler(Looper.getMainLooper());

  @Override
  protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_splash);
    container = (ViewGroup) this.findViewById(R.id.splash_container);
    splashHolder = (ImageView) findViewById(R.id.splash_holder);
    boolean needLogo = getIntent().getBooleanExtra("need_logo", true);
    needStartDemoList = getIntent().getBooleanExtra("need_start_demo_list", true);
    if (!needLogo) {
      findViewById(R.id.app_logo).setVisibility(View.GONE);
    }
    // 如果targetSDKVersion >= 23，就要申请好权限。如果您的App没有适配到Android6.0（即targetSDKVersion < 23），那么只需要在这里直接调用fetchSplashAD接口。
    if (Build.VERSION.SDK_INT >= 23) {
      checkAndRequestPermission();
    } else {
      // 如果是Android6.0以下的机器，默认在安装时获得了所有权限，可以直接调用SDK
      fetchSplashAD(this, container, getPosId(), this, 0);
    }
  }

  private String getPosId() {
    String posId = getIntent().getStringExtra("pos_id");
    return TextUtils.isEmpty(posId) ? Constants.SplashPosID : posId;
  }

  /**
    *
    * ----------非常重要----------
    *
    * Android6.0以上的权限适配简单示例：
    *
    * 如果targetSDKVersion >= 23，那么必须要申请到所需要的权限，再调用优量汇SDK，否则优量汇SDK不会工作。
    *
    * Demo代码里是一个基本的权限申请示例，请开发者根据自己的场景合理地编写这部分代码来实现权限申请。
    * 注意：下面的`checkSelfPermission`和`requestPermissions`方法都是在Android6.0的SDK中增加的API，如果您的App还没有适配到Android6.0以上，则不需要调用这些方法，直接调用优量汇SDK即可。
    */
  @TargetApi(Build.VERSION_CODES.M)
  private void checkAndRequestPermission() {
    List<String> lackedPermission = new ArrayList<String>();
    if (!(checkSelfPermission(Manifest.permission.READ_PHONE_STATE) == PackageManager.PERMISSION_GRANTED)) {
      lackedPermission.add(Manifest.permission.READ_PHONE_STATE);
    }

    if (!(checkSelfPermission(Manifest.permission.WRITE_EXTERNAL_STORAGE) == PackageManager.PERMISSION_GRANTED)) {
      lackedPermission.add(Manifest.permission.WRITE_EXTERNAL_STORAGE);
    }

    if (!(checkSelfPermission(Manifest.permission.ACCESS_FINE_LOCATION) == PackageManager.PERMISSION_GRANTED)) {
      lackedPermission.add(Manifest.permission.ACCESS_FINE_LOCATION);
    }

    // 权限都已经有了，那么直接调用SDK
    if (lackedPermission.size() == 0) {
      fetchSplashAD(this, container, getPosId(), this, 0);
    } else {
      // 请求所缺少的权限，在onRequestPermissionsResult中再看是否获得权限，如果获得权限就可以调用SDK，否则不要调用SDK。
      String[] requestPermissions = new String[lackedPermission.size()];
      lackedPermission.toArray(requestPermissions);
      requestPermissions(requestPermissions, 1024);
    }
  }

  private boolean hasAllPermissionsGranted(int[] grantResults) {
    for (int grantResult : grantResults) {
      if (grantResult == PackageManager.PERMISSION_DENIED) {
        return false;
      }
    }
    return true;
  }

  @Override
  public void onRequestPermissionsResult(int requestCode, String[] permissions, int[] grantResults) {
    super.onRequestPermissionsResult(requestCode, permissions, grantResults);
    if (requestCode == 1024 && hasAllPermissionsGranted(grantResults)) {
      fetchSplashAD(this, container, getPosId(), this, 0);
    } else {
      // 如果用户没有授权，那么应该说明意图，引导用户去设置里面授权。
      Toast.makeText(this, "应用缺少必要的权限！请点击\"权限\"，打开所需要的权限。", Toast.LENGTH_LONG).show();
      Intent intent = new Intent(Settings.ACTION_APPLICATION_DETAILS_SETTINGS);
      intent.setData(Uri.parse("package:" + getPackageName()));
      startActivity(intent);
      finish();
    }
  }

  /**
    * 拉取开屏广告，开屏广告的构造方法有3种，详细说明请参考开发者文档。
    *
    * @param activity        展示广告的activity
    * @param adContainer     展示广告的大容器
    * @param posId           广告位ID
    * @param adListener      广告状态监听器
    * @param fetchDelay      拉取广告的超时时长：取值范围[1500, 5000]，设为0表示使用优量汇SDK默认的超时时长。
    */
  private void fetchSplashAD(Activity activity, ViewGroup adContainer, String posId, SplashADListener adListener, int fetchDelay) {
    fetchSplashADTime = System.currentTimeMillis();
    // skipContainer 此时必须是 VISIBLE 状态，否则将不能正常曝光计费
    splashAD = new SplashAD(activity, posId, adListener, fetchDelay);
    splashAD.fetchAndShowIn(adContainer);
  }

  @Override
  public void onADPresent() {
    Log.i("AD_DEMO", "SplashADPresent");
  }

  @Override
  public void onADClicked() {
    Log.i("AD_DEMO", "SplashADClicked");
  }

  /**
    * 倒计时回调，返回广告还将被展示的剩余时间。
    * 通过这个接口，开发者可以自行决定是否显示倒计时提示，或者还剩几秒的时候显示倒计时
    *
    * @param millisUntilFinished 剩余毫秒数
    */
  @Override
  public void onADTick(long millisUntilFinished) {
    Log.i("AD_DEMO", "SplashADTick " + millisUntilFinished + "ms");
  }

  @Override
  public void onADExposure() {
    Log.i("AD_DEMO", "SplashADExposure");
  }

  @Override
  public void onADLoaded(long expireTimestamp) {
    Log.i("AD_DEMO", "SplashADLoaded");
  }

  @Override
  public void onADDismissed() {
    Log.i("AD_DEMO", "SplashADDismissed");
    next();
  }

  @Override
  public void onNoAD(AdError error) {
    Log.i(
        "AD_DEMO",
        String.format("LoadSplashADFail, eCode=%d, errorMsg=%s", error.getErrorCode(),
            error.getErrorMsg()));
    /**
      * 为防止无广告时造成视觉上类似于"闪退"的情况，设定无广告时页面跳转根据需要延迟一定时间，demo
      * 给出的延时逻辑是从拉取广告开始算开屏最少持续多久，仅供参考，开发者可自定义延时逻辑，如果开发者采用demo
      * 中给出的延时逻辑，也建议开发者考虑自定义minSplashTimeWhenNoAD的值
      **/
    long alreadyDelayMills = System.currentTimeMillis() - fetchSplashADTime;//从拉广告开始到onNoAD已经消耗了多少时间
    long shouldDelayMills = alreadyDelayMills > minSplashTimeWhenNoAD ? 0 : minSplashTimeWhenNoAD
        - alreadyDelayMills;//为防止加载广告失败后立刻跳离开屏可能造成的视觉上类似于"闪退"的情况，根据设置的minSplashTimeWhenNoAD
    // 计算出还需要延时多久
    handler.postDelayed(new Runnable() {
      @Override
      public void run() {
        if (needStartDemoList) {
          SplashActivity.this.startActivity(new Intent(SplashActivity.this, DemoListActivity.class));
        }
        SplashActivity.this.finish();
      }
    }, shouldDelayMills);
  }

  /**
    * 设置一个变量来控制当前开屏页面是否可以跳转，当开屏广告为普链类广告时，点击会打开一个广告落地页，此时开发者还不能打开自己的App主页。当从广告落地页返回以后，
    * 才可以跳转到开发者自己的App主页；当开屏广告是App类广告时只会下载App。
    */
  private void next() {
    if (canJump) {
      if (needStartDemoList) {
        this.startActivity(new Intent(this, DemoListActivity.class));
      }
      this.finish();
    } else {
      canJump = true;
    }
  }

  @Override
  protected void onPause() {
    super.onPause();
    canJump = false;
  }

  @Override
  protected void onResume() {
    super.onResume();
    if (canJump) {
      next();
    }
    canJump = true;
  }

  @Override
  protected void onDestroy() {
    super.onDestroy();
    handler.removeCallbacksAndMessages(null);
  }

  /** 开屏页一定要禁止用户对返回按钮的控制，否则将可能导致用户手动退出了App而广告无法正常曝光和计费 */
  @Override
  public boolean onKeyDown(int keyCode, KeyEvent event) {
    if (keyCode == KeyEvent.KEYCODE_BACK || keyCode == KeyEvent.KEYCODE_HOME) {
      return true;
    }
    return super.onKeyDown(keyCode, event);
  }

}

奖励式开屏接入示例

  // 奖励式开屏，请联系优量汇运营同学申请接入
  ServerSideVerificationOptions options = new ServerSideVerificationOptions.Builder()
      .setCustomData("APP's custom data") // 设置服务端验证的自定义信息
      .setUserId("APP's user id for server verify") // 设置服务端验证的用户信息
      .build();
  splashAD.setServerSideVerificationOptions(options);
  splashAD.setRewardListener(new ADRewardListener() {
    @Override
    public void onReward(Map<String, Object> map) {
      // TRANS_ID 获取服务端验证的唯一 ID
      Log.i("AD_DEMO", "onReward " + map.get(ServerSideVerificationOptions.TRANS_ID));
    }
  });

开屏V+广告

开屏V+广告简介

开屏V+广告是一个5s-30s的视频广告，在5s开屏呈现的过程中，用户点击右上角的“进入首页”或5s曝光结束后，视频均将收缩到APP内右下角的小视窗继续播放。

权限等级：需要申请

适用场景：开屏V+广告会在您的应用开启时加载，广告曝光过程中用户点击右上角的“进入首页”或5s曝光结束后将收缩到APP首页右下角的小视窗继续播放。

分类：开屏V+广告分为半屏和全屏，其中半屏开屏V+广告支持开发者自定义设置开屏底部的界面，用以展示应用Logo等。具体种类可以在开发者平台进行选择：

半屏	全屏	悬浮状态	落地页

视频示例

主要 API

代码中*zoomOut*命名即为开屏V+相关逻辑。

SplashAD

• com.qq.e.ads.splash.SplashAD:

和开屏广告使用同样的方法，开屏V+新增的方法如下

SplashADZoomOutListener

• com.qq.e.ads.splash.SplashADZoomOutListener:
  开屏V+广告回调接口，开屏V使用(4.310.1180)版本之后，该接口继承自SplashADListener(参见开屏广告)，同时支持开屏V+广告和非V+广告，只有开屏V+类型的广告会回调下面新增的方法。

开屏V+ demo辅助函数

demo的动画提供了开屏V+辅助函数供开发者参考，详细细节可以参见demo代码，悬浮窗的尺寸，应尽量使用推荐的尺寸，必须宽高比为 16:9。

• com.qq.e.union.demo.util.SplashZoomOutManager:

• com.qq.e.union.demo.util.SplashZoomOutLayout:
  开屏V+在悬浮时的示例布局，实现了拖动和点击传递的功能。

接入注意事项

• 同开屏广告

接入代码示例

(关键代码展示，详细请参考压缩包的代码)

public class SplashADActivity extends Activity implements View.OnClickListener,
    AdapterView.OnItemSelectedListener, SplashADZoomOutListener {
  private View splashView;
  private SplashAD splashAD;
  private ViewGroup zoomOutView;
  private boolean isZoomOuted;

  @Override
  public void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_splash_ad);
    findViewById(R.id.splashShowInView).setOnClickListener(this);
  }

  private String getPosID() {
    String posId = ((EditText) findViewById(R.id.posId)).getText().toString();
    return TextUtils.isEmpty(posId) ? PositionId.SPLASH_POS_ID : posId;
  }

  private boolean needLogo() {
    return ((CheckBox) findViewById(R.id.checkBox)).isChecked();
  }

  private boolean customSkipBtn(){
    return ((CheckBox)findViewById(R.id.checkCustomSkp)).isChecked();
  }

  @Override
  public void onClick(View v) {
    cleanZoomOut();
    switch (v.getId()) {
      case R.id.splashShowInView:
        showSplashInThisActivity();
        break;
    }
  }

  private void showSplashInThisActivity() {
    Log.d(TAG, "showSplashInThisActivity");
    DemoUtil.hideSoftInput(this);
    if (splashView == null) {
      ViewGroup contentView = findViewById(android.R.id.content);
      LayoutInflater inflater = getLayoutInflater();
      splashView = inflater.inflate(R.layout.activity_splash, null);
      splashView.setClickable(true);//显示出来的时候阻止点击事件传递到后面的按钮
      contentView.addView(splashView);
      Log.d(TAG, "contentView child count:" + contentView.getChildCount());
    } else if (splashView.getVisibility() == View.VISIBLE) {
      Toast.makeText(SplashADActivity.this.getApplicationContext(), "有开屏正在展示，忽略本次拉取",
          Toast.LENGTH_SHORT).show();
      Log.d(TAG, "有开屏正在展示，忽略本次拉取");
      return;
    } else {
      splashView.setVisibility(View.VISIBLE);
    }
    if (!needLogo()) {
      splashView.findViewById(R.id.app_logo).setVisibility(View.GONE);
    } else {
      splashView.findViewById(R.id.app_logo).setVisibility(View.VISIBLE);
    }
    TextView skipView = null;
    if (customSkipBtn()) {
      skipView = splashView.findViewById(R.id.skip_view);
      skipView.setVisibility(View.VISIBLE);
    } else {
      splashView.findViewById(R.id.skip_view).setVisibility(View.GONE);
    }
    ViewGroup container = splashView.findViewById(R.id.splash_container);
    container.removeAllViews();
    //因为SplashAD是和广告位绑定的，在广告位变化时需要重新创建
    splashAD = new SplashAD(this, skipView, getPosID(), this, 0);
    Log.d(TAG, "fetchAndShowIn");
    isZoomOuted = false;
    splashAD.fetchAndShowIn(container);
  }

  private void cleanZoomOut() {
    if (zoomOutView != null) {
      ViewUtils.removeFromParent(zoomOutView);
      zoomOutView = null;
    }
  }

  @Override
  public void onADDismissed() {
    splashView.setVisibility(View.GONE);
    if (isZoomOuted && zoomOutView != null) {
      ViewUtils.removeFromParent(zoomOutView);
    }
    Log.d(TAG, "onADDismissed");
  }

  @Override
  public void onNoAD(AdError error) {
    splashView.setVisibility(View.GONE);
    String str = String.format("LoadSplashADFail, eCode=%d, errorMsg=%s", error.getErrorCode(),
        error.getErrorMsg());
    Log.i("AD_DEMO", str);
    runOnUiThread(new Runnable() {
      @Override
      public void run() {
        Toast.makeText(SplashADActivity.this.getApplicationContext(), str, Toast.LENGTH_SHORT).show();
      }
    });
  }

  @Override
  public void onADPresent() {
    Log.d(TAG, "onADPresent");
  }

  @Override
  public void onADClicked() {
    Log.d(TAG, "onADClicked");
  }

  @Override
  public void onADTick(long millisUntilFinished) {
    Log.d(TAG, "onADTick");
    if (splashView != null) {
      TextView skipView = splashView.findViewById(R.id.skip_view);
      if (skipView != null && skipView.getVisibility() == View.VISIBLE)
        skipView.setText(String.format(SKIP_TEXT, Math.round(millisUntilFinished / 1000f)));
    }
  }

  @Override
  public void onADExposure() {
    Log.d(TAG, "onADExposure");
  }

  @Override
  public void onADLoaded(long expireTimestamp) {
    Log.d(TAG, "onADLoaded");
  }

  @Override
  public void onZoomOut() {
    Log.d(TAG, "onZoomOut");
    isZoomOuted = true;
    SplashZoomOutManager splashZoomOutManager = SplashZoomOutManager.getInstance();
    View splash = ((ViewGroup) splashView.findViewById(R.id.splash_container)).getChildAt(0);
    if (splash == null) {
      Log.e(TAG, "在开屏展示的过程中进行了新的拉取，导致广告View被清空了");
      return;
    }
    splash.setVisibility(View.VISIBLE);
    ViewGroup content = findViewById(android.R.id.content);
    zoomOutView = splashZoomOutManager.startZoomOut(splash, content, content,
        new SplashZoomOutManager.AnimationCallBack() {
      @Override
      public void animationStart(int animationTime) {
        Log.d(TAG, "animationStart:" + animationTime);
      }
      @Override
      public void animationEnd() {
        Log.d(TAG, "animationEnd");
        splashAD.zoomOutAnimationFinish();
      }
    });
    splashView.setVisibility(View.GONE);
  }

  @Override
  public void onZoomOutPlayFinish() {
    Log.d(TAG, "onPlayFinish");
  }

  @Override
  public boolean isSupportZoomOut() {
    return true;
  }
}

屏蔽摇一摇广告

开发者可以通过此接口，在广告请求维度关闭开屏广告摇一摇能力。

接口说明

import com.qq.e.comm.managers.setting.GlobalSetting;

void setExtraUserData(Map<String, String> extraUserData);

接入代码示例

Map<String, String> extraUserData = new HashMap<>();
extraUserData.put("shakable", "0"); // 屏蔽开屏摇一摇广告
GlobalSetting.setExtraUserData(extraUserData);