• Android IM SDK 集成指南
    • 概要
      • Android SDK 版本
      • JMessage SDK压缩包内容简介
      • jcenter 自动集成步骤
      • 手动集成步骤
        • 解压SDK并导入
        • 配置 AndroidManifest.xml
        • 必须权限说明
        • 调试与初始化
        • 测试确认
        • 集成时注意
        • 如果之前集成过JMessage
        • 如果之前集成过JPush
      • JMessage混淆
      • IM场景代码样例
      • 技术支持

    Android IM SDK 集成指南

    概要

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

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

    • JMessage相关指南、API、教程等文档:极光IM文档
    • JMessage Android SDK下载地址:SDK下载页

    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">
    4. <application
    5. android:icon="@drawable/icon"
    6. android:name="com.example.jpushdemo.ExampleApplication"
    7. android:label="@string/app_name" >
    8. <service android:name="cn.jpush.android.service.PushService"
    9. android:process=":multiprocess"
    10. tools:node="replace" >
    11. ……
    12. </service>
    13. ……
    14. </application>
    15. ……
    16. </manifest>
    • 确认android studio的 Project 根目录的主 gradle 中配置了jcenter支持。(新建project默认配置就支持)
    1. buildscript {
    2. repositories {
    3. jcenter()
    4. }
    5. ......
    6. }
    7. allprojects {
    8. repositories {
    9. jcenter()
    10. }
    11. }
    • 在 module 的 gradle 中添加依赖和AndroidManifest的替换变量。
    1. android {
    2. ......
    3. defaultConfig {
    4. applicationId "com.xxx.xxx" //JPush上注册的包名.
    5. ......
    6. ndk {
    7. //选择要添加的对应cpu类型的.so库。
    8. abiFilters 'armeabi', 'armeabi-v7a', 'armeabi-v8a'
    9. // 还可以添加 'x86', 'x86_64', 'mips', 'mips64'
    10. }
    11. manifestPlaceholders = [
    12. JPUSH_PKGNAME : applicationId,
    13. JPUSH_APPKEY : "你的appkey", //JPush上注册的包名对应的appkey.
    14. JPUSH_CHANNEL : "developer-default", //暂时填写默认值即可.
    15. ]
    16. ......
    17. }
    18. ......
    19. }
    20. dependencies {
    21. ......
    22. compile 'cn.jiguang.sdk:jmessage:2.8.2' // 此处以JMessage 2.8.2 版本为例。
    23. compile 'cn.jiguang.sdk:jcore:1.2.7' // 此处以JCore 1.2.7 版本为例。
    24. ......
    25. }

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

    IM场景代码样例

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

    • 更换 Logo
    • 在 JPush Web 控制台上注册应用,获取到的appkey更新到 JChat 里
      JChat Android项目源代码开源在 Github 上,供大家下载参考。JChat Android 项目源代码地址

    技术支持

    邮件联系:support@jiguang.cn