Pubblica e iscriviti

L'API Nearby Messages è un'API di pubblicazione/sottoscrizione che consente ai dispositivi nelle vicinanze di scambiarsi 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 abbastanza ridotte per mantenere un buon rendimento. Questo servizio non è pensato per lo scambio di oggetti di dimensioni maggiori come foto e video.

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

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

Questa libreria funziona su iOS 7 e versioni successive e viene compilata con l'SDK iOS 8.

Creazione di un gestore dei messaggi

Questo codice crea un oggetto gestore dei 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 uno 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")

Pubblicazione di un messaggio

Questo snippet di codice mostra la pubblicazione di un messaggio contenente un nome. La pubblicazione è attiva finché esiste l'oggetto pubblicazione. Per interrompere la pubblicazione, rilascia l'oggetto 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)))

Iscrizione ai messaggi

Questo snippet di codice mostra l'abbonamento a tutti i nomi condivisi dallo snippet di pubblicazione precedente. L'abbonamento è attivo finché esistono gli oggetti degli abbonamenti. Per interrompere l'abbonamento, rilascia l'oggetto dell'abbonamento.

Il gestore dei messaggi trovati viene chiamato quando vengono rilevati dispositivi nelle vicinanze che pubblicano messaggi. Il gestore della perdita di messaggi 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
    })

Mezzi di scoperta

Per impostazione predefinita, verranno utilizzati entrambi i mezzi (audio e Bluetooth) per rilevare i dispositivi nelle vicinanze e entrambi trasmettono e eseguono la scansione. In alcuni casi, devi obbligatoriamente aggiungere le seguenti voci al Info.plist della tua app:

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

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

In alcuni casi, l'app potrebbe dover utilizzare solo uno dei mezzi e potrebbe non dover eseguire sia la trasmissione sia la scansione su quel mezzo.

Ad esempio, un'app progettata per connettersi a un set-top box che trasmette solo in audio deve eseguire la scansione solo in audio per rilevarlo. Lo snippet seguente mostra come pubblicare un messaggio sulla TV set-top utilizzando solo la ricerca 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
      })
    })

Attivazione della registrazione di debug

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

Devi attivarla prima di creare un gestore dei messaggi. Questo snippet di codice mostra come attivare il logging di debug:

Objective-C

[GNSMessageManager setDebugLoggingEnabled:YES];

Swift

GNSMessageManager.setDebugLoggingEnabled(true)

Monitoraggio dello stato dell'autorizzazione Nelle vicinanze

Per attivare il rilevamento dei dispositivi è necessario il consenso dell'utente. Ciò è indicato dallo stato dell'autorizzazione Nelle vicinanze. Alla prima chiamata per creare una pubblicazione o un abbonamento, all'utente viene mostrata una finestra di dialogo per il consenso. Se l'utente non dà il suo consenso, il rilevamento dei dispositivi non funzionerà. In questo caso, l'app deve mostrare un messaggio per ricordare all'utente che il rilevamento del dispositivo è disattivato. Lo stato della permissione viene archiviato in NSUserDefaults.

Lo snippet seguente mostra come eseguire l'iscrizione allo stato dell'autorizzazione. Il gestore della modifica dello stato dell'autorizzazione 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 autorizzazione per interrompere l'iscrizione.

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ò offrire all'utente un modo per modificare lo stato dell'autorizzazione, ad esempio utilizzando un pulsante di attivazione/disattivazione 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

Monitoraggio delle impostazioni utente che influiscono su Nelle vicinanze

Se l'utente ha negato l'autorizzazione di accesso al microfono o al Bluetooth o se ha disattivato il Bluetooth, la funzionalità Qui vicino non funzionerà correttamente o potrebbe non funzionare affatto. In questi casi, l'app deve mostrare un messaggio che avvisa l'utente che le operazioni di Nearby sono ostacolate. Il seguente snippet mostra come monitorare lo stato di queste impostazioni utente passando i gestori durante la creazione del gestore dei 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
      }
    })

Sostituzione della finestra di dialogo di autorizzazione Nelle vicinanze

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

Se vuoi fornire una finestra di dialogo di "preflight" personalizzata, imposta il parametro permissionRequestHandler su un blocco personalizzato nei parametri di pubblicazione o di abbonamento. 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 iscrizioni che utilizzano il BLE per il rilevamento dei dispositivi possono funzionare in background. Ecco alcuni aspetti da tenere presente quando decidi di utilizzare la modalità in background:

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

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

  • Attiva la modalità in background e solo BLE nella pubblicazione o nell'abbonamento passando un oggetto GNSStrategy configurato correttamente. Lo snippet riportato di seguito mostra come eseguire questa operazione per un abbonamento:

    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:

    • UIBackgroundModes voci:

      • bluetooth-central per la ricerca BLE in background. Obbligatorio solo se la modalità di ricerca include la scansione, che è attiva per impostazione predefinita.
      • bluetooth-peripheral per la pubblicità BLE in background. Obbligatorio solo se la modalità di individuazione include la trasmissione, che è attiva per impostazione predefinita.

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

  • L'app può essere interrotta in qualsiasi momento dal sistema quando è in background. Se la modalità background è un'impostazione che può essere attivata o disattivata dall'utente, la tua app deve:

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

Notifiche in background

Se vuoi che la tua app avvisi l'utente quando un abbonamento riceve un messaggio in background, puoi utilizzare le notifiche locali.

Per aggiungerli alla tua app, segui questi passaggi:

  • Registrati per 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 di messaggi trovati della tua 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...
}