Opublikuj i zasubskrybuj

Near Messages API to interfejs API do publikowania i subskrybowania, który pozwala urządzeniom w pobliżu może wymieniać niewielkie ładunki danych. Gdy urządzenie opublikuje wiadomość, w pobliżu urządzenia mogą odebrać wiadomość. Wiadomość powinna być dość mała do i utrzymać dobrą wydajność. Ta usługa nie służy do wymiany większych plików takie jak zdjęcia i filmy.

Zbiór urządzeń w pobliżu jest określany na podstawie wymiany małych tokenów Bluetooth i dźwięk bliski ultradźwiękowy (niesłyszalny). Gdy urządzenie wykryje token z urządzenia w pobliżu, wysyła token do serwera Wiadomości w pobliżu, jego poprawność i sprawdzić, czy są jakieś komunikaty do dostarczenia dla aplikacji aktualnego zestawu subskrypcji.

Aplikacja może kontrolować zestaw mediów używanych do wykrywania urządzeń oraz czy media są używane do rozpowszechniania tokenów i/lub skanowania w poszukiwaniu tokenów. Domyślnie transmisje i skanowanie są przeprowadzane w przypadku wszystkich mediów. Do zrobienia odkrywanie w podzbiorze lub mediach oraz określanie, czy mają być emitowane czy skanowane, musisz podczas tworzenia publikacji przekazywać dodatkowe parametry oraz subskrypcji.

Uwaga: wszystkie wywołania zwrotne w tej bibliotece używają bloków, a nie przedstawicieli. Pamiętaj, aby unikać cykli zachowywania danych w implementacjach blokowych. Zobacz jabłko dokumentacja jak unikać cykli zachowywania.

Ta biblioteka działa w iOS 7 i nowszych wersjach i korzysta z pakietu SDK na iOS 8.

Tworzenie menedżera wiadomości

Ten kod tworzy obiekt menedżera wiadomości, który umożliwia publikowanie i zasubskrybować kanał. Wymiana wiadomości nie jest uwierzytelniona, więc musisz podać publiczny klucz API dla iOS. Możesz ją utworzyć przy użyciu wpisu w Google Developers Console dotyczącego w Twoim projekcie.

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 publikowanie wiadomości zawierającej nazwę. Publikacja jest aktywna, dopóki istnieje obiekt publikacji. Aby zatrzymać Publishing, 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 subskrypcję wszystkich nazw udostępnianych przez poprzedniego fragmentu kodu publikacji. Subskrypcja jest aktywna, dopóki Obiekty subskrypcji istnieją. Aby zrezygnować z subskrypcji, zwolnij subskrypcję obiektu.

Moduł obsługi znalezionej wiadomości jest wywoływany, gdy znajdują się w pobliżu urządzenia, które publikują wiadomości wiadomości są wykrywane. Moduł obsługi utraconej wiadomości jest wywoływany, gdy wiadomość nie jest jest już obserwowany (urządzenie znalazło się poza zasięgiem lub nie publikuje już ).

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 Discovery

Domyślnie do wykrywania obiektów w pobliżu używane są oba media (audio i Bluetooth) i oba media będą transmitowane i skanowane. W niektórych przypadkach należy dodać te pozycje do Info.plist aplikacji:

• Jeśli aplikacja skanuje przy użyciu dźwięku, dodaj NSMicrophoneUsageDescription, czyli tekst opisujący, dlaczego używasz mikrofonu. Na przykład „Adres mikrofon nasłuchuje anonimowych tokenów z urządzeń w pobliżu”.

• Jeśli aplikacja przesyła za pomocą BLE, dodaj NSBluetoothPeripheralUsageDescription – jest to ciąg tekstowy opisujący, będą wyświetlać reklamy w BLE. Na przykład „Reklamowany jest anonimowy token przez Bluetooth, aby wykryć urządzenia w pobliżu”.

W niektórych przypadkach aplikacja może korzystać tylko z jednego z tych mediów, być może nie będą musieli transmitować i skanować na tym medium.

Na przykład aplikacja, która łączy się z dekoderem transmisja dźwięku musi tylko przeskanować dźwięk, aby go wykryć. Poniżej fragment kodu pokazuje, jak opublikować wiadomość na dekoderze tylko przy użyciu dźwięku skanowanie w poszukiwaniu:

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łączam logowanie debugowania

Logowanie debugowania powoduje wydrukowanie w konsoli istotnych zdarzeń wewnętrznych, które można przydatne do śledzenia problemów, które mogą wystąpić przy integrowaniu funkcji W pobliżu Wiadomości do aplikacji. Poprosimy Cię o te dzienniki, jeśli skontaktujesz się z nami w sprawie pomocy technicznej.

Należy go włączyć 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 pozwolenia na korzystanie z funkcji W pobliżu

