O Nearby Messages é uma API de publicação e inscrição que permite que dispositivos próximos troquem pequenos payloads de dados. Depois que um dispositivo publica uma mensagem, os dispositivos próximos podem recebê-la. Neste guia, você vai conhecer todas as funcionalidades que seu app precisa implementar para publicar e assinar mensagens usando a API Nearby Messages.
O conjunto de dispositivos próximos é determinado pela troca de pequenos tokens por Bluetooth. Quando um dispositivo detecta um token de um dispositivo próximo, ele envia o token ao servidor do Nearby Messages para validar e verificar se há mensagens a serem entregues para o conjunto atual de inscrições do aplicativo.
Um aplicativo pode controlar o conjunto de mídias usadas para a descoberta de dispositivos e se as mídias são usadas para transmitir tokens e/ou procurar tokens. Por padrão, a transmissão e a verificação são feitas em todas as mídias. Para fazer a descoberta em um subconjunto ou em mídias e controlar se é necessário transmitir ou verificar, transmita parâmetros adicionais ao criar publicações e assinaturas.
Ao publicar e assinar ativamente, uma notificação "O Nearby está em uso" é apresentada, informando aos usuários que o Nearby está ativo. Essa notificação só aparece quando um ou mais apps estão usando o recurso Por perto ativamente, aos usuários a chance de economizar bateria se o recurso não for necessário. Ele oferece aos usuários as seguintes opções:
- Navegue até um app para desativar o recurso "Por perto".
- Forçar um app a parar de usar o Nearby.
- Acesse a tela Configurações de dispositivos por perto.
Você pode usar PublishCallback()
e SubscribeCallback()
para detectar casos em que um usuário força a interrupção do uso do Nearby pelo app. Quando isso
acontece, o método
onExpired()
é acionado.
Como as APIs Nearby Messages podem afetar a duração da bateria, elas só devem ser usadas em uma atividade em primeiro plano, exceto a assinatura em segundo plano do BLE.
Chame publish()
e/ou subscribe()
para usar a API Nearby Messages. O app precisa sempre
unpublish()
e unsubscribe()
de maneira simétrica em 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();
}
Publicar uma mensagem
Para publicar uma mensagem, chame Nearby.getMessagesClient(Activity).publish()
transmitindo sua matriz de bytes de mensagem. Recomendamos manter as mensagens com menos de
3 KB. Assim, podemos entregá-las mais rápido. No entanto, podemos oferecer suporte a até 100 KB para
apps que precisam disso. Esse serviço não foi criado para trocar objetos maiores, como fotos e vídeos.
Opcionalmente, chame PublishOptions.setStrategy()
para definir a estratégia
a ser usada.
O exemplo a seguir demonstra como chamar publish()
para enviar uma pequena mensagem de texto:
private void publish(String message) {
Log.i(TAG, "Publishing message: " + message);
mActiveMessage = new Message(message.getBytes());
Nearby.getMessagesClient(this).publish(mActiveMessage);
}
Cancelar a publicação de uma mensagem
Para cancelar a publicação de uma mensagem, chame unpublish()
. No mínimo, o
app precisa chamar "unpublish" no método onStop()
. Transmita o mesmo objeto Message
usado para publicar (mActiveMessage
neste exemplo).
O exemplo de código a seguir mostra como chamar unpublish()
:
private void unpublish() {
Log.i(TAG, "Unpublishing.");
if (mActiveMessage != null) {
Nearby.getMessagesClient(this).unpublish(mActiveMessage);
mActiveMessage = null;
}
}
Inscrever-se em mensagens
Para assinar mensagens de outros dispositivos, chame Nearby.getMessagesClient(Activity).subscribe()
. Você precisará transmitir
um MessageListener
para processar o recebimento de mensagens inscritas.
Opcionalmente, chame SubscribeOptions.setStrategy()
para definir a estratégia
a ser usada.
O exemplo a seguir demonstra como assinar mensagens:
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);
}
Cancelar inscrição
Para cancelar a inscrição e parar de receber mensagens do dispositivo, ligue para
Nearby.getMessagesClient(Activity).unsubscribe()
. Transmita o mesmo objeto
MessageListener
usado para fazer a inscrição (mMessageListener
neste exemplo).
O exemplo de código a seguir demonstra o cancelamento da inscrição:
private void unsubscribe() {
Log.i(TAG, "Unsubscribing.");
Nearby.getMessagesClient(this).unsubscribe(mMessageListener);
}