빠른 시작

Open Echo Partner SDK는 파트너 앱 웹사이트에서 TTS·실시간 마이크 방송을 임베드하는 JavaScript/TypeScript SDK입니다. 이 문서는 키 발급부터 첫 방송·연결 확인까지 최단 경로를 안내합니다.

사전 조건

Open Echo 관리 콘솔에서 파트너 앱을 만들고 다음을 준비합니다.

• 공개 키 — pk_live_… 또는 pk_test_… 형식
• allowed origin 등록 — SDK 호출이 허용될 도메인(미등록 origin은 OriginForbidden)
• capability grant — 사용할 기능(TTS·MIC)에 대한 권한

설치 · 로딩

SDK를 앱에 넣는 방법은 세 가지입니다. 현재 가용한 경로는 self-host UMD이며, npm·전용 CDN은 준비 중입니다. 세 경로의 차이는 파일을 어디서 받아 어디에 두는가뿐이고, 클라이언트를 만든 뒤의 사용 코드는 동일합니다.

<!-- 릴리스 UMD를 내려받아 자기 사이트에 same-origin 호스팅 -->
<script src="/assets/openecho-sdk.0.1.0.umd.js"></script>
<script>
  const oe = OpenEcho.createClient({
    baseUrl: "https://api.your-openecho-instance.com",
    publicKey: "pk_live_...",
  });
</script>

<script>는 classic(type 속성 없음)으로 로드해야 window.OpenEcho가 전역에 노출됩니다. 단일 UMD는 MIC·livekit을 인라인 포함하므로 별도 청크 origin이 필요 없습니다.

초기화

createClient로 클라이언트(oe)를 만듭니다. 얻는 방식만 로딩 경로에 따라 다르고, 이후 API 호출은 동일합니다.

import { createClient } from "@openecho/partner-sdk"; // npm 경로

const oe = createClient({
  baseUrl: "https://api.your-openecho-instance.com",
  publicKey: "pk_live_...",
});

연결 확인 — ping()

키·origin·baseUrl이 올바른지 첫 호출로 확인합니다. ping()은 인증된 파트너 앱 정보를 반환합니다.

const info = await oe.ping();
// info: PingResult
//   appName — 파트너 앱 이름
//   appId   — 파트너 앱 ID
//   origin  — 인증된 호출 origin

실패하면 Unauthorized(키 무효) 또는 OriginForbidden(미등록 origin)이 throw됩니다. 원인 구분은 에러 문서를 참조하세요.

첫 방송 보내기

가장 흔한 첫 동작은 TTS 방송입니다. 접수 영수증의 sessionId로 진행을 구독할 수 있습니다.

const receipt = await oe.broadcast.tts.send({
  targetHandle: "grp_main",
  text: "출입을 통제합니다",
  language: "ko",
  idempotencyKey: crypto.randomUUID(),
});
// receipt.sessionId — SSE 구독에 사용

다음 단계

• 방송 (Broadcast) — tts·subscribe·mic 메서드 레퍼런스
• 에러 (Errors) — 에러 클래스·도메인 잠금 진단