Do włączenia wykrywania urządzeń wymagana jest zgoda użytkownika. Jest to wskazywane przez tag Stan uprawnień W pobliżu. podczas pierwszej rozmowy w celu utworzenia publikacji, użytkownik zobaczy okno z prośbą o zgodę. Jeśli użytkownik nie wyrazi zgody, zgody użytkownika, wykrywanie urządzenia nie będzie działać. W takim przypadku aplikacja powinna wyświetlać przypominający użytkownikowi, że wykrywanie urządzeń jest wyłączone. Uprawnienia stan jest przechowywany w NSUserDefaults.

Ten fragment kodu pokazuje subskrypcję stanu uprawnień. moduł obsługi zmiany stanu uprawnień jest wywoływany przy każdej zmianie stanu i nie zostanie wywołana po raz pierwszy, dopóki użytkownik nie udzielił zgody lub jej odmówił. Zwolnij obiekt uprawnień, aby przestać subskrybować.

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 umożliwiać użytkownikowi zmianę stanu uprawnień; w przypadku np. za pomocą przełącznika na stronie ustawień.

Oto przykład, jak uzyskać i ustawić stan uprawnień.

Objective-C

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

Swift

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

Uwaga: aplikacja powinna ustawiać stan uprawnień tylko w odpowiedzi na dane wejściowe użytkownika. Nigdy nie zmieniaj stanu uprawnień bez zgody użytkownika.

Śledzenie ustawień użytkowników, które mają wpływ na działanie funkcji W pobliżu

jeśli użytkownik odmówił przyznania dostępu do mikrofonu, dostępu do Bluetootha lub ma wyłączony Bluetooth, funkcja W pobliżu nie będzie działać za dobrze lub może w ogóle nie działać. Aplikacja powinna w takich przypadkach wyświetlać komunikat informujący użytkownika, że funkcja W pobliżu mają utrudnianie w działaniu. Ten fragment kodu pokazuje, jak śledzić tych ustawień użytkownika przez przekazanie modułów obsługi podczas tworzenia wiadomości menedżer:

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 uprawnieniami dostępu do urządzeń w pobliżu

W zależności od parametrów, które przekazujesz w publikacjach i subskrypcjach, iOS może prosić o różne uprawnienia przed zezwoleniem na działanie funkcji W pobliżu. Dla: przykład, domyślna strategia nasłuchuje danych przesyłanych przy użyciu więc iOS poprosi o pozwolenie na korzystanie z mikrofonu. W takich przypadkach W pobliżu wyświetli się „przelot wstępny” okno dialogowe z wyjaśnieniem, dlaczego zadano użytkownikowi pytanie aby udzielić pozwolenia.

Jeśli chcesz podać niestandardowy „proces wstępny” ustaw wartość permissionRequestHandler do niestandardowego blokowania w publikacji lub parametrów subskrypcji. Blokada niestandardowa musi wywoływać metodę permissionHandler blokować po udzieleniu odpowiedzi przez użytkownika. Fragment kodu poniżej 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.
          }
        })

Działanie w tle

Publikacje i subskrypcje, które wykorzystują BLE do wykrywania urządzeń, mogą działać w tle. Oto kilka kwestii, o których należy pamiętać przy podejmowaniu decyzji tryb działania w tle:

• Operacje w tle mogą korzystać wyłącznie z medium BLE. dźwięk nie jest obsługiwany.
• Jest dodatkowy koszt baterii w przypadku obsługi BLE w tle. Koszt jest niewielki, ale należy go zmierzyć przed użyciem trybu działania w tle.
• iOS poprosi użytkownika o pozwolenie na reklamowanie się za pomocą BLE w tle.

Aby dodać tryb działania w tle do publikacji lub subskrypcji, wykonaj te dodatkowe czynności: kroki:

• Włącz tryb działania w tle i tryb BLE w swojej publikacji lub subskrypcji do prawidłowo skonfigurowanego obiektu GNSStrategy. Ten fragment kodu 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 Info.plist aplikacji:

  • UIBackgroundModes wpisów:

    • bluetooth-central do skanowania BLE w tle. Tylko potrzebne gdy tryb wykrywania obejmuje skanowanie; domyślnie.
    • bluetooth-peripheral za reklamy BLE w tle. Potrzebne tylko wtedy, gdy tryb wykrywania obejmuje nadawanie; domyślnie.

  • NSBluetoothPeripheralUsageDescription ciąg tekstowy opisujący powód będziesz reklamować się w BLE. Na przykład „Anonimowy token to reklamować się przez Bluetooth, aby wykryć urządzenia w pobliżu”. Zobacz Dokumentacja Apple .

• System może w każdej chwili zamknąć Twoją aplikację w tle. Jeśli Tryb działania w tle to ustawienie, które może włączyć lub wyłączyć powinna wykonywać te czynności:

  • Zapisuj wartość trybu działania w tle na NSUserDefaults za każdym razem, gdy użytkownik ją zmienić.
  • Po uruchomieniu odczytaj dane z urządzenia NSUserDefaults i przywróć kartę W pobliżu publikacji lub subskrypcji, jeśli jest włączony tryb działania w tle.

Powiadomienia w tle

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

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

• Zarejestruj się, aby otrzymywać lokalne powiadomienia 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 lokalne powiadomienie w ramach modułu obsługi znalezionej wiadomości w Twojej 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...
  }