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