Publicar e assinar

A 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 receber a mensagem. Este guia orienta você sobre todas as funcionalidades que seu app precisa implementar para publicar mensagens e se inscrever em 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 validação e verifica se há mensagens a serem enviadas para o conjunto atual de assinaturas do aplicativo.

Um aplicativo pode controlar o conjunto de meios usados para a descoberta de dispositivos e se os meios são usados para transmitir e/ou verificar tokens. Por padrão, a transmissão e a verificação são feitas em todos os meios. Para fazer a descoberta em um subconjunto ou meios e controlar se a transmissão ou a verificação será feita, é necessário transmitir 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 a 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.
• Navegue até a tela Configurações do recurso "Por perto".

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 método onExpired() é acionado.

Como as APIs de mensagens do app Nearby podem afetar a duração da bateria, elas só podem 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. O app precisa sempre unpublish() e unsubscribe() simetricamente 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 a matriz de bytes da mensagem. Recomendamos manter as mensagens com menos de 3 KB, que podem ser enviadas mais rapidamente, mas podemos oferecer suporte a até 100 KB para apps que precisam. Esse serviço não é destinado a 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);
}

Observação: este exemplo não definiu callbacks para o status da publicação. Para definir um callback, transmita PublishOptions com um PublishCallback válido ao publicar. Você também precisa anexar um OnFailureListener ao final da chamada de publicação, que vai notificar você se a publicação falhou. Por exemplo, se o dispositivo não tiver uma conexão de Internet ativa.

Cancelar a publicação de uma mensagem

Para cancelar a publicação de uma mensagem, chame unpublish(). No mínimo, o app precisa chamar a despublicação 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 para receber mensagens

Para se inscrever em mensagens de outros dispositivos, chame Nearby.getMessagesClient(Activity).subscribe(). Você precisa transmitir um MessageListener para processar o recebimento de mensagens assinadas.

Opcionalmente, chame SubscribeOptions.setStrategy() para definir a estratégia a ser usada.

O exemplo a seguir demonstra como se inscrever em 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);
}

Observação: assim como na publicação, é possível definir um callback para o status da assinatura. Transmita SubscribeOptions com um SubscribeCallback válido ao se inscrever. Também é necessário anexar um OnFailureListener ao final da chamada de inscrição, que vai notificar você se a inscrição falhou. Por exemplo, se o dispositivo não tiver uma conexão de Internet ativa.

Cancelar inscrição

Para cancelar a inscrição e parar de receber mensagens do dispositivo, chame Nearby.getMessagesClient(Activity).unsubscribe(). Transmita o mesmo objeto MessageListener usado para se inscrever (mMessageListener neste exemplo).

O exemplo de código abaixo demonstra como cancelar a inscrição:

private void unsubscribe() {
    Log.i(TAG, "Unsubscribing.");
    Nearby.getMessagesClient(this).unsubscribe(mMessageListener);
}