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

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

Android版快速接入指南

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

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

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

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

4.下載SDK、文檔和DEMO。

2.Demo的使用

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

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

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

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

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

3.推快遞對象的選擇

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

1.RegID：針對單一設(shè)備推快遞消息。應(yīng)用調(diào)用MiPushClient類的靜態(tài)方法registerPush注冊小米推快遞服務(wù)，注冊的結(jié)果將通過PushMessageReceiver繼承類的onCommandResult方法和onReceiveRegisterResult中的MiPushCommandMessage參數(shù)對象message傳到客戶端。當(dāng)message對象的command等于MiPushClient.COMMAND_REGISTER并且message對象的resultCode等于ErrorCode.SUCCESS時，message對象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ù)器端生成的，能夠唯一標識某臺手機上的某個應(yīng)用。應(yīng)用在獲取到RegID后，需要將RegID上報到應(yīng)用的服務(wù)器，此時應(yīng)用服務(wù)端就可以利用RegID向客戶端發(fā)快遞消息。

別名：針對單一設(shè)備推快遞消息。應(yīng)用只有在成功注冊小米推快遞服務(wù)后才能調(diào)用MiPushClient類的靜態(tài)方法setAlias設(shè)置別名。同樣，設(shè)置別名的結(jié)果將通過PushMessageReceiver繼承類的onCommandResult方法中的MiPushCommandMessage參數(shù)對象message傳到客戶端?？蛻舳岁P(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ù)器就可以通過這個別名將消息推國際快遞對應(yīng)的設(shè)備上。利用別名向設(shè)備推快遞消息的方法不需要應(yīng)用服務(wù)器保存客戶端上傳的RegID。開發(fā)者可以根據(jù)業(yè)務(wù)的需要給不同設(shè)備設(shè)置不同的別名。注：一臺設(shè)備可以設(shè)置多個不同的別名，而一個別名只能對應(yīng)某一臺設(shè)備。如果多臺設(shè)備設(shè)置同一個別名，那么只有最后設(shè)置的一臺設(shè)備生效。

userAccount:針對多個設(shè)備推快遞消息。應(yīng)用只有在成功注冊小米推快遞服務(wù)后才能調(diào)用MiPushClient類的靜態(tài)方法setUserAccount設(shè)置userAccount。同樣，設(shè)置userAccount的結(jié)果將通過PushMessageReceiver繼承類的onCommandResult方法中的MiPushCommandMessage參數(shù)對象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è)置同一個userAccount。然后使用Server SDK給該userAccount發(fā)快遞消息；此時，所有設(shè)置了該userAccount的設(shè)備都可以收到消息。

4.標簽：針對多個設(shè)備推快遞消息。應(yīng)用只有成功注冊小米推快遞服務(wù)后才能調(diào)用MiPushClient類的靜態(tài)方法subscribe訂閱標簽。同樣，訂閱標簽的結(jié)果將通過PushMessageReceiver繼承類的onCommandResult方法中的MiPushCommandMessage參數(shù)對象message傳到客戶端?？蛻舳岁P(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ù)特征，給用戶打上不同的標簽(Topic)。在消息的推快遞過程中，開發(fā)者結(jié)合每條消息的內(nèi)容和目標用戶群,選擇每條消息所對應(yīng)的標簽,可以進行更精準的定向推快遞。注：一臺設(shè)備可以訂閱多個不同的標簽，并且一個標簽可以對應(yīng)多臺設(shè)備，這點和別名不同。

4.推快遞消息的類型

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

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

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

為了發(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è)置了對客戶端也是無效的。封裝消息的MiPushMessage對象直接通過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在前臺時的通知彈出。應(yīng)用在前臺的情況下，通知消息到達客戶端后是否彈出通知可以服務(wù)端來設(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″時，app會彈出通知欄消息；當(dāng)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.通知消息的提醒類型

通知的提醒類型分為三種：聲音、振動和呼吸燈，可以是它們的任一組合。服務(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è)置為對應(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.通知消息的點擊行為

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

4.2.2.1.nnbsp;自定義點擊行為

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

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

預(yù)定義點擊行為目前支持三種：(1)打開當(dāng)前的Launcher Activity(2)打開當(dāng)前app內(nèi)的任意一個Activity(3)打開網(wǎng)頁。服務(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對應(yīng)的Launcher Activity。

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

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

對于第一種和第二種預(yù)定義的點擊行為，用戶點擊了客戶端彈出的通知消息后會將封裝消息的MiPushMessage對象通過Intent傳到客戶端，客戶端在相應(yīng)的Activity中可以調(diào)用Intent的getSerializableExtra（PushMessageHelper.KEY_MESSAGE）方法得到MiPushMessage對象。而第三種預(yù)定義行為，客戶端是獲取不到MiPushMessage對象。對于自定義點擊行為中介紹的場景1，服務(wù)端通過通過Message.Builder的extra方法設(shè)置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ù)提供當(dāng)日實時和歷史每日的已推快遞總量（區(qū)分群發(fā)和單發(fā)）、已快遞達消息數(shù)和已點擊數(shù)，開發(fā)者可以指定日期查詢相應(yīng)數(shù)據(jù)。

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

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

特別聲明：以上文章內(nèi)容僅代表作者本人觀點，不代表ESG跨境電商觀點或立場。如有關(guān)于作品內(nèi)容、版權(quán)或其它問題請于作品發(fā)表后的30日內(nèi)與ESG跨境電商聯(lián)系。