sorisdk_flutter 0.2.3

Add SORI-powered audio recognition, campaign discovery, and action-link handling to Flutter apps on Android and iOS.

sorisdk_flutter

Add SORI-powered audio recognition to Flutter apps, so audiences can interact with TV, radio, cinema, and other media from their phones. When registered media is recognized, your app can show the matching campaign, product information, coupon, event, or action link managed in SORI Console.

This package wraps the native SORI Android and iOS SDKs with a Flutter API for starting recognition, receiving campaign/result events, updating the recognition database, and reporting handled action URLs.

When to use it

Use this plugin when your Flutter app needs a second-screen experience for:

• interactive ads and commerce links
• coupons, events, quizzes, or promotions tied to broadcast content
• product, cast, location, or soundtrack information while users watch or listen
• exposure and click reporting for media campaigns

Learn more in the SORI API docs, Use Cases, and SORI Console overview.

Setup

Before integrating the Flutter package, prepare SORI resources in SORI Console:

1. Create an app_id and secret_key in Managing Application.
2. Register the media that should be recognized in Managing Material.
3. Link a campaign, image, and action URL in Managing Campaign.

Then create a recognizer with your SORI application credentials, subscribe to events, and start recognition.

final recognizer = SORIAudioRecognizer(
  applicationId: 'your-application-id',
  secretKey: 'your-secret-key',
);

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

recognizer.events.listen((event) {
  final campaign = event.campaign;
  if (campaign != null) {
    // Render campaign.name, campaign.imageUrl, and campaign.actionUrl.
  }
  final marker = event.audioMarker;
  if (marker != null) {
    // Optionally use the near-ultrasonic audiomarker code.
  }
});

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

When a user taps a campaign action URL that your app has decided to open, report that interaction back to SORI:

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

App Requirements

Android permissions and the foreground microphone service declaration are merged from the plugin. On Android, startRecognition() requests runtime microphone permission when needed and continues the same start request after permission is granted. On Android 13 and later, request notification permission if your app targets that API level and you want the foreground-service notification to be shown normally.

iOS apps must add NSMicrophoneUsageDescription to Info.plist. Add UIBackgroundModes with audio only if the app is designed to continue recognition while backgrounded.

Do not ship SORI credentials in sample or public source. Create and rotate app keys in SORI Console, and load them through your app's normal release configuration process.

Releasing

Maintainers should publish this package by pushing a vX.Y.Z git tag, such as v0.2.3, instead of creating the GitHub Release directly in the GitHub web UI. The publish workflow is intentionally triggered by tag push because pub.dev automated publishing with GitHub OIDC rejects tokens from a direct release event. Ensure pub.dev automated publishing is configured for this repository with the matching v{{version}} tag pattern; permission to push a matching tag is effectively permission to publish the package.

If pubspec.yaml includes build metadata, such as 0.2.3+4, use the base semantic version for the tag (v0.2.3). The workflow publishes from a temporary workspace with the build metadata removed, then creates or updates the matching GitHub Release after pub.dev publishing succeeds.

Notes

The plugin exposes recognition lifecycle, campaign/result/error events, database updates, and an explicit handleActionUrl() method for URLs that your app has inspected. By default recognition is fingerprint-only; set SORIRecognitionConfig(audiomarker: true) to run near-ultrasonic audiomarker recognition alongside fingerprint recognition. Audiomarker results are exposed as event.audioMarker and, when attached to a campaign, as event.campaign?.trait?.marker. Marker-only state changes are emitted as SORIRecognitionEventType.audioMarkerChanged; a null marker means the native recognizer cleared its current marker state. Location, metadata provider, raw audio buffers, and automatic action URL opening are not part of the public Flutter API.

See the example/ app for a complete recognition flow that reads credentials from --dart-define values and renders recognized campaigns.