Publier et s'abonner

Nearby Messages est une API de publication et d'abonnement qui permet aux appareils à proximité d'échanger de petites charges utiles de données. Une fois qu'un appareil a publié un message, les appareils à proximité peuvent le recevoir. Ce guide décrit 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 le Bluetooth. Lorsqu'un appareil détecte un jeton à partir d'un appareil à proximité, il l'envoie au serveur Nearby Messages pour le valider et vérifier s'il y a des messages à distribuer pour l'ensemble d'abonnements actuel de l'application.

Une application peut contrôler l'ensemble des supports utilisés pour la détection d'appareils, et si ces 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 la découverte sur un sous-ensemble ou des supports, et pour contrôler la diffusion ou l'analyse, vous devez transmettre des paramètres supplémentaires lorsque vous créez des publications et des abonnements.

Lors de la publication et de l'abonnement actifs, une notification "À proximité est utilisée" s'affiche pour informer les utilisateurs que la fonctionnalité À proximité est active. 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 cette fonctionnalité n'est pas nécessaire. Elle offre aux utilisateurs les options suivantes:

• Accédez à une application pour désactiver Nearby.
• Forcer une application à arrêter d'utiliser la fonctionnalité À proximité.
• Accédez à l'écran Nearby Settings (Paramètres de proximité).

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

Étant donné que les API Nearby Messages peuvent avoir une incidence sur l'autonomie de la batterie, elles ne doivent être utilisées qu'à partir d'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 présenter les valeurs unpublish() et unsubscribe() de façon 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 le tableau d'octets des messages. Nous vous recommandons de limiter la taille des messages à 3 Ko (messages que nous pouvons distribuer plus rapidement), mais nous pouvons prendre en charge 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 :Dans cet exemple, aucun rappel n'a été défini 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. Vous serez alors averti si la publication a échoué. (par exemple, si l'appareil ne dispose pas d'une connexion Internet active).

Annuler la publication d'un message

Pour annuler la publication d'un message, appelez unpublish(). Votre application doit au minimum appeler "unpublish" 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 depuis d'autres appareils, appelez Nearby.getMessagesClient(Activity).subscribe(). Vous devez transmettre un élément MessageListener pour gérer la réception des messages d'abonnement.

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

L'exemple suivant illustre l'abonnement à des 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. Vous serez alors averti en cas d'échec de l'abonnement. (par exemple, si l'appareil ne dispose pas d'une connexion Internet active).

Se désabonner

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

L'exemple de code suivant illustre le désabonnement:

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