Veröffentlichen und abonnieren

Nearby Messages ist eine Publish/Subscribe-API, mit der Geräte in der Nähe kleine Daten-Nutzlasten austauschen können. Sobald ein Gerät eine Nachricht veröffentlicht, können Geräte in der Nähe diese Nachricht empfangen. In dieser Anleitung wird die gesamte Funktionalität beschrieben, die Ihre App implementieren muss, um Nachrichten zu veröffentlichen und Nachrichten mit der 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 aktuelle Menge der Abonnements der Anwendung bereitgestellt werden müssen.

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

Wenn Sie aktiv veröffentlichen und abonnieren, wird die Benachrichtigung „Nearby wird verwendet“ angezeigt, die Nutzer darüber informiert, dass Nearby aktiv ist. Diese Benachrichtigung wird nur angezeigt, wenn eine oder mehrere Apps Nearby aktiv verwenden. So können Nutzer die Akkulaufzeit verlängern, wenn Nearby nicht benötigt wird. Nutzer haben folgende Möglichkeiten:

• Zu einer App wechseln, um Nearby zu deaktivieren.
• Eine App zwingen, die Verwendung von Nearby zu beenden.
• Zum Bildschirm Nearby-Einstellungen wechseln.

Mit PublishCallback() und SubscribeCallback() können Sie auf Fälle reagieren, in denen ein Nutzer die App zwingt, die Verwendung von Nearby zu beenden. In diesem Fall wird die onExpired() Methode ausgelöst.

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

Rufen Sie publish() und/oder subscribe() auf, um die Nearby Messages API zu verwenden. Ihre App sollte immer symmetrisch unpublish() und unsubscribe() in 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();
}

Nachricht veröffentlichen

Rufen Sie Nearby.getMessagesClient(Activity).publish() auf und übergeben Sie Ihr Nachrichten-Byte-Array, um eine Nachricht zu veröffentlichen. 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 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.

Im folgenden Beispiel wird gezeigt, wie publish() aufgerufen wird, um eine kurze Textnachricht zu senden:

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

Hinweis: In diesem Beispiel wurden keine Callbacks für den Status der Veröffentlichung festgelegt. Wenn Sie einen Callback festlegen möchten, übergeben Sie PublishOptions mit einem gültigen PublishCallback beim Veröffentlichen. Außerdem sollten Sie am Ende des Veröffentlichungsaufrufs einen OnFailureListener anhängen, der Sie benachrichtigt, wenn die Veröffentlichung fehlgeschlagen ist. Das kann beispielsweise der Fall sein, wenn das Gerät keine aktive Internetverbindung hat.

Veröffentlichung einer Nachricht aufheben

Rufen Sie unpublish() auf, um die Veröffentlichung einer Nachricht aufzuheben. Ihre App sollte `unpublish` mindestens in der Methode onStop() aufrufen. Übergeben Sie dasselbe Message Objekt, das zum Veröffentlichen verwendet wurde (mActiveMessage in diesem Beispiel).

Im folgenden Codebeispiel wird gezeigt, wie unpublish() aufgerufen wird:

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

Nachrichten abonnieren

Rufen Sie Nearby.getMessagesClient(Activity).subscribe() auf, um Nachrichten von anderen Geräten zu abonnieren. 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 Nachrichten abonniert werden:

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

Hinweis: Wie beim Veröffentlichen können Sie auch einen Callback für den Status des Abonnements festlegen. Übergeben Sie SubscribeOptions mit einem gültigen SubscribeCallback beim Abonnieren. Außerdem sollten Sie am Ende des Abonnementaufrufs einen OnFailureListener anhängen, der Sie benachrichtigt, wenn das Abonnieren fehlgeschlagen ist. Das kann beispielsweise der Fall sein, wenn das Gerät keine aktive Internetverbindung hat.

Abbestellen

Rufen Sie Nearby.getMessagesClient(Activity).unsubscribe() auf, um das Abonnement zu beenden und keine Gerätenachrichten mehr zu empfangen. Übergeben Sie dasselbe MessageListener Objekt, das zum Abonnieren verwendet wurde (mMessageListener in diesem Beispiel).

Im folgenden Codebeispiel wird gezeigt, wie das Abonnement beendet wird:

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