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集成步驟

一、導入 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/ 目錄下

二、配置 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>

三、必須權限說明

權限	用途
You 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	容許應用獲取網絡信息狀態，如當前的網絡鏈接是否有效。
SYSTEM_ALERT_WINDOW	容許應用顯示系統窗口，位於顯示的頂層。

四、添加代碼

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); } }

五、測試確認

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運行在真機或虛擬機上，並調試了