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

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

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

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

หมายเหตุ: การเรียกกลับทั้งหมดในไลบรารีนี้ใช้บล็อกแทนผู้มอบสิทธิ์ โปรดระมัดระวังอย่าให้เกิดวงจรการคงผู้ใช้ในการติดตั้งใช้งานบล็อก ดูเอกสารประกอบของ Apple ที่อธิบายวิธีหลีกเลี่ยงวงจรการคงไว้

ไลบรารีนี้ทำงานใน 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 เช่น "มีการโฆษณาโทเค็นที่ไม่ระบุตัวตน ผ่านบลูทูธเพื่อค้นหาอุปกรณ์ที่อยู่ใกล้เคียง"

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

เช่น แอปที่ออกแบบมาเพื่อเชื่อมต่อกับกล่องรับสัญญาณที่ออกอากาศเฉพาะเสียงก็ต้องสแกนเสียงเพื่อค้นหา ข้อมูลโค้ดต่อไปนี้ แสดงวิธีเผยแพร่ข้อความไปยังกล่องรับสัญญาณนั้นโดยใช้การสแกนเสียงเท่านั้น เพื่อการค้นพบ

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

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

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

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

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

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

• ส่งการแจ้งเตือนในเครื่องในตัวแฮนเดิลเลอร์ message-found ของการสมัครใช้บริการ

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