Publier et s'abonner

Nearby Messages est une API de publication/abonnement qui permet aux appareils à proximité d'échanger de petites charges utiles de données. Lorsqu'un appareil publie un message, les appareils à proximité peuvent le recevoir. Ce guide vous explique toutes les fonctionnalités que votre application doit implémenter pour publier des messages et s'y abonner à l'aide de l'API Nearby Messages.

L'ensemble des appareils à proximité est déterminé par l'échange de petits jetons via Bluetooth. Lorsqu'un appareil détecte un jeton provenant d'un appareil à proximité, il l'envoie au serveur Nearby Messages pour le valider et vérifier s'il existe des messages à envoyer pour l'ensemble actuel d'abonnements de l'application.

Une application peut contrôler l'ensemble des supports utilisés pour la découverte d'appareils, et si les supports sont utilisés pour diffuser des jetons et/ou rechercher des jetons. Par défaut, la diffusion et l'analyse sont effectuées sur tous les supports. Pour effectuer une découverte sur un sous-ensemble ou des supports, et pour contrôler si vous devez diffuser ou analyser, vous devez transmettre des paramètres supplémentaires lorsque vous créez des publications et des abonnements.

Lorsque vous publiez et vous abonnez activement, une notification "Nearby est utilisé" s'affiche pour informer les utilisateurs que Nearby est actif. Cette notification ne s'affiche que lorsqu'une ou plusieurs applications utilisent activement Nearby, ce qui permet aux utilisateurs de préserver l'autonomie de la batterie si Nearby n'est pas nécessaire. Il propose les options suivantes aux utilisateurs:

• Accédez à une application pour désactiver Nearby.
• Forcer une application à arrêter d'utiliser À proximité
• Accédez à l'écran Paramètres des appareils à proximité.

Vous pouvez utiliser PublishCallback() et SubscribeCallback() pour écouter les cas où un utilisateur force l'application à arrêter d'utiliser À proximité. Dans ce cas, la méthode onExpired() est déclenchée.

Étant donné que les API Nearby Messages peuvent avoir un impact sur l'autonomie de la batterie, elles ne doivent être utilisées que depuis une activité de premier plan (à l'exception de l'abonnement en arrière-plan BLE).

Appelez publish() et/ou subscribe() pour utiliser l'API Nearby Messages. Votre application doit toujours utiliser unpublish() et unsubscribe() de manière symétrique dans 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();
}

Publier un message

Pour publier un message, appelez Nearby.getMessagesClient(Activity).publish() en transmettant votre tableau d'octets de message. Nous vous recommandons de limiter la taille des messages à moins de 3 ko, car nous pouvons les envoyer plus rapidement. Toutefois, nous acceptons jusqu'à 100 ko pour les applications qui en ont besoin. Ce service n'est pas conçu pour échanger des objets plus volumineux tels que des photos et des vidéos.

Vous pouvez éventuellement appeler PublishOptions.setStrategy() pour définir la stratégie à utiliser.

L'exemple suivant montre comment appeler publish() pour envoyer un petit message texte:

private void publish(String message) {
    Log.i(TAG, "Publishing message: " + message);
    mActiveMessage = new Message(message.getBytes());
    Nearby.getMessagesClient(this).publish(mActiveMessage);
}

Remarque :Cet exemple n'a pas défini de rappels pour l'état de la publication. Pour définir un rappel, transmettez PublishOptions avec un PublishCallback valide lors de la publication. Vous devez également ajouter un OnFailureListener à la fin de l'appel de publication, qui vous avertira si la publication a échoué. Par exemple, si l'appareil n'a pas de connexion Internet active.

Annuler la publication d'un message

Pour annuler la publication d'un message, appelez unpublish(). Au minimum, votre application doit appeler la méthode de désarchivage dans sa méthode onStop(). Transmettez le même objet Message que celui utilisé pour la publication (mActiveMessage dans cet exemple).

L'exemple de code suivant montre comment appeler unpublish():

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

S'abonner aux messages

Pour vous abonner aux messages d'autres appareils, appelez Nearby.getMessagesClient(Activity).subscribe(). Vous devez transmettre un MessageListener pour gérer la réception des messages auxquels vous êtes abonné.

Vous pouvez éventuellement appeler SubscribeOptions.setStrategy() pour définir la stratégie à utiliser.

L'exemple suivant montre comment s'abonner aux messages:

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

Remarque :Comme pour la publication, vous pouvez définir un rappel pour l'état de l'abonnement. Transmettez SubscribeOptions avec un SubscribeCallback valide lors de l'abonnement. Vous devez également ajouter un OnFailureListener à la fin de l'appel d'abonnement, qui vous avertira si l'abonnement a échoué. Par exemple, si l'appareil n'a pas de connexion Internet active.

Se désabonner

Pour vous désabonner et ne plus recevoir de messages de l'appareil, appelez Nearby.getMessagesClient(Activity).unsubscribe(). Transmettez le même objet MessageListener que celui utilisé pour l'abonnement (mMessageListener dans cet exemple).

L'exemple de code suivant montre comment se désabonner:

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