Publier et s'abonner

L'API 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. La taille des messages doit être assez petite pour garantir de bonnes performances. Ce service n'est pas conçu pour échanger des objets plus volumineux, tels que des photos et des vidéos.

L'ensemble des appareils à proximité est déterminé par l'échange de petits jetons via le Bluetooth et du contenu audio quasi ultrasonique (inaudible). 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.

Cette bibliothèque fonctionne sous iOS 7 et versions ultérieures, et est compilée à l'aide du SDK iOS 8.

Créer un gestionnaire de messages

Ce code crée un objet de gestionnaire de messages qui vous permet de publier et de vous abonner. L'échange de messages n'est pas authentifié. Vous devez donc fournir une clé API publique pour iOS. Vous pouvez en créer un à l'aide de l'entrée Google Developers Console de votre projet.

Objective-C

#import <GNSMessages.h>

GNSMessageManager *messageManager =
    [[GNSMessageManager alloc] initWithAPIKey:@"API_KEY"];

Swift

let messageManager = GNSMessageManager(APIKey: "API_KEY")

Publication d'un message

Cet extrait de code illustre la publication d'un message contenant un nom. La publication est active tant que l'objet de publication existe. Pour arrêter la publication, libérez l'objet de publication.

Objective-C

id<GNSPublication> publication =
    [messageManager publicationWithMessage:[GNSMessage messageWithContent:[name dataUsingEncoding:NSUTF8StringEncoding]]];

Swift

let publication =
    messageManager.publication(with: GNSMessage(content: name.data(using: .utf8)))

Abonnement aux messages

Cet extrait de code illustre l'abonnement à tous les noms partagés par l'extrait de publication précédent. L'abonnement est actif tant que les objets de l'abonnement existeront. Pour arrêter de vous abonner, libérez l'objet abonnement.

