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. Une fois qu'un appareil a publié un message, les appareils à proximité peuvent le recevoir. Ce guide vous présente 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 y a des messages à distribuer 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 indiquer 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 la diffusion ou l'analyse doivent être effectuées, vous devez transmettre des paramètres supplémentaires lorsque vous créez des publications et des abonnements.

Lorsqu'un utilisateur publie et s'abonne activement, une notification "Nearby est en cours d'utilisation" s'affiche pour l'informer que Nearby est actif. Cette notification ne s'affiche que lorsqu'une ou plusieurs applications utilisent activement Nearby. Les utilisateurs ont ainsi la possibilité de préserver l'autonomie de la batterie si Nearby n'est pas nécessaire. Il propose aux utilisateurs les options suivantes :

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

Vous pouvez utiliser PublishCallback() et SubscribeCallback() pour écouter les cas où un utilisateur force l'arrêt de l'application à l'aide de Nearby. 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 qu'à partir d'une activité au premier plan (à l'exception de l'abonnement BLE en arrière-plan).

Appelez publish() et/ou subscribe() pour utiliser l'API Nearby Messages. Votre application doit toujours 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 pouvons accepter jusqu'à 100 Ko pour les applications qui en ont besoin. Ce service n'est pas destiné à l'échange d'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 OnFailureListener à la fin de l'appel de publication, ce qui vous avertira si la publication a échoué. Par exemple, si l'appareil n'est pas connecté à Internet.

Annuler la publication d'un message

Pour annuler la publication d'un message, appelez unpublish(). Au minimum, votre application doit appeler la méthode "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 à des messages

Pour vous abonner aux messages provenant d'autres appareils, appelez Nearby.getMessagesClient(Activity).subscribe(). Vous devrez 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 à 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, qui vous avertira si l'abonnement a échoué. Par exemple, si l'appareil n'est pas connecté à Internet.

Se désabonner

Pour vous désabonner et ne plus recevoir de messages de l'appareil, appelez le 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);
}