การนำไปใช้

สร้าง instance ของ AudioRecognition

สร้าง SORIAudioRecognizer ด้วย credentials ของแอปพลิเคชัน SORI อย่า hardcode credentials จริงใน source code สาธารณะ ให้โหลดผ่านการกำหนดค่า release, secure storage หรือกระบวนการ build เฉพาะ environment

ตัวอย่างด้านล่างใช้ค่า --dart-define เพื่อไม่ให้ source code มีค่าที่เป็นข้อมูลลับ:

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

เรียกใช้แอปด้วยค่าที่จัดเตรียมไว้ใน local หรือ CI environment:

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 ห้าม commit ค่าจริงลงใน repository แอปตัวอย่าง issue ภาพหน้าจอ หรือเอกสารสาธารณะ

Web recognizer

browser build ต้องไม่มี SORI secret_key ที่มีอายุยาวนาน หลังจากเตรียม Web bridge ในขั้นตอน การติดตั้ง แล้ว ให้สร้าง recognizer ด้วย endpoint สำหรับ ephemeral key บน application server:

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

await recognizer.configure();

ป้องกัน endpoint ด้วยการควบคุม session, origin, CSRF และ rate limit แบบเดียวกับ application APIs อื่น โดยเก็บ secret_key ที่มีอายุยาวนานไว้บนเซิร์ฟเวอร์ ส่วน applicationId จะถูก compile ลงในแอปพลิเคชันเบราว์เซอร์และไม่ถือเป็น secret endpoint จะส่งคืนเฉพาะ ephemeral key อายุสั้นให้เบราว์เซอร์ ดู คีย์ชั่วคราว

รับฟังเหตุการณ์การรู้จำ

subscribe recognizer.events ก่อนเริ่มการรู้จำ ข้อมูลแคมเปญอยู่ใน event.campaign หรือ event payload ทั้งนี้ขึ้นอยู่กับ event ของ native platform

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

campaign events และ recognition events มี event.activityId แบบไม่บังคับ เมื่อผล fingerprint แรกถูกปรับด้วย Audio Marker events ทั้งสองจะใช้ server activity ID เดียวกันที่ไม่เป็นค่าว่าง ให้ใช้ identity นี้เพื่อแทนที่ผลลัพธ์แรก และอย่าสร้าง identity จาก campaign ID หรือ material ID เซิร์ฟเวอร์รุ่นก่อนหน้ายังคงใช้งานร่วมกันได้และอาจส่งคืน null

ยกเลิก subscription เมื่อ widget หรือ scope ของแอปพลิเคชันถูก dispose:

await subscription?.cancel();

เริ่มและหยุดการรู้จำ

เรียก startRecognition() หลังจากกำหนดค่า recognizer และ UI พร้อมรับ events แล้ว

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

เปิดใช้งานการรู้จำ Audio Marker

การรู้จำ Audio Marker ถูกปิดไว้โดยค่าเริ่มต้น ให้เปิดใช้งานเฉพาะเมื่อการตั้งค่า SORI Console ใช้ Audio Markers

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

เมื่อเปิดใช้งาน การเปลี่ยนแปลงสถานะเฉพาะมาร์กเกอร์จะถูกส่งเป็น SORIRecognitionEventType.audioMarkerChanged และอ่านมาร์กเกอร์ล่าสุดได้ จาก event.audioMarker หากพบแคมเปญพร้อมมาร์กเกอร์ ก็สามารถอ่านมาร์กเกอร์เดียวกัน ได้จาก event.campaign?.trait?.marker เช่นกัน

จัดการการดำเนินการของแคมเปญ

เมื่อแคมเปญมี action URL ให้แอปตัดสินใจว่าควรเปิด URL หรือไม่ หลังจากแอปยอมรับ URL แล้ว ให้เรียก handleActionUrl() เพื่อรายงานและจัดการ interaction ผ่าน SDK

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

อัปเดตฐานข้อมูลการรู้จำ

SDK สามารถสั่งให้ native recognizer อัปเดตฐานข้อมูลการรู้จำในเครื่องได้

ปัจจุบัน Web ไม่รองรับ updateDatabase()

final result = await recognizer.updateDatabase();

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