Le gestionnaire de messages trouvés est appelé lorsque des appareils à proximité qui publient des messages sont détectés. Le gestionnaire de messages perdus est appelé lorsqu'un message n'est plus observé (l'appareil est hors de portée ou ne le publie plus).

Objective-C

id<GNSSubscription> subscription =
    [messageManager subscriptionWithMessageFoundHandler:^(GNSMessage *message) {
      // Add the name to a list for display
    }
    messageLostHandler:^(GNSMessage *message) {
      // Remove the name from the list
    }];

Swift

let subscription =
    messageManager.subscription(messageFoundHandler: { (message: GNSMessage?) in
      // Add the name to a list for display
    },
    messageLostHandler: { (message: GNSMessage?) in
      // Remove the name from the list
    })

Supports Discovery

Par défaut, les deux supports (audio et Bluetooth) seront utilisés pour détecter les appareils à proximité. Les deux supports diffusent et analysent. Dans certains cas, vous devez ajouter les entrées suivantes au fichier Info.plist de votre application:

  • Si votre application effectue l'analyse à l'aide de données audio, ajoutez NSMicrophoneUsageDescription, qui est une chaîne décrivant pourquoi vous utiliserez le micro. Par exemple, "Le micro écoute les jetons anonymes des appareils à proximité".

  • Si votre application diffuse des annonces à l'aide de la technologie BLE, ajoutez NSBluetoothPeripheralUsageDescription, qui est une chaîne décrivant la raison pour laquelle vous allez diffuser des annonces en utilisant cette technologie. Par exemple, "Un jeton anonyme est annoncé via Bluetooth pour détecter les appareils à proximité".

Dans certains cas, il se peut que votre application n'ait besoin d'utiliser qu'un seul des supports, et qu'elle n'ait pas besoin d'effectuer à la fois la diffusion et l'analyse sur ce support.

Par exemple, une application conçue pour se connecter à un boîtier décodeur diffusant des contenus audio n'a besoin d'effectuer une recherche sur le contenu audio que pour le détecter. L'extrait de code suivant montre comment publier un message sur ce boîtier décodeur en utilisant uniquement l'analyse audio pour la détection:

Objective-C

id<GNSPublication> publication = [messageManager publicationWithMessage:message
    paramsBlock:^(GNSPublicationParams *params) {
      params.strategy = [GNSStrategy strategyWithParamsBlock:^(GNSStrategyParams *params) {
        params.discoveryMediums = kGNSDiscoveryMediumsAudio;
        params.discoveryMode = kGNSDiscoveryModeScan;
      }];
    }];

Swift

let publication = messageManager.publication(with: message,
    paramsBlock: { (params: GNSPublicationParams?) in
      guard let params = params else { return }
      params.strategy = GNSStrategy(paramsBlock: { (params: GNSStrategyParams?) in
        guard let params = params else { return }
        params.discoveryMediums = .audio
        params.discoveryMode = .scan
      })
    })

Activer la journalisation de débogage

La journalisation des données de débogage imprime les événements internes importants dans la console. Ces événements peuvent vous aider à identifier les problèmes que vous pourriez rencontrer lors de l'intégration des messages à proximité à votre application. Ces journaux vous seront demandés si vous nous contactez pour obtenir une assistance technique.

Vous devez l'activer avant de créer un gestionnaire de messages. Cet extrait de code montre comment activer la journalisation de débogage:

Objective-C

[GNSMessageManager setDebugLoggingEnabled:YES];

Swift

GNSMessageManager.setDebugLoggingEnabled(true)

Suivre l'état de l'autorisation à proximité

Le consentement de l'utilisateur est requis pour activer la détection d'appareils. Cela est indiqué par l'état de l'autorisation à proximité. Lors du premier appel pour créer une publication ou un abonnement, une boîte de dialogue de recueil du consentement s'affiche. Si l'utilisateur ne donne pas son consentement, la détection de l'appareil ne fonctionnera pas. Dans ce cas, votre application doit afficher un message pour rappeler à l'utilisateur que la découverte de l'appareil est désactivée. L'état de l'autorisation est stocké dans NSUserDefaults.

L'extrait de code suivant montre comment s'abonner à l'état d'autorisation. Le gestionnaire de changement d'état d'autorisation est appelé chaque fois que l'état change. Il n'est appelé la première fois que lorsque l'utilisateur a accordé ou refusé l'autorisation. Libérez l'objet d'autorisation pour arrêter l'abonnement.

Objective-C

GNSPermission *nearbyPermission = [[GNSPermission alloc] initWithChangedHandler:^(BOOL granted) {
  // Update the UI here
}];

Swift

let nearbyPermission = GNSPermission(changedHandler: { (granted: Bool) in
  // Update the UI here
})

Votre application peut permettre à l'utilisateur de modifier l'état d'autorisation, par exemple à l'aide d'un bouton bascule sur une page de paramètres.

Voici un exemple d'obtention et de définition de l'état d'autorisation.

Objective-C

BOOL permissionState = [GNSPermission isGranted];
[GNSPermission setGranted:!permissionState];  // toggle the state

Swift

let permissionState = GNSPermission.isGranted()
GNSPermission.setGranted(!permissionState)  // toggle the state

Suivi des paramètres utilisateur qui affectent la fonctionnalité À proximité

Si l'utilisateur a refusé l'autorisation d'accéder au micro ou au Bluetooth, ou s'il a désactivé le Bluetooth, la fonctionnalité À proximité ne fonctionnera pas correctement, voire ne fonctionnera pas du tout. Dans ce cas, votre application doit afficher un message indiquant à l'utilisateur que les opérations de Nearby sont entravées. L'extrait de code suivant montre comment suivre l'état de ces paramètres utilisateur en transmettant des gestionnaires lors de la création du gestionnaire de messages:

Objective-C

GNSMessageManager *messageManager = [[GNSMessageManager alloc]
    initWithAPIKey:API_KEY
       paramsBlock:^(GNSMessageManagerParams *params) {
         params.microphonePermissionErrorHandler = ^(BOOL hasError) {
           // Update the UI for microphone permission
         };
         params.bluetoothPowerErrorHandler = ^(BOOL hasError) {
           // Update the UI for Bluetooth power
         };
         params.bluetoothPermissionErrorHandler = ^(BOOL hasError) {
           // Update the UI for Bluetooth permission
         };
}];

Swift

let messageManager = GNSMessageManager(
         APIKey: API_KEY,
    paramsBlock: { (params: GNSMessageManagerParams?) in
      guard let params = params else { return }
      params.microphonePermissionErrorHandler = { (hasError: Bool) in
        // Update the UI for microphone permission
      }
      params.bluetoothPowerErrorHandler = { (hasError: Bool) in
        // Update the UI for Bluetooth power
      }
      params.bluetoothPermissionErrorHandler = { (hasError: Bool) in
        // Update the UI for Bluetooth permission
      }
    })

Ignorer la boîte de dialogue d'autorisation à proximité

En fonction des paramètres que vous transmettez à vos publications et abonnements, iOS peut demander différentes autorisations avant d'autoriser le fonctionnement de Nearby. Par exemple, la stratégie par défaut écoute les données transmises en cas de contenu audio quasi ultrasonique. iOS demande donc l'autorisation d'utiliser le micro. Dans ce cas, Nearby affiche une boîte de dialogue de "vérification préliminaire" qui explique pourquoi l'utilisateur est invité à donner son autorisation.

Si vous souhaitez fournir une boîte de dialogue personnalisée de "vérification préliminaire", définissez le paramètre permissionRequestHandler sur un bloc personnalisé dans les paramètres de publication ou d'abonnement. Votre bloc personnalisé doit appeler le bloc permissionHandler après la réponse de l'utilisateur. L'extrait de code suivant montre comment procéder pour une publication:

Objective-C

id<GNSPublication> publication =
    [messageManager publicationWithMessage:[GNSMessage messageWithContent:[name dataUsingEncoding:NSUTF8StringEncoding]]
                               paramsBlock:^(GNSPublicationParams *params) {
                                 params.permissionRequestHandler = ^(GNSPermissionHandler permissionHandler) {
                                   // Show your custom dialog here.
                                   // Don't forget to call permissionHandler() with YES or NO when the user dismisses it.
                                 };
                               }];

Swift

let publication =
    messageManager.publication(with: GNSMessage(content: name.data(using: .utf8)),
        paramsBlock: { (params: GNSPublicationParams?) in
          guard let params = params else { return }
          params.permissionRequestHandler = { (permissionHandler: GNSPermissionHandler?) in
            // Show your custom dialog here.
            // Don't forget to call permissionHandler() with true or false when the user dismisses it.
          }
        })

Opération en arrière-plan

Les publications et les abonnements qui utilisent la technologie BLE pour la découverte d'appareils peuvent fonctionner en arrière-plan. Voici quelques points à prendre en compte avant d'utiliser le mode arrière-plan:

  • Les opérations en arrière-plan ne doivent utiliser que le support BLE ; l'audio n'est pas pris en charge.
  • Des frais supplémentaires s'appliquent à la batterie pour la technologie BLE en arrière-plan. Le coût est faible, mais vous devez le mesurer avant de décider d'utiliser le mode arrière-plan.
  • iOS demandera à l'utilisateur l'autorisation de diffuser des annonces via BLE en arrière-plan.

Pour ajouter le mode arrière-plan à une publication ou à un abonnement, procédez comme suit:

  • Activez le mode arrière-plan et la technologie BLE uniquement pour votre publication ou votre abonnement en transmettant un objet GNSStrategy correctement configuré. L'extrait de code suivant montre comment procéder pour un abonnement:

    Objective-C

    id<GNSSubscription> subscription =
        [messageManager subscriptionWithMessageFoundHandler:^(GNSMessage *message) {
          // Add the name to a list for display
        }
        messageLostHandler:^(GNSMessage *message) {
          // Remove the name from the list
        }
        paramsBlock:^(GNSSubscriptionParams *params) {
          params.strategy = [GNSStrategy strategyWithParamsBlock:^(GNSStrategyParams *params) {
            params.allowInBackground = YES;
            params.discoveryMediums = kGNSDiscoveryMediumsBLE;
          }];
        }];
    

    Swift

    let subscription =
        messageManager.subscription(messageFoundHandler: { (message: GNSMessage?) in
          // Add the name to a list for display
        },
        messageLostHandler: { (message: GNSMessage?) in
          // Remove the name from the list
        },
        paramsBlock:{ (params: GNSSubscriptionParams?) in
          guard let params = params else { return }
          params.strategy = GNSStrategy(paramsBlock: { (params: GNSStrategyParams?) in
            guard let params = params else { return }
            params.allowInBackground = true
            params.discoveryMediums = .BLE
          })
        })
    

  • Ajoutez ces entrées au fichier Info.plist de votre application:

    • UIBackgroundModes entrées:

      • bluetooth-central pour l'analyse BLE en arrière-plan. Obligatoire uniquement lorsque le mode de découverte inclut l'analyse (par défaut).
      • bluetooth-peripheral pour la publicité BLE en arrière-plan. Requis uniquement lorsque le mode de découverte inclut la diffusion (par défaut).
    • Chaîne NSBluetoothPeripheralUsageDescription décrivant la raison pour laquelle vous diffusez des annonces sur BLE. Par exemple, "Un jeton anonyme est annoncé via Bluetooth pour détecter les appareils à proximité". Pour en savoir plus, consultez la documentation d'Apple.

  • Votre application peut être fermée à tout moment par le système en arrière-plan. Si le mode d'arrière-plan est un paramètre pouvant être activé ou désactivé par l'utilisateur, votre application doit procéder comme suit:

    • Enregistrez la valeur du mode arrière-plan dans NSUserDefaults chaque fois que l'utilisateur la modifie.
    • Au démarrage, lisez-le à partir de NSUserDefaults et restaurez les publications et/ou les abonnements Nearby si le mode arrière-plan est activé.

Notifications en arrière-plan

Si vous souhaitez que votre application informe l'utilisateur lorsqu'un abonnement reçoit un message en arrière-plan, vous pouvez utiliser des notifications locales.

Pour les ajouter à votre application, procédez comme suit:

  • Inscrivez-vous pour recevoir des notifications locales au démarrage:

    Objective-C

    if ([UIApplication instancesRespondToSelector:@selector(registerUserNotificationSettings:)]) {
      [[UIApplication sharedApplication] registerUserNotificationSettings:
          [UIUserNotificationSettings settingsForTypes:
              UIUserNotificationTypeAlert | UIUserNotificationTypeBadge | UIUserNotificationTypeSound
                                            categories:nil]];
    }
    

    Swift

    UIApplication.shared.registerUserNotificationSettings(
        UIUserNotificationSettings(types: [.alert, .badge, .sound], categories: nil))
    

  • Envoyez une notification locale dans le gestionnaire des messages trouvés de votre abonnement:

    Objective-C

    GNSMessageHandler myMessageFoundHandler = ^(GNSMessage *message) {
        // Send a local notification if not in the foreground.
        if ([UIApplication sharedApplication].applicationState != UIApplicationStateActive) {
          UILocalNotification *localNotification = [[UILocalNotification alloc] init];
          localNotification.alertBody = @"Message received";
          [[UIApplication sharedApplication] presentLocalNotificationNow:localNotification];
        }
        // Process the new message...
      };
    

    Swift

    let myMessageFoundHandler: GNSMessageHandler = { (message: GNSMessage?) in
      // Send a local notification if not in the foreground.
      if UIApplication.shared.applicationState != .active {
        let localNotification = UILocalNotification()
        localNotification.alertBody = "Message received"
        UIApplication.shared.presentLocalNotificationNow(localNotification)
      }
      // Process the new message...
    }