Web SDK

@sorisdk/web-audio คือ SDK สำหรับเบราว์เซอร์ที่ใช้เพิ่มการรู้จำเสียงของ SORI ลงในบริการเว็บหรือผลิตภัณฑ์ที่ทำงานบนเบราว์เซอร์

เบต้า

ขณะนี้ Web SDK อยู่ในสถานะ เบต้า เนื่องจากการพัฒนายังดำเนินอยู่ บางส่วนของ API และขั้นตอนการผสานรวมจึงอาจมีการเปลี่ยนแปลง

ข้อกำหนดเบื้องต้น

• บริบทที่ปลอดภัย เช่น https:// หรือ http://localhost
• เบราว์เซอร์สมัยใหม่ที่รองรับ AudioContext และ MediaDevices.getUserMedia
• สิทธิ์เข้าถึงขั้นตอนการใช้งานคีย์ชั่วคราว (ephemeral key) ที่ SORI จัดเตรียมไว้
• สิทธิ์ใช้งานไมโครโฟนที่ผู้ใช้อนุญาต

การผสานรวมด้วย npm และ bundler

สำหรับแอปพลิเคชันที่ใช้ npm และ bundler ให้ติดตั้งแพ็กเกจโดยระบุเวอร์ชัน:

npm install @sorisdk/web-audio@0.6.10

แอปพลิเคชันที่ใช้ Vite ต้องติดตั้ง vite-plugin-wasm เพิ่มเติม:

npm install --save-dev vite-plugin-wasm

import wasm from "vite-plugin-wasm";

export default {
  plugins: [wasm()]
};

AudioRecognizer จัดการการเริ่มต้นการยืนยันตัวตน การจัดการเซสชัน การแคชแพ็ก และการรู้จำผ่านไมโครโฟน โปรดรับ ephemeral key จากแบ็กเอนด์ของแอปพลิเคชัน หรือ endpoint แบบ serverless:

import { AudioRecognizer } from "@sorisdk/web-audio";

const recognizer = new AudioRecognizer({
  appId: "YOUR_APP_ID",
  ephemeralKey: async () => {
    const response = await fetch("/api/ephemeral-key", {
      method: "POST"
    });

    if (!response.ok) {
      throw new Error(`Ephemeral key request failed: HTTP ${response.status}`);
    }

    const { ephemeral_key } = await response.json();
    return ephemeral_key;
  }
});

recognizer.on("campaign", (event) => {
  console.log(event.campaign);
});

recognizer.on("error", ({ error }) => {
  console.error(error);
});

await recognizer.start();

เรียก stop() หรือ destroy() เมื่อต้องการยุติการรู้จำหรือเมื่อกำลังปิดหน้าเว็บ

โมดูล Standalone สำหรับเบราว์เซอร์

สำหรับแอปพลิเคชันบนเบราว์เซอร์ที่ไม่ใช้ npm หรือ bundler ให้นำเข้าโมดูล ESM แบบ standalone โดยตรงจาก URL ที่ระบุเวอร์ชันอย่างชัดเจน วิธีนี้เป็นการนำเข้า โมดูลแบบ native และจะไม่สร้าง global API:

<script type="module">
  import { AudioRecognizer } from
    "https://cdn.iplateia.com/web/sorisdk/v0.6.10/sori-web-audio.mjs";

  const recognizer = new AudioRecognizer({
    appId: "YOUR_APP_ID",
    ephemeralKey: async () => {
      const response = await fetch("/api/ephemeral-key", {
        method: "POST"
      });

      if (!response.ok) {
        throw new Error(`Ephemeral key request failed: HTTP ${response.status}`);
      }

      const { ephemeral_key } = await response.json();
      return ephemeral_key;
    }
  });

  recognizer.on("campaign", (event) => {
    console.log(event.campaign);
  });

  recognizer.on("error", ({ error }) => {
    console.error(error);
  });

  await recognizer.start();
</script>

ใน production ให้ตรึงเวอร์ชันที่แน่นอนและอย่าเปลี่ยนเป็น URL latest ที่เปลี่ยนแปลงได้

การป้องกัน Endpoint สำหรับ Ephemeral Key

โมดูล standalone ช่วยให้ไม่ต้อง build frontend แต่ยังคงต้องมีเซิร์ฟเวอร์ที่ เชื่อถือได้ ห้ามฝัง secret ของแอปพลิเคชันที่มีอายุยาวไว้ในโค้ดของเบราว์เซอร์

ผู้ดูแลแอปพลิเคชันมีหน้าที่ป้องกัน endpoint ที่ ephemeralKey เรียกใช้ ด้วยการยืนยันตัวตนหรือการตรวจสอบเซสชันแบบไม่ระบุตัวตนที่เหมาะสมกับผลิตภัณฑ์ รวมถึงกำหนด rate limit ต่อผู้ใช้ IP หรือเซสชัน กำหนด quota การออกคีย์ และเฝ้าติดตามการใช้งานในทางที่ผิด หาก endpoint อยู่คนละ origin อาจต้องตั้งค่า CORS แต่ CORS ไม่ใช่การยืนยันตัวตน และไม่สามารถป้องกัน script, bot หรือไคลเอนต์ที่ไม่ใช่เบราว์เซอร์ไม่ให้เรียก endpoint ได้

ดูรูปแบบการออกและส่งต่อคีย์ได้ที่ คีย์ชั่วคราว

Content Security Policy

เมื่อใช้ Content Security Policy (CSP) ที่เข้มงวด ให้อนุญาตการคอมไพล์ WebAssembly ด้วย 'wasm-unsafe-eval' อนุญาต https://cdn.iplateia.com ทั้งใน script-src และ connect-src และเพิ่ม origin ของ SORI API กับ endpoint สำหรับ ephemeral key ใน connect-src ตัวอย่าง:

script-src 'self' 'wasm-unsafe-eval' https://cdn.iplateia.com;
connect-src 'self' https://cdn.iplateia.com https://console.soriapi.com;

หาก endpoint สำหรับ ephemeral key ใช้ origin อื่น ให้เพิ่ม origin นั้นใน connect-src เนื่องจากตัวอย่าง standalone ใช้ inline module script จึงต้องอนุญาตด้วย CSP nonce หรือ hash หรือย้ายโค้ดไปยัง external script ที่ได้รับอนุญาต อย่าเปิดใช้ 'unsafe-inline' เพียงเพื่อการผสานรวมนี้

ขั้นตอนถัดไป

• การตั้งค่า
• คีย์ชั่วคราว
• การเชื่อมต่อ UI