集成指南

前言

本文档介绍 Android Studio 开发环境下基于 Maven 方式集成的步骤。

本文档适用 SDK 版本：3.1.2.0 及以后

本文默认读者已经具有基础的 Android 知识，以及项目工程结构如下：

```

Getui_SDK_Demo_AS_official/

|- app/ (项目主模块)||- libs/ (第三方库)||- src/ (代码目录)||- build.gradle (模块级 gradle 文件)|- gradle/|- build.gradle (顶层 gradle 文件)|- settings.gradle|......

```

注：其中 “`......`” 表示省略其他与本教程无关的内容，以下 “`......`” 表示相同意义，不再重复说明。

重点提示

SDK 最新 so 为 libgetuiext3.so，由于仅支持Maven方式集成，故老版本升级时请删除原先jniLibs目录中所有的 libgetuiext2.so、libgetuiext.so；

移除 Gradle 中 GETUI_APP_KEY、GETUI_APP_SECRET、配置，GETUI_APP_ID 改为 GETUI_APPID, AndroidManifest 中仅保留 GETUI_APPID 占位符。

为兼容 Android 9.0，请在 application 节点添加 android:usesCleartextTraffic="true"；

简化集成步骤，只需调用新增 PushManager.getInstance().initialize(Context context) 接口即可完成 SDK 初始化， 个推 SDK 会自动去寻找相应的 PushService 和 GTIntentService，无需在代码中注册自定义的PushService以及再次调用 PushManager.getInstance().registerPushIntentService(Context context, Class userIntentService) 进行 IntentService 注册，详细步骤见本教程说明。建议替换原有的PushManager.getInstance().initialize(Context context, Class userServiceName)接口。

原先使用 2.9.5.0 以下版本的用户，升级前请删除所有已集成配置。

接口变动：移除 PushManager.getInstance().stopService() 接口。

废弃原有的 PushManager.getInstance().initialize(Context context, Class userServiceName) 、PushManager.getInstance().registerPushIntentService(Context context, Class userIntentService)接口。

新增PushManager.getInstance().initialize(Context context) 接口进行初始化，推荐使用该接口进行初始化。

新增PushManager.getInstance().setDebugLogger(Context context, IUserLoggerInterface loggerInterface) 接口，用于调试日志输出。

请在app/build.gradle 中加入以下代码，使用 java 8.compileOptions {

sourceCompatibility 1.8

targetCompatibility 1.8

}

1. 创建个推应用

请参考 创建应用 获取相应的AppID信息。该信息在之后的步骤配置中将会使用。

2. Maven 集成

注意：如果过去是手动集成方式切换到 Maven 集成，则需删除原有集成配置再进行新集成。

2.1 配置 Maven 库地址

在项目根目录 build.gradle 文件的 allprojects.repositories 块中，添加个推 maven 库地址 maven { url "http://mvn.gt.getui.com/nexus/content/repositories/releases/"}，如下所示：

buildscript {

repositories {

jcenter()

google()

}

dependencies {

......

}

}

allprojects {

repositories {

jcenter()

google()

maven {

url "http://mvn.gt.getui.com/nexus/content/repositories/releases/"

}

}

}

2.2 配置依赖

配置 so 库：目前个推 SDK 支持 armeabi、armeabi-v7a、arm64-v8a、mips、mips64、x86、x86_64 这几种 CPU 架构，请根据项目情况指定所需的架构。注意：如果项目中其他 so 库只支持其中某几种 CPU 架构，那么应该根据其他 so 库所支持的 CPU 架构的最小集来配置。否则如果在特定架构上未能支持所有 so 库，则很可能导致程序运行异常。切记！

在 app/build.gradle 文件中的 android.defaultConfig 下指定所需的 CPU 架构，如下所示：

```

defaultConfig {

ndk {

// 注意：这里需要添加项目所需 CPU 类型的最小集

abiFilters "armeabi", "armeabi-v7a", "x86_64", "x86"

}

}

......

```

- 若 Android Studio 编译出现：`NDK integration is deprecated in the current plugin. Consider trying the new experimental plugin.` 报错，请在项目根目录 gradle.properties 文件中添加：`android.useDeprecatedNdk=true`配置 SDK 依赖及应用参数：在 app/build.gradle 文件的 dependencies 块中引用个推 SDK 依赖 implementation 'com.getui:gtsdk:${version}'，此处的 ${version} 为对应的 SDK 版本号，并在android.defaultConfig 下添加 manifestPlaceholders，配置个推相关的应用参数， 如下所示：

