Nearby Messages ist eine Publish-Subscribe-API, mit der Geräte in der Nähe kleine Nutzlasten von Daten austauschen können. Sobald ein Gerät eine Nachricht veröffentlicht hat, können Geräte in der Nähe diese empfangen. In diesem Leitfaden werden alle Funktionen beschrieben, die Ihre App implementieren muss, um Nachrichten zu veröffentlichen und Nachrichten mithilfe der Nearby Messages API zu abonnieren.
Die Gruppe von Geräten 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 Abos der Anwendung gesendet werden können.
Eine Anwendung kann die Gruppe von Medien steuern, die für die Geräteerkennung verwendet werden und ob diese zum Übertragen von Tokens und/oder zum Scannen nach Tokens verwendet werden. Standardmäßig werden Übertragungen und Scans auf allen Medien ausgeführt. Wenn du die Erkennung auf einer Teilmenge oder auf Medien durchführen möchtest und um zu bestimmen, ob gesendet oder gescannt werden soll, musst du beim Erstellen von Publikationen und Abos zusätzliche Parameter übergeben.
Beim aktiven Veröffentlichen und Abonnieren wird die Benachrichtigung „Nearby wird verwendet“ angezeigt, die den Nutzer darüber informiert, dass Nearby aktiv ist. Diese Benachrichtigung wird nur angezeigt, wenn eine oder mehrere Apps Nearby aktiv verwenden. So haben Nutzer die Möglichkeit, den Akku zu schonen, wenn Nearby nicht benötigt wird. Sie bietet Nutzern folgende Möglichkeiten:
- Rufen Sie eine App auf, um Nearby zu deaktivieren.
- Erzwingen, dass eine App Nearby nicht mehr verwendet.
- Gehen Sie zum Bildschirm Nearby-Einstellungen.
Sie können PublishCallback() und SubscribeCallback() verwenden, um Fälle zu erfassen, in denen ein Nutzer die Verwendung von Nearby durch die App beendet. In diesem Fall wird die Methode onExpired() ausgelöst.
Da die Nearby Messages APIs die Akkulaufzeit beeinträchtigen können, sollten sie nur bei einer Aktivität im Vordergrund verwendet werden (mit Ausnahme von BLE-Abos im Hintergrund).
Rufen Sie publish() und/oder subscribe() auf, um die Nearby Messages API zu verwenden. Die Anwendung sollte immer symmetrisch unpublish() und unsubscribe() in onStop() enthalten 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 Nachrichtenbyte-Array. Wir empfehlen, die Nachrichten auf weniger als 3 KB zu beschränken – diese Nachrichten können wir schneller senden. Wir können aber bis zu 100 KB für Anwendungen unterstützen, die sie benötigen. Dieser Dienst ist nicht für den Austausch größerer Objekte wie Fotos und Videos gedacht.
Sie können optional PublishOptions.setStrategy() aufrufen, um die zu verwendende Strategie festzulegen.
Das folgende Beispiel zeigt, 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);
}
Veröffentlichung einer Mitteilung aufheben
Rufen Sie unpublish() auf, um die Veröffentlichung einer Mitteilung aufzuheben. Ihre App sollte mindestens den Befehl „Unpublish“ in ihrer Methode onStop() aufrufen. Übergeben Sie dasselbe Message-Objekt, das für die Veröffentlichung verwendet wurde (in diesem Beispiel mActiveMessage).
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. Du musst einen MessageListener übergeben, um abonnierte Nachrichten zu empfangen.
Sie können optional SubscribeOptions.setStrategy() aufrufen, um die zu verwendende Strategie festzulegen.
Im folgenden Beispiel wird das Abonnieren von Nachrichten veranschaulicht:
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 Nachrichten mehr auf dem Gerät erhalten möchten, rufen Sie Nearby.getMessagesClient(Activity).unsubscribe() auf. Übergib dasselbe MessageListener-Objekt, das zum Abonnieren verwendet wurde (in diesem Beispiel mMessageListener).
Im folgenden Codebeispiel wird das Kündigen des Abos veranschaulicht:
private void unsubscribe() {
Log.i(TAG, "Unsubscribing.");
Nearby.getMessagesClient(this).unsubscribe(mMessageListener);
}