Android IM SDK 集成指南

概要

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

本篇指南匹配的 JMessage Android SDK 版本为：2.0.0 及以后版本。

Android SDK 版本

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

JMessage SDK压缩包内容简介

  • demo/
    • 一个用来展示JMessage SDK接口基本用法的demo应用。
  • doc/
    • JMessage sdk中所包含所有对外接口的java doc。
  • libs/jcore-android_v1.X.Y.jar
    • 极光开发者服务的核心包。
  • libs/jmessage-android-2.X.Y.jar
    • JMessage SDK开发包
  • libs/(cpu-type)/libjcore1xy.so
    • 各种CPU类型的native开发包。

jcenter 自动集成步骤

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

  • 如果开发者需要修改组件属性，可以在本地的 AndroidManifest 中定义同名的组件并配置想要的属性，然后用 xmlns:tools 来控制本地组件覆盖 jcenter 上的组件。示例：
  1. <manifest xmlns:android="http://schemas.android.com/apk/res/android"
  2.     package="com.android.tests.flavorlib.app"
  3.     xmlns:tools="http://schemas.android.com/tools">
  5.     <application
  6.         android:icon="@drawable/icon"
  7.         android:name="com.example.jpushdemo.ExampleApplication"
  8.         android:label="@string/app_name" >
  10.         <service android:name="cn.jpush.android.service.PushService"
  11.             android:process=":multiprocess"
  12.             tools:node="replace" >
  14.             ……
  15.         </service>
  17.     ……
  18.   </application>
  20.   ……
  21. </manifest>
  • 确认android studio的 Project 根目录的主 gradle 中配置了jcenter支持。（新建project默认配置就支持）
  1. buildscript {
  2.     repositories {
  3.         jcenter()
  4.     }
  5.     ......
  6. }
  8. allprojects {
  9.     repositories {
  10.         jcenter()
  11.     }
  12. }
  • 在 module 的 gradle 中添加依赖和AndroidManifest的替换变量。
  1. android {
  2.     ......
  3.     defaultConfig {
  4.         applicationId "com.xxx.xxx" //JPush上注册的包名.
  5.         ......
  7.         ndk {
  8.             //选择要添加的对应cpu类型的.so库。
  9.             abiFilters 'armeabi', 'armeabi-v7a', 'armeabi-v8a'
  10.             // 还可以添加 'x86', 'x86_64', 'mips', 'mips64'
  11.         }
  13.         manifestPlaceholders = [
  14.             JPUSH_PKGNAME : applicationId,
  15.             JPUSH_APPKEY : "你的appkey", //JPush上注册的包名对应的appkey.
  16.             JPUSH_CHANNEL : "developer-default", //暂时填写默认值即可.
  17.         ]
  18.         ......
  19.     }
  20.     ......
  21. }
  23. dependencies {
  24.     ......
  26.     compile 'cn.jiguang.sdk:jmessage:2.8.2'  // 此处以JMessage 2.8.2 版本为例。
  27.     compile 'cn.jiguang.sdk:jcore:1.2.7'  // 此处以JCore 1.2.7 版本为例。
  28.     ......
  29. }

注 : 如果在添加以上 abiFilter 配置之后android Studio出现以下提示：

  1.     NDK integration is deprecated in the current plugin. Consider trying the new experimental plugin.

则在 Project 根目录的gradle.properties文件中添加：

  1.     android.useDeprecatedNdk=true

手动集成步骤

解压SDK并导入

  • 解压缩 jmessage-sdk-android-2.X.Y.zip 集成压缩包。
  • 复制 libs/jcore-android_v1.X.Y.jar 到工程 libs/ 目录下。
  • 复制 libs/jmessage-android_2.X.Y.jar 到工程 libs/ 目录下。
  • 复制 libs/(cpu-type)/libjcore1xy.so 到你的工程中存放对应cpu类型的目录下。
    说明 1：若没有 res/drawable-xxxx/jmessage_notification_icon 这个资源默认使用应用图标作为通知 icon，在 5.0 以上系统将应用图标作为 statusbar icon 可能显示不正常，用户可定义没有阴影和渐变色的 icon 替换这个文件，文件名不要变。

另外注意，上层应用在打包时如果开启了shrinkResources true压缩资源的功能，需要注意将jmessage_notification_icon加入到res/raw/keep.xml 文件的keep规则中去：

  1. <?xml version="1.0" encoding="utf-8"?>
  2. <resources xmlns:tools="http://schemas.android.com/tools"
  3.     tools:keep="@drawable/jmessage_notification_icon*"/>

