Nearby Messages è un'API publish-subscribe che consente ai dispositivi nelle vicinanze di scambiare piccoli payload di dati. Quando 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 iscriversi ai messaggi utilizzando l'API Nearby Messages.
L'insieme di 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 sono presenti 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 per cercare token. Per impostazione predefinita, la trasmissione e la scansione vengono eseguite su tutti i mezzi. Per eseguire il rilevamento su un sottoinsieme o dei mezzi e per stabilire se trasmettere o scansionare, devi trasmettere parametri aggiuntivi quando crei pubblicazioni e abbonamenti.
Quando pubblichi e ti abboni attivamente, viene visualizzata la notifica "Nelle vicinanze in uso", che informa gli utenti che la funzionalità è attiva. Questa notifica viene visualizzata solo quando una o più app utilizzano attivamente la funzionalità Qui vicino, dando agli utenti la possibilità di preservare la batteria se questa funzionalità non è necessaria. Offre agli utenti le seguenti opzioni:
- Apri un'app per disattivare la funzionalità Qui vicino.
- Forzare l'interruzione dell'utilizzo della funzione Qui vicino a un'app.
- Vai alla schermata Impostazioni nelle vicinanze.
Puoi utilizzare PublishCallback()
e SubscribeCallback()
per ascoltare i casi in cui un utente forza l'interruzione dell'utilizzo della funzionalità Qui vicino. Quando questo succede, 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 della abbonamento BLE in background).
Chiama il numero publish()
e/o subscribe()
per utilizzare l'API Nearby Messages. L'app deve sempre
essere 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. Consigliamo di mantenere i messaggi a meno di 3 kB (che possiamo consegnare più velocemente), ma possiamo supportare fino a 100 kB per le app che ne hanno bisogno. Questo servizio non è concepito per lo 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 piccolo messaggio:
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 richiamare l'annullamento della pubblicazione utilizzando il metodo onStop(). Trasmetti lo stesso oggetto Message utilizzato per pubblicare (mActiveMessage in questo esempio).
Nell'esempio di codice seguente viene mostrata 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 iscriverti ai messaggi da altri dispositivi, chiama il numero Nearby.getMessagesClient(Activity).subscribe(). Dovrai trasmettere un MessageListener per gestire la ricezione dei messaggi a cui hai effettuato l'iscrizione.
Facoltativamente, puoi chiamare SubscribeOptions.setStrategy() per impostare la strategia da utilizzare.
L'esempio seguente mostra l'iscrizione 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 non ricevere più messaggi sul dispositivo, chiama il numero
Nearby.getMessagesClient(Activity).unsubscribe(). Passa lo stesso oggetto MessageListener utilizzato per la sottoscrizione (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);
}