取得信標訊息

您的應用程式可使用與訂閱鄰近裝置發布訊息相同的機制，訂閱藍牙低功耗 (BLE) 信標附件。訂閱時，應用程式會自動透過信標和鄰近裝置接收訊息。

訂閱 BLE 信標訊息

您的應用程式可以透過下列兩種方式訂閱 BLE 信標訊息：

  • 在前景回應使用者動作或事件。
  • 在背景，應用程式並未運作時。

在前景訂閱

當應用程式在前景中訂閱信標訊息時，系統會持續執行掃描作業，直到應用程式取消訂閱為止。只有在應用程式處於啟用狀態時才會啟動前景訂閱項目，通常是為了回應使用者動作。

您的應用程式可呼叫 Nearby.getMessagesClient(Activity).subscribe(MessageListener, SubscribeOptions)，並將 Strategy 選項設為 BLE_ONLY，以啟動前景訂閱。

下列程式碼片段示範如何啟動前景訂閱 Nearby.getMessagesClient(Activity).subscribe(MessageListener, SubscribeOptions)：

public void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    ...
    mMessageListener = new MessageListener() {
        @Override
        public void onFound(Message message) {
            Log.d(TAG, "Found message: " + new String(message.getContent()));
        }

        @Override
        public void onLost(Message message) {
            Log.d(TAG, "Lost sight of message: " + new String(message.getContent()));
        }
    }
}

// Subscribe to receive messages.
private void subscribe() {
    Log.i(TAG, "Subscribing.");
    SubscribeOptions options = new SubscribeOptions.Builder()
            .setStrategy(Strategy.BLE_ONLY)
            .build();
    Nearby.getMessagesClient(this).subscribe(mMessageListener, options);
}

如果不再需要訂閱，應用程式應呼叫 Nearby.getMessagesClient(Activity).unsubscribe(MessageListener) 來取消訂閱。

在背景訂閱

當應用程式在背景訂閱信標訊息時，即使應用程式目前並未使用，也會在螢幕啟動事件觸發低功耗掃描。您可以使用這些掃描通知，在特定訊息中「喚醒」您的應用程式。背景訂閱項目耗電量低於前景訂閱項目，但延遲時間較長且可靠性較低。

您的應用程式可透過呼叫 Nearby.getMessagesClient(Activity).subscribe(PendingIntent, SubscribeOptions) 並將 Strategy 選項設為 BLE_ONLY，來啟動背景訂閱項目。

下列程式碼片段示範如何透過呼叫 Nearby.getMessagesClient(Activity).subscribe(PendingIntent, SubscribeOptions) 來啟動背景訂閱項目。

// Subscribe to messages in the background.
private void backgroundSubscribe() {
    Log.i(TAG, "Subscribing for background updates.");
    SubscribeOptions options = new SubscribeOptions.Builder()
            .setStrategy(Strategy.BLE_ONLY)
            .build();
    Nearby.getMessagesClient(this).subscribe(getPendingIntent(), options);
}

private PendingIntent getPendingIntent() {
    return PendingIntent.getBroadcast(this, 0, new Intent(this, BeaconMessageReceiver.class),
            PendingIntent.FLAG_UPDATE_CURRENT);
}

下列程式碼片段示範如何處理 BeaconMessageReceiver 類別中的意圖。

@Override
public void onReceive(Context context, Intent intent) {
    Nearby.getMessagesClient(context).handleIntent(intent, new MessageListener() {
        @Override
        public void onFound(Message message) {
            Log.i(TAG, "Found message via PendingIntent: " + message);
        }

        @Override
        public void onLost(Message message) {
            Log.i(TAG, "Lost message via PendingIntent: " + message);
        }
    });
}

如果不再需要訂閱，應用程式應呼叫 Nearby.getMessagesClient(Activity).unsubscribe(PendingIntent) 來取消訂閱。

剖析信標訊息

信標附件是可加入信標的任意資料 blob。每個附件由下列部分組成：

  • 命名空間：命名空間識別碼。
  • 類型：資料類型。
  • 資料：附件的資料值。

下列程式碼片段示範如何使用訊息監聽器剖析從 BLE 信標收到的訊息：

mMessageListener = new MessageListener() {
    @Override
    public void onFound(Message message) {
        // Do something with the message here.
        Log.i(TAG, "Message found: " + message);
        Log.i(TAG, "Message string: " + new String(message.getContent()));
        Log.i(TAG, "Message namespaced type: " + message.getNamespace() +
                "/" + message.getType());
    }

    ...
};

剖析內容取決於位元組的格式。此範例假設內容位元組編碼為 UTF-8 字串，但您的信標訊息可以編碼其他位元組格式 (例如序列化通訊協定緩衝區)。詳情請參閱為附件新增附件。

如要瞭解與專案相關聯的命名空間，請呼叫 namespaces.list。

附註：