Publicar e assinar

A API Nearby Messages é uma API de publicação/assinatura que permite que dispositivos próximos troquem pequenos payloads de dados. Quando um dispositivo publica uma mensagem, os dispositivos próximos podem recebê-la. Este guia explica toda a funcionalidade 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 por perto, ele envia o token para o servidor da API Nearby Messages para validá-lo e verificar se há mensagens a serem entregues para o conjunto atual de assinaturas 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 verificar 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 mídias e controlar se a transmissão ou a verificação será feita, 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ó é exibida quando um ou mais apps estão usando o Nearby ativamente, aos usuários a chance de conservar a duração da bateria se o Nearby não for necessário. Ela oferece aos usuários as seguintes opções:

Navegar até um app para desativar o Nearby.
Forçar um app a parar de usar o Nearby.
Navegar até a tela Configurações do Nearby.

Você pode usar PublishCallback() e SubscribeCallback() para detectar casos em que um usuário força o app a parar de usar o Nearby. Quando isso acontece, o onExpired() método é acionado.

Como as APIs Nearby Messages têm o potencial de afetar a duração da bateria, elas só devem ser usadas em uma atividade em primeiro plano (com exceção da assinatura em segundo plano do BLE).

Chame publish() e/ou subscribe() para usar a API Nearby Messages. Seu app sempre deve simetricamente unpublish() e unsubscribe() 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. Essas mensagens podem ser entregues mais rapidamente, mas podemos oferecer suporte a até 100 KB para apps que precisam. Esse serviço não é destinado à troca de objetos maiores, como fotos e vídeos.

Você pode chamar PublishOptions.setStrategy() para definir a estratégia a ser usada.

O exemplo a seguir demonstra a chamada de 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, seu app precisa chamar a publicação cancelada no onStop() método. Transmita o mesmo Message objeto que foi usado para publicar (mActiveMessage neste exemplo).

O exemplo de código a seguir mostra a chamada de unpublish():

private void unpublish() {
    Log.i(TAG, "Unpublishing.");
    if (mActiveMessage != null) {
        Nearby.getMessagesClient(this).unpublish(mActiveMessage);
        mActiveMessage = null;
    }
}

Assinar mensagens

Para assinar mensagens de outros dispositivos, chame Nearby.getMessagesClient(Activity).subscribe(). Você precisará transmitir um MessageListener para processar o recebimento de mensagens assinadas.

Você pode chamar SubscribeOptions.setStrategy() para definir a estratégia a ser usada.

O exemplo a seguir demonstra a assinatura de 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, chame Nearby.getMessagesClient(Activity).unsubscribe(). Transmita o mesmo MessageListener objeto que foi usado para assinar (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);
}