Opublikuj i zasubskrybuj

Nearby Messages API to interfejs API typu publikowanie-subskrypcja, który umożliwia urządzeniom w pobliżu wymianę małych pakietów danych. Gdy urządzenie opublikuje wiadomość, urządzenia w pobliżu mogą ją odebrać. Aby zachować dobrą wydajność, rozmiar wiadomości powinien być stosunkowo mały. Ta usługa nie jest przeznaczona do wymiany większych obiektów, takich jak zdjęcia i filmy.

Zestaw urządzeń w pobliżu jest określany na podstawie wymiany małych tokenów przez Bluetooth i dźwięk o częstotliwości bliskiej ultradźwiękom (niesłyszalny). Gdy urządzenie wykryje token z pobliskiego urządzenia, wysyła go na serwer Wymiany wiadomości z urządzeniami w pobliżu, aby go zweryfikować i sprawdzić, czy są jakieś wiadomości do dostarczenia w ramach bieżącego zestawu subskrypcji aplikacji.

Aplikacja może kontrolować zestaw nośników używanych do wykrywania urządzeń oraz to, czy nośniki są używane do rozgłaszania tokenów lub skanowania w poszukiwaniu tokenów. Domyślnie nadawanie i skanowanie odbywa się we wszystkich mediach. Aby przeprowadzić wykrywanie w przypadku podzbioru lub nośników oraz określić, czy ma być ono prowadzone w trybie transmisji czy skanowania, musisz przekazać dodatkowe parametry podczas tworzenia publikacji i subskrypcji.

Ta biblioteka działa w systemie iOS 7 i nowszym oraz jest tworzona za pomocą pakietu SDK na iOS 8.

Tworzenie menedżera wiadomości

Ten kod tworzy obiekt menedżera wiadomości, który umożliwia publikowanie i subskrybowanie. Wymiana wiadomości nie jest uwierzytelniona, więc musisz podać publiczny klucz interfejsu API dla iOS. Możesz go utworzyć w Google Developers Console w przypadku swojego projektu.

Objective-C

#import <GNSMessages.h>

GNSMessageManager *messageManager =
    [[GNSMessageManager alloc] initWithAPIKey:@"API_KEY"];

Swift

let messageManager = GNSMessageManager(APIKey: "API_KEY")

Publikowanie wiadomości

Ten fragment kodu pokazuje, jak opublikować wiadomość zawierającą imię. Publikacja jest aktywna, dopóki istnieje obiekt publikacji. Aby zatrzymać publikowanie, zwolnij obiekt publikacji.

Objective-C

id<GNSPublication> publication =
    [messageManager publicationWithMessage:[GNSMessage messageWithContent:[name dataUsingEncoding:NSUTF8StringEncoding]]];

Swift

let publication =
    messageManager.publication(with: GNSMessage(content: name.data(using: .utf8)))

Subskrybowanie wiadomości

Ten fragment kodu pokazuje, jak zasubskrybować wszystkie nazwy udostępnione przez poprzedni fragment publikacji. Subskrypcja jest aktywna, dopóki istnieją obiekty subskrypcji. Aby anulować subskrypcję, zwolnij obiekt subskrypcji.

Procedura obsługi znalezionych wiadomości jest wywoływana, gdy zostaną wykryte urządzenia w pobliżu, które publikują wiadomości. Funkcja obsługi utraty wiadomości jest wywoływana, gdy wiadomość nie jest już obserwowana (urządzenie wyszło poza zasięg lub nie publikuje już wiadomości).

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

Media, w których wyświetlają się reklamy Discovery