```

......

android {

defaultConfig {

manifestPlaceholders = [

//从 3.1.2.0 版本开始，APPID 占位符从 GETUI_APP_ID 切换为 GETUI_APPID

//后续所有产品的 APPID 均统一配置为 GETUI_APPID 占位符

GETUI_APPID : "your appid",

//渠道若为纯数字则不能超过 int 表示的范围。

GT_INSTALL_CHANNEL : "your channel"

]

ndk {

// 添加项目所需 CPU 类型的最小集

abiFilters "armeabi", "armeabi-v7a", "x86_64", "x86"

}

}

......

}

dependencies {

implementation 'com.getui:gtsdk:3.1.2.0' //个推SDK

implementation 'com.getui:gtc:3.1.0.0' //个推核心组件

}

```

2.3 其他说明(重要)

注意: 对于同时集成个推多个产品SDK，且SDK之间的APPID值不一致的用户，可以任选一个SDK的APPID配置到GETUI_APPID占位符中，其余SDK在AndroidManifest文件中务必添加对应的标签来补充APPID，参考以下配置：

....

android:name="PUSH_APPID"

android:value="个推SDK的appid" />

android:name="GY_APP_ID"

android:value="个验SDK的appid" />

android:name="GS_APPID"

android:value="个数SDK的appid" />

android:name="GI_APPID"

android:value="个像SDK的appid" />

....

2.4 配置可选权限

上述接入方式已包含个推服务所需的所有必备权限。在此之外，您还可以配置以下可选权限，以便使用个推提供的电子围栏功能。请在AndroidManifest.xml的根标签下添加如下配置：

3. 配置推送服务

为了让推送服务在部分主流机型上更稳定运行，从 2.9.5.0 版本开始，个推支持第三方应用配置使用自定义 Service 来作为推送服务运行的载体。

在项目源码中添加一个继承自 com.igexin.sdk.PushService 的自定义 Service：

package com.getui.demo.service;

public class DemoPushService extends com.igexin.sdk.PushService{

}

在 AndroidManifest.xml 中添加上述自定义 Service，(使用 maven 集成，android:process 属性必须为 pushservice。手动集成方式也请保证与其他组件进程名一致，建议复制本文档的默认配置即可)，如下：

android:name="com.getui.demo.service.DemoPushService"

android:exported="true"

android:label="PushService"

android:process=":pushservice"/>

4. 设置通知图标

设置通知栏及通知栏顶部图标：为了修改默认的通知图标以及通知栏顶部提示小图标，请务必在资源目录的 res/drawable-ldpi/、res/drawable-mdpi/、res/drawable-hdpi/、res/drawable-xhdpi/、res/drawable-xxhdpi/ 等各分辨率目录下，放置相应尺寸的文件名为 push.png 和 push_small.png 的图片(该图片内容为您应用自定义的图标文件)，如图所示：

Getui_SDK_Demo_AS_official/

|- app/||- src/||- main/||- res/||- drawable-hdpi/||- push.png||- push_small.png||- drawable-ldpi/||- push.png||- push_small.png||- drawable-mdpi||- push.png||- push_small.png||- drawable-xhdpi||- push.png||- push_small.png||- drawable-xxhdpi||- push.png||- push_small.png|......

push_small.png 会展示在顶部状态栏和通知左上角位置，push_small 只能内置, 不能修改。push.png 将会作为通知展示图标，请务必确认您放置的图标内容无误。建议的 push.png 图片尺寸和 push_small.png 图片尺寸分别如下：

//push.png 图片尺寸

ldpi: 48*48

mdpi: 64*64

hdpi: 96*96

xhdpi: 128*128

xxhdpi: 192*192

//push_small.png 图片尺寸

ldpi: 18*18

mdpi: 24*24

hdpi: 36*36

xhdpi: 48*48

xxhdpi: 72*72

xxxhdp: 96*96

另外，push_small.png 设计规范有以下四个注意要点：1. 必须是带 Alpha 透明通道的 PNG 图片。 2.背景必须是透明的。 3.图形必须是白色。 4. 周围不宜留过多的 padding。

