全局配置

权限申请

代码混淆

SDK 初始化

开屏广告接入

广告 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.27' // 依赖 oaid
    implementation 'com.mob.sdk:adsdk:2.7.25'
}

方法二：手动集成

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

repositories {
    flatDir {
        dirs 'libs'
    }
}

depedencies {
    implementation(name: 'oaid-sdk', ext: 'aar') // 依赖 oaid
    implementation(name: 'adsdk-2.7.25', 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。