騰訊信鴿推送Android SDK快速指南

信鴿Android SDK是一個可以提供Push服務的開發平臺，提供給開發者簡便、易用的API接口，方便快速接入。
目前支持Android 2.2及以上版本系統。

本文檔將引導用戶以最快的速度嵌入信鴿SDK。
註冊&下載SDK

前往前臺 信鴿首頁，使用QQ號碼登錄，打開註冊頁面，填寫「應用名稱」和「應用包名」（必需要跟APP一致），選擇「操做系統」和「分類」，最後點擊「建立應用」。
應用建立成功後，點擊「應用配置」便可看到APP專屬的AccessId和AccessKey等信息。
10min demo regi.png

註冊完成後，請下載最新版本的Android SDK到本地，並解壓。
工程配置

以eclipse爲開發的IDE爲例，將SDK導入到工程的步驟爲：
一、建立或打開Android工程（關於如何建立Android工程，請參照開發環境的章節）。
二、將信鴿 SDK目錄下的libs目錄全部文件拷貝到工程的libs（或lib）目錄下。
三、選中libs（或lib）目錄下的信鴿jar包，右鍵菜單中選擇Build Path， 選擇Add to Build Path將SDK添加到工程的引用目錄中。
四、打開Androidmanifest.xml，添加如下配置（建議參考下載包的Demo修改），其中YOUR_ACCESS_ID和YOUR_ACCESS_KEY替換爲APP對應的accessId和accessKey,請確保按照要求配置，不然可能致使服務不能正常使用。

<application
   <!-- APP項目的其它配置... -->

   <!-- 【必須】 信鴿receiver廣播接收 -->
    <receiver
        android:name="com.tencent.android.tpush.XGPushReceiver"
        android:process=":xg_service_v2" >
        <intent-filter android:priority="0x7fffffff" >
            <!-- 【必須】 信鴿SDK的內部廣播 -->
            <action android:name="com.tencent.android.tpush.action.SDK" />
            <action android:name="com.tencent.android.tpush.action.INTERNAL_PUSH_MESSAGE" />
            <!-- 【必須】 系統廣播：開屏和網絡切換 -->
            <action android:name="android.intent.action.USER_PRESENT" />
            <action android:name="android.net.conn.CONNECTIVITY_CHANGE" />
            
            <!-- 【可選】 一些經常使用的系統廣播，加強信鴿service的復活機會，請根據須要選擇。固然，你也能夠添加APP自定義的一些廣播讓啓動service -->
            <action android:name="android.bluetooth.adapter.action.STATE_CHANGED" />
            <action android:name="android.intent.action.ACTION_POWER_CONNECTED" />
            <action android:name="android.intent.action.ACTION_POWER_DISCONNECTED" />
        </intent-filter>
    </receiver>

    <!-- 【必須】 (2.30及以上版新增)展現通知的activity -->
    <!-- 【注意】 若是被打開的activity是啓動模式爲SingleTop，SingleTask或SingleInstance，請根據通知的異常自查列表第8點處理-->
     <activity
         android:name="com.tencent.android.tpush.XGPushActivity"
         android:exported="true" >
         <intent-filter>
            <!-- 若使用AndroidStudio，請設置android:name="android.intent.action"-->
             <action android:name="" />
         </intent-filter>
    </activity>

    <!-- 【必須】 信鴿service -->
    <service
        android:name="com.tencent.android.tpush.service.XGPushService"
        android:exported="true"
        android:persistent="true"
        android:process=":xg_service_v2" />
 
    <!-- 【必須】 通知service，此選項有助於提升抵達率 -->
    <service
        android:name="com.tencent.android.tpush.rpc.XGRemoteService"
        android:exported="true" >
        <intent-filter>
            <action android:name="應用包名.PUSH_ACTION" />
        </intent-filter>
    </service>

    <!-- 【必須】 請將YOUR_ACCESS_ID修改成APP的AccessId，「21」開頭的10位數字，中間沒空格 -->
    <meta-data
        android:name="XG_V2_ACCESS_ID"
        android:value="YOUR_ACCESS_ID" />
    <!-- 【必須】 請將YOUR_ACCESS_KEY修改成APP的AccessKey，「A」開頭的12位字符串，中間沒空格 -->
    <meta-data
        android:name="XG_V2_ACCESS_KEY"
        android:value="YOUR_ACCESS_KEY" />
</application>

