發布及訂閱

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

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

應用程式可以控制用於探索裝置的一組媒介，以及是否使用媒介廣播權杖和/或掃描權杖。根據預設，廣播及掃描會為所有媒體執行。如要探索子集或媒介，以及控制是否要播送或掃描，您必須在建立出版品和訂閱項目時傳送其他參數。

主動發布及訂閱時，系統會顯示「鄰近分享功能正在使用中」通知，告知使用者 Nearby 已啟用。只有在一或多個應用程式正在使用鄰近分享功能時，系統才會顯示這則通知。在不需要使用鄰近分享功能時，使用者有機會節省電池電力。這項服務為使用者提供以下選項：

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

使用者強制應用程式停止使用 Nearby 時，可以使用 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() 方法中呼叫取消發布。傳遞先前用於發布的 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);
}