广告 AD Android SDK 接入文档

概述

本文档描述了 Android 开发者如何集成 AD SDK(后面简称为 AdSdk),通过集成 AdSdk 展示广告创造收益。 AdSdk 提供了以下几种广告形式:SplashAd(开屏广告)、RewardVideoAd(激励视频广告)、BannerAd(横幅广告)、NativeExpressAd(原生广告)、InterstitialAd(插屏广告)、DrawVideoAd(Draw 视频广告)、快手短视频等。

术语介绍

AppId:应用 id,18位 hex 字符串。【注意】调试时请使用测试 appId:ba0063bfbc1a5ad878;外发版本请替换成正式 appId,否则不会产生收益。

UnitId:广告位 id,广告类型缩写后紧跟从1开始的编号,如开屏广告位 s1,激励视频广告位 rv1。一般情况下使用默认的广告位 id 即可,需要分配额外的广告位时,请联系客户经理。

AdId:广告 id,全局唯一,相同素材的广告每次请求也不会重复。所有广告回调返回的参数都包含广告 id。

UserId:用户 id,接入方定义的用户唯一标识,传入时可以哈希脱敏,主要用于排查问题。

SDK 集成

方法一:自动集成 (推荐)

通过在 Android Studio 工程的 build.gradle 配置脚本中添加 maven 依赖,导入最新版本 AdSdk。

步骤一:添加 Maven 仓库地址

allprojects {
    repositories {
        maven {
            credentials {
                username 'iqLuKm'
                password 'pomH01oYcR'
            }
            url 'https://repo.rdc.aliyun.com/repository/117933-release-sPkE7F/'
        }
    }
}

【注意】加在 allprojects 中,不要加在 buildscript 中哦。

步骤二:添加依赖

dependencies {
    implementation 'com.mob.sdk:oaid-sdk:1.0.25' // 依赖 oaid
    implementation 'com.mob.sdk:adsdk:2.7.19'
}

方法二:手动集成

将 AdSdk 的 aar 包复制到 Application Module 的 libs 目录下(无此目录需手动创建), 并在工程的 build.gradle 中添加如下配置:

repositories {
    flatDir {
        dirs 'libs'
    }
}

depedencies {
    implementation(name: 'oaid-sdk', ext: 'aar') // 依赖 oaid
    implementation(name: 'adsdk-2.7.19', ext: 'aar')
}

全局配置

权限申请

请参考 SplashActivity 动态申请 READ_PHONE_STATE、ACCESS_FINE_LOCATION、WRITE_EXTERNAL_STORAGE 等权限。

【注意】AdSdk 不强制校验以上权限,无以上权限 AdSdk 也可正常工作;获取以上权限将帮助 AdSdk 优化投放广告精准度和用户的交互体验,提高eCPM。

代码混淆

AdSdk 自带代码混淆规则,不需要额外配置。

SDK 初始化

开发者需要在 Application 实例的 onCreate() 方法中调用以下代码来初始化 AdSdk。 多进程 App 在所有进程都需要初始化!

public class DemoApplication extends Application {

    @Override
    public void onCreate() {
        super.onCreate();

        AdSdk.getInstance().init(getApplicationContext(),
                new AdConfig.Builder()
                        .appId(APP_ID)
                        .userId(userId) // 未登录可不设置 userId,登录时再设置
                        .debug(BuildConfig.DEBUG)
                        .build(),
                null);
    }
}

初始化配置参数说明:

private String appId;           // 应用程序 id
private String userId;          // 用户 id
private boolean debug;          // 是否 debug 模式,是则输出日志

登录时请设置 userId:

AdSdk.getInstance().setUserId(userId);

退出登录请重置 userId:

AdSdk.getInstance().setUserId(null);

设置 OAID(不同 OAID 版本可能略有差异):

@Override
public void OnSupport(boolean isSupport, IdSupplier supplier) {
    String oaid = supplier.getOAID();
    AdSdk.getInstance().setOAID(getApplicationContext(), oaid);
}

开屏广告接入

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

开发者可在主线程调用 AdSdk 实例的方法:

public void loadSplashAd(
    Activity context,       // 活动上下文
    String unitId,          // 广告位 id
    ViewGroup container,    // 展现开屏广告的容器
    int loadTimeout,    // 加载开屏广告允许的最长时间(注:建议大于3000ms)
    SplashAdListener listener // 广告回调
) 

调用示例如下:

AdSdk.getInstance().loadSplashAd(SplashActivity.this, "s1", container, SPLASH_LOAD_TIMEOUT,
        new AdSdk.SplashAdListener() {
            @Override
            public void onAdLoad(String id) {
            }
                    
            @Override
            public void onAdShow(String id) {
            }

            @Override
            public void onAdClick(String id) {
            }

            @Override
            public void onAdDismiss(String id) {
                if (!mPaused) {
                    goToMainActivity();
                }
            }

            @Override
            public void onError(String id, int code, String message) {
                goToMainActivity();
            }
        });

