การนำไปใช้

คู่มือนี้ใช้ iOS SDK 5.1.0 ดูขั้นตอนการติดตั้งและอัปเดต

กำหนดค่า recognizer

นำเข้า SORI framework และกำหนดค่า shared recognizer ด้วย credentials ของแอปพลิเคชัน SORI

import SORI

let recognizer = SORIAudioRecognizer.shared()
let configuration = SORIAudioRecognizer.Configuration(
    applicationID: "YOUR_SORI_APP_ID",
    secretKey: "YOUR_SORI_SECRET_KEY"
)

recognizer.configure(configuration)

เริ่มการรู้จำ

หลังจากกำหนดค่าแล้ว ให้เรียก startRecognition(repeat:handler:) โดย handler จะรับ payload ของแคมเปญที่ SORI API ส่งคืน เมื่อตรวจพบสื่อ (Material) ที่ลงทะเบียนไว้

recognizer.startRecognition(repeat: true) { media, error in
    if let error {
        print("SORI recognition error: \(error)")
        return
    }

    guard let campaign = media as? [String: Any] else {
        return
    }

    handleRecognizedCampaign(campaign)
}

เปิดใช้งานการรู้จำ Audio Marker

การรู้จำ Audio Marker ถูกปิดไว้โดยค่าเริ่มต้น ในโหมดเริ่มต้น การรู้จำบน iOS จะใช้เฉพาะ fingerprint เท่านั้น ให้เปิดใช้งานเฉพาะเมื่อการตั้งค่า SORI Console ใช้ Audio Markers

let configuration = SORIAudioRecognizer.Configuration(
    applicationID: "YOUR_SORI_APP_ID",
    secretKey: "YOUR_SORI_SECRET_KEY"
)
configuration.audiomarker = true

recognizer.configure(configuration)

สำหรับ UI มาร์กเกอร์ปัจจุบันและการเสริมข้อมูลกิจกรรมภายหลัง ให้ใช้ API สถานะและผลลัพธ์กิจกรรมที่ SDK จัดการ SDK จัดการการหมดอายุ trait ของมาร์กเกอร์ และการอัปเดตกิจกรรมเดิม โดยยังรองรับ callback ของแคมเปญและการค้นพบเดิม

แสดง timeline ของกิจกรรมต่อเนื่องตามลำดับ

คำแนะนำต่อไปนี้ใช้กับ callback แคมเปญเดิม สำหรับผลลัพธ์กิจกรรมใหม่ที่ SDK ยืนยันแล้ว ให้ใช้กฎอัปเดตด้วย ID ที่ตรงกันใน สถานะ Audio Marker และผลลัพธ์กิจกรรม ซึ่งสามารถอัปเดตกิจกรรมย้อนหลังที่ตรงกันได้

handler การรู้จำอาจส่งแคมเปญของสื่อกลับมาก่อน แล้วจึงส่งแคมเปญที่ปรับละเอียดด้วย marker สำหรับกิจกรรมเดียวกัน ให้แสดงผลลัพธ์แรกทันที แต่เก็บ segment ปัจจุบัน ไว้อย่างชัดเจน ใน state ของแอปพลิเคชัน public payload dictionary อาจมี activity_id, material_id และ trait.marker

• activity_id ที่ไม่ว่างจะปรับละเอียดได้เฉพาะแถวปัจจุบันที่มี ID ตรงกันเท่านั้น อย่าค้นหาทั้ง timeline ด้วย ID ของกิจกรรม แคมเปญ หรือสื่อ
• payload รุ่นเก่าอาจไม่มี activity_id ในกรณีนี้ให้ใช้ material_id เป็น fallback ได้เฉพาะกับแถวปัจจุบัน และต้องไม่ใช้เป็น identity แบบ global
• คงเวลา ตำแหน่ง และ metadata อื่นของการตรวจพบครั้งแรกที่เก็บไว้สำหรับแถวนั้น callback ในภายหลังจะอัปเดตฟิลด์ marker และการแสดงผลแคมเปญ ไม่ใช่การตรวจพบเดิม
• รวมค่า marker และค่าแคมเปญที่ปรับละเอียดแล้ว เพื่อไม่ให้การตรวจไม่พบ marker หรือ payload ซ้ำที่มีข้อมูลน้อยกว่าในภายหลังลดทอนแถวปัจจุบัน
• material_id อื่นจะปิด segment ก่อนหน้า ให้ละเว้นการปรับละเอียดที่ล่าช้าของกิจกรรมเก่า หลังขอบเขตนั้น

ดังนั้น A(activity-1) -> A'(activity-1, marker) -> A(activity-1, marker miss) จึงเป็นหนึ่งแถว ส่วน A(activity-1) -> B(activity-2) -> delayed A'(activity-1) จะคง B เป็นรายการปัจจุบันและไม่เขียนทับ A ในประวัติ

หยุดการรู้จำ

หยุดการรู้จำเมื่อแอปไม่จำเป็นต้องรับเสียงจากไมโครโฟนแล้ว

recognizer.stopRecognition()

การรู้จำในพื้นหลัง

หากแอปต้องการการรู้จำในพื้นหลัง ให้เพิ่ม audio ลงใน UIBackgroundModes ใน Info.plist การรู้จำในพื้นหลังจะทำงานขณะที่แอปกำลังทำงาน หากแอป ถูกยุติ การรู้จำจะหยุดด้วย

การจัดการข้อผิดพลาด

ข้อผิดพลาดในการรู้จำจะส่งผ่าน recognition handler และการแจ้งเตือนข้อผิดพลาดของ SORI หากต้องการติดตามการแจ้งเตือนข้อผิดพลาด ให้ลงทะเบียน SORIError.errorNotificationName():

NotificationCenter.default.addObserver(forName: SORIError.errorNotificationName(), object: nil, queue: OperationQueue.main) { notification in
    guard let error = notification.object as? NSError,
          let code = SORIErrorCode(rawValue: error.code) else {
        print("Unknown error notification: \(notification)")
        return
    }

    if code == .authenticationFailure {
        print("Failed to authenticate")
    }
}