Domyślnie do wykrywania urządzeń w pobliżu będą używane oba media (audio i Bluetooth), a oba będą nadawać i skanować. W niektórych przypadkach musisz dodać do pliku Info.plist aplikacji te wpisy:

  • Jeśli aplikacja skanuje za pomocą dźwięku, dodaj NSMicrophoneUsageDescription, czyli ciąg znaków opisujący, dlaczego będziesz używać mikrofonu. Na przykład: „Mikrofon nasłuchuje anonimowych tokenów z urządzeń w pobliżu”.

  • Jeśli Twoja aplikacja nadaje sygnały za pomocą BLE, dodaj element NSBluetoothPeripheralUsageDescription, czyli ciąg znaków opisujący, dlaczego będziesz wyświetlać reklamy za pomocą BLE. Na przykład: „Anonimowy token jest rozgłaszany przez Bluetooth w celu wykrywania urządzeń w pobliżu”.

W niektórych przypadkach aplikacja może potrzebować tylko jednego z tych mediów i nie musi jednocześnie nadawać i skanować w jego obrębie.

Na przykład aplikacja przeznaczona do łączenia się z dekoderem, który nadaje tylko dźwięk, musi skanować tylko dźwięk, aby go wykryć. Poniższy fragment kodu pokazuje, jak opublikować wiadomość na dekoderze, używając tylko skanowania dźwięku do wykrywania:

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

Włączanie logowania debugowania

Logowanie debugowania zapisuje w konsoli ważne zdarzenia wewnętrzne, które mogą być przydatne do wykrywania problemów, jakie mogą wystąpić podczas integrowania z aplikacją interfejsu Nearby Messages. Jeśli skontaktujesz się z nami w sprawie pomocy technicznej, poprosimy Cię o te logi.

Włącz tę funkcję przed utworzeniem menedżera wiadomości. Ten fragment kodu pokazuje, jak włączyć logowanie debugowania:

Objective-C

[GNSMessageManager setDebugLoggingEnabled:YES];

Swift

GNSMessageManager.setDebugLoggingEnabled(true)

Śledzenie stanu uprawnień dotyczących urządzeń w pobliżu

Aby włączyć wykrywanie urządzeń, musisz uzyskać zgodę użytkownika. Wskazuje to stan uprawnień do korzystania z funkcji w pobliżu. Podczas pierwszego wywołania funkcji tworzenia publikacji lub subskrypcji użytkownikowi wyświetla się okno z prośbą o zgodę. Jeśli użytkownik nie wyrazi zgody, wykrywanie urządzeń nie będzie działać. W takim przypadku aplikacja powinna wyświetlić komunikat przypominający użytkownikowi, że wykrywanie urządzeń jest wyłączone. Stan uprawnień jest przechowywany w pliku NSUserDefaults.

Poniższy fragment kodu pokazuje, jak zasubskrybować stan uprawnień. Procedura obsługi zmiany stanu uprawnień jest wywoływana za każdym razem, gdy stan się zmienia. Nie jest wywoływana po raz pierwszy, dopóki użytkownik nie przyzna lub nie odmówi uprawnień. Zwolnij obiekt uprawnień, aby anulować subskrypcję.

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

Aplikacja może udostępniać użytkownikowi sposób zmiany stanu uprawnień, np. za pomocą przełącznika na stronie ustawień.

Oto przykład uzyskiwania i ustawiania stanu uprawnień.

Objective-C

BOOL permissionState = [GNSPermission isGranted];
[GNSPermission setGranted:!permissionState];  // toggle the state

Swift

let permissionState = GNSPermission.isGranted()
GNSPermission.setGranted(!permissionState)  // toggle the state

Śledzenie ustawień użytkownika, które wpływają na Udostępnianie w pobliżu

Jeśli użytkownik odmówi dostępu do mikrofonu lub Bluetootha albo wyłączy Bluetootha, funkcja W pobliżu nie będzie działać prawidłowo lub wcale. W takich przypadkach aplikacja powinna wyświetlać komunikat informujący użytkownika, że działanie funkcji W pobliżu jest utrudnione. Poniższy fragment kodu pokazuje, jak śledzić stan tych ustawień użytkownika, przekazując moduły obsługi podczas tworzenia menedżera wiadomości:

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

