Publier et s'abonner

L'API Nearby Messages est une API de publication/abonnement qui permet aux appareils à proximité de petites charges utiles de données. Une fois qu'un appareil a publié un message, appareils peuvent recevoir le message. La taille du message doit être assez petite pour maintenir de bonnes performances. Ce service n'est pas conçu pour échanger des données tels que des photos et des vidéos.

L'ensemble des appareils à proximité est déterminé par l'échange de petits jetons sur Bluetooth et audio proche ultrasons (inaudible). Lorsqu'un appareil détecte un jeton depuis un appareil à proximité, le jeton est envoyé au serveur Nearby Messages le valider et vérifier s'il y a des messages à distribuer pour le ensemble actuel d'abonnements.

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

Cette bibliothèque fonctionne sous iOS 7 et versions ultérieures, et est compilée avec le SDK iOS 8.

Créer un gestionnaire de messages

Ce code crée un objet Gestionnaire de messages qui vous permet de publier et s'abonner. Comme l'échange de messages n'est pas authentifié, vous devez indiquer un clé API publique pour iOS. Vous pouvez en créer un via l'entrée Google Play Console pour 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 , 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)))

S'abonner aux messages

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

Le gestionnaire de messages trouvés est appelé lorsque des appareils à proximité qui publient messages sont découverts. Le gestionnaire de messages perdus est appelé lorsqu'un message n'est pas n'est plus observée (l'appareil est hors de portée ou ne 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) sont utilisés pour détecter les lieux à proximité et les deux supports diffuseront et analyseront. Dans certains cas, vous pour ajouter les entrées suivantes au fichier Info.plist de votre application:

  • Si votre application effectue des recherches audio, ajoutez NSMicrophoneUsageDescription, qui est un chaîne décrivant la raison pour laquelle vous utiliserez le micro. Par exemple, "Le le micro détecte les jetons anonymes provenant d'appareils situés à proximité."

  • Si votre application diffuse du contenu à l'aide de la technologie BLE, ajoutez NSBluetoothPeripheralUsageDescription, qui est une chaîne décrivant la raison pour laquelle va faire de la publicité sur BLE. Par exemple, "Un jeton anonyme est annoncé via le Bluetooth pour détecter les appareils à proximité. »

Dans certains cas, il se peut que votre application n'ait besoin d'utiliser qu'un seul de ces supports. peut ne pas avoir besoin de diffuser à la fois et de scanner sur ce support.

Par exemple, une application conçue pour se connecter à un boîtier décodeur la diffusion sur l'audio n'a besoin que d'analyser le contenu audio pour le découvrir. Les éléments suivants : extrait montre comment publier un message sur ce boîtier en n'utilisant que l'audio à des fins de découverte:

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 des données de débogage

La journalisation des données de débogage affiche dans la console les événements internes importants utile pour identifier les problèmes que vous pouvez rencontrer lors de l'intégration de Nearby Messages dans votre application Nous vous demanderons ces journaux si vous nous contactez pour l'assistance technique.

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

Objective-C

[GNSMessageManager setDebugLoggingEnabled:YES];

Swift

GNSMessageManager.setDebugLoggingEnabled(true)

Suivre l'état de l'autorisation Nearby

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

L'extrait de code suivant montre comment s'abonner à l'état d'autorisation. La Le gestionnaire modifié d'état d'autorisation est appelé chaque fois que l'état change. n'est pas appelé la première fois tant que l'utilisateur n'a pas donné 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 fournir à l'utilisateur un moyen de modifier l'état d'autorisation. pour par exemple à l'aide d'un bouton bascule sur une page de paramètres.

Voici un exemple montrant comment obtenir et définir 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 ayant une incidence sur Nearby

Si l'utilisateur a refusé l'autorisation d'accès au micro ou Bluetooth, ou a désactivé le Bluetooth, la fonctionnalité À proximité ne fonctionnera pas aussi bien, voire ne fonctionnera pas du tout. Dans ce cas, votre application doit afficher un message pour avertir l'utilisateur que l'application Nearby sont entravées. L'extrait de code suivant montre comment effectuer le suivi l'état de ces paramètres utilisateur en transmettant les gestionnaires lors de la création du message. responsable:

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

Remplacer la boîte de dialogue d'autorisation Nearby

Selon les paramètres que vous transmettez à vos publications et abonnements, iOS peut demander différentes autorisations avant d'autoriser le fonctionnement de Nearby. Pour la stratégie par défaut écoute les données transmises sur le réseau audio, iOS vous demandera donc l'autorisation d'utiliser le microphone. Dans ces cas, Nearby affiche une requête de type "vol préliminaire" boîte de dialogue expliquant pourquoi on demande à l'utilisateur pour donner leur autorisation.

Si vous souhaitez fournir une requête de "vérification préliminaire" personnalisée , définissez le paramètre permissionRequestHandler à un blocage personnalisé de la publication ou paramètres d'abonnement. Votre bloc personnalisé doit appeler le 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étection d'appareils peuvent fonctionner en arrière-plan. Voici quelques points à prendre en compte avant de décider d'utiliser 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 coûts supplémentaires liés à la batterie s'appliquent pour la technologie BLE en arrière-plan. Le coût est faible, mais vous vous devez la 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, suivez ces étapes:

  • Activez le mode arrière-plan et BLE uniquement dans votre publication ou votre abonnement en en transmettant un objet GNSStrategy correctement configuré. L'extrait 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 les entrées suivantes au fichier Info.plist de votre application:

    • UIBackgroundModes entrées:

      • bluetooth-central pour la recherche BLE en arrière-plan. Requis uniquement lorsque le mode découverte inclut l'analyse ; ce qu'il fait par défaut.
      • bluetooth-peripheral pour la publicité BLE en arrière-plan. Obligatoire uniquement lorsque le mode découverte inclut la diffusion ; ce qu'il fait par défaut.

    • Chaîne NSBluetoothPeripheralUsageDescription décrivant pourquoi pour vos annonces sur BLE. Par exemple, « Un jeton anonyme est annoncés via Bluetooth pour découvrir les appareils à proximité. » Voir Documentation Apple pour en savoir plus.

  • En arrière-plan, votre application peut être fermée à tout moment par le système. Si le mode arrière-plan est un paramètre qui peut être activé ou désactivé par l'utilisateur, votre doit effectuer les opérations suivantes:

    • Enregistrez la valeur du mode arrière-plan sur NSUserDefaults chaque fois que l'utilisateur le modifie.
    • Au démarrage, lisez-le depuis NSUserDefaults et restaurez l'application Nearby publications et/ou abonnements 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 tandis qu'en arrière-plan, notifications locales.

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

  • S'inscrire 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 de 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...
}