Android消息推送 SDK 集成指南

使用提示

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

匹配的 SDK 版本为：r1.8.0及以后版本。

本文随SDK压缩包分发。在你看到本文时，可能当前的版本与本文已经不是很适配。所以建议关注在线文档：

• 3 分钟快速 Demo（Android）：如果您想要快速地测试、感受下极光推送的效果，请参考本文在几分钟内跑通Demo。
• 极光推送文档网站上，有极光推送相关的所有指南、API、教程等全部的文档。包括本文档的更新版本，都会及时地发布到该网站上。
• 极光推送问答网站：大家除了文档之外，还有问题与疑问，会到这里来提问题，以及时地得到解答。
• 如果您看到本文档，但还未下载Android SDK，请访问SDK下载页面下载。

产品功能说明

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

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

主要功能

• 保持与服务器的长连接，以便消息能够即时推送到达客户端
• 接收通知与自定义消息，并向开发者App 传递相关信息

主要特点

• 客户端维持连接占用资源少、耗电低
• SDK丰富的接口，可定制通知栏提示样式
• 服务器大容量、稳定

jpush-sdk_v1.x.y.zip 集成压缩包内容

• AndoridManifest.xml
  • 客户端嵌入SDK参考的配置文件
• libs/jpush-sdk-release1.x.y.jar
  • SDK Java 开发包
• libs/armeabi/libjpush.so
  • SDK native 开发包
• res
  • 集成SDK必须添加的资源文件
• example
  • 是一个完整的 Android 项目，通过这个演示了 JPush SDK 的基本用法，可以用来做参考。

Android SDK 版本

目前SDK只支持Android 2.1或以上版本的手机系统。富媒体信息流功能则需Android3.0或以上版本的系统。

SDK集成步骤

1、导入 SDK 开发包到你自己的应用程序项目

• 解压缩 jpush-sdk_v1.x.y.zip 集成压缩包
• 复制 libs/jpush-sdk-release1.x.y.jar 到工程 libs/ 目录下
• 复制 libs/armeabi/libjpush1xy.so 到工程 libs/armeabi 目录下
• 复制 libs/armeabi-v7a/libjpush.so 到工程 libs/armeabi-v7a 目录下

如果您的项目有 libs/armeabi-v7a 这个目录，请把 libs/armeabi-v7a下的so文件 也复制一份到这个目录。

• 复制 res/drawable-hdpi 中的资源文件到工程的 res/drawable-hdpi/ 目录下
• 复制 res/layout 中的布局文件到工程的 res/layout/ 目录下

2、配置 AndroidManifest.xml

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

主要步骤为：

• 复制备注为 "Required" 的部分
• 将备注为替换包名的部分，替换为当前应用程序的包名
• 将AppKey替换为在Portal上注册该应用的的Key,例如（9fed5bcb7b9b87413678c407）

AndroidManifest.xml权限配置：
<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="Your Package"
    android:versionCode="100"
    android:versionName="1.0.0"
    >
    <uses-sdk android:minSdkVersion="11" android:targetSdkVersion="17" />

    <!-- Required -->
    <permission android:name="Your Package.permission.JPUSH_MESSAGE" android:protectionLevel="signature" />

    <!-- Required -->
    <uses-permission android:name="You Package.permission.JPUSH_MESSAGE" />
    <uses-permission android:name="android.permission.RECEIVE_USER_PRESENT" />
    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.WAKE_LOCK" />
    <uses-permission android:name="android.permission.READ_PHONE_STATE" />
    <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
    <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
    <uses-permission android:name="android.permission.VIBRATE" />
    <uses-permission android:name="android.permission.MOUNT_UNMOUNT_FILESYSTEMS" />
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
    <uses-permission android:name="android.permission.WRITE_SETTINGS" /> 

    <!-- Optional. Required for location feature -->
    <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
    <uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
    <uses-permission android:name="android.permission.CHANGE_WIFI_STATE" />
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
    <uses-permission android:name="android.permission.ACCESS_LOCATION_EXTRA_COMMANDS" />
    <uses-permission android:name="android.permission.CHANGE_NETWORK_STATE" />

