Android SDK 集成指南

Android SDK 集成指南
本文是JPush Android SDK 标准的集成指南文档。

用以指导SDK 的使用方法，默认读者已经熟悉IDE（Eclipse 或者Android Studio）的基本使用方法，以及具有一定的Android 编程知识基础。

本篇指南匹配的JPush Android SDK 版本为：v3.0.0 及以后版本。

∙ 3 分钟快速Demo（Android）：如果您想要快速地测试、感受下极光推送的效果，请参考本文在几分钟内跑通Demo。

∙极光推送文档网站上，有极光推送相关的所有指南、API、教程等全部的文档。

包括本文档的更新版本，都会及时地发布到该网站上。

∙如果您看到本文档，但还未下载Android SDK，请访问SDK下载页面下载。

极光推送（JPush）是一个端到端的推送服务，使得服务器端消息能够及时地推送到终端用户手机上，让开发者积极地保持与用户的连接，从而提高用户活跃度、提高应用的留存率。

极光推送客户端支持Android, iOS 两个平台。

本Android SDK 方便开发者基于JPush 来快捷地为Android App 增加推送功能。

主要功能
∙保持与服务器的长连接，以便消息能够即时推送到达客户端
∙接收通知与自定义消息，并向开发者App 传递相关信息
主要特点
∙客户端维持连接占用资源少、耗电低
∙SDK丰富的接口，可定制通知栏提示样式
∙服务器大容量、稳定
jpush-android-release-3.x.y.zip 集成压缩包内容
∙AndroidManifest.xml
o客户端嵌入SDK参考的配置文件
∙libs/jcore-android.v1.x.y.jar
o极光开发者服务的核心包。

∙libs/jpush-android_v3.x.y.jar
o JPush SDK 开发包。

∙libs/(cpu-type)/libjcore1xy.so
o各种CPU类型的native开发包。

∙res
o集成SDK必须添加的资源文件
∙example
o是一个完整的Android 项目，通过这个演示了JPush SDK 的基本用法，可以用来做参考。

Android SDK 版本
目前SDK只支持Android 2.3或以上版本的手机系统。

富媒体信息流功能则需Android3.0或以上版本的系统。

说明：使用jcenter自动集成的开发者，不需要在项目中添加jar和so，jcenter 会自动完成依赖；在AndroidManifest.xml中不需要添加任何JPush SDK 相关的配置，jcenter会自动导入。

∙如果开发者需要修改组件属性，可以在本地的AndroidManifest 中定义同名的组件并配置想要的属性，然后用xmlns:tools 来控制本地组件覆盖jcenter 上的组件。

示例：
∙臧廷杰整理
∙确认android studio的Project 根目录的主gradle 中配置了jcenter 支持。

（新建project默认配置就支持）
∙在module 的gradle 中添加依赖和AndroidManifest的替换变量。

注 : 如果在添加以上abiFilter 配置之后android Studio出现以下提示：
则在Project 根目录的gradle.properties文件中添加：
说明：若没有res/drawable-xxxx/jpush_notification_icon这个资源默认使用应用图标作为通知icon，在5.0以上系统将应用图标作为statusbar icon可能显示不正常，用户可定义没有阴影和渐变色的icon替换这个文件，文件名不要变。

∙解压缩jpush-android-release-3.x.y.zip 集成压缩包。

∙复制libs/jcore-android_v1.x.y.jar 到工程libs/ 目录下。

∙复制libs/jpush-android_v3.x.y.jar 到工程libs/ 目录下。

∙复制libs/(cpu-type)/libjcore1xy.so 到你的工程中存放对应cpu类型的目录下。

∙复制res/ 中drawable-hdpi, layout, values文件夹中的资源文件到你的工程中res/ 对应同名的目录下。

说明1：若没有res/drawable-xxxx/jpush_notification_icon这个资源默认使用应用图标作为通知icon，在5.0以上系统将应用图标作为statusbar icon可能显示不正常，用户可定义没有阴影和渐变色的icon替换这个文件，文件名不要变。

说明2：使用android studio的开发者，如果使用jniLibs文件夹导入so文件，则仅需将所有cpu类型的文件夹拷进去；如果将so文件添加在module的libs 文件夹下，注意在module的gradle配置中添加一下配置：
配置AndroidManifest.xml
根据SDK 压缩包里的AndroidManifest.xml 样例文件，来配置应用程序项目的AndroidManifest.xml 。

主要步骤为：
∙复制备注为"Required" 的部分
∙将标注为“您应用的包名”的部分，替换为当前应用程序的包名
∙将标注为“您应用的Appkey”的部分，替换为在Portal上注册该应用的的Key,例如：9fed5bcb7b9b87413678c407
小帖士
如果使用android studio, 可在AndroidManifest中引用applicationId的值，在build.gradle配置中defaultConfig节点下配置，如：
在AndroidManifest中使用${applicationId} 引用gradle中定义的包名AndroidManifest 示例
必须权限说明
集成JPush Android SDK 的混淆
∙请下载4.x及以上版本的proguard.jar，并替换你Android Sdk "tools\proguard\lib\proguard.jar"
∙请在工程的混淆文件中添加以下配置：
∙v2.0.5 ~ v2.1.7 版本有引入gson 和protobuf ，增加排除混淆的配置。

(2.1.8版本不需配置)
添加代码
JPush SDK 提供的API 接口，都主要集中在
cn.jpush.android.api.JPushInterface 类里。

基础API
∙init 初始化SDK
∙setDebugMode 设置调试模式
注：该接口需在init接口之前调用，避免出现部分日志没打印的情况。

多进程情况下建议在自定义的Application中onCreate中调用。

添加统计代码
调用示例代码（参考example 项目）
∙init 只需要在应用程序启动时调用一次该API 即可。

∙以下代码定制一个本应用程序Application 类。

需要在
AndoridManifest.xml 里配置。

请参考上面AndroidManifest.xml 片断，或者example 项目。

测试确认
∙确认所需的权限都已经添加。

如果必须的权限未添加，日志会提示错误。

∙确认AppKey（在Portal上生成的）已经正确的写入
Androidmanifest.xml 。

∙确认在程序启动时候调用了init(context) 接口
∙确认测试手机（或者模拟器）已成功连入网络＋客户端调用init 后不久，如果一切正常，应有登录成功的日志信息
∙启动应用程序，在Portal 上向应用程序发送自定义消息或者通知栏提示。

详情请参考管理Portal。

o在几秒内，客户端应可收到下发的通知或者正定义消息，如果SDK 工作正常，则日志信息会如下：
如图所示，客户端启动分为 4 步：
∙检查metadata 的appKey 和channel ，如果不存在，则启动失败∙初始化JPush SDK，检查JNI 等库文件的有效性，如果库文件无效，则启动失败
∙检查Androidmanifest.xml，如果有Required 的权限不存在，则启动失败
∙连接服务器登录，如果存在网络问题，则登陆失败,或者前面三步有问题，不会启动JPush SDK。