小米應用商店：Android版快速接入指南

1.客戶端接入小米推送前的準備工作

1.在小米開發(fā)者站開通小米開發(fā)者賬號。

2.創(chuàng)建應用，開發(fā)者賬號審核通過后你就可以在開發(fā)者站創(chuàng)建你的應用。

3.開啟應用的推送服務。

4.下載SDK、文檔和DEMO。

2.Demo的使用

Android Demo提供了一些基本功能，比如注冊小米推送服務、設置別名、取消別名、訂閱標簽、取消標簽、設置消息的接收時間段等等。Demo的主Activity包含兩個部分：基本操作的Button和顯示這些操作結果信息（成功或失敗）TextView。通過修改Anroid Demo中部分代碼，可以使在開發(fā)者站創(chuàng)建的應用快速的接入小米推送服務。

1.將DemoApplication.java中APP_ID、APP_KEY值替換為應用的對應值，TAG替換為應用的包名

2.將AndroidManifest.xml中package和permission包名替換為應用的包名。

3.如果使用的IDE是Android Studio，還需要修改gradle配置

修改了以上幾處的代碼，可以在模擬器或者手機上安裝此應用。Demo啟動后，主界面上顯示了"Register push success."表示注冊小米推送服務成功，這時可以設置別名、訂閱標簽。開發(fā)者可以利用小米網(wǎng)頁推送工具向對應的別名或標簽推送消息。為了能夠看到更詳細的log信息，可以在命令行下輸入：adb logcat|grep應用包名

3.推送對象的選擇

推送對象目前支持四種：RegID、別名、userAccount、標簽。

1.RegID：針對單一設備推送消息。應用調用MiPushClient類的靜態(tài)方法registerPush注冊小米推送服務，注冊的結果將通過PushMessageReceiver繼承類的onCommandResult方法和onReceiveRegisterResult中的MiPushCommandMessage參數(shù)對象message傳到客戶端。當message對象的command等于MiPushClient.COMMAND_REGISTER并且message對象的resultCode等于ErrorCode.SUCCESS時，message對象commandArguments包含了服務器返回的RegID?？蛻舳说年P鍵代碼如下：

