Android iOS Unity JS API Media API 常见问题

开屏广告

简介

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

权限等级:开放

适用场景:App启动时,常会使用开屏广告

分类:开屏广告分为半屏和全屏,具体种类可以在开发者平台进行选择:

半屏 全屏

接入代码示例

(详细内容请参考压缩包中的代码示例,示例代码已过期,请参考压缩包的代码)
public class SplashActivity extends Activity implements SplashADListener {

  private SplashAD splashAD;
  private ViewGroup container;
  private TextView skipView;
  private ImageView splashHolder;
  private static final String SKIP_TEXT = "点击跳过 %d";

  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);
    skipView = (TextView) findViewById(R.id.skip_view);
    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, skipView, 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, skipView, 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, skipView, 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 skipContainer   自定义的跳过按钮:传入该view给SDK后,SDK会自动给它绑定点击跳过事件。SkipView的样式可以由开发者自由定制,其尺寸限制请参考activity_splash.xml或者接入文档中的说明。
   * @param posId           广告位ID
   * @param adListener      广告状态监听器
   * @param fetchDelay      拉取广告的超时时长:取值范围[3000, 5000],设为0表示使用广点通SDK默认的超时时长。
   */
  private void fetchSplashAD(Activity activity, ViewGroup adContainer, View skipContainer, String posId, SplashADListener adListener, int fetchDelay) {
    fetchSplashADTime = System.currentTimeMillis();
    // skipContainer 此时必须是 VISIBLE 状态,否则将不能正常曝光计费
    splashAD = new SplashAD(activity, skipContainer, posId, adListener, fetchDelay);
    splashAD.fetchAndShowIn(adContainer);
  }

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

  @Override
  public void onADClicked() {
    Log.i("AD_DEMO", "SplashADClicked clickUrl: "
        + (splashAD.getExt() != null ? splashAD.getExt().get("clickUrl") : ""));
  }

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

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

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

}

主要 API

加了删除线的方法即将废弃。

SplashAD

方法名 方法介绍
SplashAD(Activity activity, String posId, SplashADListener adListener) 构造方法,广告相关状态会通过 adListener 通知开发者。参数说明:activity(展示广告的 activity)、posId(广告位 ID)、adListener(广告状态监听器)。
SplashAD(Activity activity, String posId, SplashADListener adListener, int fetchDelay) 构造方法,这个方法可以通过传入 fetchDelay 参数,设置开屏广告从请求到展示所花的最大时长(并不是指广告曝光时长),取值范围为[3000, 5000]ms。如果需要使用默认值,可以调用上一个构造方法,或者给 fetchDelay 设为0。
SplashAD(Activity activity, View skipContainer, String posId, SplashADListener adListener, int fetchDelay) 构造方法,这个方法可以通过传入传入 skipContainer 参数,支持开发者自定义的跳过按钮。SDK 要求skipContainer一定在传入后要处于 VISIBLE 状态(一定要在构造方法之前将 skipContainer 处于 VISIBLE 状态,不要在onADPresent等广告回调中再修改为可见),且其宽高都不得小于3x3dp。如果需要使用 SDK 默认的跳过按钮,可以选择上面两个构造方法。
SplashAD(Activity activity, String appId, String posId,SplashADListener adListener) 构造方法,广告相关状态会通过 adListener 通知开发者。参数说明:activity(展示广告的 activity)、appId(媒体 ID)、posId(广告位 ID)、adListener(广告状态监听器)。
SplashAD(Activity activity, String appId, String posId,SplashADListener adListener, int fetchDelay) 构造方法,这个方法可以通过传入 fetchDelay 参数,设置开屏广告从请求到展示所花的最大时长(并不是指广告曝光时长),取值范围为[3000, 5000]ms。如果需要使用默认值,可以调用上一个构造方法,或者给 fetchDelay 设为0。
SplashAD(Activity activity, View skipContainer, String appId, String posId,SplashADListener adListener, int fetchDelay) 构造方法,这个方法可以通过传入传入 skipContainer 参数,支持开发者自定义的跳过按钮。SDK 要求skipContainer一定在传入后要处于 VISIBLE 状态,且其宽高都不得小于3x3dp。如果需要使用 SDK 默认的跳过按钮,可以选择上面两个构造方法。
preLoad() 预加载广告(4.330.1200版本后支持预加载效果广告,需要申请才会有效,之前版本只支持预加载合约广告),调用后开屏广告会尝试进行广告数据和图片/视频素材的预加载(若视频广告的视频素材未能提前预加载,在得到播放机会时将退化为图片广告进行播放),预加载的广告在得到展示机会时可以跳过广告素材下载的步骤而直接展示,该接口有频次控制,默认最小间隔2小时及以上调用才会生效,建议一天执行一次。
fetchAndShowIn(ViewGroup container) 拉取并展示广告,调用后开屏广告会尝试加载广告,并将广告内容填充到 container 参数指向的 ViewGroup,该 ViewGroup 原有的内容会被清空。
fetchAdOnly() 拉取广告,是fetchAndShowIn接口的一部分,配合showAd实现和fetchAndShowIn相同的功能。调用后开屏广告会尝试拉取广告,并通过回调反馈结果
showAd(ViewGroup container) 配合fetchAdOnly使用,在通过fetchAdOnly成功拉取到广告后,通过该接口展示拉取到的广告,将广告内容填充到 container 参数指向的 ViewGroup,该 ViewGroup 原有的内容会被清空。
getECPMLevel() 获取本条广告实时的eCMP价格层级标签,每个层级标签对应线下预定的eCPM价格范围,成功返回一个包含数字的字符串,比如“1”,无权限调用该接口或后台异常会返回空字符串

SplashADListener

方法名 方法介绍
onNoAD(AdError error) 广告加载失败,error 对象包含了错误码和错误信息,错误码的详细内容可以参考文档第5章
onADDismissed() 广告关闭时调用,可能是用户关闭或者展示时间到。此时一般需要跳过开屏的 Activity,进入应用内容页面
onADPresent() 广告成功展示时调用,成功展示不等于有效展示(比如广告容器高度不够)
onADClicked() 广告被点击时调用,不代表满足计费条件(如点击时网络异常)
onADExposure() 广告曝光时调用
onADTick(long millisUntilFinished) 倒计时回调,返回广告还将被展示的剩余时间,单位是 ms
onADLoaded(long expireTimestamp) 广告加载成功的回调,在fetchAdOnly的情况下,表示广告拉取成功可以显示了。广告需要在SystemClock.elapsedRealtime <expireTimestamp前展示,否则在showAd时会返回广告超时错误。

接入注意事项


Copyright © 1998 - 2020 Tencent Inc. All Rights Reserved.
腾讯公司 版权所有 | 加入优量汇