發布及訂閱

Nearby Messages 是一種發布/訂閱 API，可讓附近裝置交換小型資料酬載。裝置發布訊息後，附近的裝置就能接收該訊息。本指南將逐步說明應用程式必須實作哪些功能，才能使用 Nearby Messages API 發布及訂閱訊息。

系統會透過藍牙交換小型權杖，判斷附近裝置的組合。當裝置偵測到附近裝置的符記時，就會將符記傳送至 Nearby Messages 伺服器，以便驗證符記，並檢查應用程式目前的訂閱項目組合是否有任何訊息要傳送。

應用程式可以控制用於裝置探索的媒介組合，以及媒介是否用於廣播權杖和/或掃描權杖。根據預設，系統會在所有媒體上進行廣播和掃描。如要針對子集或媒體進行探索，並控制要發布或掃描內容，您必須在建立發布內容和訂閱項目時傳遞其他參數。

在積極發布及訂閱時，系統會顯示「鄰近分享功能正在使用中」通知，通知使用者鄰近分享功能已啟用。只有在有一或多個應用程式正在使用鄰近功能時，系統才會顯示這則通知，讓使用者有機會在不需要使用鄰近功能時節省電池續航力。並提供下列選項：

  • 前往要停用鄰近分享功能的應用程式。
  • 強制停止應用程式使用鄰近分享功能。
  • 前往「鄰近設定」畫面。

您可以使用 PublishCallback() 和 SubscribeCallback() 監聽使用者強制應用程式停止使用附近功能的情況。發生這種情況時，系統會觸發 onExpired() 方法。

由於 Nearby Messages API 可能會影響電池續航力，因此應僅在前景活動中使用 (BLE 背景訂閱除外)。

呼叫 publish() 和/或 subscribe() 即可使用 Nearby Messages API。應用程式應一律在 onStop() 中對稱地使用 unpublish() 和 unsubscribe()。

@Override
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()));
        }
    }

    mMessage = new Message("Hello World".getBytes());
}

@Override
public void onStart() {
    super.onStart();
    ...
    Nearby.getMessagesClient(this).publish(mMessage);
    Nearby.getMessagesClient(this).subscribe(mMessageListener);
}

@Override
public void onStop() {
    Nearby.getMessagesClient(this).unpublish(mMessage);
    Nearby.getMessagesClient(this).unsubscribe(mMessageListener);
    ...
    super.onStop();
}

發布訊息

如要發布訊息，請呼叫 Nearby.getMessagesClient(Activity).publish()，並傳遞訊息位元組陣列。建議您將訊息大小控制在 3 KB 以下，這樣我們才能更快傳送這些訊息，但我們也支援最多 100 KB 的應用程式。這項服務不適用於交換較大的物件，例如相片和影片。

您可以選擇呼叫 PublishOptions.setStrategy() 來設定要使用的策略。

以下範例示範如何呼叫 publish() 以傳送小型文字訊息：

private void publish(String message) {
    Log.i(TAG, "Publishing message: " + message);
    mActiveMessage = new Message(message.getBytes());
    Nearby.getMessagesClient(this).publish(mActiveMessage);
}

取消發布訊息

如要取消發布訊息，請呼叫 unpublish()。應用程式至少應在其 onStop() 方法中呼叫 unpublish。傳遞用於發布相同的 Message 物件 (本例為 mActiveMessage)。

以下程式碼範例示範如何呼叫 unpublish()：

private void unpublish() {
    Log.i(TAG, "Unpublishing.");
    if (mActiveMessage != null) {
        Nearby.getMessagesClient(this).unpublish(mActiveMessage);
        mActiveMessage = null;
    }
}

訂閱訊息

如要訂閱其他裝置傳送的訊息，請呼叫 Nearby.getMessagesClient(Activity).subscribe()。您必須傳遞 MessageListener，才能處理接收已訂閱訊息的作業。

您可以選擇呼叫 SubscribeOptions.setStrategy() 來設定要使用的策略。

以下範例示範如何訂閱訊息：

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.");
    Nearby.getMessagesClient(this).subscribe(mMessageListener, options);
}

取消訂閱

如要取消訂閱並停止接收裝置訊息，請呼叫 Nearby.getMessagesClient(Activity).unsubscribe()。傳遞用於訂閱的相同 MessageListener 物件 (本例為 mMessageListener)。

以下程式碼範例示範如何取消訂閱：

private void unsubscribe() {
    Log.i(TAG, "Unsubscribing.");
    Nearby.getMessagesClient(this).unsubscribe(mMessageListener);
}