Pubblica e iscriviti

L'API Nearby Messages è un'API publish-subscribe che consente ai dispositivi nelle vicinanze di scambiare piccoli payload di dati. Quando un dispositivo pubblica un messaggio, i dispositivi nelle vicinanze possono riceverlo. Le dimensioni dei messaggi devono essere ridotte per mantenere buone prestazioni. Questo servizio non è concepito per lo scambio di oggetti più grandi, come foto e video.

L'insieme di dispositivi nelle vicinanze è determinato dallo scambio di piccoli token su Bluetooth e audio quasi a ultrasuoni (non udibile). Quando un dispositivo rileva un token da un dispositivo nelle vicinanze, lo invia al server Nearby Messaggi per convalidarlo e controllare se ci sono messaggi da recapitare per l'insieme attuale di abbonamenti 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 per cercare token. Per impostazione predefinita, la trasmissione e la scansione vengono eseguite su tutti i mezzi. Per eseguire il rilevamento su un sottoinsieme o dei mezzi e per stabilire se trasmettere o scansionare, devi trasmettere parametri aggiuntivi quando crei pubblicazioni e abbonamenti.

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

Creazione di un gestore dei messaggi

Questo codice crea un oggetto gestore dei messaggi, 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 relativa al 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'iscrizione a tutti i nomi condivisi dallo snippet di pubblicazione precedente. La sottoscrizione rimane attiva finché esistono gli oggetti degli abbonamenti. Per interrompere la sottoscrizione, rilascia l'oggetto abbonamento.

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

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, per rilevare i dispositivi nelle vicinanze vengono utilizzati entrambi i mezzi (audio e Bluetooth) e entrambi i mezzi saranno trasmessi e ricercati. In alcuni casi, devi aggiungere le seguenti voci al Info.plist dell'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 rimane in ascolto di token anonimi provenienti da dispositivi vicini".

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

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

Ad esempio, un'app progettata per connettersi a un decoder che trasmette audio deve solo eseguire la scansione dell'audio per rilevarlo. Il seguente snippet mostra come pubblicare un messaggio su quel decoder 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
      })
    })

Attivazione del logging di debug

Il logging di debug visualizza nella console eventi interni significativi, che possono essere utili per tenere traccia dei 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 degli utenti. Ciò è indicato dallo stato di 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 acconsente, il rilevamento del dispositivo non funzionerà. In questo caso, l'app dovrebbe mostrare un messaggio per ricordare all'utente che il rilevamento del dispositivo è disattivato. Lo stato dell'autorizzazione è archiviato in NSUserDefaults.

Lo snippet seguente mostra l'iscrizione allo stato di 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 concede o nega 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'opzione di attivazione/disattivazione in una pagina delle impostazioni.

Ecco un esempio di come ottenere e impostare lo stato di 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 dell'utente che hanno effetto sulla funzione Qui vicino

Se l'utente ha negato l'autorizzazione di accesso al microfono o Bluetooth o ha disattivato il Bluetooth, la funzione Qui vicino potrebbe non funzionare o non funzionare affatto. In questi casi, la tua app dovrebbe mostrare un messaggio per avvisare l'utente che le operazioni di Nelle vicinanze 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
      }
    })

Override della finestra di dialogo dell'autorizzazione Nelle vicinanze

In base ai parametri trasmessi alle pubblicazioni e agli abbonamenti, iOS potrebbe richiedere varie autorizzazioni per consentire il funzionamento della funzione Qui vicino. Ad esempio, la strategia predefinita ascolta i dati trasmessi su audio quasi a ultrasuoni, quindi iOS richiederà l'autorizzazione per utilizzare il microfono. In questi casi, Nelle vicinanze verrà visualizzata una finestra di dialogo "preflight" che spiega il motivo per cui 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 della pubblicazione o dell'abbonamento. Il tuo 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 la tecnologia BLE per il rilevamento dei dispositivi possono funzionare in background. Ecco alcuni aspetti da tenere presente quando decidi di utilizzare la modalità in background:

  • Per le operazioni in background è necessario utilizzare solo il supporto BLE; l'audio non è supportato.
  • È previsto un costo aggiuntivo per la batteria BLE in background. Il costo è basso, ma è consigliabile 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à in background e solo BLE nella pubblicazione o nell'abbonamento passando in 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 Info.plist dell'app:

    • UIBackgroundModes voci:

      • bluetooth-central per la scansione BLE in background. Necessaria solo quando la modalità di rilevamento include la scansione; lo fa per impostazione predefinita.
      • bluetooth-peripheral per pubblicità BLE in background. Necessario solo quando la modalità di rilevamento include la trasmissione; lo fa per impostazione predefinita.
    • Stringa NSBluetoothPeripheralUsageDescription che descrive perché fai pubblicità su BLE. Ad esempio, "Viene pubblicizzato un token anonimo tramite Bluetooth per rilevare i dispositivi nelle vicinanze". Per ulteriori dettagli, consulta la documentazione di Apple.

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

    • Salva il valore della modalità background su 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à in background è attiva.

Notifiche in background

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

Per aggiungerli alla tua app, procedi nel seguente modo:

  • Registrati per ricevere 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 tua iscrizione:

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