เผยแพร่และสมัครรับข้อมูล

Nearby Messages API คือ API การสมัครรับข้อมูลแบบเผยแพร่ ซึ่งช่วยให้อุปกรณ์ที่อยู่ใกล้เคียงแลกเปลี่ยนข้อมูลปริมาณน้อยได้ เมื่ออุปกรณ์เผยแพร่ข้อความแล้ว อุปกรณ์ที่อยู่ใกล้เคียงจะได้รับข้อความ ข้อความควรมีขนาดที่เล็กพอสมควรเพื่อรักษาประสิทธิภาพที่ดี บริการนี้ไม่ได้มีไว้สำหรับการแลกเปลี่ยนออบเจ็กต์ขนาดใหญ่ เช่น รูปภาพและวิดีโอ

ชุดอุปกรณ์ใกล้เคียงจะกำหนดโดยการแลกเปลี่ยนโทเค็นขนาดเล็กผ่านบลูทูธและเสียงแบบเกือบอัลตราโซนิก (ไม่ได้ยินเสียง) เมื่ออุปกรณ์ตรวจพบโทเค็นจากอุปกรณ์ใกล้เคียง อุปกรณ์จะส่งโทเค็นไปยังเซิร์ฟเวอร์ข้อความใกล้เคียงเพื่อตรวจสอบและตรวจสอบว่ามีข้อความที่จะส่งสำหรับชุดการสมัครใช้บริการปัจจุบันของแอปพลิเคชันหรือไม่

แอปพลิเคชันสามารถควบคุมชุดสื่อที่ใช้ในการค้นพบอุปกรณ์ และกำหนดว่าจะใช้สื่อในการกระจายโทเค็นและ/หรือสแกนหาโทเค็นหรือไม่ โดยค่าเริ่มต้น การแพร่สัญญาณและการสแกนจะกระทำในสื่อทั้งหมด หากต้องการสร้างการค้นพบในสื่อชุดย่อยหรือสื่อ และหากต้องการควบคุมว่าจะออกอากาศหรือสแกนหรือไม่ คุณต้องส่งพารามิเตอร์เพิ่มเติมเมื่อสร้างสื่อเผยแพร่และการสมัครใช้บริการ

ไลบรารีนี้ใช้งานได้ใน iOS 7 ขึ้นไป และสร้างด้วย iOS 8 SDK

การสร้างตัวจัดการข้อความ

โค้ดนี้จะสร้างออบเจ็กต์ตัวจัดการข้อความ ซึ่งช่วยให้คุณเผยแพร่และสมัครใช้บริการได้ การแลกเปลี่ยนข้อความไม่ผ่านการตรวจสอบสิทธิ์ คุณจึงต้องระบุคีย์ API สาธารณะสำหรับ iOS คุณสร้างได้โดยใช้รายการ 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
    })

สื่อการค้นพบ

โดยค่าเริ่มต้น ระบบจะใช้ทั้ง 2 สื่อ (เสียงและบลูทูธ) เพื่อค้นหาอุปกรณ์ที่อยู่ใกล้เคียง และสื่อทั้ง 2 รายการจะออกอากาศและสแกน ในบางกรณี คุณต้องเพิ่มรายการต่อไปนี้ลงใน Info.plist ของแอป

  • หากแอปสแกนโดยใช้เสียง ให้เพิ่ม NSMicrophoneUsageDescription ซึ่งเป็นสตริงที่อธิบายเหตุผลที่คุณจะใช้ไมโครโฟน เช่น "ไมโครโฟนจะคอยฟังโทเค็นที่ไม่ระบุตัวตนจากอุปกรณ์ใกล้เคียง"

  • หากแอปออกอากาศโดยใช้ BLE ให้เพิ่ม NSBluetoothPeripheralUsageDescription ซึ่งเป็นสตริงที่อธิบายเหตุผลที่คุณจะลงโฆษณาใน BLE ตัวอย่างเช่น "มีการโฆษณาโทเค็นที่ไม่ระบุตัวตน ผ่านบลูทูธเพื่อให้พบอุปกรณ์ที่อยู่ใกล้เคียง"

ในบางกรณี แอปอาจต้องใช้สื่อเพียงประเภทเดียวและไม่จำเป็นต้องทำทั้งการเผยแพร่และสแกนสื่อนั้น

ตัวอย่างเช่น แอปที่ออกแบบมาเพื่อเชื่อมต่อกับ Set-top box ที่ออกอากาศด้วยเสียงต้องการแค่สแกนเสียงเพื่อค้นหาเสียง ตัวอย่างต่อไปนี้แสดงวิธีเผยแพร่ข้อความไปยัง Set-top box โดยใช้เพียงการสแกนหาเสียงเพื่อค้นหาเท่านั้น

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

หากผู้ใช้ปฏิเสธสิทธิ์เข้าถึงไมโครโฟน ปฏิเสธสิทธิ์เข้าถึงบลูทูธ หรือปิดบลูทูธไว้ ฟีเจอร์ใกล้เคียงก็จะทำงานได้ไม่ดีหรือไม่ทำงานเลย แอปของคุณควรแสดงข้อความในกรณีเหล่านี้เพื่อแจ้งให้ผู้ใช้ทราบว่าระบบกำลังขัดขวางการทำงานของ 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 อาจขอสิทธิ์ต่างๆ ก่อนที่จะอนุญาตให้ Nearby ทำงานได้ ทั้งนี้ขึ้นอยู่กับพารามิเตอร์ที่คุณส่งไปยังสื่อเผยแพร่และการสมัครใช้บริการ เช่น กลยุทธ์เริ่มต้นจะคอยฟังข้อมูลที่ส่งผ่านเสียงแบบเกือบอัลตราโซนิก ดังนั้น 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 และคืนค่าสื่อเผยแพร่และ/หรือการสมัครใช้บริการใกล้เคียงหากเปิดใช้โหมดพื้นหลัง

การแจ้งเตือนพื้นหลัง

หากต้องการให้แอปแจ้งเตือนผู้ใช้เมื่อการสมัครใช้บริการได้รับข้อความ ขณะใช้งานเบื้องหลังอยู่ ให้ใช้การแจ้งเตือนในเครื่อง

ทำตามขั้นตอนต่อไปนี้เพื่อเพิ่มลงในแอป

  • ลงทะเบียนรับการแจ้งเตือนในท้องถิ่นเมื่อเริ่มต้นระบบ:

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