SplashAdListener 接口说明:

public interface SplashAdListener {
    void onAdLoad(String id);   // 广告页面展示

    void onAdShow(String id);   // 广告页面展示

    void onAdClick(String id);  // 广告被点击

    void onAdDismiss(String id);    // 广告被关闭
    
    void onError(String id, int code, String message);  // 广告出错
}

【强烈建议】 App 切到后台超过三分钟返回时加载开屏,以提升开屏广告的曝光量,具体示例详见 Demo 中的 SplashActivity 和 setMinSplashInterval 方法。

激励视频广告接入

激励视频广告是指将短视频融入到 app 场景当中,用户观看完激励视频广告后可以得到一些应用内奖励。使用场景包括但不限于: 1、游戏等应用内观看视频广告获得游戏内金币等:用户必须观看完整视频才能获取奖励; 2、积分类应用接入。

开发者可在主线程调用 AdSdk 实例的方法:

public void loadRewardVideoAd(
    Activity context,       // 活动上下文
    String unitId,          // 广告位 id
    boolean showWhenCached, // 是否完全加载后才开始播放
    RewardVideoAdListener listener  // 广告回调
)

调用示例如下:

AdSdk.getInstance().loadRewardVideoAd(RewardVideoActivity.this, "rv1", false,
        new AdSdk.RewardVideoAdListener() {
            @Override
            public void onAdLoad(String id) {
            }

            @Override
            public void onVideoCached(String id) {
            }

            @Override
            public void onAdShow(String id) {
            }

            @Override
            public void onReward(String id) {
            }

            @Override
            public void onAdClick(String id) {
            }

            @Override
            public void onVideoComplete(String id) {
            }

            @Override
            public void onAdClose(String id) {
            }

            @Override
            public void onError(String id, int code, String message) {
            }
        });

RewardVideoAdListener 接口说明:

public interface RewardVideoAdListener {
    void onAdLoad(String id);    // 广告加载成功

    void onVideoCached(String id);   // 视频素材缓存成功

    void onAdShow(String id);    // 广告页面展示

    void onReward(String id);    // 广告奖励有效性回调,onReward 一定在 onAdClose 之前,但不保证与 onVideoComplete 的先后顺序,建议在 onAdClose 中判断 onReward 已回调才给用户奖励

    void onAdClick(String id);   // 广告被点击

    void onVideoComplete(String id); // 广告播放完毕

    void onAdClose(String id);   // 广告被关闭

    void onError(String id, int code, String message);  // 广告出错
}

加载激励视频广告具体示例详见 Demo 中的 RewardVideoActivity。

横幅广告接入

Banner 广告(横幅广告)位于 app 顶部、中部、底部任意一处,横向贯穿整个app页面;当用户与 app 互动时,Banner 广告会停留在屏幕上,并可在一段时间后自动刷新。

开发者可在主线程调用 AdSdk 实例的方法:

public void loadBannerAd(
    Activity context,   // 活动上下文
    String unitId,      // 广告位 id
    ViewGroup container, // 展现 Banner 广告的容器
    float width,        // Banner 宽度,单位 dp
    float height,       // Banner 高度,单位 dp,推荐宽高比 6.4:1
    BannerAdListener listener   // 广告回调
)

调用示例如下:

AdSdk.getInstance().loadBannerAd(BannerActivity.this, "b1", container, width, height,
        new AdSdk.BannerAdListener() {
            @Override
            public void onAdLoad(String id, AdSdk.BannerAd ad) {
            }

            @Override
            public void onAdShow(String id) {
            }

            @Override
            public void onAdClose(String id) {
            }

            @Override
            public void onAdClick(String id) {
            }

            @Override
            public void onError(String id, int code, String message) {
            }
        });

BannerAd 接口说明:

public interface BannerAd {
    void setRefreshInterval(int seconds);   // 设置刷新频率,为0或30~120之间的整数,单位秒,0表示不自动轮播,默认30秒

    void destroy(); // 释放广告资源
}

BannerAdListener 接口说明:

public interface BannerAdListener {
    void onAdLoad(String id, BannerAd ad); // 广告加载成功

    void onAdShow(String id);   // 广告页面展示

    void onAdClose(String id);  // 广告被关闭

    void onAdClick(String id);  // 广告被点击
    
    void onError(String id, int code, String message);  // 广告出错
}

加载 Banner 广告具体示例详见 Demo 中的 BannerActivity。

原生广告接入

原生模板广告,支持图文和视频样式,开发者不用自行对广告样式进行编辑和渲染,可直接调用相关接口获取广告 view。

