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、必須許可權說明

許可權	用途
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	允許應用顯示系統視窗，位於顯示的頂層。

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

Android訊息推送 SDK 整合指南