说明 2：使用android studio的开发者，如果使用jniLibs文件夹导入so文件，则仅需将所有cpu类型的文件夹拷进去；如果将so文件添加在module的libs文件夹下，注意在module的gradle配置中添加一下配置：

  1.     android {
  2.         ......
  3.         sourceSets {
  4.             main {
  5.                 jniLibs.srcDirs = ['libs']
  6.                 ......
  7.             }
  8.             ......
  9.         }
  10.         ......
  11.     }

配置 AndroidManifest.xml

根据 SDK 压缩包里demo中的 AndroidManifest.xml 样例文件，来配置应用程序项目的 AndroidManifest.xml 。

主要步骤为：

  • 复制备注为 "Required" 的部分
  • 将标注为“您应用的包名”的部分，替换为当前应用程序的包名
  • 将标注为“您应用的Appkey”的部分，替换为在Portal上注册该应用的的Key,例如：9fed5bcb7b9b87413678c407
    小帖士

如果使用android studio, 可在AndroidManifest中引用applicationId的值，在build.gradle配置中 defaultConfig节点下配置，如：

  1. defaultConfig {
  2.       applicationId "cn.jmessage.example" // <--您应用的包名
  3.       ……
  4.  }

在AndroidManifest中使用 ${applicationId} 引用gradle中定义的包名

AndroidManifest 示例

  1. <?xml version="1.0" encoding="utf-8"?>
  2. <manifest package="您自己的包名"
  3.           xmlns:android="http://schemas.android.com/apk/res/android"
  4.           android:versionCode="2"
  5.           android:versionName="1.0.1">
  7.     <permission
  8.         android:name="您自己的包名.permission.JPUSH_MESSAGE"
  9.         android:protectionLevel="signature"/>
  11.     <!-- Required -->
  12.     <uses-permission android:name="您自己的包名.permission.JPUSH_MESSAGE" />
  13.     <uses-permission android:name="android.permission.RECEIVE_USER_PRESENT" />
  14.     <uses-permission android:name="android.permission.INTERNET" />
  15.     <uses-permission android:name="android.permission.WAKE_LOCK" />
  16.     <uses-permission android:name="android.permission.READ_PHONE_STATE" />
  17.     <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
  18.     <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
  19.     <uses-permission android:name="android.permission.VIBRATE" />
  20.     <uses-permission android:name="android.permission.MOUNT_UNMOUNT_FILESYSTEMS" />
  21.     <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
  22.     <uses-permission android:name="android.permission.WRITE_SETTINGS" />
  23.     <uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
  26.     <!-- Optional. Required for location feature -->
  27.     <uses-permission android:name="android.permission.SYSTEM_ALERT_WINDOW" />
  28.     <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
  29.     <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
  30.     <uses-permission android:name="android.permission.ACCESS_LOCATION_EXTRA_COMMANDS" />
  31.     <uses-permission android:name="android.permission.CHANGE_WIFI_STATE" />
  32.     <uses-permission android:name="android.permission.CHANGE_NETWORK_STATE" />
  33.     <uses-permission android:name="android.permission.GET_TASKS" />
  35.     <application
  36.         android:name="Your Application Name"
  37.         android:icon="@mipmap/ic_launcher"
  38.         android:label="@string/app_name">
  40.         <!-- Required SDK 核心功能-->
  41.         <!-- 可配置android:process参数将PushService放在其他进程中 -->
  42.         <service
  43.             android:name="cn.jpush.android.service.PushService"
  44.             android:enabled="true"
  45.             android:exported="false">
  46.             <intent-filter>
  47.                 <action android:name="cn.jpush.android.intent.REGISTER" />
  48.                 <action android:name="cn.jpush.android.intent.REPORT" />
  49.                 <action android:name="cn.jpush.android.intent.PushService" />
  50.                 <action android:name="cn.jpush.android.intent.PUSH_TIME" />
  51.             </intent-filter>
  52.         </service>
  54.         <!-- Required SDK核心功能-->
  55.         <receiver
  56.             android:name="cn.jpush.android.service.PushReceiver"
  57.             android:enabled="true"
  58.             android:exported="false">
  59.             <intent-filter android:priority="1000">
  60.                 <action android:name="cn.jpush.android.intent.NOTIFICATION_RECEIVED_PROXY" />
  61.                 <category android:name="您自己的包名" />
  62.             </intent-filter>
  63.             <intent-filter>
  64.                 <action android:name="android.intent.action.USER_PRESENT" />
  65.                 <action android:name="android.net.conn.CONNECTIVITY_CHANGE" />
  66.             </intent-filter>
  67.             <!-- Optional -->
  68.             <intent-filter>
  69.                 <action android:name="android.intent.action.PACKAGE_ADDED" />
  70.                 <action android:name="android.intent.action.PACKAGE_REMOVED" />
  72.                 <data android:scheme="package" />
  73.             </intent-filter>
  74.         </receiver>
  76.         <!-- Required SDK核心功能-->
  77.         <receiver
  78.             android:name="cn.jpush.android.service.AlarmReceiver"
  79.             android:exported="false" />
  81.         <!-- Required since JCore 1.1.7. SDK 核心功能-->
  82.         <provider
  83.             android:name="cn.jpush.android.service.DataProvider"
  84.             android:authorities="您自己的包名.DataProvider"
  85.             android:exported="false" />
  87.         <!-- Required since JMessage 2.7.0 SDK 核心功能-->
  88.         <provider
  89.             android:name="cn.jpush.im.android.helpers.ipc.IMProvider"
  90.             android:authorities="您自己的包名.IMProvider"
  91.             android:exported="false" />
  93.         <!-- Required JMessage SDK核心功能-->
  94.         <receiver
  95.             android:name="cn.jpush.im.android.helpers.IMReceiver"
  96.             android:enabled="true"
  97.             android:exported="false">
  98.         </receiver>
  100.         <!-- since JCore 1.8.0 option 可选项。用于同一设备中不同应用的 jiguang 服务相互拉起的功能。 -->
  101.         <!-- 若不启用该功能可删除该组件，或把 enabled 设置成 false ；拉起服务被关闭，App 不会通过拉起服务拉起其他的 App，也不会被其他 App 拉起。 -->
  102.          <service
  103.              android:name="cn.jpush.android.service.DaemonService"
  104.              android:enabled="true"
  105.              android:exported="true">
  106.              <intent-filter >
  107.                  <action android:name="cn.jpush.android.intent.DaemonService" />
  108.                  <category android:name="您应用的包名"/>
  109.              </intent-filter>
  110.          </service>
  112.         <!-- Required. For publish channel feature -->
  113.         <!-- JPUSH_CHANNEL 是为了方便开发者统计APK分发渠道。-->
  114.         <!-- 例如: -->
  115.         <!-- 发到 Google Play 的APK可以设置为 google-play; -->
  116.         <!-- 发到其他市场的 APK 可以设置为 xxx-market。 -->
  117.         <!-- 目前这个渠道统计功能的报表还未开放。-->
  118.         <meta-data
  119.             android:name="JPUSH_CHANNEL"
  120.             android:value="developer-default" />
  122.         <!-- Required. AppKey copied from Portal -->
  123.         <meta-data
  124.             android:name="JPUSH_APPKEY"
  125.             android:value="您自己的appkey" />
  128.     </application>
  130. </manifest>