开发者可在主线程调用 AdSdk 实例的方法:

public void loadNativeExpressAd(
    Activity context,   // 活动上下文
    String unitId,      // 广告位 id
    float width,        // 广告宽度,单位 dp,高度自适应
    int count,          // 请求广告数量
    NativeExpressAdListener listener    // 广告回调
)

调用示例如下:

AdSdk.getInstance().loadNativeExpressAd(NativeExpressActivity.this, "n1", width, 1,
        new AdSdk.NativeExpressAdListener() {
    @Override
    public void onAdLoad(List<AdSdk.NativeExpressAd> ads) {
        mNativeExpressAd = ads.get(0);
        mNativeExpressAd.render(mContainer);
    }

    @Override
    public void onAdShow(String id) {
    }

    @Override
    public void onAdClose(String id) {
    }

    @Override
    public void onAdClick(String id) {
    }

    @Override
    public void onError(String id, int code, String message) {
    }
});

NativeExpressAd 接口说明:

public interface NativeExpressAd {
    String getId(); // 获取广告 id

    void render(ViewGroup container); // 渲染广告

    void destroy(); // 释放广告资源
}

NativeExpressAdListener 接口说明:

public interface NativeExpressAdListener {
    void onAdLoad(List<NativeExpressAd> ads);   // 广告加载成功

    void onAdShow(String id);   // 广告页面展示

    void onAdClose(String id);  // 广告被关闭

    void onAdClick(String id);  // 广告被点击
    
    void onError(String id, int code, String message);  // 广告出错
}

加载原生广告具体示例详见 Demo 中的 NativeExpressActivity。

插屏广告接入

插屏广告是移动广告的一种常见形式,在应用开流程中弹出,当应用展示插页式广告时,用户可以选择点击广告,访问其目标网址,也可以将其关闭,返回应用。

开发者可在主线程调用 AdSdk 实例的方法:

public void loadInterstitialAd(
    Activity context,   // 活动上下文
    String unitId,      // 广告位 id
    float width,        // 广告宽度,单位 dp,高度自适应
    InterstitialAdListener listener // 广告回调
)

调用示例如下:

AdSdk.getInstance().loadInterstitialAd(InterstitialActivity.this, "i1", width,
        new AdSdk.InterstitialAdListener() {
            @Override
            public void onAdLoad(String id) {
            }

            @Override
            public void onAdShow(String id) {
            }

            @Override
            public void onAdClose(String id) {
            }

            @Override
            public void onAdClick(String id) {
            }

            @Override
            public void onError(String id, int code, String message) {
            }
        });
}

InterstitialAdListener 接口说明:

public interface InterstitialAdListener {
    void onAdLoad(String id);   // 广告加载成功

    void onAdShow(String id);   // 广告页面展示

    void onAdClose(String id);  // 广告被关闭

    void onAdClick(String id);  // 广告被点击
    
    void onError(String id, int code, String message);  // 广告出错
}

加载插屏广告具体示例详见 Demo 中的 InterstitialActivity。

全屏插屏广告接入

全屏插屏广告是移动广告的一种常见形式,在应用流程中弹出,当应用展示插页式广告时,用户可以选择点按广告,访问其目标网址,也可以将其关闭,返回应用。

开发者可在主线程调用 AdSdk 实例的方法:

public void loadFullScreenInterstitialAd(
    Activity context,   // 活动上下文
    String unitId,      // 广告位 id
    InterstitialAdListener listener // 广告回调
)

调用示例如下:

AdSdk.getInstance().loadFullScreenInterstitialAd(InterstitialActivity.this, "fi1",
        new AdSdk.InterstitialAdListener() {
            @Override
            public void onAdLoad(String id) {
            }

            @Override
            public void onAdShow(String id) {
            }

            @Override
            public void onAdClose(String id) {
            }

            @Override
            public void onAdClick(String id) {
            }

            @Override
            public void onError(String id, int code, String message) {
            }
        });
}

InterstitialAdListener 接口说明:

public interface InterstitialAdListener {
    void onAdLoad(String id);   // 广告加载成功

    void onAdShow(String id);   // 广告页面展示

    void onAdClose(String id);  // 广告被关闭

    void onAdClick(String id);  // 广告被点击
    
    void onError(String id, int code, String message);  // 广告出错
}

加载全屏插屏广告具体示例详见 Demo 中的 InterstitialActivity。

Draw 视频广告接入

竖版视频信息流广告,该广告适合在竖版全屏视频流中使用,接入方可以控制视频暂停或继续播放,默认视频播放不可干预。

开发者可在主线程调用 AdSdk 实例的方法:

public void loadDrawVideoAd(
    Activity context,   // 活动上下文
    String unitId,      // 广告位 id
    int count,          // 请求广告数量
    DrawVideoAdListener listener    // 广告回调
)

