Pubblica e iscriviti

L'API Nearby Messages è un'API di pubblicazione/sottoscrizione che consente ai dispositivi nelle vicinanze di scambiare piccoli payload di dati. Una volta che un dispositivo pubblica un messaggio, i dispositivi nelle vicinanze possono riceverlo. Le dimensioni dei messaggi devono essere mantenute piuttosto ridotte per garantire buone prestazioni. Questo servizio non è pensato per lo scambio di oggetti più grandi come foto e video.

L'insieme dei dispositivi nelle vicinanze è determinato dallo scambio di piccoli token tramite audio Bluetooth e quasi ultrasonico (inaudibile). Quando un dispositivo rileva un token da un dispositivo nelle vicinanze, lo invia al server Nearby Messages per convalidarlo e verificare se ci sono messaggi da recapitare per l'insieme attuale di sottoscrizioni dell'applicazione.

Un'applicazione può controllare l'insieme dei supporti utilizzati per il rilevamento dei dispositivi e se i supporti vengono utilizzati per trasmettere token e/o cercare token. Per impostazione predefinita, la trasmissione e la scansione vengono eseguite su tutti i supporti. Per eseguire il rilevamento su un sottoinsieme di supporti e controllare se trasmettere o eseguire la scansione, devi passare parametri aggiuntivi quando crei pubblicazioni e sottoscrizioni.

Questa libreria viene eseguita su iOS 7 e versioni successive e viene creata con l'SDK iOS 8.

Creare un gestore di messaggi

Questo codice crea un oggetto gestore di messaggi, che ti consente di pubblicare e sottoscrivere. Lo scambio di messaggi non è autenticato, quindi devi fornire una chiave API pubblica per iOS. Puoi crearne una utilizzando la voce Google Developers Console per il tuo progetto.

Objective-C

#import <GNSMessages.h>

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

Swift

let messageManager = GNSMessageManager(APIKey: "API_KEY")

Pubblicare un messaggio

Questo snippet di codice mostra come pubblicare un messaggio contenente un nome. La pubblicazione è attiva finché esiste l'oggetto di pubblicazione. Per interrompere la pubblicazione, rilascia l'oggetto di pubblicazione.

Objective-C

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

Swift

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

Sottoscrivere i messaggi

Questo snippet di codice mostra come sottoscrivere tutti i nomi condivisi dallo snippet di pubblicazione precedente. La sottoscrizione è attiva finché esistono gli oggetti di sottoscrizione. Per interrompere la sottoscrizione, rilascia l'oggetto di sottoscrizione.

Il gestore dei messaggi trovati viene chiamato quando vengono rilevati dispositivi nelle vicinanze che pubblicano messaggi. Il gestore dei messaggi persi viene chiamato quando un messaggio non viene più osservato (il dispositivo è fuori portata o non pubblica più il messaggio).

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

Supporti di rilevamento

Per impostazione predefinita, verranno utilizzati entrambi i supporti (audio e Bluetooth) per rilevare i dispositivi nelle vicinanze e verranno trasmessi ed eseguiti la scansione su entrambi i supporti. In alcuni casi, devi aggiungere le seguenti voci al file Info.plist della tua app:

  • Se la tua app esegue la scansione utilizzando l'audio, aggiungi NSMicrophoneUsageDescription, una stringa che descrive il motivo per cui utilizzerai il microfono. Ad esempio, "Il microfono ascolta i token anonimi dei dispositivi nelle vicinanze".

  • Se la tua app trasmette utilizzando BLE, aggiungi NSBluetoothPeripheralUsageDescription, una stringa che descrive il motivo per cui pubblicherai annunci su BLE. Ad esempio, "Un token anonimo viene pubblicizzato tramite Bluetooth per rilevare i dispositivi nelle vicinanze".

In alcuni casi, la tua app potrebbe dover utilizzare solo uno dei supporti e potrebbe non dover eseguire sia la trasmissione sia la scansione su quel supporto.

Ad esempio, un'app progettata per connettersi a un set-top box che trasmette solo audio deve eseguire la scansione dell'audio per rilevarlo. Il seguente snippet mostra come pubblicare un messaggio su quel set-top box utilizzando solo la scansione audio per il rilevamento:

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

Abilitare la registrazione di debug

La registrazione di debug stampa nella console gli eventi interni significativi che possono essere utili per individuare i problemi che potresti riscontrare durante l'integrazione di Nearby Messages nella tua app. Ti chiederemo questi log se ci contatti per ricevere assistenza tecnica.

Devi abilitarla prima di creare un gestore di messaggi. Questo snippet di codice mostra come abilitare la registrazione di debug:

Objective-C

[GNSMessageManager setDebugLoggingEnabled:YES];

Swift

GNSMessageManager.setDebugLoggingEnabled(true)

Monitorare lo stato dell'autorizzazione Dispositivi nelle vicinanze

