Wiadomości w pobliżu to interfejs API publikowania i subskrypcji, który umożliwia urządzeniom w pobliżu wymianę niewielkich ładunków danych. Gdy urządzenie opublikuje wiadomość, urządzenia znajdujące się w pobliżu mogą ją odebrać. W tym przewodniku opisujemy wszystkie funkcje, które musi wdrożyć Twoja aplikacja, by publikować wiadomości i subskrybować je przy użyciu interfejsu w pobliżu.
Zestaw urządzeń w pobliżu jest określany na podstawie wymiany małych tokenów przez Bluetooth. Gdy urządzenie wykryje token z pobliskiego urządzenia, wysyła go do serwera Wiadomości w pobliżu, aby go zweryfikować i sprawdzić, czy są jakieś wiadomości do dostarczenia w przypadku bieżącego zestawu subskrypcji aplikacji.
Aplikacja może kontrolować zbiór nośników używanych do wykrywania urządzeń oraz to, czy mają one być używane do wysyłania tokenów lub skanowania w poszukiwaniu tokenów. Domyślnie transmisja i skanowanie odbywa się w przypadku wszystkich mediów. Aby przeprowadzać wykrywanie na podzbiorze lub mediach i określać, czy mają być rozpowszechniane czy skanowane, musisz przekazać dodatkowe parametry podczas tworzenia publikacji i subskrypcji.
Podczas aktywnego publikowania treści i subskrybowania wyświetla się powiadomienie „W pobliżu jest używane”. Dzięki temu użytkownicy są informowani, że funkcja W pobliżu jest aktywna. To powiadomienie wyświetla się tylko wtedy, gdy co najmniej jedna aplikacja aktywnie korzysta z funkcji W pobliżu. Dzięki temu użytkownicy mogą wydłużyć czas pracy na baterii, jeśli funkcja W pobliżu nie jest potrzebna. Daje użytkownikom te opcje:
- Przejdź do aplikacji, aby wyłączyć funkcję W pobliżu.
- Wymuszaj, aby aplikacja przestała korzystać z funkcji W pobliżu.
- Otwórz ekran Ustawienia W pobliżu.
Możesz używać interfejsów PublishCallback()
i SubscribeCallback()
, aby wykrywać sytuacje, w których użytkownik wymusza wyłączenie aplikacji W pobliżu. W takim przypadku uruchamiana jest metoda onExpired()
.
Ponieważ interfejsy API Wiadomości w pobliżu mogą wpływać na czas pracy na baterii, należy ich używać tylko w ramach aktywności na pierwszym planie (z wyjątkiem subskrypcji BLE w tle).
Wywołaj metodę publish()
lub subscribe()
, aby użyć interfejsu w pobliżu do interfejsu API Wiadomości w pobliżu. Aplikacja powinna zawsze być symetrycznie unpublish()
i unsubscribe()
w 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();
}
Opublikuj wiadomość
Aby opublikować wiadomość, wywołaj metodę Nearby.getMessagesClient(Activity).publish()
przekazującą tablicę bajtów wiadomości. Zalecamy, aby długość wiadomości nie przekraczała 3 KB, ponieważ możemy ją dostarczyć szybciej. W przypadku aplikacji, które tego potrzebują, obsługujemy do 100 KB. Ta usługa nie służy do wymiany
większych obiektów, takich jak zdjęcia czy filmy.
Opcjonalnie możesz wywołać PublishOptions.setStrategy()
, aby ustawić strategię, której chcesz używać.
Poniższy przykład pokazuje wywoływanie metody publish()
w celu wysłania małego SMS-a:
private void publish(String message) {
Log.i(TAG, "Publishing message: " + message);
mActiveMessage = new Message(message.getBytes());
Nearby.getMessagesClient(this).publish(mActiveMessage);
}
Cofanie publikacji wiadomości
Aby cofnąć publikację wiadomości, zadzwoń pod numer unpublish()
. Aplikacja powinna przynajmniej wywoływać w metodzie onStop()
cofnięcie publikacji. Przekaż ten sam obiekt Message
, który został użyty do opublikowania (w tym przykładzie mActiveMessage
).
Oto przykładowy kod, który przedstawia wywołanie metody unpublish()
:
private void unpublish() {
Log.i(TAG, "Unpublishing.");
if (mActiveMessage != null) {
Nearby.getMessagesClient(this).unpublish(mActiveMessage);
mActiveMessage = null;
}
}
Subskrybowanie wiadomości
Aby zasubskrybować wiadomości z innych urządzeń, zadzwoń pod numer Nearby.getMessagesClient(Activity).subscribe()
. Aby odbierać subskrybowane wiadomości, musisz przekazywać parametr MessageListener
.
Opcjonalnie możesz wywołać SubscribeOptions.setStrategy()
, aby ustawić strategię, której chcesz używać.
Ten przykład ilustruje subskrybowanie wiadomości:
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);
}
Anuluj subskrypcję
Aby anulować subskrypcję i przestać otrzymywać wiadomości na urządzeniu, zadzwoń pod numer Nearby.getMessagesClient(Activity).unsubscribe()
. Przekaż ten sam obiekt MessageListener
, który został użyty do subskrybowania (w tym przykładzie mMessageListener
).
Anulowanie subskrypcji wygląda na przykładzie tego kodu:
private void unsubscribe() {
Log.i(TAG, "Unsubscribing.");
Nearby.getMessagesClient(this).unsubscribe(mMessageListener);
}