public void onCommandResult(Context context, MiPushCommandMessage message) {

        String command = message.getCommand();

        List<String> arguments = message.getCommandArguments();

        if (MiPushClient.COMMAND_REGISTER.equals(command)) {

            if (message.getResultCode() == ErrorCode.SUCCESS) {

              mRegID = arguments.get(0);

        }

}

2.RegID是由服務器端生成的，能夠唯一標識某臺手機上的某個應用。應用在獲取到RegID后，需要將RegID上報到應用的服務器，此時應用服務端就可以利用RegID向客戶端發(fā)送消息。

別名：針對單一設備推送消息。應用只有在成功注冊小米推送服務后才能調用MiPushClient類的靜態(tài)方法setAlias設置別名。同樣，設置別名的結果將通過PushMessageReceiver繼承類的onCommandResult方法中的MiPushCommandMessage參數(shù)對象message傳到客戶端。客戶端關鍵代碼如下：

public void onCommandResult(Context context, MiPushCommandMessage message) {

        String command = message.getCommand();

        List<String> arguments = message.getCommandArguments();

        if (MiPushClient.COMMAND_SET_ALIAS.equals(command)) {

            if (message.getResultCode() == ErrorCode.SUCCESS) {

              mAlias = arguments.get(0);

        }

}

3.成功設置別名后，服務器就可以通過這個別名將消息推送到對應的設備上。利用別名向設備推送消息的方法不需要應用服務器保存客戶端上傳的RegID。開發(fā)者可以根據(jù)業(yè)務的需要給不同設備設置不同的別名。注：一臺設備可以設置多個不同的別名，而一個別名只能對應某一臺設備。如果多臺設備設置同一個別名，那么只有最后設置的一臺設備生效。

userAccount:針對多個設備推送消息。應用只有在成功注冊小米推送服務后才能調用MiPushClient類的靜態(tài)方法setUserAccount設置userAccount。同樣，設置userAccount的結果將通過PushMessageReceiver繼承類的onCommandResult方法中的MiPushCommandMessage參數(shù)對象message傳到客戶端?？蛻舳岁P鍵代碼如下：

public void onCommandResult(Context context, MiPushCommandMessage message) {

        String command = message.getCommand();

        List<String> arguments = message.getCommandArguments();

        if (MiPushClient.COMMAND_SET_ACCOUNT.equals(command)) {

            if (message.getResultCode() == ErrorCode.SUCCESS) {

              mAccount = arguments.get(0);

        }

}

開發(fā)者可以在不同設備上設置同一個userAccount。然后使用Server SDK給該userAccount發(fā)送消息；此時，所有設置了該userAccount的設備都可以收到消息。

4.標簽：針對多個設備推送消息。應用只有成功注冊小米推送服務后才能調用MiPushClient類的靜態(tài)方法subscribe訂閱標簽。同樣，訂閱標簽的結果將通過PushMessageReceiver繼承類的onCommandResult方法中的MiPushCommandMessage參數(shù)對象message傳到客戶端?？蛻舳岁P鍵代碼如下：

public void onCommandResult(Context context, MiPushCommandMessage message) {

        String command = message.getCommand();

        List<String> arguments = message.getCommandArguments();

        if (MiPushClient.COMMAND_SUBSCRIBE_TOPIC.equals(command)) {

            if (message.getResultCode() == ErrorCode.SUCCESS) {

              mTopic = arguments.get(0);

        }

}

開發(fā)者可以結合自己的業(yè)務特征，給用戶打上不同的標簽(Topic)。在消息的推送過程中，開發(fā)者結合每條消息的內容和目標用戶群,選擇每條消息所對應的標簽,可以進行更精準的定向推送。注：一臺設備可以訂閱多個不同的標簽，并且一個標簽可以對應多臺設備，這點和別名不同。

4.推送消息的類型

用戶成功設置別名（訂閱標簽）后，服務端可以向該別名（標簽）發(fā)送消息。從開發(fā)者網(wǎng)站中下載的包含Server API的jar包只是封裝了一些簡單的HTTP請求，開發(fā)者可以根據(jù)需要封裝成不同的語言版本。服務端通過調用Message.Builder類的passThrough(int)方法設置pass_through參數(shù)來定義消息的類型，1表示透傳消息，0表示通知消息。

·透傳消息———封裝消息的MiPushMessage對象直接通過PushMessageReceiver繼承類的的onReceivePassThroghMessage方法傳到客戶端。

·通知消息———消息到達客戶端后會彈出通知，通知消息到達時，不需要用戶點擊通知就會通過PushMessageReceiver繼承類的onNotificationMessageArrived方法傳到客戶端，只有在用戶點擊了通知后封裝消息的MiPushMessage對象才會通過PushMessageReceiver繼承類的onNotificationMessageClicked方法傳到客戶端。對于應用在前臺時不彈通知類型的通知信息，通知到達后會通過PushMessageReceiver繼承類的onNotificationMessageArrived方法傳到客戶端，但不會觸發(fā)onNotificationMessageClicked方法。注：通知消息通過onNotificationMessageClicked傳到客戶端只對"自定義點擊行為"有效。注：在MIUI上，如果沒有收到onNotificationMessageArrived回調，是因為使用的MIUI版本還不支持該特性，需要升級到MIUI7之后。非MIUI手機都可以收到這個回調。

客戶端接收消息的關鍵代碼：

public void onReceivePassThroughMessage(Context context, MiPushMessage message) {

        mMessage = message.getContent();

        if(!TextUtils.isEmpty(message.getTopic())) {

            mTopic=message.getTopic();

        } else if(!TextUtils.isEmpty(message.getAlias())) {

            mAlias=message.getAlias();

        }

    }

public void onNotificationMessageClicked(Context context, MiPushMessage message) {

        mMessage = message.getContent();

        if(!TextUtils.isEmpty(message.getTopic())) {

            mTopic=message.getTopic();

        } else if(!TextUtils.isEmpty(message.getAlias())) {

            mAlias=message.getAlias();

        }

    }

public void onNotificationMessageArrived(Context context, MiPushMessage message) {

        mMessage = message.getContent();

        if(!TextUtils.isEmpty(message.getTopic())) {

            mTopic=message.getTopic();

        } else if(!TextUtils.isEmpty(message.getAlias())) {

            mAlias=message.getAlias();

        }

    }

4.1.透傳消息

為了發(fā)送通知消息，服務端必須調用Message.Builder類的passThrough(int)方法將參數(shù)pass_through設置為1。除了需要pass_through參數(shù)外，通知消息還需要設置一些其他的參數(shù)，比如payload、restricted_package_name、registration_id、alias、topic。注：服務器不需要設置的title和description，即使設置了對客戶端也是無效的。封裝消息的MiPushMessage對象直接通過PushMessageReceiver繼承類的的onReceivePassThroughMessage方法傳到客戶端。

4.2.通知消息

為了發(fā)送通知消息，服務端必須調用Message.Builder類的passThrough(int)方法將參數(shù)pass_through設置為0。除了需要pass_through參數(shù)外，通知消息還需要設置一些其他的參數(shù)，比如payload、restricted_package_name、registration_id、alias、topic、pass_through、title、description、notify_type等。首先，介紹如何開啟/關閉app在前臺時的通知彈出。應用在前臺的情況下，通知消息到達客戶端后是否彈出通知可以服務端來設置。服務端調用Message.Builder類的extra(String key,String value)方法將EXTRA_PARAM_NOTIFY_FOREGROUND的值設置為"0"或者"1"。當EXTRA_PARAM_NOTIFY_FOREGROUND值為”1″時，app會彈出通知欄消息；當EXTRA_PARAM_NOTIFY_FOREGROUND值為”0″時，app不會彈出通知欄消息。注：默認情況下會彈出通知欄消息。例如：

private Message buildMessage() throws Exception {

     String PACKAGENAME = "com.xiaomi.mipushdemo";

     String messagePayload = “This is a message”;

     String title = “notification title”;

     String description = “notification description”;

     Message message = new Message.Builder()

          .title(title)

          .description(description).payload(messagePayload)

          .restrictedPackageName(MY_PACKAGE_NAME)

          .passThrough(0)

          .notifyType(1)

          .extra(Constants.EXTRA_PARAM_NOTIFY_FOREGROUND, "0")

          .build();

    return message;

}

接下來介紹通知消息的提醒類型和通知消息的點擊行為。

4.2.1.通知消息的提醒類型

通知的提醒類型分為三種：聲音、振動和呼吸燈，可以是它們的任一組合。服務端調用Message.Builder類的notifyType(int)方法設置通知的提醒類型。notifyType的值可以是以下幾種的OR組合：

·DEFAULT_SOUND=1;

·DEFAULT_VIBRATE=2;

·DEFAULT_LIGHTS=4;

·DEFAULT_ALL=-1;

另外，服務端可以調用Message.Builder類的extra(String key,String value)方法將Constants.EXTRA_PARAM_SOUND_URI的值設置為對應通知聲音的URI。例如：

private Message buildMessage() throws Exception {

     String PACKAGENAME = "com.xiaomi.mipushdemo";

     String messagePayload = “This is a message”;

     String title = “notification title”;

     String description = “notification description”;

     Message message = new Message.Builder()

          .title(title)

          .description(description).payload(messagePayload)

          .restrictedPackageName(MY_PACKAGE_NAME)

          .passThrough(0)

          .notifyType(1)

          .extra(Constants.EXTRA_PARAM_SOUND_URI, "android.resource://" + PACKAGENAME + "/raw/shaking")

          .build();

    return message;

}

4.2.2.通知消息的點擊行為

通知消息的點擊行為，分為自定義點擊行為和預定義點擊行為。

4.2.2.1.&nnbsp;自定義點擊行為

用戶點擊了客戶端彈出的通知消息后會將封裝消息的MiPushMessage對象通過PushMessageReceiver繼承類的onNotificationMessageClicked方法傳到客戶端。下面介紹一個應用場景。場景1：開發(fā)者希望客戶端在收到消息后啟動應用的某一個Activity。解決方法：開發(fā)者可以在onNotificationMessageClicked中調用context.startActivity方法，將所需要的信息通過Intent傳過去。對于場景1，如果客戶端工程師不想寫啟動actvity的代碼，可以使用下面介紹的預定義點擊行為。

4.2.2.2.預定義點擊行為

預定義點擊行為目前支持三種：(1)打開當前的Launcher Activity(2)打開當前app內的任意一個Activity(3)打開網(wǎng)頁。服務端調用Message.Builder類的extra(String key,String value)方法，將key設置為Constants.EXTRA_PARAM_NOTIFY_EFFECT，value設置為Constants.NOTIFY_LAUNCHER_ACTIVITY、Constants.NOTIFY_ACTIVITY或Constants.NOTIFY_WEB以得到不同的預定義行為。

·Constants.NOTIFY_LAUNCHER_ACTIVITY：打開當前app對應的Launcher Activity。

·Constants.ACTIVITY：打開當前app內的任意一個Activity。

·Constants.NOTIFY_WEB：打開網(wǎng)頁。

對于第一種和第二種預定義的點擊行為，用戶點擊了客戶端彈出的通知消息后會將封裝消息的MiPushMessage對象通過Intent傳到客戶端，客戶端在相應的Activity中可以調用Intent的getSerializableExtra（PushMessageHelper.KEY_MESSAGE）方法得到MiPushMessage對象。而第三種預定義行為，客戶端是獲取不到MiPushMessage對象。對于自定義點擊行為中介紹的場景1，服務端通過通過Message.Builder的extra方法設置Constants.EXTRA_PARAM_NOTIFY_EFFECT和Constants.EXTRA_PARAM_INTENT_URI值就可以解決，不需要客戶端添加任何代碼。

5.推送統(tǒng)計

目前小米推送提供了推送數(shù)據(jù)、消息記錄、用戶數(shù)據(jù)供開發(fā)者查詢。開發(fā)者既可以在小米開發(fā)者中心網(wǎng)站上查看，也可以利用數(shù)據(jù)API獲取。

1.推送數(shù)據(jù)提供當日實時和歷史每日的已推送總量（區(qū)分群發(fā)和單發(fā)）、已送達消息數(shù)和已點擊數(shù)，開發(fā)者可以指定日期查詢相應數(shù)據(jù)。

2.用戶數(shù)據(jù)實時數(shù)據(jù)提供當日實時在線用戶數(shù)、截至目前最高在線用戶數(shù)；歷史數(shù)據(jù)提供歷史上每天的最高在線用戶數(shù)、新增用戶數(shù)和日活躍用戶數(shù)，同樣支持指定時間段的查詢。注：用戶數(shù)據(jù)中的在線和活躍是以長連接是否連接為標準的，應用不一定啟動。

3.消息記錄消息記錄：提供最近30天內的消息記錄列表，每條消息提供計劃推送數(shù)、送達數(shù)和送達率、點擊數(shù)和點擊率的統(tǒng)計，支持通過消息id或通知標題摘要中的關鍵詞進行查詢。注：為了避免展示用戶較為隱私的信息，計劃推送數(shù)在10以下的通知我們沒有展示通知的內容，也屏蔽了針對這部分通知內容的檢索。