配置多套通知栏图标：如果您需要根据不同推送场景切换不同通知栏图标或者其他配置多套通知栏图标的场景，可以参考以下步骤：

首先，在资源目录的 res/drawable-ldpi/、res/drawable-mdpi/、res/drawable-hdpi/、res/drawable-xhdpi/、res/drawable-xxhdpi/ 等各分辨率目录下放置相应的多套通知图标，例如 push1.png、push2.png，如下：

Getui_SDK_Demo_AS_official/

|- app/||- src/||- main/||- res/||- drawable-hdpi/||- push1.png||- push2.png||- push_small.png||- drawable-ldpi/||- push1.png||- push2.png||- push_small.png||- drawable-mdpi||- push1.png||- push2.png||- push_small.png||- drawable-xhdpi||- push1.png||- push2.png||- push_small.png||- drawable-xxhdpi||- push1.png||- push2.png||- push_small.png|......

然后，通过服务端推送 API，Style 样式 API 中的 setLogo 方法指定通知栏图标的名称，例如 style.setLogo("push1.png") 来指定要切换展示的对应名称的通知图标(仅切换通知栏图标)，详见 服务端推送模版。

5. 其他配置

5.1 资源精简配置

5.1.1 shrinkResources

如果您的工程启用了资源精简，即如果在 app/build.gradle 的 android.buildTypes.release 下配置了 shrinkResources true，为了避免个推 SDK 所需资源被错误精简导致功能异常，需要在项目资源目录 res/raw 中添加 keep.xml 文件，并在 keep.xml 文件中使用 tools:keep 定义哪些资源需要被保留(资源之间用“,”隔开)，如 tools:keep="@drawable/push,@drawable/push_small,...,"，此处 @drawable/push、@drawable/push_small 通知图标的名称应为您当前放着于应用中的图标名称，如下：

xmlns:tools="http://schemas.android.com/tools"

tools:keep="......,

@drawable/push,

@drawable/push_small"/>

5.1.2 AndResGuard

如果您的工程使用了 AndResGuard 进行资源精简，为了避免个推 SDK 所需资源被错误精简导致功能异常，需要为个推添加白名单配置。gradle 集成 AndResGuard 的方式，需要您在 AndResGuard 的 whiteList 节点下添加如下代码：

andResGuard {

......

whiteList = [

......

// for getui

"R.drawable.push",

"R.drawable.push_small"

// 若您需要使用其他自定义推送图标，也需要在此处添加，此处的 R.drawable.push，R.drawable.push_small 应为您当前放置的推送图标。

]

......

}

命令行使用 AndResGuard 的方式，需要您在 config.xml 文件中的 节点下添加如下代码：

6. 编写集成代码

初始化 SDK

调用个推初始化代码：com.igexin.sdk.PushManager.getInstance().initialize(Context context) 进行 SDK 的初始化。我们建议开发者在 Application.onCreate() 和主 Activity.onCreate() 方法中初始化个推 SDK。多次调用 SDK 初始化并无影响。为了保证 SDK 服务稳定，推荐引导用户授权相关的隐私权限。

另外，为了保证推送通知更好的触达用户，降低用户对于通知开关设置的难度，我们建议在应用代码中引导用户前往通知页面打开允许应用通知开关，具体实现代码可以参考 Demo 工程。

自定义接收推送服务事件

在项目源码中添加一个继承自 com.igexin.sdk.GTIntentService 的类，用于接收 CID、透传消息以及其他推送服务事件。请参考下列代码实现各个事件回调方法：

package com.getui.demo;

import android.content.Context;

import android.util.Log;

import com.igexin.sdk.GTIntentService;

import com.igexin.sdk.message.GTCmdMessage;

import com.igexin.sdk.message.GTNotificationMessage;

import com.igexin.sdk.message.GTTransmitMessage;

/**

* 继承 GTIntentService 接收来自个推的消息，所有消息在线程中回调，如果注册了该服务，则务必要在 AndroidManifest 中声明，否则无法接受消息

*/

