Nearby Messages è un'API di pubblicazione e sottoscrizione che consente ai dispositivi nelle vicinanze di scambiare piccoli payload di dati. Una volta che un dispositivo pubblica un messaggio, i dispositivi nelle vicinanze possono riceverlo. Questa guida illustra tutte le funzionalità che la tua app deve implementare per pubblicare messaggi e sottoscrivere messaggi utilizzando l'API Nearby Messages.
L'insieme dei dispositivi nelle vicinanze è determinato dallo scambio di piccoli token tramite Bluetooth. Quando un dispositivo rileva un token da un dispositivo nelle vicinanze, lo invia il token al server Nearby Messages per convalidarlo e verificare se sono presenti eventuali messaggi da recapitare per l'insieme attuale di sottoscrizioni dell'applicazione.
Un'applicazione può controllare l'insieme dei supporti utilizzati per il rilevamento dei dispositivi e se i supporti vengono utilizzati per trasmettere token e/o eseguire la scansione dei token. Per impostazione predefinita, la trasmissione e la scansione vengono eseguite su tutti i supporti. Per eseguire il rilevamento su un sottoinsieme di supporti e per controllare se trasmettere o eseguire la scansione, devi passare parametri aggiuntivi quando crei pubblicazioni e sottoscrizioni.
Quando la pubblicazione e la sottoscrizione sono attive, viene visualizzata una notifica "Nearby è in uso" che informa gli utenti che Nearby è attivo. Questa notifica viene visualizzata solo quando una o più app utilizzano attivamente Nearby, dando agli utenti la possibilità di risparmiare la durata della batteria se Nearby non è necessario. Fornisce agli utenti le seguenti opzioni:
- Vai a un'app per disattivare Nearby.
- Forza l'interruzione dell'utilizzo di Nearby da parte di un'app.
- Vai alla schermata Impostazioni di Nearby.
Puoi utilizzare PublishCallback()
e SubscribeCallback()
per ascoltare i casi in cui un utente forza l'interruzione dell'utilizzo di Nearby da parte dell'app. In questo
caso, viene attivato il
onExpired()
metodo.
Poiché le API Nearby Messages possono potenzialmente influire sulla durata della batteria, devono essere utilizzate solo da un'attività in primo piano (ad eccezione di sottoscrizione in background BLE).
Chiama publish()
e/o subscribe()
per utilizzare l'API Nearby Messages. La tua app deve sempre
eseguire simmetricamente unpublish()
e 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();
}
Pubblica un messaggio
Per pubblicare un messaggio, chiama Nearby.getMessagesClient(Activity).publish()
passando l'array di byte del messaggio. Ti consigliamo di mantenere i messaggi inferiori a
3 KB, in quanto possiamo recapitarli più velocemente, ma possiamo supportare fino a 100 KB per
le app che ne hanno bisogno. Questo servizio non è destinato allo scambio di oggetti più grandi come
foto e video.
Facoltativamente, puoi chiamare PublishOptions.setStrategy()
per impostare la strategia
da utilizzare.
L'esempio seguente mostra la chiamata a publish() per inviare un breve messaggio di testo:
private void publish(String message) {
Log.i(TAG, "Publishing message: " + message);
mActiveMessage = new Message(message.getBytes());
Nearby.getMessagesClient(this).publish(mActiveMessage);
}
Annulla la pubblicazione di un messaggio
Per annullare la pubblicazione di un messaggio, chiama unpublish(). Come minimo, la tua
app deve chiamare la pubblicazione annullata nel suo onStop()
metodo. Passa lo stesso Message
oggetto utilizzato per la pubblicazione (mActiveMessage in questo esempio).
L'esempio di codice seguente mostra la chiamata a unpublish():
private void unpublish() {
Log.i(TAG, "Unpublishing.");
if (mActiveMessage != null) {
Nearby.getMessagesClient(this).unpublish(mActiveMessage);
mActiveMessage = null;
}
}
Sottoscrivi i messaggi
Per sottoscrivere i messaggi di altri dispositivi, chiama Nearby.getMessagesClient(Activity).subscribe(). Dovrai passare
un MessageListener
per gestire la ricezione dei messaggi sottoscritti.
Facoltativamente, puoi chiamare SubscribeOptions.setStrategy()
per impostare la strategia
da utilizzare.
L'esempio seguente mostra la sottoscrizione ai messaggi:
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);
}
Annulla iscrizione
Per annullare la sottoscrizione e interrompere la ricezione dei messaggi del dispositivo, chiama
Nearby.getMessagesClient(Activity).unsubscribe(). Passa lo stesso
MessageListener
oggetto utilizzato per la sottoscrizione (mMessageListener in questo esempio).
L'esempio di codice seguente mostra l'annullamento della sottoscrizione:
private void unsubscribe() {
Log.i(TAG, "Unsubscribing.");
Nearby.getMessagesClient(this).unsubscribe(mMessageListener);
}