<!-- 【必須】 信鴿SDK所需權限 -->
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.READ_PHONE_STATE" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED" />
<uses-permission android:name="android.permission.RESTART_PACKAGES" />
<uses-permission android:name="android.permission.BROADCAST_STICKY" />
<uses-permission android:name="android.permission.WRITE_SETTINGS" />
<uses-permission android:name="android.permission.RECEIVE_USER_PRESENT" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.WAKE_LOCK" />
<uses-permission android:name="android.permission.KILL_BACKGROUND_PROCESSES" />
<uses-permission android:name="android.permission.GET_TASKS" />
<uses-permission android:name="android.permission.READ_LOGS" />
<uses-permission android:name="android.permission.VIBRATE" />
<!-- 【可選】 信鴿SDK所需權限 -->
<uses-permission android:name="android.permission.BLUETOOTH" />
<uses-permission android:name="android.permission.BATTERY_STATS" />

啓動並註冊App

完成工程配置後，打開工程的主Activity，在其onCreate(Bundle savedInstanceState)重載方法內，添加如下代碼，完成信鴿服務的啓動與APP註冊過程。

// 開啓logcat輸出，方便debug，發佈時請關閉
// XGPushConfig.enableDebug(this, true);
// 若是須要知道註冊是否成功，請使用registerPush(getApplicationContext(), XGIOperateCallback)帶callback版本
// 若是須要綁定帳號，請使用registerPush(getApplicationContext(),account)版本
// 具體可參考詳細的開發指南
// 傳遞的參數爲ApplicationContext
Context context = getApplicationContext();
XGPushManager.registerPush(context);    

// 2.36（不包括）以前的版本須要調用如下2行代碼
Intent service = new Intent(context, XGPushService.class);
context.startService(service);


// 其它經常使用的API：
// 綁定帳號（別名）註冊：registerPush(context,account)或registerPush(context,account, XGIOperateCallback)，其中account爲APP帳號，能夠爲任意字符串（qq、openid或任意第三方），業務方必定要注意終端與後臺保持一致。
// 取消綁定帳號（別名）：registerPush(context,"*")，即account="*"爲取消綁定，解綁後，該針對該帳號的推送將失效
// 反註冊（再也不接收消息）：unregisterPush(context)
// 設置標籤：setTag(context, tagName)
// 刪除標籤：deleteTag(context, tagName)

代碼嵌入完成後，啓動APP，若是在logcat中的TPush標籤看到如下相似的輸出，說明已經註冊成功，並返回token。

    圖：註冊成功本地標籤爲「TPush」標籤的logcat日誌打印

10 min demo token.png
驗證

前往信鴿前臺，選擇「建立通知」，輸入「標題」和「內容」，點擊「確認推送」。稍等幾秒後，若是順利的話，終端設備應該可以收到這條通知。

    圖：前臺下發通知界面

10min demo pushprocess.png

    圖：終端設備收到通知界面

10 min demo arrived.png

經過上面的接入，APP已經具有接收通知推送的能力。
固然，若是還須要更高級的功能，請繼續閱讀或參數《SDK開發指南》
通知的異常自查列表

信鴿的發佈包都是通過嚴格測試的，遇到問題時，尤爲是開發環境問題，建議先自行搜索網上解決方案。
常見的檢查列表：
1.設備是否正常聯網？
2.檢查AndroidManifest.xml是否配置正確？建議直接參考demo的例子改

2.1. accessId、accessKey設置是否與前臺註冊的一致？
2.2. 相關權限是否齊全？
2.3. receiver、service和activity相關組件是否配置好？

3.設備是否註冊成功？
4.當前APP包名是否與前臺註冊的一致，若是不一致請在前臺選中「使用多包名」選項？
5.前臺下發通知時，「時段控制」選項裏的時間段是否符合終端設備當前時間？
6.請根據「常見問題與解答」，看看是否有解決方案。
7.2.30及以上版本請檢查xml配置文件是否添加com.tencent.android.tpush.XGPushActivity相關的內容
8.停留在後臺的APP點擊通知不能打開APP：被打開的activity（特別是LAUNCHER）啓動模式爲SingleTop，SingleTask或SingleInstance，請在該activity重載onNewIntent方法：

@Override
protected void onNewIntent(Intent intent) {
    super.onNewIntent(intent);        
    setIntent(intent);// 必需要調用這句
}

9.對於使用AndriodStudio的同窗，若AndroidManifest.xml編譯不經過，XGPushActivity配置改成： <action android:name="android.intent.action" />
10.請檢查AndroidManifest.xml是否已正確配置XGRemoteService，且intent-filter中是否正確設置： <action android:name="應用包名.PUSH_ACTION" />，應用包名爲當前APP包名，如com.tencent.xgdemo
11.是否已設置APP默認的icon？因爲系統緣由，若沒有icon，通知將不能展現。
12.（2.36以前的版本）已知MIUI V6上會禁用全部靜態廣播，若出現有相似的狀況，請添加如下代碼兼容該系統。

// 在XGPushManager.registerPush(context)或其它版本的註冊接口以後調用如下代碼
// 使用ApplicationContext
Context context = getApplicationContext();
Intent service = new Intent(context, XGPushService.class);
context.startService(service);


