구현

recognizer 구성

SORI 프레임워크를 import하고 SORI 애플리케이션 인증 정보로 shared recognizer를 구성합니다.

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는 SORI API가 반환한 campaign payload를 받습니다.

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

오디오마커 인식 활성화

오디오마커 인식은 기본적으로 비활성화되어 있습니다. 기본 모드에서 iOS 인식은 fingerprint-only로 동작합니다. SORI Console 설정에서 오디오마커를 사용하는 경우에만 활성화하세요.

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)

campaign result가 감지된 marker와 연결된 경우, recognition 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이 감지된 marker를 오디오마커에 설정한 attributes와 연결하여 activity history, statistics, reports, webhooks에서 사용할 수 있게 합니다.

순서 기반 연속 활동 타임라인 렌더링

인식 handler는 소재의 캠페인을 먼저 반환한 뒤 같은 활동에 대해 marker로 정제된 캠페인을 반환할 수 있습니다. 최초 결과는 즉시 표시하되 애플리케이션 상태에 명시적인 현재 세그먼트를 유지하세요. 공개 payload dictionary에는 activity_id, material_id, trait.marker가 포함될 수 있습니다.

• 비어 있지 않은 activity_id는 정확히 같은 ID를 가진 현재 행만 정제할 수 있습니다. 활동, 캠페인 또는 소재 ID로 전체 타임라인을 검색하지 마세요.
• 이전 payload에는 activity_id가 없을 수 있습니다. 이 경우 material_id fallback은 현재 행에만 안전하며 전역 식별자로 사용하면 안 됩니다.
• 행에 저장한 시각, 위치 및 기타 최초 관측 메타데이터를 유지하세요. 후속 콜백은 marker와 캠페인 표시 필드를 갱신하며 최초 관측을 바꾸지 않습니다.
• 이후의 marker miss 또는 덜 완전한 중복 payload가 현재 행을 이전 상태로 되돌리지 않도록 marker와 정제된 캠페인 값을 병합하세요.
• 다른 material_id가 관측되면 이전 세그먼트가 닫힙니다. 이 경계 뒤에 도착한 이전 활동의 지연된 정제는 무시하세요.

따라서 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()

백그라운드 인식

앱에 백그라운드 인식이 필요하다면 Info.plist의 UIBackgroundModes에 audio를 추가하세요. 백그라운드 인식은 앱이 실행 중일 때 작동합니다. 앱이 종료되면 인식도 중지됩니다.

오류 처리

인식 오류는 recognition handler와 SORI error notifications를 통해 전달됩니다. 오류 알림을 관찰하려면 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")
    }
}