การนำไปใช้

กำหนดค่า 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
configuration.audiomarkerChangeHandler = { marker in
    print("Audio Marker:", marker ?? "none")
}

recognizer.configure(configuration)

เมื่อผลลัพธ์แคมเปญเชื่อมโยงกับมาร์กเกอร์ที่ตรวจพบ มาร์กเกอร์อาจ รวมอยู่ใน payload การรู้จำในรูปแบบ marker หรือ trait.marker:

recognizer.startRecognition(repeat: true) { media, error in
    guard let campaign = media as? [String: Any], error == nil else {
        return
    }

    let marker = campaign["marker"] as? String
        ?? ((campaign["trait"] as? [String: Any])?["marker"] as? String)

    if let marker {
        print("Campaign marker:", marker)
    }
}

ในฝั่งเซิร์ฟเวอร์นั้น SORI Console จะจับคู่มาร์กเกอร์ที่ตรวจพบกับแอตทริบิวต์ ที่กำหนดค่าไว้ของ Audio Marker เพื่อใช้กับประวัติกิจกรรม สถิติ รายงาน และ Webhook

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

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