Web SDK

@sorisdk/web-audio는 웹 서비스나 브라우저 기반 제품에 SORI 오디오 인식을 연동하기 위한 브라우저 SDK입니다.

Beta

Web SDK는 현재 Beta 상태입니다. 아직 구현이 발전 중이므로 일부 API나 연동 흐름은 변경될 수 있습니다.

사전 요구 사항

https:// 또는 http://localhost 같은 secure context
AudioContext와 MediaDevices.getUserMedia를 지원하는 최신 브라우저
SORI가 제공하는 ephemeral key 흐름에 대한 접근
사용자가 허용한 마이크 권한

npm 및 번들러 연동

npm과 번들러를 사용하는 애플리케이션에서는 버전을 지정해 패키지를 설치합니다.

bash

npm install @sorisdk/web-audio@0.6.10

Vite 기반 애플리케이션에는 vite-plugin-wasm도 필요합니다.

bash

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

import wasm from "vite-plugin-wasm";

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

AudioRecognizer는 인증 부트스트랩, 세션 관리, pack 캐싱, 마이크 인식 흐름을 처리합니다. ephemeral key는 애플리케이션 백엔드 또는 서버리스 엔드포인트에서 가져오세요.

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이나 번들러를 사용하지 않는 브라우저 애플리케이션에서는 정확한 버전 URL에서 standalone ESM 모듈을 직접 가져옵니다. 브라우저의 기본 모듈 import를 사용하며 global API를 만들지 않습니다.

html

<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>

프로덕션에서는 정확한 버전을 고정하고 가변적인 latest URL로 바꾸지 마세요.

Ephemeral Key 엔드포인트 보호

Standalone 모듈을 사용하면 프런트엔드 빌드는 필요하지 않지만 신뢰할 수 있는 서버는 여전히 필요합니다. 수명이 긴 애플리케이션 secret을 브라우저 코드에 포함하지 마세요.

애플리케이션 운영자는 제품에 적합한 인증 또는 익명 세션 검증과 함께 사용자, IP 또는 세션별 rate limit, 발급 quota, abuse monitoring으로 ephemeralKey가 호출하는 엔드포인트를 보호할 책임이 있습니다. 엔드포인트가 다른 origin에 있다면 CORS 헤더가 필요할 수 있습니다. CORS는 인증이 아니며 script, bot 또는 브라우저가 아닌 클라이언트의 호출을 막지 못합니다.

키 발급과 relay 패턴은 Ephemeral Key에서 확인하세요.

Content Security Policy

엄격한 Content Security Policy(CSP)를 사용한다면 'wasm-unsafe-eval'로 WebAssembly 컴파일을 허용하세요. https://cdn.iplateia.com을 script-src와 connect-src에 모두 허용하고, SORI API와 ephemeral key 엔드포인트의 origin도 connect-src에 추가하세요. 예:

text

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

ephemeral key 엔드포인트가 다른 origin을 사용한다면 해당 origin을 connect-src에 추가하세요. Standalone 예제는 inline module script를 사용하므로 CSP nonce 또는 hash로 허용하거나, 허용된 외부 script로 코드를 옮기세요. 이 연동만을 위해 'unsafe-inline'을 활성화하지 마세요.

Web SDK ​

사전 요구 사항 ​

npm 및 번들러 연동 ​

브라우저용 Standalone 모듈 ​

Ephemeral Key 엔드포인트 보호 ​

Content Security Policy ​