Publicar e assinar

A API Nearby Messages é uma API de publicação e assinatura que permite que dispositivos próximos troquem pequenos payloads de dados. Depois que um dispositivo publica uma mensagem, os dispositivos por perto podem recebê-la. Este guia mostra todas as funcionalidades que seu app precisa implementar para publicar e se inscrever em mensagens usando a API Nearby Messages.

O conjunto de dispositivos por perto é determinado pela troca de pequenos tokens por Bluetooth. Quando um dispositivo detecta um token de um dispositivo por perto, ele o envia ao servidor da API Nearby Messages para validação e para 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 descoberta de dispositivos e se as mídias são usadas para transmitir e/ou procurar 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 em mídias e controlar se é preciso transmitir ou verificar, é necessário transmitir parâmetros adicionais ao criar publicações e assinaturas.

Durante a publicação e a inscrição, uma notificação "O Nearby está em uso" é apresentada, informando aos usuários que o Nearby está ativo. Essa notificação é exibida apenas quando um ou mais apps estão usando o recurso, 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 Por Perto.
  • Forçar um app a parar de usar o recurso Compartilhar por Proximidade.
  • Acesse 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 Nearby Messages podem 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. O app precisa sempre fazer 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 que as mensagens tenham menos de 3 KB, porque elas são entregues mais rapidamente. No entanto, podemos aceitar até 100 KB para apps que precisam desse tamanho. Esse serviço não é destinado à troca de objetos maiores, como fotos e vídeos.

Se quiser, 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 o cancelamento de publicação no método onStop(). Transmita o mesmo objeto Message que foi 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;
    }
}

Assinar mensagens

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

Se quiser, 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);
}

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 a seguir demonstra como cancelar a inscrição:

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