Nearby Messages è un'API di pubblicazione e iscrizione 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 abbonarsi ai 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 al server Nearby Messages per convalidarlo e verificare se ci sono messaggi da recapitare per l'insieme attuale di abbonamenti dell'applicazione.
Un'applicazione può controllare l'insieme di mezzi utilizzati per il rilevamento dei dispositivi e se i mezzi vengono utilizzati per trasmettere token e/o cercare token. Per impostazione predefinita, la trasmissione e la scansione vengono eseguite su tutti i mezzi. Per eseguire il rilevamento su un sottoinsieme o su supporti e per controllare se trasmettere o eseguire la scansione, devi trasmettere parametri aggiuntivi quando crei pubblicazioni e abbonamenti.
Durante la pubblicazione e l'iscrizione attive, viene visualizzata una notifica "Qui vicino è in uso" che informa gli utenti che la funzionalità è attiva. Questa notifica viene visualizzata solo quando una o più app utilizzano attivamente Nearby, offrendo agli utenti la possibilità di risparmiare batteria se Nearby non è necessario. Fornisce agli utenti le seguenti opzioni:
- Vai a un'app per disattivare la funzionalità Nelle vicinanze.
- Forzare l'interruzione dell'utilizzo di Nearby da parte di un'app.
- Vai alla schermata Impostazioni nelle vicinanze.
Puoi utilizzare PublishCallback()
e SubscribeCallback()
per rilevare i casi in cui un utente forza l'app a interrompere l'utilizzo di Nearby. Quando ciò
accade, viene
attivato il metodo
onExpired().
Poiché le API Nearby Messages possono influire sulla durata della batteria, devono essere utilizzate solo da un'attività in primo piano (ad eccezione di BLE background subscribe).
Chiama publish()
e/o subscribe()
per utilizzare l'API Nearby Messages. La tua app deve sempre
essere simmetrica 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 al di sotto dei 3 KB, in modo da poterli recapitare più rapidamente, ma possiamo supportare fino a 100 KB per le app che ne hanno bisogno. Questo servizio non è pensato per lo scambio di oggetti più grandi
come foto e video.
Puoi facoltativamente chiamare PublishOptions.setStrategy()
per impostare la strategia
da utilizzare.
L'esempio seguente mostra la chiamata a publish() per inviare un piccolo messaggio
di testo:
private void publish(String message) {
Log.i(TAG, "Publishing message: " + message);
mActiveMessage = new Message(message.getBytes());
Nearby.getMessagesClient(this).publish(mActiveMessage);
}
Annullare la pubblicazione di un messaggio
Per annullare la pubblicazione di un messaggio, chiama il numero unpublish(). Come minimo, la tua
app deve chiamare l'annullamento della pubblicazione nel metodo
onStop(). Passa lo stesso oggetto Message
utilizzato per la pubblicazione (mActiveMessage in questo esempio).
Il seguente esempio di codice mostra la chiamata a unpublish():
private void unpublish() {
Log.i(TAG, "Unpublishing.");
if (mActiveMessage != null) {
Nearby.getMessagesClient(this).unpublish(mActiveMessage);
mActiveMessage = null;
}
}
Iscriviti ai messaggi
Per abbonarti ai messaggi provenienti da altri dispositivi, chiama il numero Nearby.getMessagesClient(Activity).subscribe(). Per gestire la ricezione dei messaggi a cui hai effettuato l'iscrizione, devi superare
un MessageListener.
Puoi facoltativamente 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 l'iscrizione e interrompere la ricezione di messaggi dal dispositivo, chiama
Nearby.getMessagesClient(Activity).unsubscribe(). Passa lo stesso oggetto
MessageListener
utilizzato per l'abbonamento (mMessageListener in questo esempio).
Il seguente esempio di codice mostra l'annullamento dell'iscrizione:
private void unsubscribe() {
Log.i(TAG, "Unsubscribing.");
Nearby.getMessagesClient(this).unsubscribe(mMessageListener);
}