시작하기

개요

Open Echo Partner SDK 는 파트너 앱 웹사이트에서 TTS 및 실시간 마이크 방송 기능을 임베드할 수 있는 JavaScript/TypeScript SDK 입니다. 이 문서는 설치부터 클라이언트 초기화까지의 절차를 안내합니다.

시작하기 전에

파트너 앱 발급은 Open Echo 측에서 수행합니다. 아래 항목을 발급받아 준비하세요(절차는 킷 루트 ONBOARDING.md).

파트너 앱 공개 키(pk_live_… 또는 pk_test_… 형식)
allowed origin 등록 — SDK 호출이 허용될 도메인
capability grant — 사용할 기능(TTS, MIC 등)에 대한 권한

도메인 잠금(allowed origin)

파트너 앱은 등록된 origin 에서만 SDK 호출을 수락합니다. 등록되지 않은 origin 에서 호출하면 OriginForbidden 에러가 발생합니다.

운영: https://your-site.example.com
개발: http://localhost:5175(개발 서버 기본 포트)

주의: 앱을 서빙하는 포트(page origin)는 등록된 allowed origin 과 정확히 일치해야 합니다. 등록 origin 이 http://localhost:5174 라면 그 포트로 개발 서버를 실행하세요. 불일치하면 모든 API 호출이 OriginForbidden(403)으로 실패합니다. 드물게 여러분 측 프록시가 오류 응답을 HTML 로 치환하면 GatewayMasked 로 나타날 수도 있습니다. 자세한 진단은 에러 처리를 참고하세요.

origin 등록·변경은 Open Echo 지원 채널로 요청합니다.

설치 / 로딩

SDK를 앱에 넣는 방법은 두 가지입니다. 두 경로의 차이는 파일을 어디서 받아 어디에 두는가뿐이고, 클라이언트를 만든 뒤의 사용 코드는 동일합니다.

① self-host UMD

단일 UMD 파일을 내려받아 여러분의 서버에 직접 호스팅하고, 같은 origin에서 <script>로 로드합니다. same-origin이므로 SRI·crossorigin이 필요 없습니다.

다운로드 — Open Echo 담당자(지원 채널)에게서 릴리스 UMD(openecho-sdk.<version>.umd.js)를 전달받습니다.
호스팅 — 그 파일을 여러분 사이트의 정적 자산 경로에 둡니다(예: /assets/openecho-sdk.<version>.umd.js).
로드 & 초기화

html

<script src="/assets/openecho-sdk.<version>.umd.js"></script>
<script>
  const oe = OpenEcho.createClient({
    baseUrl: "https://openecho.example.com",
    publicKey: "pk_live_...",
  });
</script>

무결성(선택): 자기 자신이 same-origin으로 호스팅하는 파일이라 SRI는 필수가 아닙니다. 다운로드 파일의 무결성은 킷에 동봉된 sdk/sri-manifest.json의 sha384 값과 대조해 확인할 수 있습니다.

MIC 포함: 이 단일 UMD는 실시간 마이크(MIC)와 실시간 미디어 엔진을 인라인으로 포함합니다. 별도 청크 로딩이 없으므로 micChunkUrl·scriptNonce 옵션은 필요 없습니다.

② npm — 동봉 tarball 로 설치

번들러(Vite/webpack 등)에 통합하는 경로입니다. 킷에 동봉된 tarball 로 설치합니다 — 타입(.d.ts) 포함 경로입니다.

bash

# 킷 루트 기준 상대경로 — <version>은 sdk/ 디렉토리의 실제 파일명으로
npm install ./sdk/openecho-partner-sdk-<version>.tgz

또는 package.json에 직접 지정합니다.

json

// package.json
"dependencies": { "@openecho/partner-sdk": "file:./sdk/openecho-partner-sdk-<version>.tgz" }

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

Open Echo 전용 CDN

Open Echo가 직접 호스팅하는 CDN에서 <script>로 임베드하는 경로는 아직 제공하지 않습니다. 지금은 위 ①·② 중 하나를 사용하세요.

①·②의 이후 사용 코드는 동일합니다 — import한 createClient 또는 전역 OpenEcho.createClient로 클라이언트(oe)를 만들면, 나머지 API 호출은 로딩 방식과 무관하게 같습니다.

초기화

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

html

<!-- self-host UMD / CDN — 전역 OpenEcho -->
<script>
  const oe = OpenEcho.createClient({
    baseUrl: "https://openecho.example.com",
    publicKey: "pk_live_...",
  });
</script>

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

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

참고: 여러분의 사이트와 Open Echo API 는 서로 다른 origin 입니다. 파트너 앱의 allowed origin 에 여러분 사이트의 origin 을 등록해야 브라우저의 cross-origin 요청이 허용됩니다.

`ClientConfig` 옵션

이름	타입	설명	기본값	필수
`baseUrl`	`string`	Open Echo API 호스트 URL	-	O
`publicKey`	`string`	파트너 앱 공개 키(`pk_live_…` 또는 `pk_test_…`)	-	O
`micChunkUrl`	`string`	MIC 청크 URL 수동 지정. 번들러(npm) 경로 전용	-	X
`scriptNonce`	`string`	CSP nonce — MIC 청크 `<script>` 태그에 주입. 번들러 경로 전용	-	X
`fetch`	`typeof fetch`	`fetch` 구현 수동 지정(Node.js·테스트 환경용)	-	X

초기화 확인 — `oe.ping()`

클라이언트를 만든 직후 oe.ping() 으로 키·origin 구성이 올바른지 확인할 수 있습니다.

기본 정보

메서드	앱 capability	참조 handle 조건	반환 타입
`oe.ping()`	없음(인증 확인 전용 — capability 게이트 없음)	없음	`Promise<PingResult>`

요청

입력 파라미터가 없습니다.

응답

이름	타입	설명
`appName`	`string`	파트너 앱 이름
`appId`	`string`	파트너 앱 ID
`origin`	`string`	인식된 호출 origin

예제

const info = await oe.ping();
console.log(`연결됨: ${info.appName} (${info.origin})`);

대표 에러

에러	HTTP 상태	원인	해결 방법
`Unauthorized`	401	`publicKey` 가 잘못되었거나 폐기됨	`publicKey` 값을 다시 확인하세요
`OriginForbidden`	403	현재 페이지 origin 이 allowed origin 에 미등록	Open Echo 지원 채널로 origin 등록을 요청하세요

에러별 대응은 에러 처리를 참조합니다.

개발 환경 준비

개발 단계에서 SDK 를 테스트하려면 아래 절차를 따르세요.

Open Echo 지원 채널로 dev 파트너 앱 발급을 요청합니다 — 테스트용 공개 키(pk_test_…), 사용할 capability grant, 개발 origin(예: http://localhost:5175) 등록을 함께 요청하세요.
발급받은 값으로 클라이언트를 초기화합니다. 방법은 위 "초기화" 절과 동일합니다.
oe.ping()으로 연결을 확인합니다.

주의: dev 키를 코드 저장소에 커밋하지 마세요. 환경변수나 버전 관리에서 제외한 로컬 설정 파일로 관리하세요.

dev 테스트 세션이 끝나면 발급받은 dev 파트너 앱과 키의 폐기를 Open Echo 지원 채널에 요청하세요. 노출된 dev 키의 악용 가능성을 차단하기 위한 절차입니다.

참고 코드

킷에 동봉된 레퍼런스 앱(partner-app/)은 이 문서의 초기화 절차와 TTS 방송 등 기능별 가이드를 실제로 구현한 예시입니다. 로컬 실행 방법은 partner-app/README.md를 참고하세요.