JPush接入指南for Android

一． 接入須知：（JPush基本概念）

1. 消息形式

JPush提供四種消息形式：通知，自定義消息，富媒體和本地通知。

a. 通知

或者說 Push Notification，即指在手機的通知欄（狀態欄）上會顯示的一條通知信息。
通知主要用於提示用戶的目的，應用於新聞內容、促銷活動、產品信息、版本更新提醒、訂單狀態提醒等多種場景
開發者參考文檔：Push API v3 notification

b. 自定義消息

自定義消息不是通知，所以不會被SDK展示到通知欄上。其內容完全由開發者自己定義。
自定義消息主要用於應用的內部業務邏輯。一條自定義消息推送過來，有可能沒有任何界面顯示。
開發者參考文檔：Push API v3 message

c. 富媒體

JPush支持開發者發送圖文並茂的通知，從而更好的傳達信息，帶來更豐富的用戶互動。
JPush提供了5種模板，開發者可以通過填充模板的內容，發送landing page、彈窗、信息流形式的富媒體通知。
開發者還可以直接通過URL發送預先編輯好的頁面。
富媒體當前支持Android平台，為更好的使用富媒體的功能，建議更新當前SDK版本至v2.1.8及以上。
暫時只能通過極光推送的控制台發送，不支持API形式。
Android 開發者參考文檔：Rich Push開發指南

d. 本地通知

本地通知API不依賴於網絡，無網條件下依舊可以觸發；本地通知的定時時間是自發送時算起的，不受中間關機等操作的影響。
本地通知與網絡推送的通知是相互獨立的，不受保留最近通知條數上限的限制。
本地通知適用於在特定時間發出的通知，如一些Todo和鬧鐘類的應用，在每周、每月固定時間提醒用戶回到應用查看任務。
Android 開發者參考文檔：Android 本地通知
iOS 開發者參考文檔：iOS 本地通知

2. 推送目標

通過使用標簽，別名，Registration ID 和用戶分群，開發者可以向特定的一個或多個用戶推送消息。

a. 標簽

為安裝了應用程序的用戶打上標簽，其目的主要是方便開發者根據標簽，來批量下發 Push 消息。
可為每個用戶打多個標簽。
舉例： game, old_page, women

b. 別名

每個用戶只能指定一個別名。
同一個應用程序內，對不同的用戶，建議取不同的別名。這樣，盡可能根據別名來唯一確定用戶。
Android 開發者參考文檔：Android 標簽和別名
iOS 開發者參考文檔：iOS 標簽和別名
使用別名和標簽推送請參考文檔：Push API v3 Audience
c. 用戶分群
用戶分群的篩選條件有：標簽、地理位置、系統版本、注冊時間、活躍用戶和在線用戶。
比如，開發者可以設置這樣的用戶分群：位於北京、上海、廣州和深圳，並且最近7天在線的用戶。
開發者可以通過在控制台設置好用戶分群之後，在控制台推送時指定該分群的名稱或使用API調用該分群的id發送。
用戶分群控制台使用指南：用戶分群

二． 創建應用

1. 創建應用步驟:

創建應用 :

點擊［創建應用］按鈕即可;

配置應用信息：

Step1： 基本信息：輸入應用名稱 (必填), 上傳一個圖標；
配置android平台信息：填寫應用包名, JPush 系統會在後台根據你輸入的包名生成的推送的 Android 應用 Demo, 該 Demo 包含了該配置的信息;
Step2： 配置iOS平台信息：上傳相關環境的推送證書，並填寫和證書配套的密碼；
Step3： 配置WinPhone平台信息：選擇是否開啟即可；

Step4： 信息配置完成後，查看應用信息如下：

三． 應用管理

點擊［home］回到首頁，可浏覽所有應用的信息，點擊應用名稱或設置可查看應用詳情，點擊推送可去到發送通知頁，編輯並推送通知，點擊統計，可查看該應用的所有統計數據；

應用詳情如下

應用設置如下

四． 發送通知

路徑：選擇應用－>推送－>發送通知
填寫推送內容後點擊頁面最下方的［立即發送］按鈕即可；

Web界面會彈出對話框, 提示是否發送, 選［發送吧］即可;

推送成果後，彈出對話框，點擊［去看看］即可查看推送結果;

五． JPush Android SDK基本介紹

1. JPush Android

開發者集成 JPush Android SDK 到其應用裡，JPush Android SDK 創建到 JPush Cloud 的長連接，為 App 提供永遠在線的能力。
當開發者想要及時地推送消息到達 App 時，只需要調用 JPush API 推送，或者使用其他方便的智能推送工具，即可輕松與用戶交流。
圖中紅色部分，是 JPush 與 App 開發者的接觸點。手機客戶端側，App 需要集成 JPush SDK；服務器端部分，開發者調用 JPush REST API 來進行推送。

2. Android SDK 服務

