Android SDK 集成指南

说明：

极光联盟SDK需要在主进程中初始化

涉及多进程WebView的使用，用户想要使用自己的数据路径，可以在SDK初始化之前调用WebView.setDataDirectorySuffix()

开发者需要在Application#onCreate()方法中调用初始化接口来初始化极光联盟SDK。

运行环境

操作系统：支持 Linux/Mac/Windows 系统，具体依赖开发者选择的 IDE
开发工具：支持 Android studio、Eclipse、Intellij
部署目标：接入极光联盟SDK的应用
支持设备：运行了 Android 5.0 以及以上系统的 Android 设备
接入方式：aar包方式集成或 gradle maven自动集成。如使用 gradle自动集成方式，请参考下方：
implementation 'cn.jiguang.sdk.jcore:版本号' implementation 'cn.jiguang.sdk:jad:版本号'
```
          implementation 'cn.jiguang.sdk.jcore:版本号'
implementation 'cn.jiguang.sdk:jad:版本号'

        
```
此代码块在浮窗中显示

SDK版本要求：接入JAd SDK时，基础库JCore SDK最低版本要求为JCore3.2.0

集成方式

方式一：使用maven自动集成

implementation 'cn.jiguang.sdk.jcore:3.2.4' implementation 'cn.jiguang.sdk:jad:5.0.3'

          implementation 'cn.jiguang.sdk.jcore:3.2.4'  
implementation 'cn.jiguang.sdk:jad:5.0.3'

此代码块在浮窗中显示

方式二：导入aar包集成

请在工程文件根目录下创建一个名为 libs 的子目录，并将极光联盟 SDK 的 jad-android-5.0.3.aar 包拷贝到 libs 目录下
请在工程build.gradle中添加如下配置：

android{ sourceSets { main { jniLibs.srcDirs = ['libs'] } } } repositories{ flatDir{ dirs 'libs' } } dependencies { implementation (name:'jcore-android-3.2.4', ext:'aar') implementation (name:'jad-anroid-5.0.3', ext:'aar') }

          android{ 
    sourceSets {
        main {
            jniLibs.srcDirs = ['libs']
        }
    }
}
  
repositories{
    flatDir{
        dirs 'libs'
    }
}

dependencies {
    implementation (name:'jcore-android-3.2.4', ext:'aar')
    implementation (name:'jad-anroid-5.0.3', ext:'aar')
}

此代码块在浮窗中显示

注：jcore-android-3.2.4、jad-anroid-5.0.3 仅为举例，接入时请使用当前接入aar的文件名

AndroidManifest配置

添加权限

<permission android:name="${applicationId}.permission.JPUSH_MESSAGE" android:protectionLevel="signature" /> <uses-permission android:name="${applicationId}.permission.JPUSH_MESSAGE" /> <permission android:name="cn.jiguang.ads.component.PERMISSION" android:protectionLevel="signature" /> <uses-permission android:name="cn.jiguang.ads.component.PERMISSION" />  <uses-permission android:name="android.permission.INTERNET" />  <uses-permission android:name="android.permission.READ_PHONE_STATE" /> <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" /> <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" /> <uses-permission android:name="android.permission.VIBRATE" /> <uses-permission android:name="android.permission.REQUEST_INSTALL_PACKAGES" />  <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" /> <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" /> <uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" />  <uses-permission android:name="android.permission.QUERY_ALL_PACKAGES"/>

          <!--必选权限，解决安全风险漏洞，发送和注册广播事件需要调用带有传递权限的接口-->
<permission android:name="${applicationId}.permission.JPUSH_MESSAGE" android:protectionLevel="signature" />
<uses-permission android:name="${applicationId}.permission.JPUSH_MESSAGE" />
<permission android:name="cn.jiguang.ads.component.PERMISSION" android:protectionLevel="signature" />
<uses-permission android:name="cn.jiguang.ads.component.PERMISSION" />
   
<!-- 必选权限 -->
<uses-permission android:name="android.permission.INTERNET" />
 
<!-- 可选权限 -->
<uses-permission android:name="android.permission.READ_PHONE_STATE" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.VIBRATE" />
<uses-permission android:name="android.permission.REQUEST_INSTALL_PACKAGES" />
   
