Publicar e assinar

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);
}