A API Nearby Messages é uma API de publicação/assinatura que permite que dispositivos próximos troquem pequenos payloads de dados. Quando um dispositivo publica uma mensagem, ela pode ser recebida pelos dispositivos próximos. O tamanho das mensagens precisa ser pequeno para manter um bom desempenho. Esse serviço não serve para trocar objetos maiores, como fotos e vídeos.
O conjunto de dispositivos próximos é determinado pela troca de pequenos tokens por Bluetooth e áudio quase ultrassônico (audível). Quando um dispositivo detecta um token de um dispositivo próximo, ele o envia ao servidor do Nearby Messages para validá-lo e verificar se há alguma mensagem a ser entregue para o conjunto atual de assinaturas do aplicativo.
Um aplicativo pode controlar o conjunto de meios usados para a descoberta de dispositivos e se as mídias são usadas para transmitir tokens e/ou procurar tokens. Por padrão, a transmissão e a verificação são feitas em todas as mídias. Para fazer a descoberta em um subconjunto ou mídias e controlar se é necessário transmitir ou verificar, você precisa transmitir outros parâmetros ao criar publicações e assinaturas.
Essa biblioteca é executada no iOS 7 ou superior e se baseia no SDK para iOS 8.
Como criar um gerenciador de mensagens
Esse código cria um objeto gerenciador de mensagens que permite publicar e assinar. A troca de mensagens não é autenticada. Portanto, é necessário fornecer uma chave de API pública para iOS. Você pode criar um usando a entrada do Google Developers Console do seu projeto.
Objective-C
#import <GNSMessages.h>
GNSMessageManager *messageManager =
[[GNSMessageManager alloc] initWithAPIKey:@"API_KEY"];
Swift
let messageManager = GNSMessageManager(APIKey: "API_KEY")
Publicar uma mensagem
Este snippet de código demonstra a publicação de uma mensagem contendo um nome. A publicação fica ativa enquanto o objeto de publicação existir. Para interromper a publicação, libere o objeto de publicação.
Objective-C
id<GNSPublication> publication =
[messageManager publicationWithMessage:[GNSMessage messageWithContent:[name dataUsingEncoding:NSUTF8StringEncoding]]];
Swift
let publication =
messageManager.publication(with: GNSMessage(content: name.data(using: .utf8)))
Como se inscrever nas mensagens
Este snippet de código demonstra a inscrição em todos os nomes compartilhados pelo snippet da publicação anterior. A assinatura fica ativa enquanto os objetos de assinatura existirem. Para interromper a assinatura, libere o objeto de assinatura.
O gerenciador de mensagens encontradas é chamado quando dispositivos próximos que estão publicando mensagens são descobertos. O gerenciador de mensagens perdidas é chamado quando uma mensagem não é mais observada (o dispositivo saiu do alcance ou não está mais publicando a mensagem).
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
})
Mídias Discovery
Por padrão, os dois meios (áudio e Bluetooth) serão usados para descobrir dispositivos
por perto, e ambos serão transmitidos e buscados. Em alguns casos, é
necessário adicionar as seguintes entradas ao Info.plist
do app:
Se o app fizer verificações usando áudio, adicione
NSMicrophoneUsageDescription
, que é uma string que descreve por que você vai usar o microfone. Por exemplo, "O microfone detecta tokens anônimos de dispositivos próximos".Se o app transmitir usando BLE, adicione
NSBluetoothPeripheralUsageDescription
, que é uma string que descreve por que você vai anunciar nele. Por exemplo, "Um token anônimo é anunciado via Bluetooth para descobrir dispositivos por perto".
Em alguns casos, o app pode precisar usar apenas uma das mídias e pode não precisar fazer transmissão e leitura nessa mídia.
Por exemplo, um app projetado para se conectar a um conversor que transmite áudio só precisa fazer uma busca no áudio para descobri-lo. O snippet a seguir mostra como publicar uma mensagem nesse conversor usando apenas a busca de áudio para descoberta:
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
})
})
Como ativar a geração de registros de depuração
O registro de depuração imprime eventos internos significativos no console que podem ser úteis para rastrear problemas que podem ser encontrados ao integrar o app Nearby Messages. Esses registros serão solicitados se você entrar em contato conosco para suporte técnico.
Você deve ativá-lo antes de criar um gerenciador de mensagens. Este snippet de código mostra como ativar a geração de registros de depuração:
Objective-C
[GNSMessageManager setDebugLoggingEnabled:YES];
Swift
GNSMessageManager.setDebugLoggingEnabled(true)
Rastrear o estado de permissão do Nearby
O consentimento do usuário é necessário para ativar a descoberta de dispositivos. Isso é indicado pelo
estado de permissão do Nearby. Na primeira chamada para criar uma publicação ou
assinatura, o usuário verá uma caixa de diálogo de consentimento. Se o usuário não consentir, a descoberta de dispositivos não funcionará. Nesse caso, o app precisa mostrar uma
mensagem para lembrar o usuário de que a descoberta de dispositivos está desativada. O estado
da permissão é armazenado em NSUserDefaults
.
O snippet a seguir demonstra como se inscrever no estado de permissão. O gerenciador de mudança do estado de permissão é chamado sempre que o estado muda e não é chamado na primeira vez até que o usuário tenha concedido ou negado a permissão. Libere o objeto de permissão para interromper a assinatura.
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
})
Seu app pode oferecer uma maneira de o usuário mudar o estado de permissão, por exemplo, usando uma chave de ativação em uma página de configurações.
Confira um exemplo de como acessar e definir o estado da permissão.
Objective-C
BOOL permissionState = [GNSPermission isGranted];
[GNSPermission setGranted:!permissionState]; // toggle the state
Swift
let permissionState = GNSPermission.isGranted()
GNSPermission.setGranted(!permissionState) // toggle the state
Rastrear configurações de usuários que afetam o "Por perto"
Se o usuário tiver negado a permissão para o microfone ou para o Bluetooth ou tiver desativado o Bluetooth, o Proximidade não funcionará tão bem ou não funcionará. O app precisa mostrar uma mensagem nesses casos, alertando o usuário de que as operações do Nearby estão sendo prejudicadas. O snippet a seguir mostra como rastrear o status dessas configurações do usuário transmitindo gerenciadores ao criar o gerenciador de mensagens:
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
}
})
Substituir a caixa de diálogo de permissão do Nearby
Dependendo dos parâmetros transmitidos para suas publicações e assinaturas, o iOS pode solicitar várias permissões antes de permitir o funcionamento do Nearby. Por exemplo, a estratégia padrão detecta dados transmitidos em áudio quase ultrassônico. Por isso, o iOS vai pedir permissão para usar o microfone. Nesses casos, o Nearby mostrará uma caixa de diálogo "simulação" que explica por que o usuário precisa conceder permissão.
Para fornecer uma caixa de diálogo "simulação" personalizada, defina o parâmetro
permissionRequestHandler
como um bloco personalizado nos parâmetros de publicação ou
assinatura. Seu bloqueio personalizado precisa chamar o bloco permissionHandler
depois da resposta do usuário. O snippet a seguir mostra como fazer isso
para uma publicação:
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.
}
})
Operação em segundo plano
As publicações e assinaturas que usam BLE para descoberta de dispositivos podem funcionar em segundo plano. Confira alguns pontos que você precisa considerar ao decidir usar o modo em segundo plano:
- As operações em segundo plano precisam usar somente a mídia BLE. Áudio não é aceito.
- O custo da bateria é extra para o BLE em segundo plano. O custo é baixo, mas é necessário medir antes de decidir usar o modo em segundo plano.
- O iOS vai solicitar permissão ao usuário para anunciar usando BLE em segundo plano.
Para adicionar o modo de segundo plano a uma publicação ou assinatura, siga estas outras etapas:
Ative o modo de segundo plano e somente BLE na publicação ou assinatura transmitindo um objeto
GNSStrategy
configurado corretamente. O snippet abaixo mostra como fazer isso para uma assinatura: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 }) })
Adicione estas entradas ao
Info.plist
do seu app:UIBackgroundModes
entradas:bluetooth-central
para verificação de BLE em segundo plano. Necessária apenas quando o modo de descoberta inclui verificação. Isso é feito por padrão.bluetooth-peripheral
para publicidade de BLE em segundo plano. Necessária apenas quando o modo de descoberta inclui transmissão. Isso acontece por padrão.
String
NSBluetoothPeripheralUsageDescription
que descreve por que você anunciará em BLE. Por exemplo, "Um token anônimo é anunciado por Bluetooth para descobrir dispositivos por perto". Consulte a documentação da Apple para mais detalhes.
Seu app pode ser encerrado a qualquer momento pelo sistema em segundo plano. Se o modo de segundo plano for uma configuração que pode ser ativada ou desativada pelo usuário, seu app precisa fazer o seguinte:
- Salve o valor do modo de segundo plano em
NSUserDefaults
sempre que ele for alterado pelo usuário. - Na inicialização, leia de
NSUserDefaults
e restaure as publicações e/ou assinaturas do Nearby, se o modo de segundo plano estiver ativado.
- Salve o valor do modo de segundo plano em
Notificações em segundo plano
Se você quiser que seu app notifique o usuário quando uma assinatura receber uma mensagem em segundo plano, use as notificações locais.
Siga estas etapas para adicioná-los ao app:
Registrar as notificações locais na inicialização:
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))
Envie uma notificação local no gerenciador de mensagens da sua assinatura:
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... }