13.點擊通知，出現不能打開activity的狀況，請在AndroidManifest.xml中將XGPushActivity的exported屬性設置爲true。
14.點擊通知，出現重複打開APP的狀況，請將被打開的Activity啓動模式改成SingleTop，SingleTask或SingleInstance。
15.點擊通知，不但願觸發activity被打開的動做，能夠：1.推送時，填寫一個不存在的頁面名稱；2.使用消息透傳（命令字）推送，收到消息後，本身彈出通知。
若是還不能排查問題，請加入信鴿開發者技術QQ羣：333782566，會有專門的人員協助。

包衝突

1.jar包衝突：

若是提示jar包衝突，請刪除衝突的包，保留一份便可，建議保留版本高的。
常見的衝突有：
1）MSDK與信鴿衝突：刪除wup.jar
2）MTA與信鴿衝突：刪除低版本的mid.jar

2. .so文件導入：.so文件是信鴿必須的組件，支持armeabi、armeabi-v7a、misp和x86平臺，請根據本身當前.so支持的平臺添加

1）若是你的項目中沒有使用其它.so，建議複製四個平臺目錄到本身工程中
2）若是已有.so文件，只須要複製信鴿對應目錄下的文件
3）如果MSDK接入的遊戲，一般只須要armeabi目錄下的.so
4）若當前工程已經有armeabi，那麼只須要添加信鴿的armeabi下的.so，其它目錄無需添加。其它狀況相似，只添加當前平臺存在的平臺便可。

代碼混淆

若是你的項目中使用proguard等工具作了代碼混淆，請保留如下選項，不然將致使信鴿服務不可用。

-keep public class * extends android.app.Service
-keep public class * extends android.content.BroadcastReceiver
-keep class com.tencent.android.tpush.**  {* ;}
-keep class com.tencent.mid.**  {* ;}

關於抵達量/點擊量和自定義key-value的統計

2.30及以上版本
2.30及以上版本：使用信鴿SDK內置的activity展現頁面，默認已經統計通知/消息的抵達量、通知的點擊和清除動做。但若是開發者要監聽這些事 件，可參考「Android SDK開發指南」中的「【2.30及以上版本】通知效果監聽和自定義key-value」章節。
XGPushManager.onActivityStarted(this)獲取通知被點擊及自定義key-value由原來的onStart()改成onResume()

        @Override
    protected void onResume() {
        super.onResume();
        XGPushClickedResult click = XGPushManager.onActivityStarted(this);
        if (click != null) { // 判斷是否來自信鴿的打開方式
            // 根據實際狀況處理...
            // 如獲取自定義key-value
        }
    }

    同理，XGPushManager.onActivityStoped(this)由onStop()改成onPause()內調用，即：

    @Override
    protected void onPause() {
        super.onPause();
        XGPushManager.onActivityStoped(this);
    }

    注意：
1）須要將onActivityStarted和onActivityStoped嵌入到全部可能被打開的activity，建議全部activity都加上。
2）若是被打開的activity啓動模式爲SingleTop，SingleTask或SingleInstance，請根據如下在該activity重載onNewIntent方法：

    @Override
    protected void onNewIntent(Intent intent) {
        super.onNewIntent(intent);        
        setIntent(intent);// 必需要調用這句
    }

通知在通知欄被點擊或清除時的回調，即自定義Receiver（需重載XGPushBaseReceiver）的 onNotifactionClickedResult重載方法中區分點擊和清除動做，XGPushClickedResult添加 getActionType()，其中XGPushClickedResult.NOTIFACTION_CLICKED_TYPE表示點擊操 做，XGPushClickedResult.NOTIFACTION_DELETED_TYPE表示清除操做。即：

    @Override
    public void onNotifactionClickedResult(Context context,
            XGPushClickedResult message) {
        if (context == null || message == null) {
            return;
        }
        if (message.getActionType() == XGPushClickedResult.NOTIFACTION_CLICKED_TYPE) {
            // 通知在通知欄被點擊啦。。。。。
            // APP本身處理點擊的相關動做
            // 這個動做能夠在activity的onResume也能監聽，請看第3點相關內容
        } else if (message.getActionType() == XGPushClickedResult.NOTIFACTION_DELETED_TYPE) {
            // 通知被清除啦。。。。
            // APP本身處理通知被清除後的相關動做
        }
    }

2.30版本以前
2.0/2.1x/2.2x版本：SDK默認統計通知/消息的抵達量，但對於點擊量和自定義key-value，須要全部activity的 onStart重載方法中調用 XGPushManager.onActivityStarted(this);才能統計，具體請參考「Android SDK開發指南」中的「【2.30之前版本】通知打開效果和自定義key-value」章節