È necessario il consenso dell'utente per abilitare il rilevamento dei dispositivi. Questo è indicato dallo stato dell'autorizzazione Dispositivi nelle vicinanze. Alla prima chiamata per creare una pubblicazione o una sottoscrizione, all'utente viene mostrata una finestra di dialogo per il consenso. Se l'utente non dà il consenso, il rilevamento dei dispositivi non funzionerà. In questo caso, la tua app deve mostrare un messaggio per ricordare all'utente che il rilevamento dei dispositivi è disattivato. Lo stato dell'autorizzazione viene memorizzato in NSUserDefaults.

Il seguente snippet mostra come sottoscrivere lo stato dell'autorizzazione. Il gestore dello stato dell'autorizzazione modificato viene chiamato ogni volta che lo stato cambia e non viene chiamato la prima volta finché l'utente non ha concesso o negato l'autorizzazione. Rilascia l'oggetto di autorizzazione per interrompere la sottoscrizione.

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

La tua app può fornire all'utente un modo per modificare lo stato dell'autorizzazione, ad esempio utilizzando un interruttore a levetta in una pagina delle impostazioni.

Ecco un esempio di come ottenere e impostare lo stato dell'autorizzazione.

Objective-C

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

Swift

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

Monitorare le impostazioni utente che influiscono su Dispositivi nelle vicinanze

Se l'utente ha negato l'autorizzazione al microfono, ha negato l'autorizzazione Bluetooth o ha disattivato il Bluetooth, Dispositivi nelle vicinanze non funzionerà altrettanto bene o potrebbe non funzionare affatto. In questi casi, la tua app deve mostrare un messaggio che avvisa l'utente che le operazioni di Dispositivi nelle vicinanze sono ostacolate. Il seguente snippet mostra come monitorare lo stato di queste impostazioni utente passando i gestori durante la creazione del gestore di messaggi:

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

Ignorare la finestra di dialogo dell'autorizzazione Dispositivi nelle vicinanze

A seconda dei parametri che passi alle pubblicazioni e alle sottoscrizioni, iOS potrebbe richiedere varie autorizzazioni prima di consentire il funzionamento di Dispositivi nelle vicinanze. Ad esempio, la strategia predefinita ascolta i dati trasmessi tramite audio quasi ultrasonico, quindi iOS chiederà l'autorizzazione a utilizzare il microfono. In questi casi, Dispositivi nelle vicinanze mostrerà una finestra di dialogo "preflight" che spiega perché all'utente viene chiesto di concedere l'autorizzazione.

Se vuoi fornire una finestra di dialogo "preflight" personalizzata, imposta il parametro permissionRequestHandler su un blocco personalizzato nei parametri di pubblicazione o sottoscrizione. Il blocco personalizzato deve chiamare il blocco permissionHandler dopo che l'utente ha risposto. Il seguente snippet mostra come eseguire questa operazione per una pubblicazione:

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

Operazione in background

Le pubblicazioni e le sottoscrizioni che utilizzano BLE per il rilevamento dei dispositivi possono funzionare in background. Ecco alcune cose di cui devi essere a conoscenza quando decidi di utilizzare la modalità in background:

  • Le operazioni in background devono utilizzare solo il supporto BLE; l'audio non è supportato.
  • Il BLE in background comporta un costo aggiuntivo per la batteria. Il costo è basso, ma devi misurarlo prima di decidere di utilizzare la modalità in background.
  • iOS chiederà all'utente l'autorizzazione a pubblicare annunci tramite BLE in background.

Per aggiungere la modalità in background a una pubblicazione o a una sottoscrizione, segui questi passaggi aggiuntivi:

  • Abilita la modalità in background e solo BLE nella pubblicazione o nella sottoscrizione passando un oggetto GNSStrategy configurato correttamente. Il seguente snippet mostra come eseguire questa operazione per una sottoscrizione:

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

  • Aggiungi queste voci al file Info.plist della tua app:

    • Voci UIBackgroundModes:

      • bluetooth-central per la scansione BLE in background. Necessario solo quando la modalità di rilevamento include la scansione; per impostazione predefinita.
      • bluetooth-peripheral per la pubblicità BLE in background. Necessario solo quando la modalità di rilevamento include la trasmissione; per impostazione predefinita.

    • Stringa NSBluetoothPeripheralUsageDescription che descrive il motivo per cui pubblicherai annunci su BLE. Ad esempio, "Un token anonimo viene pubblicizzato tramite Bluetooth per rilevare i dispositivi nelle vicinanze". Per maggiori dettagli, consulta la documentazione di Apple.

  • Il sistema può chiudere la tua app in qualsiasi momento mentre è in background. Se la modalità in background è un'impostazione che può essere attivata o disattivata dall'utente, la tua app deve eseguire le seguenti operazioni:

    • Salva il valore della modalità in background in NSUserDefaults ogni volta che l'utente lo modifica.
    • All'avvio, leggilo da NSUserDefaults e ripristina le pubblicazioni e/o le sottoscrizioni di Dispositivi nelle vicinanze se la modalità in background è abilitata.

Notifiche in background

Se vuoi che la tua app invii una notifica all'utente quando una sottoscrizione riceve un messaggio in background, puoi utilizzare le notifiche locali.

Segui questi passaggi per aggiungerli alla tua app:

  • Registra le notifiche locali all'avvio:

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

  • Invia una notifica locale nel gestore dei messaggi trovati della sottoscrizione:

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