Implementation

Configure the recognizer

Import the SORI framework and configure the shared recognizer with your SORI application credentials.

import SORI

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

recognizer.configure(configuration)

Start recognition

Call startRecognition(repeat:handler:) after configuration. The handler receives the campaign payload returned by SORI API when a registered material is recognized.

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

Enable Audio Marker recognition

Audio Marker recognition is disabled by default. In the default mode, iOS recognition remains fingerprint-only. Enable it only when your SORI Console setup uses 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)

When a campaign result is associated with a detected marker, the marker can be included as marker or trait.marker in the recognition payload:

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

On the server side, SORI Console maps the detected marker to the Audio Marker's configured attributes for activity history, statistics, reports, and webhooks.

Render an ordered continuous-activity timeline

The recognition handler can first return a campaign for a material and later return a marker-refined campaign for that same activity. Show the first result immediately, but keep an explicit current segment in application state. The public payload dictionary may provide activity_id, material_id, and trait.marker.

• A non-empty activity_id may refine only the current row with that exact ID. Do not search the complete timeline by activity, campaign, or material ID.
• Older payloads may omit activity_id. In that case, a material_id fallback is safe only for the current row and must not become a global identity.
• Retain the time, position, and other first-observation metadata stored for the row. The later callback updates marker and campaign presentation fields, not the original observation.
• Merge marker and refined campaign values so later marker misses or less complete duplicate payloads cannot downgrade the current row.
• A different material_id seals the previous segment. Ignore delayed refinements for an older activity after that boundary.

Therefore A(activity-1) -> A'(activity-1, marker) -> A(activity-1, marker miss) is one row, while A(activity-1) -> B(activity-2) -> delayed A'(activity-1) keeps B current and does not rewrite the historical A.

Stop recognition

Stop recognition when your app no longer needs microphone capture.

recognizer.stopRecognition()

Background recognition

If your app needs background recognition, add audio to UIBackgroundModes in Info.plist. Background recognition works while the app is running. If the app is terminated, recognition also stops.

Error handling

Recognition errors are delivered through the recognition handler and SORI error notifications. To observe error notifications, register for 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")
    }
}