Android SDK集成说明

开始之前

我们支持Android系统版本Version 4.1 (API Level 16) 及以上。请确保满足以下要求：

使用Android Studio 2.0 版本及以上

Target Android API level 28

MinSdkVersion level 16 及以上

1. 概述

本手册介绍如何将京媒SDK集成到您的Android应用中。

京媒SDK支持开屏、信息流等丰富的广告类型。

注意：
针对 2.0.0 以前升级用户，广告接口更改，详情见接口升级说明文档
针对 2.1.0 及以后版本 ，京媒SDK默认支持AndroidX版本，接入时请注意是否为AndroidX项目

2. Ads ID

在进行SDK集成之前，您得先有一个 京媒合作平台 的账号，然后注册您的应用、创建广告位等操作，得到集成所必要的信息：APP_ID 和 Slot ID。

APP_ID: APP_ID 是给开发者应用分配的唯一标识，您可以在京媒合作平台创建应用后即可获取APP_ID。

Slot ID: 是广告位的唯一标识。开发者可以创建多个广告位。 京媒SDK广告位类型支持开屏、插屏、横幅、信息流四种广告类型。

3. 添加SDK到开发项目中

方式一：整包接入

下载SDK后，解压将本SDK压缩包内的jad_yun_sdk_x.x.x.aar复制到Application Module/libs文件夹(没有的话须手动创建), 并将以下代码添加到您app的build.gradle中：

repositories {
    flatDir {
        dirs 'libs'
    }
}
depedencies {
    implementation(name: 'jad_yun_sdk_x.x.x', ext: 'aar')
}

方式二：分包接入

将开屏、信息流、媒体渲染5种广告类型的组件化，您可以按实际业务场景接入所需的广告组件。 下载SDK后，解压将本SDK压缩包内您需要的aar复制到Application Module/libs文件夹(没有的话须手动创建), 并将以下代码添加到您app的build.gradle中：

repositories {
    flatDir {
        dirs 'libs'
    }
}
depedencies {
    implementation(name: 'jad_yun_core_x.x.x', ext: 'aar')         //必选
    implementation(name: 'jad_yun_splash_x.x.x', ext: 'aar')       //可选，京东渲染开屏
    implementation(name: 'jad_yun_feed_x.x.x', ext: 'aar')         //可选，京东渲染信息流
    implementation(name: 'jad_yun_native_x.x.x', ext: 'aar')       //可选，媒体渲染广告（开屏、信息流）

}

``

方式三：自动接入

添加仓库：在project级别的build.gradle文件中添加Maven的引用

 allprojects {
    repositories {
        ...
        maven { url 'https://jitpack.io' }
    }
}

添加依赖：在主module的build.gradle文件添加SDK依赖

//方式1. 单广告位按需接入
dependencies {
    implementation 'com.github.JAD-FE-TEAM.JADYunAndroid:jad_yun_core:x.x.x'   //必选，核心功能
    implementation 'com.github.JAD-FE-TEAM.JADYunAndroid:jad_yun_splash:x.x.x' //可选，开屏广告
    implementation 'com.github.JAD-FE-TEAM.JADYunAndroid:jad_yun_feed:x.x.x'   //可选，信息流广告
    implementation 'com.github.JAD-FE-TEAM.JADYunAndroid:jad_yun_native:x.x.x' //可选，媒体渲染广告
}

//方式2. 全广告位接入
dependencies {
    implementation 'com.github.JAD-FE-TEAM.JADYunAndroid:jad_yun_sdk:x.x.x'
}

4. AndroidManifest.xml配置

接下来需要添加配置到您的AndroidManifest.xml 文件中.

<!--必要权限 用户SDK可访问网络-->
<uses-permission android:name="android.permission.INTERNET"/>

<!--可选权限-->
<!--用于SDK可获取网络状态变化，更及时的更新媒体广告位配置-->
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<!--用于SDK，在媒体允许的情况下，获取IMEI 标识用户的唯一性，有助于广告填充-->
<uses-permission android:name="android.permission.READ_PHONE_STATE" />
<!--用于SDK，在媒体允许的情况下，获取使用Wi-Fi等WLAN无线网，有助于广告精准投放-->
 <uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<!--用于SDK，在媒体允许的情况下，获取位置信息，更精确的推送最有价值的广告-->
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<!--用于京东渲染广告图片缓存 -->
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
<!--建议添加“query_all_package”权限，京东广告将通过此权限在Android R系统上判定广告对应的应用是否在用户的app上安装，
避免投放错误的广告，以此提高用户的广告体验。若添加此权限，需要在您的用户隐私文档中声明！-->
<uses-permission android:name="android.permission.QUERY_ALL_PACKAGES" />

注意: 广告SDK不强制获取以上权限，即使没有获取可选权限SDK也能正常运行；获取以上权限将帮助优化投放广告精准度和广告填充率，提高收益。

5. Proguard

-keep class com.jd.ad.sdk.** { *; }

6. 初始化SDK

