実装

AudioRecognition instanceの作成

SORIアプリケーション認証情報を使ってSORIAudioRecognizerを作成します。実際の認証情報を公開ソースコードにハードコードしないでください。リリース設定、セキュアストレージ、環境ごとのビルドプロセスを通じて読み込んでください。

次の例では、ソースコードに機密値が残らないように--dart-define値を使用します。

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();

ローカルまたはCI環境から値を渡してアプリを実行します。

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

WARNING

app_idとsecret_keyは、アプリをSORI API Serverで認証するための値です。実際の値をリポジトリ、サンプルアプリ、Issue、スクリーンショット、公開ドキュメントにコミットしないでください。

Web recognizer

ブラウザビルドには長期有効なSORI secret_keyを含めないでください。インストールでWeb bridgeを準備した後、アプリケーションサーバー上のephemeral key endpointを使用してrecognizerを作成します。

final recognizer = SORIAudioRecognizer.web(
  applicationId: applicationId,
  webAuth: SORIWebAuthOptions.ephemeralKeyEndpoint(
    Uri.parse('/api/sori/ephemeral-key'),
    requestCredentials: SORIWebRequestCredentials.sameOrigin,
  ),
);

await recognizer.configure();

endpointは、他のアプリケーションAPIと同じsession、origin、CSRF、rate limit制御で保護してください。長期有効なsecret_keyはサーバーに保持しますが、applicationIdはブラウザアプリケーションにコンパイルされるためsecretではありません。endpointは短期有効なephemeral keyだけをブラウザに返します。Ephemeral Keyを参照してください。

認識イベントの受信

認識を開始する前にrecognizer.eventsを購読します。キャンペーン情報は、ネイティブプラットフォームイベントに応じてevent.campaignまたはイベントpayloadから取得できます。

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'];
    // STARTING、STARTED、stoppedの状態に合わせてUIを更新します。
  }

  final campaign = event.campaign;
  if (campaign != null) {
    // campaign.name、campaign.imageUrl、campaign.actionUrlを表示します。
    final marker = campaign.trait?.marker;
    if (marker != null) {
      // このキャンペーンに付与されたオーディオマーカーcodeを必要に応じて使用します。
    }
  }

  if (event.type == SORIRecognitionEventType.audioMarkerChanged) {
    final marker = event.audioMarker;
    // marker専用のUIや状態を更新します。
  }

  if (event.type == SORIRecognitionEventType.error ||
      event.type == SORIRecognitionEventType.networkError) {
    // アプリのエラーUIにevent.messageを表示します。
  }
});

キャンペーンイベントと認識イベントは、オプションのevent.activityIdを公開します。最初のfingerprint結果がオーディオマーカーによってrefineされると、両方のイベントで同じ空でないサーバーactivity IDが使用されます。このidentityを使って最初の結果を置き換えてください。キャンペーンIDやマテリアルIDからidentityを推測しないでください。以前のサーバーとの互換性は維持され、その場合はnullが返ることがあります。

ウィジェットまたはアプリケーションscopeが破棄されるときにsubscriptionをキャンセルします。

await subscription?.cancel();

認識の開始と停止

recognizerの設定が完了し、UIがイベントを受け取る準備ができたら、startRecognition()を呼び出します。

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

notificationオプションはAndroidのforeground-service通知で使用されます。iOSとWebでは無視されます。Webでは、ブラウザがマイク権限を要求できるように、ユーザー操作からstartRecognition()を呼び出してください。

認識を停止するには、次を呼び出します。

await recognizer.stopRecognition();

現在のrecorder状態も確認できます。

final isRunning = await recognizer.isRecorderRunning();

オーディオマーカー認識の有効化

オーディオマーカー認識はデフォルトで無効です。SORI Consoleの設定でオーディオマーカーを使用する場合にのみ有効にしてください。

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

有効にすると、marker-only状態変更はSORIRecognitionEventType.audioMarkerChangedとして配信され、最新のmarkerはevent.audioMarkerから読み取れます。markerを含むキャンペーンが見つかった場合、同じmarkerはevent.campaign?.trait?.markerからも確認できます。

キャンペーンアクションの処理

キャンペーンにaction URLがある場合、まずアプリ側でそのURLを開くかどうかを判断します。アプリがURLを受け入れた後、handleActionUrl()を呼び出すと、SDKを通じてインタラクションがレポートされ処理されます。

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

認識データベースの更新

SDKは、ネイティブrecognizerにローカル認識データベースの更新をリクエストできます。

updateDatabase()は現在Webではサポートされていません。

final result = await recognizer.updateDatabase();

if (!result.success) {
  // result.errorMessageを確認し、必要に応じて再試行オプションを表示します。
}