ZJSDK

SDK 集成

SDK 集成

此章节将演示如何集成ZJSDK到您的原生项目中。

提示

接入完成后，在正式上线前需要提供测试包，测试广告正常展现

SDK 不支持模拟器运行，需要使用真机调试

当前版本仅支持 AndroidX 环境

版本配置

SDK 可运行于 Android5.0 (API Level 21) 及以上版本，请确保build.gradle中的minSdkVersion参数不小于21

资源引入

提示

导入后无法编译等问题详见常见问题-编译

下载SDK的压缩包，解压后 ZJSDK_$VERSION 的文件夹里面会有以下内容：

目录/文件说明
libs需要集成的包目录(将里面的aar和jar放置开发工程的libs目录下)
build.gradle项目gradle需要集成的代码内容（包含repositories和dependencies）
AndroidManifest.xml需将AndroidManifest里的组件和权限信息等添加到开发工程的AndroidManifest（文件不存在则不需要配置）
proguard-android.txt混淆配置（文件不存在则不需要配置）
res必须导入的资源（有则将里面所有的文件夹复制到工程的res目录下，没有则不需要导入）
keep.xml如果打包时有开启shrinkResources或者接入了部分第三方的资源优化框架（如：AndResProguard），则必须将此文件中的资源添加到白名单，否则将导致崩溃或者广告异常
whitelists.txt如果接入了部分第三方的资源优化框架（如：AndResProguard），则必须将此文件中的资源添加到白名单，否则将导致崩溃或者广告异常

配置 APPCOMPAT

SDK 功能依赖于AppCompat包，开发者需要根据当前应用的开发环境引入对应的AppCompat依赖：

depedencies {
    //...

    // AndroidX 工程需要添加
    implementation "androidx.appcompat:appcompat:1.1.0"
    implementation "com.google.android.material:material:1.1.0"
    implementation "androidx.legacy:legacy-support-v4:1.0.0"
    implementation "androidx.constraintlayout:constraintlayout:2.1.4"

    //...
}

引入 SDK

当应用集成的本地 SDK 包较多的情况下，libs目录可能会存在比较多的文件，建议在工程中libs目录的同级目录下创建新的目录，如zj_libs目录，并将压缩包里libs的文件全部复制到zj_libs目录内，然后在build.gradle中批量引入

dependencies {
    // x5内核，需要引入，如已引入，可忽略
    implementation "com.tencent.tbs:tbssdk:44286"
    // 微信 OpenSdk ，需要引入，如已引入，可忽略
    implementation "com.tencent.mm.opensdk:wechat-sdk-android:6.8.30"
    // AGP 7+
    implementation(fileTree(mapOf("dir" to "zj_libs", "include" to listOf("*.jar", "*.aar"))))
}

权限声明

提示

若您的 targetSDKVersion>=23 ，您还需要在运行时进行动态权限申请（可参考示例工程）

(1) SDK 所需权限如下

<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.READ_PHONE_STATE" />
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission
    android:name="android.permission.QUERY_ALL_PACKAGES"
    tools:ignore="QueryAllPackagesPermission" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.VIBRATE" />
<uses-permission android:name="android.permission.REQUEST_INSTALL_PACKAGES" /> 
<!-- 【可选】访问WIFI状态权限 -->
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" /> 
<!-- 【可选】允许应用程序读取外部存储 -->
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" /> 
<!-- 【可选】允许应用程序写入外部存储 -->
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />

提示

SDK 不强制获取以上权限，即使没有获取可选权限 SDK 也能正常运行。获取以上权限将帮助优化投放广告精准度和用户的交互体验，提高收益

建议获取READ_PHONE_STATE权限

(2) 广告平台所需权限，必须将下载的SDK压缩包中的AndroidManifest.xml内容配置到您的项目上

混淆配置说明

PROGUARD 配置

SDK 所需的混淆配置，已集成在 AAR 包中，不需要额外配置

额外的混淆规则，必须参考下载的压缩包中proguard-android.txt文件，将文件中的内容添加到项目配置中

资源优化

如果您开启了shrinkResource，则需要在 res/raw 路径下加一个keep.xml，内容是压缩包的keep.xml文件的内容

如果引入了部分第三方的资源优化框架（如：AndResProguard），需要将压缩包内的whitelists.txt内容全部复制到插件的whiteLists配置中

OAID SDK 说明

Android10 起无法通过常规方式获取 IMEI 等设备 ID，影响部分广告网络正常广告加载、展示等业务。

2.4.6版本起 SDK 不再主动集成OAID SDK，开发者需要自行接入才可以正常加载这些广告网络的广告。

集成方式见OAID SDK 集成说明

Android 9 适配

HTTP LEGACY 兼容

注意： 如果缺少以下配置，可能导致广告图片显示不出来或者广告加载没有回调

在AndroidManifest中新增以下配置：

<application>
    ...
    <uses-library android:name="org.apache.http.legacy" android:required="false"/>
    ...
</application>

HTTP 明文传输配置

部分网络请求依赖 HTTP 明文传输，需要在AndroidManifest中进行配置：

<application 
    ...
    android:usesCleartextTraffic="true"
    >
</application>

若你的<application>中已经配置了android:networkSecurityConfig，则需要在对应的 xml 文件中增加

<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
    <!-- 新增全局配置 -->
    <base-config cleartextTrafficPermitted="true" />
    <!-- 新增全局配置 -->
</network-security-config>

AndroidManifest 配置说明

android:label 冲突

请在主 module->AndroidManifest.xml-><Application节点下添加android:lable="YOUR_LABEL"配置，然后追加tools:replace="android:label配置以覆盖

如果提示找不到 tools 的 NS，在<Manifest节点追加xmlns:tools="http://schemas.android.com/tools"

android:allowBackup 冲突

请在主 module->AndroidManifest.xml-><Application节点下添加android:allowBackup="YOUR_STRATEGY"配置，然后追加tools:replace="android:allowBackup配置以覆盖

如果提示找不到 tools 的 NS，在<Manifest节点追加xmlns:tools="http://schemas.android.com/tools"

minSdkVersion 冲突

ZJSDK 的 minSdkVersion 为 21，部分渠道 SDK 为 24，如果您的工程最低支持 21，请在主 module 的AndroidManifest.xml中添加<uses-sdk tools:overrideLibrary="com.bytedance.gromore,com.bytedance.sdk.openadsdk,com.bytedance.tools"/> 如配置中已有tools:overrideLibrary，则追加内容

目录