必须权限说明

权限用途
Your Package.permission.JPUSH_MESSAGE官方定义的权限，允许应用接收JPUSH内部代码发送的广播消息。
RECEIVE_USER_PRESENT允许应用可以接收点亮屏幕或解锁广播。
INTERNET允许应用可以访问网络。
WAKE_LOCK允许应用在手机屏幕关闭后后台进程仍然运行
READ_PHONE_STATE允许应用访问手机状态。
WRITE_EXTERNAL_STORAGE允许应用写入外部存储。
READ_EXTERNAL_STORAGE允许应用读取外部存储。
WRITE_SETTINGS允许应用读写系统设置项。
VIBRATE允许应用震动。
MOUNT_UNMOUNT_FILESYSTEMS允许应用挂载/卸载 外部文件系统。
ACCESS_NETWORK_STATE允许应用获取网络信息状态，如当前的网络连接是否有效。

调试与初始化

基础API

  • setDebugMode 设置调试模式
  1. // You can enable debug mode in developing state. You should close debug mode when release.
  2. JMessageClient.setDebugMode(boolean debugEnalbed)
  • init 初始化SDK
  1. JMessageClient.init(Context context)

调用示例代码（参考 example 项目）

  • init 只需要在应用程序启动时调用一次即可。

  • 以下代码定制一个本应用程序 Application 类。需要在 AndoridManifest.xml 里配置。请参考上面 AndroidManifest.xml 片断，或者 demo 项目。

  1. public class IMDebugApplication extends Application {
  2. @Override
  3.     public void onCreate() {
  4.         super.onCreate();
  5.         JMessageClient.setDebugMode(true);
  6.         JMessageClient.init(this);
  7.     }
  8. }

测试确认

  • 确认所需的权限都已经添加。如果必须的权限未添加，日志会提示错误。
  • 确认 AppKey（在Portal上生成的）已经正确的写入 Androidmanifest.xml 。
  • 确认在程序启动时候调用了init(context) 接口
  • 确认测试手机（或者模拟器）已成功连入网络 ＋ 客户端调用 init 后不久，如果一切正常，应有长连接登陆成功的日志信息,日志信息会如下:
  1. [JMessageClient] JMessage SDK init finished!
  3. .......
  5. [ConnectingHelper] Login succeed!

