Pubblica e iscriviti

L'API Nearby Messages è un'API di pubblicazione e iscrizione 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 mantenere un buon rendimento. 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 Bluetooth e audio 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 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 il rilevamento su un sottoinsieme o su supporti e per controllare se trasmettere o eseguire la scansione, devi trasmettere parametri aggiuntivi quando crei pubblicazioni e abbonamenti.

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

Creare un gestore dei messaggi

Questo codice crea un oggetto Message Manager, che 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 la sottoscrizione a tutti i nomi condivisi dallo snippet di pubblicazione precedente. L'abbonamento è attivo finché esistono gli oggetti dell'abbonamento. 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 dei messaggi persi viene chiamato quando un messaggio non viene più osservato (il dispositivo è fuori dal raggio d'azione 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 verranno eseguiti sia la trasmissione che la scansione. In alcuni casi, devi aggiungere le seguenti voci al Info.plist della tua app:

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

  • Se la tua app trasmette utilizzando BLE, aggiungi NSBluetoothPeripheralUsageDescription, 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 che la scansione su quel mezzo.

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

Attivare il logging di debug

La registrazione di debug stampa eventi interni significativi nella console, che possono essere utili per rintracciare 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.

Ti consigliamo di attivarlo prima di creare un gestore dei messaggi. Questo snippet di codice mostra come attivare la registrazione di debug:

Objective-C

[GNSMessageManager setDebugLoggingEnabled:YES];

Swift

GNSMessageManager.setDebugLoggingEnabled(true)

Monitoraggio dello stato dell'autorizzazione Dispositivi 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 fornisce il consenso, il rilevamento dei dispositivi non funzionerà. In questo caso, la tua app dovrebbe mostrare un messaggio per ricordare all'utente che il rilevamento dei dispositivi è disattivato. Lo stato dell'autorizzazione è memorizzato in NSUserDefaults.

Il seguente snippet mostra la sottoscrizione allo stato dell'autorizzazione. Il gestore di modifiche 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'abbonamento.

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 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 al microfono, l'autorizzazione al Bluetooth o 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 avvisi 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 di Message Manager:

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 trasmetti alle tue pubblicazioni e ai tuoi abbonamenti, iOS potrebbe richiedere varie autorizzazioni prima di consentire il funzionamento di Nearby. Ad esempio, la strategia predefinita ascolta i dati trasmessi tramite audio quasi ultrasonico, quindi iOS chiederà l'autorizzazione per utilizzare il microfono. In questi casi, Nearby mostrerà una finestra di dialogo "prevolo" 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 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 gli abbonamenti che utilizzano 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.
  • Per il Bluetooth Low Energy in background è previsto 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 fare pubblicità tramite BLE in background.

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

  • Attiva la modalità background e la modalità solo BLE nella tua pubblicazione o nel tuo abbonamento passando un oggetto GNSStrategy configurato correttamente. Il seguente snippet 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 scansione BLE in background. Necessario solo quando la modalità di rilevamento include la scansione, come avviene per impostazione predefinita.
      • bluetooth-peripheral per la pubblicità BLE in background. Necessario solo quando la modalità di individuazione include la trasmissione, che avviene per impostazione predefinita.

    • NSBluetoothPeripheralUsageDescription string describing why you will be advertising on BLE. Ad esempio, "Un token anonimo viene pubblicizzato via Bluetooth per rilevare i dispositivi nelle vicinanze". Per maggiori dettagli, consulta la documentazione di Apple.

  • L'app può essere chiusa in qualsiasi momento dal sistema mentre è 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 in NSUserDefaults ogni volta che l'utente lo modifica.
    • All'avvio, leggilo da NSUserDefaults e ripristina le pubblicazioni e/o gli abbonamenti nelle vicinanze se la modalità background è attiva.

Notifiche in background

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

Segui questi passaggi per aggiungerli alla tua app:

  • 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 message-found dell'abbonamento:

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