JPush Android SDK 是作為 Android Service 長期運行在後台的，從而創建並保持長連接，保持永遠在線的能力。
多平台支持
JPush Android SDK 除了 jar 包，還有一個 .so 文件。.so 文件的存在 CPU 平台適配的問題。需要支持哪個平台的 CPU，就需要包含這個平台相應的 .so 編譯文件。
除支持默認的 ARM CPU 平台之外，JPush SDK 還提供 x86 與 MIPs 平台的 CPU 版本 SDK。請單獨到 資源下載 頁下載。
電量與流量
JPush Android SDK 由於使用自定義協議，協議體做得極致地小，流量消耗非常地小。
電量方面，JPush Android SDK 經過持續地優化，盡可能減少不必要的代碼執行；並且，長期的版本升級迭代，不斷地調優，在保證一定的網絡連接穩定性的要求小，減少電量消耗。
壓縮包說明
供下載的 JPush Android SDK 壓縮包，一般包含以下幾個部分：
? .jar 文件
? .so 文件
? AndroidManifest.xml 配置示例
其中 .jar, .so 文件有版本號後綴，需要互相匹配。請升級時一定記得檢查版本號，並刪除舊版本。
AndroidManifest.xml 配置示例可能在版本升級時，會有變更。請留意版本發布說明。

六． Android SDK 集成步奏

1. jpush-android-release-2.x.y.zip 集成壓縮包內容

? AndroidManifest_androidstudio_example.xml / AndroidManifest_eclipse_example.xml
o 客戶端嵌入SDK參考的配置文件
? libs/jpush-android-2.x.y.jar
o SDK Java 開發包
? libs/(cpu-type)/libjpush2xy.so
o 各種CPU類型的native開發包
? res
o 集成SDK必須添加的資源文件
? example
o 是一個完整的 Android 項目，通過這個演示了 JPush SDK 的基本用法，可以用來做參考。

2. Android SDK 版本

目前SDK只支持Android 2.3或以上版本的手機系統。富媒體信息流功能則需Android3.0或以上版本的系統。

3. jcenter 自動集成步驟

說明 ： 使用jcenter自動集成的開發者，不需要在項目中添加jar和so，jcenter會自動完成依賴；在AndroidManifest.xml中不需要添加任何JPush SDK 相關的配置，jcenter會自動導入, 如果手動添加則是以開發者添加的為准覆蓋掉默認配置。
? 確認android studio的 Project 根目錄的主 gradle 中配置了jcenter支持。（新建project默認配置就支持）
?

buildscript {
?       repositories {
?           jcenter()
?       }
?       ......
?   }
?   
?   allprojets {
?       repositories {
?           jcenter()
?       }
?   }
?   //在 module 的 gradle 中添加依賴和AndroidManifest的替換變量。
?   android {
?       ......
?       defaultConfig {
?           applicationId "com.xxx.xxx" //JPush上注冊的包名.
?           ......
?   
?           ndk {
?               //選擇要添加的對應cpu類型的.so庫。 
?               abiFilters 'armeabi', 'armeabi-v7a', 'armeabi-v8a' 
?               // 還可以添加 'x86', 'x86_64', 'mips', 'mips64'
?           }
?   
?           manifestPlaceholders = [
?               JPUSH_PKGNAME : applicationId,
?               JPUSH_APPKEY : "你的appkey", //JPush上注冊的包名對應的appkey.
?               JPUSH_CHANNEL : "developer-default", //暫時填寫默認值即可.
?           ]
?           ......
?       }
?       ......
?   }
?   
?   dependencis {
?       ......
?   
?       compile 'cn.jiguang:jpush:2.1.8'  // 此處以SDK 2.1.8版本為例
?   
?       ......
?   }

注 : 如果在添加以上 abiFilter 配置之後android Studio出現以下提示：
NDK integration is deprecated in the current plugin. Consider trying the new experimental plugin.
則在 Project 根目錄的gradle.properties文件中添加：
android.useDeprecatedNdk=true。

4. 手動集成步驟

? 解壓縮 jpush-android-release-2.x.y.zip 集成壓縮包。
? 復制 libs/jpush-sdk-2.x.y.jar 到工程 libs/ 目錄下。
? 復制 libs/(cpu-type)/libjpush2xy.so 到你的工程中存放對應cpu類型的目錄下。
? 復制 res/ 中drawable-hdpi, layout, values文件夾中的資源文件到你的工程中 res/ 對應的目錄下。
說明 1：若沒有res/drawable-xxxx/jpush_notification_icon這個資源默認使用應用圖標作為通知icon，在5.0以上系統將應用圖標作為statusbar icon可能顯示不正常，用戶可定義沒有陰影和漸變色的icon替換這個文件，文件名不要變。
說明 2：使用android studio的開發者，如果使用jniLibs文件夾導入so文件，則僅需將所有cpu類型的文件夾拷進去；如果將so文件添加在module的libs文件夾下，注意在module的gradle配置中添加一下配置：

 android {
        ......
        sourceSets {
            main {
                jniLibs.srcDirs = ['libs']
                ......
            }
            ......
        }
        ......
    }

5. 配置 AndroidManifest.xml

根據 SDK 壓縮包裡的 AndroidManifest.xml 樣例文件，來配置應用程序項目的 AndroidManifest.xml 。
主要步驟為：
? 復制備注為 “Required” 的部分
? 將備注為替換包名的部分，替換為當前應用程序的包名
? 將AppKey替換為在Portal上注冊該應用的的Key,例如（9fed5bcb7b9b87413678c407）
溫馨提示
如果使用android studio, 可在AndroidManifest中引用applicationId的值，在build.gradle配置中 defaultConfig節點下配置，如：

defaultConfig {
      applicationId "cn.jpush.example" // <--您應用的包名
      ……
 }

在AndroidManifest中使用 ${applicationId} 引用gradle中定義的包名
AndroidManifest 示例

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