<!--可选，只有当应用添加位置权限并且在用户权限地理位置权限情况下，SDK才可能会去获取地理位置信息，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.ACCESS_BACKGROUND_LOCATION" />
 
<!-- 建议添加“query_all_package”权限，极光联盟将通过此权限在Android R系统上判定广告对应的应用是否在用户的app上安装，避免投放错误的广告，以此提高用户的广告体验。若添加此权限，需要在您的用户隐私文档中声明！ -->
<uses-permission android:name="android.permission.QUERY_ALL_PACKAGES"/>

此代码块在浮窗中显示

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

添加组件

          <application>
    
    <!-- Since5.0.0 Require： SDK基础核心组件，提升SDK稳定性 -->
    <service
        android:name="cn.jiguang.ads.app.service.UserService"
        android:exported="false"
        android:process=":remote">
        <intent-filter>
            <action android:name="cn.jiguang.user.service.action" />
        </intent-filter>
    </service>

    <!-- Since5.0.0 Require： h5广告应用内落地页承接，提升广告体验 -->
    <activity
        android:name="cn.jiguang.ads.base.component.JAdActivity"
        android:configChanges="orientation|keyboardHidden"
        android:exported="false"
        android:launchMode="singleTop"
        android:theme="@android:style/Theme.NoTitleBar">
        <intent-filter>
            <action android:name="cn.jiguang.ads.core.component.JAdActivity" />
            <category android:name="android.intent.category.DEFAULT" />
            <category android:name="${applicationId}" />
        </intent-filter>
    </activity>

    <!-- Since5.0.0 Require： 拉新等广告交互组件，缺失将影响广告转化与效果 -->
    <activity
        android:name="cn.jiguang.ads.base.component.JTransparentActivity"
        android:exported="false"
        android:taskAffinity="junion.custom"
        android:theme="@android:color/transparent">
        <intent-filter>
            <action android:name="cn.jiguang.ads.component.JTransparentActivity" />
            <category android:name="android.intent.category.DEFAULT" />
            <category android:name="${applicationId}" />
        </intent-filter>
    </activity>

    <!-- Since5.0.0 Require： SDK基础业务组件 -->
    <provider
        android:name="cn.jiguang.ads.base.component.JAdProvider"
        android:authorities="${applicationId}.ads.provider"
        android:exported="false" />

    <!-- Since5.0.0 Require： 拉新类广告必须配置，提升流量转化 -->
    <provider
        android:name="cn.jiguang.ads.base.component.JAdFileProvider"
        android:authorities="${applicationId}.JAdFileProvider"
        android:exported="false"
        android:grantUriPermissions="true">
        <meta-data
            android:name="android.support.FILE_PROVIDER_PATHS"
            android:resource="@xml/jad_file_paths" />
        <intent-filter>
            <action android:name="cn.jpush.android.intent.FileProvider" />
            <category android:name="${applicationId}" />
        </intent-filter>
    </provider>

    <!-- Since5.0.0 Require： SDK基础业务组件 -->
    <receiver
        android:name="cn.jiguang.ads.base.component.JAdReceiver"
        android:exported="false"
        android:permission="cn.jiguang.ads.component.PERMISSION" />

    <!-- 值来自开发者平台取得的AppKey -->
    <meta-data
        android:name="JPUSH_APPKEY"
        android:value="${JPUSH_APPKEY}" />
    <meta-data
        android:name="JPUSH_CHANNEL"
        android:value="${JPUSH_CHANNEL}" />
            
</application>

此代码块在浮窗中显示

Provider配置

注意：

（1）为不影响下载类型广告使用，无论APP处于任何阶段provider都需要在清单文件中正常配置（2）为不影响到广告的转化及收益，请务必在清单文件中配置FileProvider组件