Zastępowanie okna z prośbą o uprawnienia do korzystania z usług w pobliżu

W zależności od parametrów przekazywanych do publikacji i subskrypcji system iOS może poprosić o różne uprawnienia, zanim zezwoli na działanie interfejsu Nearby. Na przykład strategia domyślna nasłuchuje danych przesyłanych w zakresie dźwięków zbliżonych do ultradźwięków, więc iOS poprosi o pozwolenie na korzystanie z mikrofonu. W takich przypadkach funkcja W pobliżu wyświetli okno „przed lotem”, które wyjaśni użytkownikowi, dlaczego prosi się go o udzielenie uprawnień.

Jeśli chcesz wyświetlać niestandardowe okno „wstępnego sprawdzania”, ustaw parametr permissionRequestHandler na blok niestandardowy w parametrach publikacji lub subskrypcji. Twój blok niestandardowy musi wywoływać blok permissionHandler po udzieleniu przez użytkownika odpowiedzi. Poniższy fragment kodu pokazuje, jak to zrobić w przypadku publikacji:

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

Operacja w tle

Publikacje i subskrypcje, które używają BLE do wykrywania urządzeń, mogą działać w tle. Oto kilka kwestii, o których musisz pamiętać, gdy zdecydujesz się używać trybu w tle:

  • Operacje w tle muszą korzystać tylko z BLE; dźwięk nie jest obsługiwany.
  • W przypadku BLE w tle występuje dodatkowy koszt baterii. Koszt jest niski, ale przed podjęciem decyzji o użyciu trybu działania w tle warto go zmierzyć.
  • iOS poprosi użytkownika o zezwolenie na wyświetlanie reklam przez BLE w tle.

Aby dodać tryb tła do publikacji lub subskrypcji, wykonaj te dodatkowe czynności:

  • Włącz tryb działania w tle i tylko BLE w publikacji lub subskrypcji, przekazując prawidłowo skonfigurowany obiekt GNSStrategy. Poniższy fragment kodu pokazuje, jak to zrobić w przypadku subskrypcji:

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

  • Dodaj te wpisy do pliku Info.plist aplikacji:

    • UIBackgroundModes wpisy:

      • bluetooth-central do skanowania BLE w tle. Wymagane tylko wtedy, gdy tryb wykrywania obejmuje skanowanie (domyślnie tak jest).
      • bluetooth-peripheral – w przypadku reklamowania BLE w tle. Wymagane tylko wtedy, gdy tryb wykrywania obejmuje transmisję. Jest to domyślne ustawienie.

    • NSBluetoothPeripheralUsageDescription ciąg znaków opisujący, dlaczego będziesz wyświetlać reklamy w BLE. Na przykład: „Anonimowy token jest reklamowany przez Bluetooth w celu wykrywania urządzeń w pobliżu”. Szczegóły znajdziesz w dokumentacji Apple.

  • Gdy aplikacja działa w tle, system może ją w każdej chwili zamknąć. Jeśli tryb działania w tle jest ustawieniem, które użytkownik może włączyć lub wyłączyć, aplikacja powinna:

    • Zapisuj wartość trybu działania w tle w NSUserDefaults za każdym razem, gdy użytkownik ją zmieni.
    • Podczas uruchamiania odczytuje go z NSUserDefaults i przywraca publikacje lub subskrypcje w pobliżu, jeśli włączony jest tryb działania w tle.

Powiadomienia w tle

Jeśli chcesz, aby aplikacja powiadamiała użytkownika o otrzymaniu wiadomości w subskrypcji w tle, możesz użyć powiadomień lokalnych.

Aby dodać je do aplikacji, wykonaj te czynności:

  • Rejestrowanie powiadomień lokalnych przy uruchamianiu:

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

  • Wyślij powiadomienie lokalne w obsłudze znalezionych wiadomości w subskrypcji:

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