public class DemoIntentService extends GTIntentService {

@Override

public void onReceiveServicePid(Context context, int pid) {

}

// 处理透传消息

@Override

public void onReceiveMessageData(Context context, GTTransmitMessage msg) {

// 透传消息的处理，详看 SDK demo

}

// 接收 cid

@Override

public void onReceiveClientId(Context context, String clientid) {

Log.e(TAG, "onReceiveClientId -> " + "clientid = " + clientid);

}

// cid 离线上线通知

@Override

public void onReceiveOnlineState(Context context, boolean online) {

}

// 各种事件处理回执

@Override

public void onReceiveCommandResult(Context context, GTCmdMessage cmdMessage) {

}

// 通知到达，只有个推通道下发的通知会回调此方法

@Override

public void onNotificationMessageArrived(Context context, GTNotificationMessage msg) {

}

// 通知点击，只有个推通道下发的通知会回调此方法

@Override

public void onNotificationMessageClicked(Context context, GTNotificationMessage msg) {

}

}

在 AndroidManifest.xml 中配置上述 IntentService 类，如下：

android:name="com.getui.demo.service.DemoIntentService"

android:permission="android.permission.BIND_JOB_SERVICE"/>

7. 验证推送

查看调试日志信息

在 Application 的 onCreate 中添加以下代码：com.igexin.sdk.PushManager.getInstance().setDebugLogger(this, new IUserLoggerInterface() {

@Override

public void log(String s) {

Log.i("PUSH_LOG",s);

}

});

连接手机或启动 Android 模拟器，编译运行你的工程，查看 logcat 信息。过滤 logcat 中的 PUSH_LOG 信息，如果看到 Login successed with cid = xxx 日志输出，则说明 SDK 初始化成功。

[GT-PUSH] [PushManager]Start initializing sdk

[GT-PUSH] [PushManager]start pushService = com.getui.demo.DemoPushServiceNew

[GT-PUSH] [LOG-LogController] Sdk version = 3.0.1.0

[GT-PUSH] [PushManager]call registerPushIntentService

[GT-PUSH] onHandleIntent() = get sdkservicepid

[GT-PUSH] ServiceManager start from initialize...

[GT-PUSH] load so = getuiext3 bysystemsuccess

[GT-PUSH] Start login appid = TI85ilD*******L89MFNV appkey = 1qNlp*******BP9COgYjA

[GT-PUSH] Login successed with cid = e3f004e873f9a5d9e2e006c4a9ca2f5f

[GT-PUSH] onHandleIntent() = receivedclientid

注意：com.igexin.sdk.PushManager.getInstance().setDebugLogger 接口仅限调试的时候使用，切勿发布到线上版本，重复调用仅以第一次为准。 可以任意顺序调用该接口与个推初始化接口，但建议紧邻着个推初始化接口调用该接口。 如果看到 Warning! the log cache is too long to show the full content,we suggest you call initialize and setDebugLogger in a short time interval. 这样的提示请调整调用时间间隔。

测试推送功能

登录 个推 ，点击相应应用创建推送，进入待测试应用的推送通知界面：

依次填写通知标题和通知内容，点击发送按钮即可向该推送应用名下所有 CID 推送通知消息。具体推送操作方法详见：创建推送通知，下拉通知栏，如果手机或模拟器收到消息，那么恭喜您，个推 SDK 接入测试已经成功完成！

8. 常见问题

如果无法获取cid，建议调用PushManager.getInstance().checkManifest()接口检查集成结果！此接口会自动检测运行环境且只在debug状态下时才会工作，线上release版本不会被执行。

try {

PushManager.getInstance().checkManifest(this);

} catch (Exception e) {

e.printStackTrace();

}在logcat过滤GetuiPushException日志。若有集成问题会打印类似如下日志：

W/System.err: com.igexin.sdk.GetuiPushException: 自定义GTIntentService需配置BIND_JOB_SERVICE权限

W/System.err: at com.getui.demo.GetuiSdkDemoActivity.test(GetuiSdkDemoActivity.java:115)

W/System.err: at com.getui.demo.GetuiSdkDemoActivity.onCreate(GetuiSdkDemoActivity.java:25)更多详细信息可参考个推 SDK 集成 Demo，资料包中的路径如下：

GETUI_ANDROID_SDK/

|- Demo 工程/||- Getui_SDK_Demo_AS_maven/ (AndroidStudio 快速集成 Demo 工程)

更多问题详见 FAQ