本頁面由 Cloud Translation API 翻譯而成。

發布及訂閱

Nearby Messages API 是一種發布訂閱 API，可讓鄰近裝置以及交換小型資料酬載裝置發布訊息後，就在附近裝置就能接收訊息。訊息大小應保持小短維持良好效能這項服務無法用於交換大型企業像是相片和影片等物件

鄰近裝置組合是由先前使用的小權杖交換而決定藍牙和近乎超音波 (無聲) 音訊。裝置偵測到權杖時，將權杖傳送至 Nearby Messages 伺服器，進行驗證，並檢查應用程式是否有任何要傳送的訊息現有訂閱項目組合

應用程式可以控制用於探索裝置的媒介組合，是否使用媒介來廣播符記和/或掃描符記。根據預設，所有媒介都會播送及掃描。待辦與特定類型或媒介相關的探索內容，並控制要播送或掃描、您必須在建立出版品時傳送其他參數訂閱項目。

這個程式庫可在 iOS 7 以上版本中執行，而且會透過 iOS 8 SDK 建立。

建立訊息管理員

這段程式碼會建立訊息管理員物件訊息交換未經驗證，因此請務必提供 iOS 的公用 API 金鑰您可以使用 Google Developers Console 項目建立。

Objective-C

#import <GNSMessages.h>

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

Swift

let messageManager = GNSMessageManager(APIKey: "API_KEY")

正在發布訊息

這個程式碼片段示範如何發布包含名稱的訊息。只要出版品物件存在，出版品就會處於有效狀態。停止釋出發布物件

Objective-C

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

Swift

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

訂閱訊息

這段程式碼片段示範如何訂閱由先前出版品程式碼片段只要訂閱物件已存在。如要停止訂閱，請釋出訂閱物件。

附近的裝置發布應用程式時，系統會呼叫找到的訊息處理常式就會發現訊息如果沒有訊息，則呼叫訊息遺失的處理常式未觀察到狀態 (裝置超出範圍或已停止發布) 訊息)。

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

探索媒介

根據預設，系統會使用媒體 (音訊和藍牙) 尋找附近的裝置裝置，並透過這兩種媒介播送及掃描。在某些情況下必須將下列項目新增至應用程式的 Info.plist：

如果應用程式使用音訊掃描，請加入 NSMicrophoneUsageDescription 說明您使用麥克風的原因。例如：「麥克風會監聽鄰近裝置上的匿名符記。」
如果您的應用程式是使用 BLE 廣播，請新增 NSBluetoothPeripheralUsageDescription：這個字串可說明原因願意在 BLE 上打廣告例如：「宣傳匿名權杖透過藍牙探索鄰近裝置。」

在某些情況下，應用程式可能只需要使用其中一種媒介，可能不需要同時在該媒介上進行廣播及掃描

例如，應用程式設計為連線到機上盒，廣播播送時，只需掃描音訊即可找到。下列程式碼片段顯示如何僅使用音訊，將訊息發布至該機上盒掃描尋找發現：

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

啟用偵錯記錄功能

偵錯記錄功能會輸出重要的內部事件至主控台可以追蹤您在整合「鄰近分享」時可能會遇到的問題將訊息傳送到您的應用程式。如果您與我們聯絡，我們會請您提供這些記錄技術支援服務

請務必在建立訊息管理員前啟用該功能。這個程式碼片段顯示如何啟用偵錯記錄功能：

Objective-C

[GNSMessageManager setDebugLoggingEnabled:YES];

Swift

GNSMessageManager.setDebugLoggingEnabled(true)

追蹤鄰近分享權限狀態

必須取得使用者同意，才能啟用裝置探索功能。會由附近權限狀態。第一次呼叫建立出版品時，訂閱項目後，系統會向使用者顯示同意對話方塊。如果使用者尚未同意，裝置探索功能將無法運作。在此情況下，應用程式應顯示訊息提醒使用者探索裝置功能已停用。權限狀態會儲存在 NSUserDefaults 中。

以下程式碼片段示範如何訂閱權限。每當狀態變更，系統就會呼叫權限狀態已變更的處理常式未授予使用者或拒絕權限。如要停止訂閱，請釋出權限物件。

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

應用程式可讓使用者變更權限狀態。的例如在設定頁面使用切換鈕

以下範例說明如何取得及設定權限狀態。

Objective-C

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

Swift

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

追蹤影響鄰近分享功能的使用者設定

如果使用者拒絕授予麥克風權限、拒絕藍牙權限，或關閉藍牙，鄰近分享功能也將無法正常運作，或者完全無法運作。在這種情況下，您的應用程式應顯示訊息，提醒使用者 Nearby 的這類情形下列程式碼片段說明如何追蹤建立訊息時傳遞處理常式，即可瞭解這些使用者設定的狀態經理：

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

覆寫「附近」權限對話方塊

視您傳遞至出版品和訂閱的參數而定 iOS 可能必須先要求各種權限，才能允許「鄰近分享」功能正常運作。適用對象舉例來說，預設策略會監聽在超音波情況下傳輸的資料因此 iOS 會要求你授予麥克風存取權。在這些情況下附近的地點會顯示「預檢」說明系統要求使用者為何並授予相關權限

如果您要提供自訂「預檢」對話方塊，則將將 permissionRequestHandler 參數加到出版品中的自訂區塊，或是訂閱參數自訂區塊必須呼叫 permissionHandler 並在使用者回覆後封鎖下列程式碼片段說明如何執行這項作業出版品：

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

背景作業

凡是採用 BLE 搜尋裝置的出版品和訂閱項目，皆可在背景。決定使用 Cookie 時，請注意下列事項背景模式：

背景作業只能使用 BLE 媒介；不支援此音訊
背景 BLE 的電池費用增加。費用很低應該先測量再決定是否使用背景模式。
iOS 會要求使用者授權在背景透過 BLE 放送廣告。

如要為出版品或訂閱項目新增背景模式，請額外遵守步驟：

如要在出版品或訂閱中啟用背景模式和 BLE 專屬功能，請按照下列步驟操作：傳入正確設定的 GNSStrategy 物件。下列程式碼片段顯示如何在訂閱中執行這項操作：

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

將下列項目新增至應用程式的 Info.plist：
- UIBackgroundModes 個項目：
  - bluetooth-central，可在背景進行 BLE 掃描。僅需要探索模式納入掃描的時機預設會執行這項作業
  - bluetooth-peripheral：可在背景執行 BLE 廣告。必要探索模式支援廣播功能時；預設會執行這項作業
- NSBluetoothPeripheralUsageDescription 字串說明原因即將在 BLE 上放送廣告例如：「匿名權杖是並透過藍牙進行宣傳，藉此發掘鄰近裝置。」詳情請見 Apple 說明文件。
系統隨時在背景執行時，可能會終止您的應用程式。如果背景模式是一項設定，可由使用者、您的應用程式應執行以下操作：
- 每當使用者時，將背景模式值儲存至 NSUserDefaults 變更內容。
- 啟動時，從 NSUserDefaults 中讀取，並還原鄰近分享功能如果啟用背景模式，則出版品和/或訂閱的項目。

背景通知

如果您希望您的應用程式在收到訂閱項目時通知使用者並在背景執行時本地通知。

您可以按照下列步驟將這類標籤加入應用程式：

在啟動時註冊本機通知：

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

在訂閱項目的訊息找到處理常式中傳送本機通知：

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