Publicar e assinar

O Nearby Messages é uma API de publicação/assinatura que permite trocar dispositivos por perto pequenos payloads de dados. Quando um dispositivo publica uma mensagem, os dispositivos próximos podem receber a mensagem. Este guia explica todos os recursos seu app precisa implementar para publicar mensagens 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 para o servidor do Nearby Messages para validá-lo e verificar se há algum 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 tokens e/ou procurar tokens. Por padrão, a transmissão e a verificação são feitas em todos os meios. Afazeres descoberta em um subconjunto ou mídias e para controlar a transmissão ou a verificação, é necessário transmitir parâmetros adicionais ao criar publicações e assinaturas.

Ao publicar e assinar ativamente, um "Por perto está em uso" notificação é exibido, informando aos usuários que o Nearby está ativo. Esta notificação é exibido apenas quando um ou mais apps estão usando o "Por perto" ativamente, oferecendo aos usuários uma chance de conservar a duração da bateria se o recurso "Por perto" não for necessário. Oferece os usuários com as seguintes opções:

• Navegue até um app para desativar o "Por perto".
• Forçar um app a parar de usar o "Por perto".
• Navegue até a tela Configurações do Nearby.

Você pode usar o PublishCallback() e SubscribeCallback() para detectar casos em que um usuário força o app a parar de usar o "Por perto". Quando isso acontecer, 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 de assinatura em segundo plano de BLE.

Chamar publish() e/ou subscribe() para usar a API Nearby Messages. Seu app deve sempre unpublish() simétrico 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(). passando a matriz de bytes da mensagem. Recomendamos manter as mensagens em menos de 3 KB - estas mensagens podemos entregar mais rapidamente - mas podemos oferecer até 100 KB para e apps que precisam dela. Este serviço não se destina à troca de objetos maiores, como como fotos e vídeos.

Também é possível chamar PublishOptions.setStrategy(). para definir a estratégia usar.

O exemplo a seguir demonstra como chamar publish() para enviar um pequeno texto mensagem:

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 de retorno, transmita PublishOptions com um PublishCallback válido durante a publicação. Também é necessário anexar um objeto OnFailureListener ao final da chamada de publicação, que vai notificar você se a publicação tiver 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, sua app precisa chamar o cancelamento da publicação no onStop() . Transmita o mesmo Message objeto que foi usado para publicar (mActiveMessage neste exemplo).

O exemplo de código abaixo mostra como chamar unpublish():

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

Inscrever-se nas mensagens

Para se inscrever em mensagens de outros dispositivos, chame Nearby.getMessagesClient(Activity).subscribe(). Você precisará passar MessageListener para lidar com o recebimento de mensagens em que se inscreveu.

Também é possível chamar SubscribeOptions.setStrategy() para definir a estratégia usar.

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

Observação :assim como na publicação, é possível definir um callback para o status do assinatura. Passe SubscribeOptions com um SubscribeCallback válido ao se inscrever. Também é necessário anexar um objeto OnFailureListener ao final da chamada de inscrição, que o notificará se o inscrito 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 no dispositivo, ligue Nearby.getMessagesClient(Activity).unsubscribe() Transmita o mesmo MessageListener objeto que foi usado para fazer a assinatura (neste exemplo, mMessageListener).

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