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

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

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

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

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

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

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

สื่อที่ใช้ในการค้นหา

โดยค่าเริ่มต้น ระบบจะใช้สื่อทั้ง 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)

การติดตามสถานะสิทธิ์เข้าถึง Nearby

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

การลบล้างกล่องโต้ตอบสิทธิ์เข้าถึง Nearby

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 และกู้คืนการเผยแพร่และ/หรือการสมัครรับข้อมูล 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...
}