Android版快速接入指南,android定制工具完整中文版-ESG跨境

Android版快速接入指南,android定制工具完整中文版

Android版快速接入指南

1.客戶端接入小米推快遞前的準(zhǔn)備工作

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

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

3.開啟應(yīng)用的推快遞服務(wù)。

4.下載SDK、文檔和DEMO。

2.Demo的使用

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

1.將DemoApplication.java中APP_ID、APP_KEY值替換為應(yīng)用的對(duì)應(yīng)值，TAG替換為應(yīng)用的包名

2.將AndroidManifest.xml中package和permission包名替換為應(yīng)用的包名。

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

修改了以上幾處的代碼，可以在模擬器或者手機(jī)上安裝此應(yīng)用。Demo啟動(dòng)后，主界面上顯示了Register push success.表示注冊(cè)小米推快遞服務(wù)成功，這時(shí)可以設(shè)置別名、訂閱標(biāo)簽。開發(fā)者可以利用小米網(wǎng)頁(yè)推快遞工具向?qū)?yīng)的別名或標(biāo)簽推快遞消息。為了能夠看到更詳細(xì)的log信息，可以在命令行下輸入：adb logcatgrep應(yīng)用包名

3.推快遞對(duì)象的選擇

推快遞對(duì)象目前支持四種：RegID、別名、userAccount、標(biāo)簽。

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

public void onCommandResult(Context context, MiPushCommandMessage message) {

    String command = message.getCommand();

    ListString arguments = message.getCommandArguments();

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

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

       mRegID = arguments.get(0);

    }

}

2.RegID是由服務(wù)器端生成的，能夠唯一標(biāo)識(shí)某臺(tái)手機(jī)上的某個(gè)應(yīng)用。應(yīng)用在獲取到RegID后，需要將RegID上報(bào)到應(yīng)用的服務(wù)器，此時(shí)應(yīng)用服務(wù)端就可以利用RegID向客戶端發(fā)快遞消息。

別名：針對(duì)單一設(shè)備推快遞消息。應(yīng)用只有在成功注冊(cè)小米推快遞服務(wù)后才能調(diào)用MiPushClient類的靜態(tài)方法setAlias設(shè)置別名。同樣，設(shè)置別名的結(jié)果將通過(guò)PushMessageReceiver繼承類的onCommandResult方法中的MiPushCommandMessage參數(shù)對(duì)象message傳到客戶端。客戶端關(guān)鍵代碼如下：

public void onCommandResult(Context context, MiPushCommandMessage message) {

    String command = message.getCommand();

    ListString arguments = message.getCommandArguments();

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

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

       mAlias = arguments.get(0);

    }

}

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

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

public void onCommandResult(Context context, MiPushCommandMessage message) {

    String command = message.getCommand();

    ListString arguments = message.getCommandArguments();

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

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

       mAccount = arguments.get(0);

    }

}

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

4.標(biāo)簽：針對(duì)多個(gè)設(shè)備推快遞消息。應(yīng)用只有成功注冊(cè)小米推快遞服務(wù)后才能調(diào)用MiPushClient類的靜態(tài)方法subscribe訂閱標(biāo)簽。同樣，訂閱標(biāo)簽的結(jié)果將通過(guò)PushMessageReceiver繼承類的onCommandResult方法中的MiPushCommandMessage參數(shù)對(duì)象message傳到客戶端。客戶端關(guān)鍵代碼如下：

public void onCommandResult(Context context, MiPushCommandMessage message) {

    String command = message.getCommand();

    ListString arguments = message.getCommandArguments();

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

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

       mTopic = arguments.get(0);

    }

}

開發(fā)者可以結(jié)合自己的業(yè)務(wù)特征，給用戶打上不同的標(biāo)簽(Topic)。在消息的推快遞過(guò)程中，開發(fā)者結(jié)合每條消息的內(nèi)容和目標(biāo)用戶群,選擇每條消息所對(duì)應(yīng)的標(biāo)簽,可以進(jìn)行更精準(zhǔn)的定向推快遞。注：一臺(tái)設(shè)備可以訂閱多個(gè)不同的標(biāo)簽，并且一個(gè)標(biāo)簽可以對(duì)應(yīng)多臺(tái)設(shè)備，這點(diǎn)和別名不同。

4.推快遞消息的類型

用戶成功設(shè)置別名（訂閱標(biāo)簽）后，服務(wù)端可以向該別名（標(biāo)簽）發(fā)快遞消息。從開發(fā)者網(wǎng)站中下載的包含Server API的jar包只是封裝了一些簡(jiǎn)單的HTTP請(qǐng)求，開發(fā)者可以根據(jù)需要封裝成不同的語(yǔ)言版本。服務(wù)端通過(guò)調(diào)用Message.Builder類的passThrough(int)方法設(shè)置pass_through參數(shù)來(lái)定義消息的類型，1表示透?jìng)飨ⅲ?表示通知消息。

·透?jìng)飨ⅰ庋b消息的MiPushMessage對(duì)象直接通過(guò)PushMessageReceiver繼承類的的onReceivePassThroghMessage方法傳到客戶端。

·通知消息———消息到達(dá)客戶端后會(huì)彈出通知，通知消息到達(dá)時(shí)，不需要用戶點(diǎn)擊通知就會(huì)通過(guò)PushMessageReceiver繼承類的onNotificationMessageArrived方法傳到客戶端，只有在用戶點(diǎn)擊了通知后封裝消息的MiPushMessage對(duì)象才會(huì)通過(guò)PushMessageReceiver繼承類的onNotificationMessageClicked方法傳到客戶端。對(duì)于應(yīng)用在前臺(tái)時(shí)不彈通知類型的通知信息，通知到達(dá)后會(huì)通過(guò)PushMessageReceiver繼承類的onNotificationMessageArrived方法傳到客戶端，但不會(huì)觸發(fā)onNotificationMessageClicked方法。注：通知消息通過(guò)onNotificationMessageClicked傳到客戶端只對(duì)自定義點(diǎn)擊行為有效。注：在MIUI上，如果沒有收到onNotificationMessageArrived回調(diào)，是因?yàn)槭褂玫腗IUI版本還不支持該特性，需要升級(jí)到MIUI7之后。非MIUI手機(jī)都可以收到這個(gè)回調(diào)。

客戶端接收消息的關(guān)鍵代碼：

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.透?jìng)飨?/strong>

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

4.2.通知消息

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

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;

}

接下來(lái)介紹通知消息的提醒類型和通知消息的點(diǎn)擊行為。

4.2.1.通知消息的提醒類型

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

·DEFAULT_SOUND=1;

·DEFAULT_VIBRATE=2;

·DEFAULT_LIGHTS=4;

·DEFAULT_ALL=1;

另外，服務(wù)端可以調(diào)用Message.Builder類的extra(String key,String value)方法將Constants.EXTRA_PARAM_SOUND_URI的值設(shè)置為對(duì)應(yīng)通知聲音的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.通知消息的點(diǎn)擊行為

通知消息的點(diǎn)擊行為，分為自定義點(diǎn)擊行為和預(yù)定義點(diǎn)擊行為。

4.2.2.1.nnbsp;自定義點(diǎn)擊行為

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

4.2.2.2.預(yù)定義點(diǎn)擊行為

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

·Constants.NOTIFY_LAUNCHER_ACTIVITY：打開當(dāng)前app對(duì)應(yīng)的Launcher Activity。

·Constants.ACTIVITY：打開當(dāng)前app內(nèi)的任意一個(gè)Activity。

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

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

5.推快遞統(tǒng)計(jì)

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

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

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

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