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.
- Salva il valore della modalità background su
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... }