發布及訂閱

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

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

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

主動發布及訂閱時，系統會顯示「鄰近分享正在使用中」通知，告知使用者鄰近分享已啟用。只有在有一或多個應用程式主動使用「鄰近分享」時，系統才會顯示這則通知，讓使用者在不需要「鄰近分享」時節省電量。使用者可選擇下列選項：

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

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

Nearby Messages API 可能會影響電池續航力，因此只能從前景活動使用 (BLE 背景訂閱除外)。

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

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

注意： 這個範例尚未設定發布狀態的回呼。如要設定回呼，請在發布時傳遞 PublishOptions 和有效的 PublishCallback。您也應該在發布呼叫的結尾附加 OnFailureListener ，這樣一來，如果發布失敗，您就會收到通知。例如裝置未連上網際網路。

取消發布訊息

如要取消發布訊息，請呼叫 unpublish()。應用程式至少應在 onStop() 方法中呼叫取消發布。傳遞用於發布的相同 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);
}

注意： 與發布作業相同，您可以為訂閱狀態設定回呼。訂閱時，請傳遞有效的 SubscribeCallback SubscribeOptions。您也應在訂閱呼叫的結尾附加 OnFailureListener，以便在訂閱失敗時收到通知。例如裝置未連上網際網路。

取消訂閱

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

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

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