应用包名及appkey替换：
    <application
        android:icon="@drawable/ic_launcher"
        android:label="@string/app_name"
        android:name="Your Application">

        <!-- Required -->
        <service
            android:name="cn.jpush.android.service.PushService"
            android:enabled="true"
            android:exported="false" >
            <intent-filter>
                <action android:name="cn.jpush.android.intent.REGISTER" />
                <action android:name="cn.jpush.android.intent.REPORT" />
                <action android:name="cn.jpush.android.intent.PushService" />
                <action android:name="cn.jpush.android.intent.PUSH_TIME" />
            </intent-filter>
        </service>

        <!-- Required SDK 核心功能-->
         <!-- since 1.8.0 -->
         <service
             android:name="cn.jpush.android.service.DaemonService"
             android:enabled="true"
             android:exported="true">
             <intent-filter >
                 <action android:name="cn.jpush.android.intent.DaemonService" />
                 <category android:name="Your Package"/>
             </intent-filter>
         </service>

        <!-- Required -->
        <receiver
            android:name="cn.jpush.android.service.PushReceiver"
            android:enabled="true" >
          <intent-filter android:priority="1000">
                <action android:name="cn.jpush.android.intent.NOTIFICATION_RECEIVED_PROXY" />
                <category android:name="Your Package"/>
            </intent-filter>
            <intent-filter>
                <action android:name="android.intent.action.USER_PRESENT" />
                <action android:name="android.net.conn.CONNECTIVITY_CHANGE" />
            </intent-filter>
            <!-- Optional -->
            <intent-filter>
                <action android:name="android.intent.action.PACKAGE_ADDED" />
                <action android:name="android.intent.action.PACKAGE_REMOVED" />
                <data android:scheme="package" />
            </intent-filter>
        </receiver>
     <!-- Required SDK核心功能-->
        <activity
            android:name="cn.jpush.android.ui.PushActivity"
            android:configChanges="orientation|keyboardHidden"
            android:exported="false" >
            <intent-filter>
                <action android:name="cn.jpush.android.ui.PushActivity" />
                <category android:name="android.intent.category.DEFAULT" />
                <category android:name="Your Package" />
            </intent-filter>
        </activity>
        <!-- Required SDK核心功能-->
        <service
            android:name="cn.jpush.android.service.DownloadService"
            android:enabled="true"
            android:exported="false" >
        </service>
        <!-- Required SDK核心功能-->
        <receiver android:name="cn.jpush.android.service.AlarmReceiver" />

        <!-- User defined. 用户自定义的广播接收器-->
         <receiver
             android:name="您自己定义的Receiver"
             android:enabled="true">
             <intent-filter>
                 <!--Required 用户注册SDK的intent-->
                 <action android:name="cn.jpush.android.intent.REGISTRATION" />
                 <action android:name="cn.jpush.android.intent.UNREGISTRATION" />
                 <!--Required 用户接收SDK消息的intent-->
                 <action android:name="cn.jpush.android.intent.MESSAGE_RECEIVED" />
                 <!--Required 用户接收SDK通知栏信息的intent-->
                 <action android:name="cn.jpush.android.intent.NOTIFICATION_RECEIVED" />
                 <!--Required 用户打开自定义通知栏的intent-->
                 <action android:name="cn.jpush.android.intent.NOTIFICATION_OPENED" />
                 <!--Optional 用户接受Rich Push Javascript 回调函数的intent-->
                 <action android:name="cn.jpush.android.intent.ACTION_RICHPUSH_CALLBACK" />
                 <!-- 接收网络变化 连接/断开 since 1.6.3 -->
                 <action android:name="cn.jpush.android.intent.CONNECTION" />
                 <category android:name="您应用的包名" />
             </intent-filter>
         </receiver>

        <!-- Required. For publish channel feature -->
        <!-- JPUSH_CHANNEL 是为了方便开发者统计APK分发渠道。-->
        <!-- 例如: -->
        <!-- 发到 Google Play 的APK可以设置为 google-play; -->
        <!-- 发到其他市场的 APK 可以设置为 xxx-market。 -->
        <!-- 目前这个渠道统计功能的报表还未开放。-->
        <meta-data android:name="JPUSH_CHANNEL" android:value="developer-default"/>
        <!-- Required. AppKey copied from Portal -->
        <meta-data android:name="JPUSH_APPKEY" android:value="Your AppKey"/>
    </application>
</manifest>

3、必须权限说明

4、添加代码

JPush SDK 提供的 API 接口，都主要集中在 cn.jpush.android.api.JPushInterface 类里。

基础API

• init 初始化SDK

  public static void init(Context context)

• setDebugMode 设置调试模式

  // You can enable debug mode in developing state. You should close debug mode when release.
  public static void setDebugMode(boolean debugEnalbed)

添加统计代码

• 参考文档： 统计分析 API

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

• init 只需要在应用程序启动时调用一次该 API 即可。
• 以下代码定制一个本应用程序 Application 类。需要在 AndoridManifest.xml 里配置。请参考上面 AndroidManifest.xml 片断，或者 example 项目。

  public class ExampleApplication extends Application {
  @Override
          public void onCreate() {
              super.onCreate();
      JPushInterface.setDebugMode(true);
      JPushInterface.init(this);
      }
  }

5、测试确认

1. 确认所需的权限都已经添加。如果必须的权限未添加，日志会提示错误。
2. 确认 AppKey（在Portal上生成的）已经正确的写入 Androidmanifest.xml 。
3. 确认在程序启动时候调用了init(context) 接口
4. 确认测试手机（或者模拟器）已成功连入网络 ＋ 客户端调用 init 后不久，如果一切正常，应有登录成功的日志信息
5. 启动应用程序，在 Portal 上向应用程序发送自定义消息推送或者通知栏提示。详情请参考管理Portal。
   • 在几秒内，客户端应可收到下发的通知或者正定义消息 如果 SDK 工作正常，则日志信息会如下图所示：

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

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

从Eclipse工程导入到Android Studio

JPush Demo 是极光推送随压缩包提供的用法示例Demo，原本适用于Eclipse工程。本教程将指导JPush用户用最简单的方法将极光推送Demo导入Android Studio。

6.1 快速集成JPush

参考3 分钟快速 Demo（Android），把JPush跑起来。之后你在Eclipse包浏览器中有可运行的项目。

6.2 右键点击demo工程，选择Export

6.3 选择导出目标位Gradle build文件，并确认

6.4 从文件浏览器中检查

在Eclipse的workspace中，该Demo工程的文件夹中，生成了Gradle相关配置文件.

6.5 打开你的Android Studio工程，选择 File->Import Module

在Android Studio中，一次只能打开一个Project，它相当于Eclipse中的一个workspace。而我们从Eclipse中导出的一个Project，则相当于Android Studio中的一个Module。

6.6 选择Eclipse workspace下的Demo工程，并确认

6.7 查看导入的Module，并且gradle会自动生成编译选项

现在就可以将极光推送Demo作为Android Studio的Module运行在真机或虚拟机上，并调试了