Votre application peut s'abonner aux rattachements de balises Bluetooth à basse consommation (BLE) en utilisant le même mécanisme que celui utilisé pour s'abonner aux messages publiés par d'autres appareils à proximité. Lors de l'abonnement, votre application reçoit automatiquement les messages des balises et des appareils à proximité.
S'abonner aux messages de balise BLE
Votre application peut s'abonner aux messages de la balise BLE:
- En premier plan, en réponse à une action ou un événement utilisateur.
- En arrière-plan, lorsque votre application n'est pas en cours d'exécution.
S'abonner au premier plan
Lorsque votre application s'abonne aux messages contenant des balises au premier plan, les analyses sont effectuées en continu jusqu'à ce que votre application se désabonne. Ne souscrivez un abonnement au premier plan que lorsque votre application est active, généralement en réponse à une action de l'utilisateur.
Votre application peut initier un abonnement de premier plan en appelant Nearby.getMessagesClient(Activity).subscribe(MessageListener, SubscribeOptions)
et en définissant l'option Strategy
sur BLE_ONLY
.
L'extrait de code suivant illustre le lancement d'un abonnement Nearby.getMessagesClient(Activity).subscribe(MessageListener, SubscribeOptions)
au premier plan :
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.");
SubscribeOptions options = new SubscribeOptions.Builder()
.setStrategy(Strategy.BLE_ONLY)
.build();
Nearby.getMessagesClient(this).subscribe(mMessageListener, options);
}
Lorsque l'abonnement n'est plus nécessaire, votre application doit se désabonner en appelant Nearby.getMessagesClient(Activity).unsubscribe(MessageListener)
.
S'abonner en arrière-plan
Lorsque votre application s'abonne à des messages contenant des balises en arrière-plan, des analyses à faible consommation sont déclenchées lors des événements à l'écran, même lorsque votre application n'est pas active actuellement. Vous pouvez utiliser ces notifications d'analyse pour réactiver votre application en réponse à un message particulier. Les abonnements en arrière-plan consomment moins d'énergie que les abonnements au premier plan, mais ils présentent une latence plus élevée et une fiabilité moindre.
Votre application peut initier un abonnement en arrière-plan en appelant Nearby.getMessagesClient(Activity).subscribe(PendingIntent, SubscribeOptions)
et en définissant l'option Strategy
sur BLE_ONLY
.
L'extrait de code suivant montre comment initier un abonnement en arrière-plan en appelant Nearby.getMessagesClient(Activity).subscribe(PendingIntent, SubscribeOptions)
.
// Subscribe to messages in the background.
private void backgroundSubscribe() {
Log.i(TAG, "Subscribing for background updates.");
SubscribeOptions options = new SubscribeOptions.Builder()
.setStrategy(Strategy.BLE_ONLY)
.build();
Nearby.getMessagesClient(this).subscribe(getPendingIntent(), options);
}
private PendingIntent getPendingIntent() {
return PendingIntent.getBroadcast(this, 0, new Intent(this, BeaconMessageReceiver.class),
PendingIntent.FLAG_UPDATE_CURRENT);
}
L'extrait de code suivant illustre la gestion de l'intent dans la classe BeaconMessageReceiver
.
@Override
public void onReceive(Context context, Intent intent) {
Nearby.getMessagesClient(context).handleIntent(intent, new MessageListener() {
@Override
public void onFound(Message message) {
Log.i(TAG, "Found message via PendingIntent: " + message);
}
@Override
public void onLost(Message message) {
Log.i(TAG, "Lost message via PendingIntent: " + message);
}
});
}
Lorsque l'abonnement n'est plus nécessaire, votre application doit se désabonner en appelant Nearby.getMessagesClient(Activity).unsubscribe(PendingIntent)
.
Analyser les messages de la balise
Les pièces jointes de balises sont des blobs de données arbitraires que vous pouvez ajouter à des balises. Chaque pièce jointe se compose des éléments suivants:
- Espace de noms: identifiant d'espace de noms
- Type: type de données.
- Données: valeur des données de la pièce jointe.
L'extrait de code suivant illustre l'utilisation d'un écouteur de message pour analyser les messages reçus d'une balise BLE:
mMessageListener = new MessageListener() {
@Override
public void onFound(Message message) {
// Do something with the message here.
Log.i(TAG, "Message found: " + message);
Log.i(TAG, "Message string: " + new String(message.getContent()));
Log.i(TAG, "Message namespaced type: " + message.getNamespace() +
"/" + message.getType());
}
...
};
L'analyse du contenu dépend du format des octets. Cet exemple suppose que les octets de contenu codent une chaîne UTF-8, mais votre message de balise peut encoder d'autres formats d'octets (par exemple, un tampon de protocole sérialisé). Pour en savoir plus, consultez Ajouter des pièces jointes aux balises.
Pour savoir quels espaces de noms sont associés à votre projet, appelez la méthode namespaces.list.
Remarques :
-
Pour préserver l'autonomie de la batterie, appelez
Nearby.getMessagesClient(Activity).unsubscribe()
dans la fonctiononStop()
de votre activité. Notez que cela ne s'applique que lorsque vous vous abonnez au premier plan. -
Pour réduire la latence, utilisez l'option
Strategy.BLE_ONLY
lorsque vous appelezNearby.getMessagesClient(Activity).subscribe()
. Lorsque cette option est définie, l'API Nearby Messages ne déclenche pas les recherches Bluetooth classiques. Cela réduit la latence pour la détection de balises, car le système n'effectue pas de cycles d'exécution successifs pour tous les types d'analyses possibles. - Pour joindre la charge utile d'un message à une balise, utilisez l'API Proximity Beacon.