Implementation

Create AudioRecognition instance

Create a SORIAudioRecognizer with your SORI application credentials. Do not hardcode real credentials in public source code. Load them through your release configuration, secure storage, or environment-specific build process.

The example below uses --dart-define values so the source code can stay free of sensitive values:

import 'package:sorisdk_flutter/sorisdk_flutter.dart';

const applicationId = String.fromEnvironment('SORI_APP_ID');
const secretKey = String.fromEnvironment('SORI_SECRET_KEY');

final recognizer = SORIAudioRecognizer(
  applicationId: applicationId,
  secretKey: secretKey,
);

await recognizer.configure();

Run your app with values provided by your local or CI environment:

flutter run \
  --dart-define=SORI_APP_ID=your-application-id \
  --dart-define=SORI_SECRET_KEY=your-secret-key

WARNING

app_id and secret_key authenticate your app with the SORI API Server. Do not commit real values to a repository, sample app, issue, screenshot, or public documentation.

Listen for recognition events

Subscribe to recognizer.events before starting recognition. Campaign information is available from event.campaign or from the event payload depending on the native platform event.

import 'dart:async';

import 'package:sorisdk_flutter/sorisdk_flutter.dart';

late final SORIAudioRecognizer recognizer;
StreamSubscription<SORIRecognitionEvent>? subscription;

subscription = recognizer.events.listen((event) {
  if (event.type == SORIRecognitionEventType.stateChanged) {
    final state = event.payload['state'];
    // Update your UI for STARTING, STARTED, or stopped states.
  }

  final campaign = event.campaign;
  if (campaign != null) {
    // Render campaign.name, campaign.imageUrl, and campaign.actionUrl.
    final marker = campaign.trait?.marker;
    if (marker != null) {
      // Optionally use the Audio Marker code attached to this campaign.
    }
  }

  if (event.type == SORIRecognitionEventType.audioMarkerChanged) {
    final marker = event.audioMarker;
    // Update marker-specific UI or state.
  }

  if (event.type == SORIRecognitionEventType.error ||
      event.type == SORIRecognitionEventType.networkError) {
    // Show event.message in your app's error UI.
  }
});

Cancel the subscription when your widget or application scope is disposed:

await subscription?.cancel();

Start and stop recognition

Call startRecognition() after the recognizer is configured and your UI is ready to receive events.

await recognizer.startRecognition(
  notification: const SORIAndroidNotificationOptions(
    title: 'SORI recognition',
    body: 'Listening for SORI audio signals',
  ),
);

The notification option is used by Android foreground-service notifications. It is ignored on iOS.

To stop recognition:

await recognizer.stopRecognition();

You can also check the current recorder state:

final isRunning = await recognizer.isRecorderRunning();

Enable Audio Marker recognition

Audio Marker recognition is disabled by default. Enable it only when your SORI Console setup uses Audio Markers.

await recognizer.configure(
  config: const SORIRecognitionConfig(audiomarker: true),
);

When enabled, marker-only state changes are emitted as SORIRecognitionEventType.audioMarkerChanged, and the latest marker can be read from event.audioMarker. If a campaign is found with a marker, the same marker is also available from event.campaign?.trait?.marker.

Handling campaign actions

When a campaign has an action URL, decide in your app whether the URL should be opened. After your app accepts the URL, call handleActionUrl() to report and handle the interaction through the SDK.

final actionUrl = campaign.actionUrl;
if (actionUrl != null && actionUrl.isNotEmpty) {
  await recognizer.handleActionUrl(actionUrl);
}

Updating the recognition database

The SDK can ask the native recognizer to update its local recognition database.

final result = await recognizer.updateDatabase();

if (!result.success) {
  // Inspect result.errorMessage and show a retry option if needed.
}