适配Anroid7.0及以上 如果您的应用需要在Anroid7.0及以上环境运行，请在AndroidManifest中添加如下代码：

          <manifest xmlns:android="http://schemas.android.com/apk/res/android">
    ...
    <!-- 1.配置安装应用权限 -->
    <uses-permission android:name="android.permission.REQUEST_INSTALL_PACKAGES" />
    <!-- 适配android11 -->
    <uses-permission android:name="android.permission.QUERY_ALL_PACKAGES"/>
    ...
  
    <application>
        ...
        <!-- Since5.0.0 适配Anroid7.0及以上，如果您的应用需要在Anroid7.0及以上环境运行 -->
        <provider
            android:name="cn.jiguang.ads.base.component.JAdFileProvider"
            android:authorities="${applicationId}.JAdFileProvider"
            android:exported="false"
            android:grantUriPermissions="true">
            <meta-data
                android:name="android.support.FILE_PROVIDER_PATHS"
                android:resource="@xml/jad_file_paths" />
            <intent-filter>
                <action android:name="cn.jpush.android.intent.FileProvider" />
                <category android:name="${applicationId}" />
            </intent-filter>
        </provider>
                
    </application>
</manifest>

此代码块在浮窗中显示

需要注意的是 provider 的 authorities 值为 ${applicationId}.JAdFileProvider，对于每一个开发者而言，这个值都是不同的，${applicationId} 在代码中和 Context.getPackageName() 值相等，是应用的唯一 id。

在res/xml目录下，新建一个xml文件jad_file_paths，在该文件中添加如下代码：

<?xml version="1.0" encoding="utf-8"?> <resources> <paths> <root-path name="jad_root_path" path="."/> <external-path name="jad_external_path" path="JAdDownload" /> <external-files-path name="jad_external_files_path" path="JAdDownload" /> <files-path name="jad_files_path" path="JAdDownload" /> <cache-path name="jad_cache_path" path="JAdDownload" /> </paths> </resources>

          <?xml version="1.0" encoding="utf-8"?>
<resources>
   <paths>    
        <root-path name="jad_root_path" path="."/>
        <external-path name="jad_external_path" path="JAdDownload" />
        <external-files-path name="jad_external_files_path" path="JAdDownload" />
        <files-path name="jad_files_path" path="JAdDownload" />
        <cache-path name="jad_cache_path" path="JAdDownload" />  
    </paths>
</resources>

此代码块在浮窗中显示

资源文件配置

极光联盟SDK进行广告渲染，需要依赖相关资源文件进行，资源文件包括：

以jad为前缀的目录drawable、layout以及xml下的资源文件

目录	文件名称	说明
目录	文件名称	说明
res/drawable	jad_actionbar_back.png
	jad_actionbar_divider.png
	jad_back.xml
	jad_btn_bg_green_playable.xml
	jad_cancle.png
	jad_close.png
	jad_close_white.png
	jad_close_gray.png
	jad_progressbar.xml
res/layout	jad_layout.xml
	jad_notification.xml
	jad_notification_large.xml
	jad_notification_middle.xml
	jad_download_notification_layout.xml
res/layout-21	jad_notification.xml	layout-21目录下的这三个资源文件，与layout目录下相同文件名的资源文件有区别，需要严格添加SDK包的相应目录中的该文件。
	jad_notification_large.xml
	jad_notification_middle.xml
res/xml	jad_file_paths.xml

如果您的工程中接入了资源混淆插件AndResGuard，为了保证SDK的资源可以被正常使用，需要在build.gradle中新增极光联盟资源白名单配置，内容如下：
andResGuard { // 白名单配置 whiteList = [ "R.drawable.jad_*" "R.layout.jad_*" "R.id.jad_*" ] }
```
          andResGuard {
  // 白名单配置
  whiteList = [
        "R.drawable.jad_*"
        "R.layout.jad_*"
        "R.id.jad_*"
    ]
}

        
```
此代码块在浮窗中显示

代码混淆

如果您需要使用proguard混淆代码，需确保不要混淆SDK的代码。请在proguard.cfg文件(或其他混淆文件)尾部添加如下配置:

-dontoptimize -dontpreverify -dontwarn cn.jpush.** -keep class cn.jpush.** { *; } -dontwarn cn.jiguang.** -keep class cn.jiguang.** { *; }

          -dontoptimize
-dontpreverify

-dontwarn cn.jpush.**
-keep class cn.jpush.** { *; }

-dontwarn cn.jiguang.**
-keep class cn.jiguang.** { *; }

此代码块在浮窗中显示

注意: SDK代码被混淆后会导致广告无法展现或者其它异常