Veröffentlichen und abonnieren

Nearby Messages ist eine Publish/Subscribe-API, mit der Geräte in der Nähe kleine Datenmengen austauschen können. Sobald ein Gerät eine Nachricht veröffentlicht hat, können Geräte in der Nähe die Nachricht empfangen. In dieser Anleitung werden Sie durch alle Funktionen geführt, die Ihre App implementieren muss, um Nachrichten zu veröffentlichen und Nachrichten über die Nearby Messages API zu abonnieren.

Die Menge der Geräte in der Nähe wird durch den Austausch kleiner Tokens über Bluetooth bestimmt. Wenn ein Gerät ein Token von einem Gerät in der Nähe erkennt, sendet es das Token an den Nearby Messages-Server, um es zu validieren und zu prüfen, ob Nachrichten für die aktuellen Abonnements der Anwendung gesendet werden müssen.

Eine Anwendung kann die für die Geräteerkennung verwendeten Medien sowie die Verwendung der Medien zum Senden von Tokens und/oder zum Scannen nach Tokens steuern. Standardmäßig erfolgt die Übertragung und das Scannen auf allen Media. Wenn Sie die Erkennung auf eine Teilmenge oder bestimmte Media beschränken und festlegen möchten, ob gesendet oder gescannt werden soll, müssen Sie beim Erstellen von Publikationen und Abonnements zusätzliche Parameter übergeben.

Wenn Sie aktiv veröffentlichen und abonnieren, wird die Benachrichtigung „Nearby wird verwendet“ angezeigt, um Nutzer darüber zu informieren, dass Nearby aktiv ist. Diese Benachrichtigung wird nur angezeigt, wenn eine oder mehrere Apps aktiv Nearby verwenden. So haben Nutzer die Möglichkeit, Akku zu sparen, wenn Nearby nicht benötigt wird. Sie bietet Nutzern die folgenden Optionen:

  • Rufen Sie eine App auf, um die Funktion „In der Nähe“ zu deaktivieren.
  • Erzwingen Sie das Beenden der Nearby-Funktion für eine App.
  • Rufen Sie den Bildschirm Einstellungen für Geräte in der Nähe auf.

Mit PublishCallback() und SubscribeCallback() können Sie erfassen, wenn ein Nutzer die App zwingt, Nearby zu beenden. In diesem Fall wird die Methode onExpired() ausgelöst.

Da die Nearby Messages APIs die Akkulaufzeit beeinträchtigen können, sollten sie nur über eine Vordergrundaktivität verwendet werden (mit Ausnahme von BLE background subscribe).

Rufen Sie publish() und/oder subscribe() auf, um die Nearby Messages API zu verwenden. Ihre App sollte immer symmetrisch unpublish() und unsubscribe() in onStop() sein.

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

Nachricht veröffentlichen

Rufen Sie zum Veröffentlichen einer Nachricht Nearby.getMessagesClient(Activity).publish() auf und übergeben Sie Ihr Nachrichten-Byte-Array. Wir empfehlen, die Nachrichten auf weniger als 3 KB zu beschränken, da wir diese Nachrichten schneller zustellen können. Für Apps, die es benötigen, können wir jedoch auch Nachrichten mit einer Größe von bis zu 100 KB unterstützen. Dieser Dienst ist nicht für den Austausch größerer Objekte wie Fotos und Videos vorgesehen.

Optional können Sie PublishOptions.setStrategy() aufrufen, um die zu verwendende Strategie festzulegen.

Das folgende Beispiel zeigt, wie publish() aufgerufen wird, um eine kurze SMS zu senden:

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

Veröffentlichung einer Mitteilung aufheben

Wenn Sie die Veröffentlichung einer Mitteilung aufheben möchten, rufen Sie unpublish() an. Ihre App sollte die Methode onStop() mindestens einmal aufrufen, um die Veröffentlichung aufzuheben. Übergeben Sie dasselbe Message-Objekt, das zum Veröffentlichen verwendet wurde (mActiveMessage in diesem Beispiel).

Das folgende Codebeispiel zeigt, wie unpublish() aufgerufen wird:

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

Nachrichten abonnieren

Wenn Sie Nachrichten von anderen Geräten abonnieren möchten, rufen Sie Nearby.getMessagesClient(Activity).subscribe() an. Sie müssen einen MessageListener übergeben, um abonnierte Nachrichten zu empfangen.

Optional können Sie SubscribeOptions.setStrategy() aufrufen, um die zu verwendende Strategie festzulegen.

Im folgenden Beispiel wird gezeigt, wie Sie Nachrichten abonnieren:

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

Abbestellen

Wenn Sie das Abo kündigen und keine Gerätenachrichten mehr erhalten möchten, rufen Sie Nearby.getMessagesClient(Activity).unsubscribe() an. Übergeben Sie dasselbe MessageListener-Objekt, das zum Abonnieren verwendet wurde (mMessageListener in diesem Beispiel).

Das folgende Codebeispiel zeigt, wie Sie sich abmelden:

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