Nearby Messages ist eine Publish-Subscribe-API, mit der Geräte in der Nähe kleine Datennutzlasten austauschen können. Sobald ein Gerät eine Nachricht veröffentlicht hat, können Geräte in der Nähe sie empfangen. In diesem Leitfaden werden alle Funktionen beschrieben, die Ihre App implementieren muss, um Nachrichten mit der Nearby Messages API zu veröffentlichen und Nachrichten zu abonnieren.
Die Geräte in der Nähe werden 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 Abos der Anwendung zuzustellen sind.
Eine Anwendung kann die Medien steuern, die für die Gerätesuche verwendet werden, und festlegen, ob die Medien zum Übertragen von Tokens und/oder zum Scannen nach Tokens verwendet werden. Standardmäßig werden die Übertragung und das Scannen auf allen Medien ausgeführt. Wenn Sie die Suche auf eine Teilmenge oder bestimmte Medien beschränken und festlegen möchten, ob gesendet oder gescannt werden soll, müssen Sie beim Erstellen von Publikationen und Abos zusätzliche Parameter übergeben.
Wenn Inhalte aktiv veröffentlicht und abonniert werden, wird die Benachrichtigung „Nearby wird verwendet“ angezeigt, die Nutzer darüber informiert, dass Nearby aktiv ist. Diese Benachrichtigung wird nur angezeigt, wenn mindestens eine App Nearby aktiv nutzt. So können Nutzer die Akkulaufzeit verlängern, wenn Nearby nicht benötigt wird. Sie bietet Nutzern die folgenden Optionen:
- Rufen Sie eine App auf, um Nearby zu deaktivieren.
- Sie können erzwingen, dass eine App Nearby nicht mehr verwendet.
- Rufen Sie den Bildschirm Einstellungen für Nearby Share auf.
Mit PublishCallback() und SubscribeCallback() können Sie prüfen, ob ein Nutzer die Verwendung von Nearby in der App erzwungen hat. In diesem Fall wird die Methode onExpired() ausgelöst.
Da die Nearby Messages APIs die Akkulaufzeit beeinträchtigen können, sollten sie nur in einer Vordergrundaktivität verwendet werden (mit Ausnahme von BLE-Hintergrundabonnement).
Rufen Sie publish() und/oder subscribe() auf, um die Nearby Messages API zu verwenden. In Ihrer App sollten unpublish() und unsubscribe() immer symmetrisch in onStop() angeordnet 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 Nearby.getMessagesClient(Activity).publish() auf und übergeben Sie das Byte-Array der Nachricht, um eine Nachricht zu veröffentlichen. Wir empfehlen, die Nachrichten auf weniger als 3 KB zu begrenzen, da sie dann schneller zugestellt werden können. Für Apps, die dies erfordern, 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 gedacht.
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 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, drücken Sie die Taste unpublish(). Ihre App sollte in der Methode onStop() mindestens die Funktion „deaktivieren“ aufrufen. Übergebe dasselbe Message-Objekt, das für die Veröffentlichung verwendet wurde (mActiveMessage in diesem Beispiel).
Im folgenden Codebeispiel wird unpublish() aufgerufen:
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, drücken Sie die Taste Nearby.getMessagesClient(Activity).subscribe(). Du musst einen MessageListener übergeben, um abonnierte Nachrichten zu verarbeiten.
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);
}
Abbestellen
Wenn Sie sich abmelden und keine Gerätenachrichten mehr erhalten möchten, rufen Sie Nearby.getMessagesClient(Activity).unsubscribe() an. Übergebe dasselbe MessageListener-Objekt, das für die Anmeldung verwendet wurde (mMessageListener in diesem Beispiel).
Das folgende Codebeispiel zeigt, wie du den Newsletter abmeldest:
private void unsubscribe() {
Log.i(TAG, "Unsubscribing.");
Nearby.getMessagesClient(this).unsubscribe(mMessageListener);
}