Publicar e assinar

O 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 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 o envia ao servidor do Nearby Messages para validá-lo e verificar se há alguma mensagem a ser entregue para o conjunto atual de assinaturas do aplicativo.

Um aplicativo pode controlar o conjunto de meios usados 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 mídias e controlar se é necessário transmitir ou verificar, você precisa transmitir outros parâmetros 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 é mostrada apenas quando um ou mais apps estão usando o Nearby. Isso oferece 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:

• Acesse um app para desativar o recurso.
• Forçar um app a parar de usar o Proximidade.
• Navegue até a tela Configurações do 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 Nearby Messages têm o potencial de 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 de BLE.

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

Se preferir, 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. Também é preciso anexar um OnFailureListener ao final da chamada de publicação, que vai enviar uma notificação se a publicação falhar. 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, seu app precisa chamar o cancelamento da publicação no método onStop(). Transmita o mesmo objeto Message que foi usado para publicar (neste exemplo, mActiveMessage).

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 se inscrever em mensagens de outros dispositivos, chame Nearby.getMessagesClient(Activity).subscribe(). Você vai precisar transmitir um MessageListener para processar o recebimento de mensagens inscritas.

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

O exemplo a seguir demonstra a inscrição 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, você pode definir um callback para o status da assinatura. Transmita SubscribeOptions com um SubscribeCallback válido ao assinar. Você também precisa adicionar um OnFailureListener ao final da chamada de assinatura, que vai notificar você se a assinatura falhar. 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 que foi usado para fazer a assinatura (neste exemplo, mMessageListener).

O exemplo de código a seguir demonstra o cancelamento da assinatura:

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