调用示例如下:

AdSdk.getInstance().loadDrawVideoAd(DrawVideoActivity.this, "dv1", 1,
        new AdSdk.DrawVideoAdListener() {
            @Override
            public void onAdLoad(List<AdSdk.DrawVideoAd> ads) {
                mDrawVideoAd = ads.get(0);
                mDrawVideoAd.render(container);
            }

            @Override
            public void onAdShow(String id) {
            }

            @Override
            public void onAdClick(String id) {
            }

            @Override
            public void onVideoStart(String id) {
            }

            @Override
            public void onVideoPause(String id) {
            }

            @Override
            public void onVideoResume(String id) {
            }
            
            @Override
            public void onVideoComplete(String id) {
            }

            @Override
            public void onError(String id, int code, String message) {
            }
        });

DrawVideoAd 接口说明:

public interface DrawVideoAd {
    String getId(); // 获取广告 id

    void render(ViewGroup container); // 渲染广告

    void destroy(); // 释放广告资源
}

DrawVideoAdListener 接口说明:

public interface DrawVideoAdListener {
    void onAdLoad(List<DrawVideoAd> ads);   // 广告加载成功

    void onAdShow(String id);   // 广告页面展示

    void onAdClick(String id);  // 广告被点击
    
    void onVideoStart(String id); // 广告播放开始

    void onVideoPause(String id); // 广告播放暂停

    void onVideoResume(String id); // 广告播放恢复

    void onVideoComplete(String id); // 广告播放完毕

    void onError(String id, int code, String message);  // 广告出错
}

加载 Draw 视频广告具体示例详见 Demo 中的 DrawVideoActivity。

快手短视频接入

AdSdk 将快手短视频封装成了 Fragment,接入方只需将 Fragment 放置在对应的 container 容器中即可。

Fragment fragment = AdSdk.getInstance().getDrawVideoFragment(DrawFeedActivity.this, "df1", mDrawVideoListener);
getSupportFragmentManager() // fragment 嵌套替换成 getChildFragmentManager()
        .beginTransaction()
        .replace(R.id.container, fragment)
        .commitNowAllowingStateLoss();

视频播放事件监听:

mDrawVideoListener = new AdSdk.DrawVideoListener() {
    @Override
    public void onVideoShow(String id, int videoType) { // 视频切换展示
    }

    @Override
    public void onVideoStart(String id, int videoType) { // 视频播放开始
    }

    @Override
    public void onVideoPause(String id, int videoType) { // 视频播放暂停
    }

    @Override
    public void onVideoResume(String id, int videoType) { // 视频播放恢复
    }

    @Override
    public void onVideoComplete(String id, int videoType) { // 视频播放完成
    }

    @Override
    public void onVideoError(String id, int videoType) { // 视频播放出错
    }
    
    @Override
    public void onError(String id, int code, String message) { // 出错
    }
};

视频类型包括:VideoType.VIDEO,VideoType.AD

接入快手短视频具体示例详见 Demo 中的 DrawFeedActivity。

横版视频接入

AdSdk 将横版视频封装成了 Fragment,接入方只需将 Fragment 放置在对应的 container 容器中即可。

Fragment fragment = AdSdk.getInstance().getHorizontalVideoFragment(HorizontalFeedActivity.this, "hf1", null);
getSupportFragmentManager() // fragment 嵌套替换成 getChildFragmentManager()
        .beginTransaction()
        .replace(R.id.container, fragment)
        .commitNowAllowingStateLoss();

接入横版视频具体示例详见 Demo 中的 HorizontalFeedActivity。

互动广告接入

互动广告是一种与用户交互的新型广告形式,包括但不限于发券、抽奖等。

打开互动广告 H5 活动页面的方法如下:

AdSdk.getInstance().startWebActivity(InteractiveActivity.this, "w1", null);

接入互动广告具体示例详见 Demo 中的 InteractiveActivity。

互动广告浮标接入

点击浮标跳转互动广告 H5 活动页面,提高流量利用率。接入方只需将浮标 View 放置在 container 容器中适当的位置即可。

// 浮标位置示例:右下角,边距15dp
FrameLayout.LayoutParams layoutParams = new FrameLayout.LayoutParams(FrameLayout.LayoutParams.WRAP_CONTENT, FrameLayout.LayoutParams.WRAP_CONTENT);
layoutParams.gravity = Gravity.BOTTOM | Gravity.END;
int margin = DensityUtils.dip2px(this, 15);
layoutParams.setMargins(margin, margin, margin, margin);

View floatView = AdSdk.getInstance().getFloatView(FloatActivity.this, "f1", 15, null);
contentLayout.addView(floatView, layoutParams);

接入互动广告浮标具体示例详见 Demo 中的 FloatActivity。