2. Maven 集成(推荐)
。Getui_SDK_Demo_AS_official/
|- app/ (项目主模块)
| |- libs/ (第三方库)
| |- src/ (代码目录)
| |- build.gradle (模块级 gradle 文件)
|- gradle/
|- build.gradle (顶层 gradle 文件)
|- settings.gradle
| ......
注:其中 “......
” 表示省略其他与本教程无关的内容,以下 “......
” 表示相同意义,不再重复说明。android:usesCleartextTraffic="true"
; PushManager.getInstance().initialize(Context context)
接口即可完成 SDK 初始化, 个推 SDK 会自动去寻找相应的 PushService 和 GTIntentService,无需在代码中注册自定义的PushService
以及再次调用 PushManager.getInstance().registerPushIntentService(Context context, Class<T> userIntentService)
进行 IntentService 注册,详细步骤见本教程说明。建议替换原有的PushManager.getInstance().initialize(Context context, Class<T> userServiceName)
接口。PushManager.getInstance().stopService()
接口。PushManager.getInstance().initialize(Context context, Class<T> userServiceName)
、PushManager.getInstance().registerPushIntentService(Context context, Class<T> userIntentService)
接口。 PushManager.getInstance().initialize(Context context)
接口进行初始化,推荐使用该接口进行初始化。PushManager.getInstance().setDebugLogger(Context context, IUserLoggerInterface loggerInterface)
接口,用于调试日志输出。请参考 创建应用 获取相应的AppID
、AppKey
、AppSecret
信息。该信息在之后的步骤配置中将会使用。
注意:由手动集成切换到 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/"
}
}
}
配置 so 库:目前个推 SDK 支持 armeabi、armeabi-v7a、arm64-v8a、mips、mips64、x86、x86_64 这几种 CPU 架构,请根据项目情况指定所需的架构。
app/build.gradle
文件中的 android.defaultConfig
下指定所需的 CPU 架构,如下所示:defaultConfig {
ndk {
// 注意:这里需要添加项目所需 CPU 类型的最小集
abiFilters "armeabi", "armeabi-v7a", "x86_64", "x86"
}
}
......
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:sdk:${version}'
,此处的 ${version}
为对应的 SDK 版本号,并在android.defaultConfig
下添加 manifestPlaceholders
,配置个推相关的应用参数(参见【步骤 1】), 如下所示:
......
android {
defaultConfig {
manifestPlaceholders = [
//个推应用参数,请填写您申请的 GETUI_APP_ID,GETUI_APP_KEY,GETUI_APP_SECRET 值
GETUI_APP_ID : "",
GETUI_APP_KEY : "",
GETUI_APP_SECRET : "",
]
ndk {
// 添加项目所需 CPU 类型的最小集
abiFilters "armeabi", "armeabi-v7a", "x86_64", "x86"
}
}
......
}
dependencies {
implementation 'com.getui:sdk:${version}' //请将此处的 ${version} 替换成您当前相应的 SDK 版本号,如 2.14.2.0
}
上述接入方式已包含个推服务所需的所有必备权限。在此之外,您还可以配置以下可选权限,以便使用个推提供的电子围栏功能。请在AndroidManifest.xml
的<manifest>
根标签下添加如下配置:
<!-- iBeancon 功能所需权限 -->
<uses-permission android:name="android.permission.BLUETOOTH"/>
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN"/>
<!-- 个推电子围栏功能所需权限 -->
<uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
注意:若您尚未下载 SDK,请点击前往 下载 Android SDK。若选择 Maven 集成方式,可以跳过本小节。
打开下载的 SDK 资料包,资料包的详细结构如下:
GETUI_ANDROID_SDK/
|- readme.txt (SDK 相关文档链接、注意事项)
|- 资源文件/
| |- res/
| | |- raw
| | | |- keep.xml (用于资源保留的描述文件)
| |- so/ (各 CPU 架构 so 库)
| | |- arm64-v8a/
| | |- armeabi/
| | |- armeabi-v7a/
| | |- mips/
| | |- mips64/
| | |- x86/
| | |- x86_64/
| |- GetuiSDK-<version>.jar
| - Demo 工程/
| |- Getui_SDK_Demo_AS_maven/ (AndroidStudio 快速集成 Demo 工程)
| |- Getui_SDK_Demo_AS_official/ (AndroidStudio 标准集成 Demo 工程)
Demo 工程的 Getui_SDK_Demo_AS_official/
工程对应我们的手动集成项目,集成过程中可以参考该工程,资源文件/GetuiSDK-<version>.jar
为我们的个推 SDK jar 包,其中 <version>
为对应的 SDK 版本号,资料包的其他文件说明请见注释。
说明:在进行集成代码编写之前,我们需要先导入个推 SDK、个推 so 库。
注意:如果项目中包含的其他 so 库只支持其中某几种 CPU 架构,那么应该根据其他 so 库所支持的 CPU 架构的最小集来配置。否则如果在特定架构上未能支持所有 so 库,则很可能导致程序运行异常。切记!
详细步骤如下:
GETUI_ANDROID_SDK/
资源文件目录下的 GetuiSDK-<version>.jar
复制到 app
模块目录下的 libs
文件夹中。导入个推 so 库:将 SDK 资料包中 GETUI_ANDROID_SDK/资源文件/so
目录下所需 CPU 架构的目录拷贝到 app/src/main/jniLibs
目录下。目前个推 SDK 支持 armeabi、armeabi-v7a、arm64-v8a、mips、mips64、x86、x86_64 这几种 CPU 架构,请根据项目情况指定所需的架构。
app/src/main/jniLibs
以外的其他目录,请在 app/build.gradle
文件中的 android
段内正确设置 so 路径。假设 so 路径为 app/libs
,则需添加如下配置代码: ......
android{
sourceSets {
main {
jniLibs.srcDirs = ['libs']
}
}
}
......
最后完整的目录结构如下所示:
Getui_SDK_Demo_AS_official/
|- app/
| |- libs/
| |- GetuiSDK-<version>.jar
| |- src/
| |- main/
| |- jniLibs/
| |- armeabi/
| |- libgetuiext3.so
| |- armeabi-v7a/
| |- libgetuiext3.so
| |- x86_64/
| |- libgetuiext3.so
| |- x86/
| |- libgetuiext3.so
| ......
配置个推应用参数及依赖:在 app/build.gradle
文件中的 android.defaultConfig
块中添加 manifestPlaceholders
块,配置个推 SDK 相关的应用参数,并在 dependencies
块中添加 implementation fileTree(dir: 'libs', include: ['*.jar'])
依赖个推 SDK jar 文件(新工程创建的时候默认已包含该配置)。 如下所示:
......
android {
defaultConfig {
manifestPlaceholders = [
//个推应用参数,请填写您申请的 GETUI_APP_ID,GETUI_APP_KEY,GETUI_APP_SECRET 值
GETUI_APP_ID : "",
GETUI_APP_KEY : "",
GETUI_APP_SECRET : "",
]
}
......
}
dependencies {
implementation fileTree(dir: 'libs', include: ['*.jar'])
......
}
请根据【步骤 1】获取到的应用参数进行相应填写 GETUI_APP_ID、GETUI_APP_KEY、GETUI_APP_SECRET 的值。
在 Manifest 中配置个推 SDK 组件:请在AndroidManifest.xml
中<application>
标签内增加以下组件配置(由于使用了manifestPlaceholders
来做参数替换,因此以下配置无需手工修改,直接复制粘贴即可):
<!-- 个推 SDK 配置开始 -->
<!-- Android9.0 以上默认不支持 http 通信,为保证 SDK 正常使用,请在 application 节点下新增该属性 -->
<application android:usesCleartextTraffic="true">
<!-- 配置的第三方参数属性 -->
<meta-data
android:name="PUSH_APPID"
android:value="${GETUI_APP_ID}" />
<meta-data
android:name="PUSH_APPKEY"
android:value="${GETUI_APP_KEY}" />
<meta-data
android:name="PUSH_APPSECRET"
android:value="${GETUI_APP_SECRET}" />
<!-- 配置 SDK 核心服务 -->
<!-- permission 属性在 2.13.1.0 版本后必须配置 -->
<service
android:name="com.igexin.sdk.PushService"
android:permission="android.permission.BIND_JOB_SERVICE"
android:exported="false"
android:label="NotificationCenter"
android:process=":pushservice"/>
<receiver android:name="com.igexin.sdk.PushReceiver" >
<intent-filter>
<action android:name="android.intent.action.BOOT_COMPLETED" />
<action android:name="android.net.conn.CONNECTIVITY_CHANGE" />
<action android:name="android.intent.action.USER_PRESENT" />
<!-- 以下三项为可选的 action 声明,有助于提高 service 存活率 -->
<action android:name="android.intent.action.MEDIA_MOUNTED" />
<action android:name="android.intent.action.ACTION_POWER_CONNECTED" />
<action android:name="android.intent.action.ACTION_POWER_DISCONNECTED" />
</intent-filter>
</receiver>
<activity
android:name="com.igexin.sdk.PushActivity"
android:excludeFromRecents="true"
android:exported="false"
android:process=":pushservice"
android:taskAffinity="com.igexin.sdk.PushActivityTask"
android:theme="@android:style/Theme.Translucent.NoTitleBar" >
</activity>
<activity
android:name="com.igexin.sdk.GActivity"
android:excludeFromRecents="true"
android:exported="true"
android:process=":pushservice"
android:taskAffinity="com.igexin.sdk.PushActivityTask"
android:theme="@android:style/Theme.Translucent.NoTitleBar"/>
<!-- 个推 SDK 配置结束 -->
<manifest>
根标签下加入个推 SDK 所必需的权限,配置如下(由于使用了manifestPlaceholders
来做参数替换,因此以下配置无需手工修改,直接复制粘贴即可):
<!-- 个推 SDK 权限配置开始 -->
<!-- 必选权限 -->
<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.ACCESS_WIFI_STATE" />
<uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.VIBRATE" />
<uses-permission android:name="android.permission.GET_TASKS" />
<!-- 以下为可选权限 -->
<!-- 支持 iBeancon 需要蓝牙权限 -->
<uses-permission android:name="android.permission.BLUETOOTH" />
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />
<!-- 支持个推电子围栏功能 -->
<uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<!-- 自定义权限 -->
<uses-permission android:name="getui.permission.GetuiService.${applicationId}" />
<permission
android:name="getui.permission.GetuiService.${applicationId}"
android:protectionLevel="normal"/>
<!-- 个推 SDK 权限配置结束 -->
为了让推送服务在部分主流机型上更稳定运行,从 2.9.5.0 版本开始,个推支持第三方应用配置使用自定义 Service 来作为推送服务运行的载体。
在项目源码中添加一个继承自 com.igexin.sdk.PushService 的自定义 Service:
package com.getui.demo.service;
// 仅 2.13.1.0 及以上版本才能直接 extends PushService,低于此版本请延用之前实现方式
public class DemoPushService extends com.igexin.sdk.PushService {
}
在 AndroidManifest.xml
中添加上述自定义 Service,(使用 maven 集成,android:process
属性必须为 pushservice。手动集成方式也请保证与其他组件进程名一致,建议复制本文档的默认配置即可),如下:
<!-- 请根据您当前自定义的 PushService 名称路径进行配置-->
<service
android:name="com.getui.demo.service.DemoPushService"
android:exported="true"
android:label="PushService"
android:process=":pushservice"/>
设置通知栏及通知栏顶部图标:为了修改默认的通知图标以及通知栏顶部提示小图标,请务必在资源目录的 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
| ......
setLogo
方法指定通知栏图标的名称,例如 style.setLogo("push1.png")
来指定要切换展示的对应名称的通知图标(仅切换通知栏图标),详见 服务端推送模版。app/build.gradle
的android.buildTypes.release
下配置了minifyEnabled true
,为了避免个推 SDK 被错误混淆导致功能异常,需要在app/proguard-rules.pro
混淆配置文件中添加如下配置:-dontwarn com.igexin.**
-keep class com.igexin.** { *; }
如果您的工程启用了资源精简,即如果在 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
通知图标的名称应为您当前放着于应用中的图标名称,如下:
<?xml version="1.0" encoding="utf-8"?>
<resources
xmlns:tools="http://schemas.android.com/tools"
tools:keep="......,
@drawable/push,
@drawable/push_small"/>
<!-- 若您需要使用其他自定义推送图标,也需要在此处添加 -->
如果您的工程使用了 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
文件中的
<issue id="whitelist" isactive="true">
<path value="<your_package_name>.R.drawable.push"/>
<path value="<your_package_name>.R.drawable.push_small"/>
<!-- 若您需要使用其他自定义推送图标,也需要在此处添加,此处的 R.drawable.push,R.drawable.push_small 应为您当前放置的推送图标。 -->
</issue>
初始化 SDK
com.igexin.sdk.PushManager.getInstance().initialize(Context context)
进行 SDK 的初始化。我们建议开发者在 Application.onCreate()
和主 Activity.onCreate()
方法中初始化个推 SDK。多次调用 SDK 初始化并无影响。为了保证 SDK 服务稳定,推荐引导用户授权相关的隐私权限。自定义接收推送服务事件
在项目源码中添加一个继承自 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 类,如下:
<service
android:name="com.getui.demo.service.DemoIntentService"
android:permission="android.permission.BIND_JOB_SERVICE"/>
查看调试日志信息
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 = 2.14.0.0
[GT-PUSH] [PushManager]call registerPushIntentService
[GT-PUSH] onHandleIntent() = get sdk service pid
[GT-PUSH] ServiceManager start from initialize...
[GT-PUSH] load so = getuiext3 by system success
[GT-PUSH] Start login appid = TI85ilD*******L89MFNV appkey = 1qNlp*******BP9COgYjA
[GT-PUSH] Login successed with cid = e3f004e873f9a5d9e2e006c4a9ca2f5f
[GT-PUSH] onHandleIntent() = received client id
注意: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.
这样的提示请调整调用时间间隔。
测试推送功能
PushManager.getInstance().checkManifest()
接口检查集成结果!此接口会自动检测运行环境且只在debug状态下时才会工作,线上release版本不会被执行。 try {
PushManager.getInstance().checkManifest(this);
} catch (Exception e) {
e.printStackTrace();
}
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)
GETUI_ANDROID_SDK/
| - Demo 工程/
| |- Getui_SDK_Demo_AS_maven/ (AndroidStudio 快速集成 Demo 工程)
| |- Getui_SDK_Demo_AS_official/ (AndroidStudio 标准集成 Demo 工程)
更多问题详见 FAQ