本頁面由 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
      })
    })

啟用偵錯記錄

偵錯記錄會將重要的內部事件列印到控制台，有助於追蹤將 Nearby Messages 整合至應用程式時可能遇到的問題。如果您與我們聯絡以尋求技術支援，我們會要求您提供這些記錄。

您應先啟用這項功能，再建立訊息管理工具。以下程式碼片段說明如何啟用偵錯記錄：

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 會要求麥克風使用權限。在這些情況下，Nearby 會顯示「預檢」對話方塊，說明系統要求使用者授予權限的原因。

如要提供自訂的「預檢」對話方塊，請在發布或訂閱參數中，將 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 探索裝置的發布和訂閱作業可以在背景執行。決定使用背景模式時，請注意下列事項：

背景作業只能使用 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 讀取，並在啟用背景模式時還原 Nearby 發布項目和/或訂閱項目。

背景通知

如要讓應用程式在背景執行時，於訂閱項目收到訊息時通知使用者，可以使用本機通知。

如要在應用程式中新增這些元素，請按照下列步驟操作：

在啟動時註冊本機通知：

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

發布及訂閱 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

建立訊息管理員

Objective-C

Swift

發布訊息

Objective-C

Swift

訂閱訊息

Objective-C

Swift

探索媒介

Objective-C

Swift

啟用偵錯記錄

Objective-C

Swift

追蹤「附近」權限狀態

Objective-C

Swift

Objective-C

Swift

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

Objective-C

Swift

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

Objective-C

Swift

背景作業

Objective-C

Swift

背景通知

Objective-C

Swift

Objective-C

Swift

發布及訂閱