如图所示，客户端启动分为 4 步：

  • 检查 metadata 的 appKey 和 channel ，如果不存在，则启动失败
  • 初始化 JMessage SDK，检查 JNI 等库文件的有效性，如果库文件无效，则启动失败
  • 检查 Androidmanifest.xml，如果有 Required 的权限不存在，则启动失败
  • 连接服务器登录，如果存在网络问题，则长连接登陆失败,或者前面三步有问题，不会启动JMessage SDK

集成时注意

因为从JMessage 2.0.0版本开始jar包的结构和之前发生了一些变化， 集成时有一些注意事项开发者需要注意

如果之前集成过JMessage

对于集成过JMessage 2.0.0以前版本的开发者,之前的JMessage是包含了Push的完整功能的，所以仅需要集成JMessage一个包就能同时拥有JMessage和JPush的完整功能。

而新的JMessage 2.0.0将不再包含JPush的功能。JMessage和JPush今后将会作为两个相对独立的模块需要分别集成。所以对于之前已经集成过JMessage（2.0.0版本以前）的开发者，将JMessage升级到2.0.0之后，如果还需要使用JPush相关功能，请参照JPush3.0.0的集成文档将JPush集成进项目。

基于JMessage手动集成JPush时注意事项：

  • 版本要求：对应的JCore需要1.1.0或以上版本，JPush需要3.0.0或以上版本。
  • jcore的替换：下载下来的JPush SDK zip包中同样包含了名为jcore-android_v1.X.Y的jar包,集成时需要注意项目中只保留一个jcore的jar就好，如果出现JPush和JMessage中所包含的jcore jar包版本不一致的情况，则保留版本号更新的那一个。so文件同理。

  • Manifest的配置：关于manifest中必要组件的配置，因为JMessage和JPush的manifest示例中包含了一部分公共的组件配置，对于已经集成JMessage 2.0.0（及以上）的开发者，仅需要将其中JPush部分的组件配置复制过来就好，包括（但不仅限以下组件，可能根据JPush之后版本变化而有不同，具体请参考JPush3.0.0的集成文档）：

    • cn.jpush.android.service.DaemonService
    • cn.jpush.android.ui.PushActivity
    • cn.jpush.android.service.DownloadService
    • cn.jpush.android.ui.PopWinActivity
    • JPush用户的自定义广播接收器（需要的话）

  • 别忘了添加JPush SDK中的res资源

  • 加上JPush的初始化代码：JPushInterface.init(context)

如果之前集成过JPush

对于已经集成了JPush 3.0.0或以上版本的开发者，如果需要IM功能，直接参照上面"jcenter自动集成步骤"或“手动集成步骤”一节配置JMessage就好，其中有以下几项需要注意：

基于JPush手动集成JMessage时注意事项：

  • 版本要求：JCore需要1.1.0或以上版本，对应的JMessage需要2.0.0或以上版本。
  • jcore的替换：下载下来的JMessage SDK zip包中同样包含了名为jcore-android_v1.X.Y的jar包,集成时需要注意项目中只保留一个jcore的jar就好，如果出现JPush和JMessage中所包含的jcore jar包版本不一致的情况，则保留版本号更新的那一个。so文件同理

  • Manifest的配置：因为JMessage和JPush的manifest示例中包含了一部分公共的组件配置，对于已经集成JPush 3.0.0（及以上）的开发者，仅需要将其中JMessage部分的组件配置复制过来就好，包括（但不仅限以下组件，可能根据JMessage之后版本变化而有改动，具体参照上文中的“AndroidManifest 示例”)

    • cn.jpush.im.android.helpers.IMReceiver
  • 加上JMessage的初始化代码：JMessageClient.init(context)

JMessage混淆

  • 请在工程的混淆文件中添加以下配置：
  1. -dontoptimize
  2. -dontpreverify
  3. -keepattributes  EnclosingMethod,Signature
  4. -dontwarn cn.jpush.**
  5. -keep class cn.jpush.** { *; }
  7. -dontwarn cn.jiguang.**
  8. -keep class cn.jiguang.** { *; }
  10. -dontwarn cn.jmessage.**
  11. -keep class cn.jmessage.**{ *; }
  13. -keepclassmembers class ** {
  14.     public void onEvent*(**);
  15. }
  17. #========================gson================================
  18. -dontwarn com.google.**
  19. -keep class com.google.gson.** {*;}
  21. #========================protobuf================================
  22. -keep class com.google.protobuf.** {*;}

IM场景代码样例

极光 JMessage 提供了一个完整的IM场景下的应用JChat，可以认为它就是一个 IM App。如果你的 App 需求只是 IM 功能，做以下两个变更就可以把它变成你自己的 IM App 了：

技术支持

邮件联系：support@jiguang.cn