建议开发者在Application#onCreate()方法中调用以下代码来初始化京媒SDK

        //初始化SDK配置
        JADYunSdkConfig config = new JADYunSdkConfig
                .Builder()
                .setAppId(Constants.APP_ID) //媒体在平台申请的 APP ID
                .setEnableLog(BuildConfig.DEBUG) //测试阶段打开，可以通过日志排查问题，上线时去除该调用
                .setPrivateController(createPrivateController()) //隐私信息控制设置，此项必须设置！！
                .setSupportMultiProcess(true)//是否支持多进程，true表示支持，默认不支持,若不支持多进程场景，无需设置该配置
                .build();

        //初始化SDK
        JADYunSdk.init(this, config);

        //同步初始化SDK
        JADYunSdk.syncInit(this, config, new JADInitCallback() {
            /**
             * 初始化成功
             */
            @Override
            public void onInitSuccess() {

            }
            /**
             * 初始化失败
             */
            @Override
            public void onInitFailure(int code, String msg) {

            }
        });

        //异步初始化SDK
        JADYunSdk.asyncInit(this, config, new JADInitCallback() {
            /**
             * 初始化成功
             */
            @Override
            public void onInitSuccess() {

            }
            /**
             * 初始化失败
             */
            @Override
            public void onInitFailure(int code, String msg) {

            }
        });

7.初始化接口说明

    /**
     * @param context Context 上下文
     * @param config 初始化配置信息
     */
    public static void init(@NonNull Context context, @NonNull JADYunSdkConfig config);

    /**
     * 同步初始化方法
     *
     * @param context      上下文对象
     * @param sdkConfig    初始化配置
     * @param initCallback 同步初始化回调
     */
    public static void syncInit(@NonNull Context context, @NonNull JADYunSdkConfig sdkConfig, JADInitCallback initCallback);

     /**
     * 异步初始化方法
     *
     * @param context      上下文对象
     * @param sdkConfig    初始化配置
     * @param initCallback 异步初始化回调
     */
    public static void asyncInit(@NonNull Context context, @NonNull JADYunSdkConfig sdkConfig, JADInitCallback initCallback);

    /**
     * 初始化是否成功
     */
    public static boolean isInitSuccess();

8.隐私信息控制开关

请媒体用户设置OAID参数, 否则可能影响广告填充
1、OAID的获取请查看移动安全联盟文档, 将获取的OAID值按照如下进行设置：
2、设置其他控制权限(位置，IMEI等)

JADYunSdkConfig config = new JADYunSdkConfig.Builder()
                ...
                .setPrivateController(new JADPrivateController() {
                    @Override
                    public String getOaid() {
                        return mIdSupplier.getOAID();
                    }

                    @Override
                    public boolean isCanUsePhoneState() {
                        return true;
                    }
                })
                ...

3、隐私信息控制类说明: 重要！！重要！！

创建隐私信息控制类的实例，媒体可以自主控制是否提供权限给广告SDK使用
为了保证广告的填充率，注意oaid和imei的配置：
(1)oaid配置项必须实现，并传入有效值
(2)imei的配置与isCanUsePhoneState有关（isCanUsePhoneState配置项默认为true）
当isCanUsePhoneState 配置为false，不允许SDK主动获取imei，但是需要接入方主动传入imei
当isCanUsePhoneState 配置为true，允许SDK主动获取imei，但必须保证接入方已经动态申请了 Manifest.permission.READ_PHONE_STATE，否则SDK会获取失败
其他采用可以采用默认配置(可以不用实现相关方法，默认都是支持SDK主动获取的)

    private JADPrivateController createPrivateController() {
        return new JADPrivateController() {
            /**
             * 是否允许SDK主动使用手机硬件参数，如：imei
             *
             * @return true可以使用，false禁止使用。默认为true
             */
            public boolean isCanUsePhoneState() {
                return true;
            }

            /**
             * 当 isCanUsePhoneState=false 时，
             * 可传入 imei 信息，sdk使用您传入的 imei 信息
             *
             * @return imei信息
             */
            public String getImei() {
                return "";
            }

            /**
             * 开发者可以传入oaid
             *
             * @return oaid
             */
            @Override
            public String getOaid() {
                return mIdSupplier != null ? mIdSupplier.getOAID() : "";
            }

            /**
             * 是否允许SDK主动使用地理位置信息
             *
             * @return true可以获取，false禁止获取。默认为true
             */
            public boolean isCanUseLocation() {
                return true;
            }

            /**
             * 当isCanUseLocation=false时，可传入地理位置信息，sdk使用您传入的地理位置信息
             *
             * @return 地理位置参数
             */
            public JADLocation getLocation() {
                return new JADLocation();
            }

            /**
             * 是否允许SDK主动使用IP信息
             * @return true可以使用，false禁止使用。默认为true
             */
            @Override
            public boolean isCanUseIP() {
                return true;
            }

            /**
             * 当 isCanUseIP=false 时，
             * 可传入 IP 信息，SDK使用您传入的 IP 信息
             *
             * @return IP
             */
            @Override
            public String getIP() {
                return "";
            }

        };
    }

9.重点说明

为了广告SDK正常使用，请对所有广告SDK 接口的调用， 都放在主线程中,如广告的创建，广告的加载等

注意: 1.集成移动安全联盟SDK需要将 supplierconfig.json 拷贝到项目 assets 目录下 2.appid 只与 VAID(开发者匿名设备标识符) 的获取有关，用于判断是否为同一开发者，如不需获取 vaid 可 不填写。目前只需设置 vivo 的 appid。 3.其他注意事项可参考移动广告联盟SDK F&Q文档

恭喜您完成了京媒SDK的集成。接下来请在您的应用中完集成开屏、信息流广告。