OPWS Developers

호환성 · 버전 안내

이 킷의 구성 버전

킷 이름이 버전을 담습니다: open-echo-partner-kit-<APP버전>-sdk-<SDK버전>(예: open-echo-partner-kit-0.1.1-sdk-0.2.2 = partner-app 0.1.1 + partner-sdk 0.2.2).

구성물버전 확인 위치
partner-sdksdk/ 의 tarball/UMD 파일명, partner-app/node_modules/@openecho/partner-sdk/package.json(설치 후), 코드에서 import { SDK_VERSION } from '@openecho/partner-sdk'*
partner-apppartner-app/package.json, partner-app/CHANGELOG.md

* SDK_VERSION 상수는 0.2.1 이상에서 신뢰할 수 있습니다. 그 전 버전에서는 파일명·package.json 을 기준으로 확인하세요.

호환 매트릭스

partner-app요구 partner-sdk비고
0.5.10.7.0 이상문서 개편 전용(카카오 developers 준거 킷 문서 전면 재작성 + API 레퍼런스 파생본 동봉) 릴리스입니다. 요구 조합은 0.5.0 과 동일 — 앱 런타임 코드 변경 없음. 이 킷(open-echo-partner-kit-0.5.1-sdk-0.7.0)이 검증된 조합입니다
0.5.00.7.0 이상MIC 관찰성 UI(onSessionEnded·devices[]·resolvedDeviceCount 실소비) — 이 킷(open-echo-partner-kit-0.5.0-sdk-0.7.0)이 검증된 조합입니다. sdk 0.6.x 와 조합하면 종료 통보(onSessionEnded)와 조인 전 대상 대수 요약("대상 N대", resolvedDeviceCount 필드 부재)은 비활성화됩니다. 콜백이 발화하지 않고 값 가드로 조용히 생략될 뿐 오류나 undefined 같은 깨진 표기는 없습니다. 디바이스 조인 행과 devices 수신 후 연결 요약("연결 M/N대")은 broadcast.subscribe 자체가 sdk 버전과 무관해 api-server 0.39.0 이상이면 그대로 표시됩니다(devices[] 는 서버측 게이트 — 기능별 서버 요구는 아래 MIC 관찰성 기능별 호환 참조)
0.4.10.6.0 이상최소 요구는 0.4.0 과 동일합니다(app 코드 자체는 무변경 — 신규 표면을 소비하는 UI 가 없습니다). 이 킷(open-echo-partner-kit-0.4.1-sdk-0.7.0)은 sdk 0.7.0 을 번들하는데, 이 행은 app 0.4.1 이 동작하는 데 필요한 최소 sdk 버전이며 킷에 실제로 들어있는 sdk 버전과는 별개입니다. MIC 세션 관찰성(onSessionEnded·resolvedDeviceCount·devices[] 조인 결과)을 직접 쓰려면 sdk 0.7.0 이 필요합니다(기능별 서버 요구는 아래 MIC 관찰성 기능별 호환 참조)
0.4.00.6.0 이상목록 필터 — 그룹·컨텐츠·예약(이름/제목)·이력(타입 TTS/MIC + 컨텐츠 제목) 부분일치·대소문자무시입니다. 응답 HistoryView.type 이 `'MIC'
0.3.00.5.0 이상마이크 미연결·권한 거부 전용 안내(MicUnavailable)입니다. SDK 가 마이크를 선확보해 로컬 실패 시 서버에 접촉하지 않고, 실패한 방송의 점유를 즉시 해제합니다. api-server 0.30.0 이상이 필요합니다
0.2.00.4.0 이상TTS·MIC 다중 대상 선택 UI + DEVICE_IN_USE 사다리입니다. api-server 0.30.0 이상이 필요합니다
0.1.20.4.0 이상deviceHandles 다중 대상·busyHandles payload 는 api-server 0.30.0 이상이 필요합니다(다중 대상 점유 검사를 포함한 릴리스)
0.1.10.2.0 이상0.1.0 대비 테스트 위생만 변경되었습니다(런타임 동일). SDK 요구는 동일합니다
0.1.00.2.0 이상방송 중단(tts.stop)·컨텐츠 방송(tts.fromContent)·언어 목록(languages.list)·per-device 진행이 0.2.0 에서 추가되었습니다. 0.1.0 SDK 와 조합하면 해당 기능에서 오류가 발생합니다

같은 킷에 담긴 조합은 항상 함께 검증된 조합입니다. 킷 안의 sdk 와 partner-app 을 그대로 쓰면 호환성을 신경 쓸 필요가 없습니다. SDK 만 단독으로 업그레이드할 때 이 표를 확인하세요.

버전별 주요 표면 변경

partner-sdk 각 릴리스에서 공개 표면이 어떻게 바뀌었는지 정리합니다. 동작 fix 는 각 CHANGELOG.md 를 참고하세요.

버전구분내용
0.7.0추가mic.start() 에 onSessionEnded 콜백을 지정하면 서버측 세션 종료(대상 전원 조인 실패·최대 시간 초과·인증 상실 등)를 통지받습니다
0.7.0추가MicSession.resolvedDeviceCount — 세션의 방송 대상 디바이스 수를 바로 읽을 수 있습니다
0.7.0추가MIC devices[] 조인 결과 어휘(PENDING/JOINED/FAILED/TIMEOUT)가 확정되었습니다. api-server 0.39.0 이상에서 실제 값이 채워지고, 그 미만은 항상 빈 배열입니다
0.7.0추가PhaseSnapshot.skippedAtDispatch — 송출 시점에 제외된 대상 수입니다. devices[] 가 빈 배열인 이유를 구분하는 데 씁니다
0.7.0동작 변화서버에서 세션 종료가 감지되면 SDK 가 마이크와 연결을 자동으로 정리합니다. 이전에는 세션이 끝나도 클라이언트가 이를 알 수 없어 마이크가 계속 열려 있었습니다
0.6.0BREAKINGHistoryView.type 이 string 에서 'MIC' | 'TTS' 로 좁혀졌습니다. 서버 응답의 AUDIO 값은 TTS 로 정규화되고, 알 수 없는 값은 ProtocolError 를 던집니다
0.6.0추가groups.list()·contents.list()·schedules.list()·history.list() 에 검색·필터 옵션(search·type 등)이 추가되었습니다. 이 필터를 지원하는 api-server 릴리스 이상에서만 실제로 적용됩니다
0.5.0추가MicUnavailable 에러 클래스 — 마이크 획득 실패를 별도 타입으로 구분합니다
0.5.0동작 변화마이크 획득 실패 시 서버에 접촉하지 않고 즉시 실패로 처리합니다. 이전에는 브라우저가 던진 원래 에러가 그대로 전달됐습니다
0.5.0동작 변화마이크 연결이나 송출에 실패하면 SDK 가 마이크·연결 자원을 정리한 뒤 원래 에러를 그대로 전달합니다
0.4.0추가deviceHandles — TTS·MIC 요청에서 디바이스를 다중 지정합니다(targetHandle 과 배타)
0.4.0추가DeviceInUse 에러 클래스 — 대상 디바이스가 사용 중일 때 별도 타입으로 구분됩니다(busyHandles·busyCount 포함). 이전에는 원인을 알 수 없는 에러로 도착했습니다
0.3.0추가SdkVersionUnsupported 에러 클래스 — 서버가 요구하는 최소 SDK 버전에 미달하면 별도 타입으로 구분됩니다
0.3.0추가모든 요청에 SDK 버전 헤더가 자동으로 붙습니다. 서버가 곧 지원 종료될 버전을 감지하면 브라우저 콘솔에 경고가 1회 출력됩니다
0.2.2추가LanguageOption 타입 export, BroadcastReceipt.admitted 필드(참고용 — 수락 여부 판정에는 status 를 쓰세요)
0.2.0BREAKINGcontents.clone() 메서드가 제거되었습니다. 컨텐츠 확보는 노출된 컨텐츠 조회 또는 직접 생성으로 대체하세요
0.2.0추가languages.list()·broadcast.tts.stop()·broadcast.tts.fromContent()·contents.create()/update() 등 다수 메서드가 추가되었습니다
0.2.0추가템플릿 생성 시 groupHandle 또는 deviceHandles 중 하나를 지정하는 방식으로 확장되었습니다(기존 groupHandle 단일 지정도 계속 동작합니다). groups.create() 에는 description 옵션이 추가되었습니다
0.2.0추가여러 응답 타입에 서버 확장 필드가 optional 로 추가되었습니다(값이 없으면 undefined)
0.1.0추가최초 preview 릴리스입니다. 리소스 관리·TTS 방송 전체 표면이 이 버전에서 시작되었습니다

서버측 단독 변경 (앱·SDK 버전 무관)

호환 매트릭스는 partner-app 버전이 키라 앱·SDK 변경 없이 서버만 바뀌는 항목은 담기지 않습니다. 이런 변경은 여기에 기록합니다.

api-serversdkapp비고
0.38.00.6.00.4.1MIC 부분 활성화(대상 디바이스 일부만 조인해도 방송 시작)·에러 코드 세분화(MIC_SESSION_NOT_FOUND/MIC_NO_ELIGIBLE_DEVICE/MIC_SESSION_ENDED/MIC_JOIN_FAILED/MIC_SESSION_EXPIRED/MIC_LEASE_HELD)입니다. 서버측 변경이라 클라이언트 대응은 필요 없습니다. MIC 경로에서 ContentNotReady(BROADCAST_CONTENT_NOT_READY)는 이 버전부터 더 이상 발생하지 않습니다
0.39.00.6.00.4.1MIC devices[](join_state 조인 결과 투영)가 서버에 표면화되었습니다. 클라이언트에서 값을 소비하려면 SDK 0.7.0 이상이 필요합니다(그 미만 SDK 는 DeviceProgress 타입은 있으나 MIC 어휘를 문서화하지 않습니다)

MIC 관찰성 기능별 호환 (SDK 0.7.0+)

SDK 0.7.0 의 MIC 세션 관찰성 표면은 기능마다 필요한 api-server 최소 버전이 다릅니다. 실제로 서버 버전을 요구하는 것은 onSessionEnded 의 서버측 종착 감지와 devices[] 뿐이고, 나머지(AUTH_FAILED 합성·resolvedDeviceCount)는 서버 버전과 무관하게 항상 동작합니다.

기능최소 api-server비고
onSessionEnded — 서버측 종착 감지(quorum 실패·만료·MIC_SESSION_ENDED 등)0.38.0 이상(미만은 콜백 미발화)Phase 1 이전 서버는 세션 종착 시 heartbeat 가 세분화된 MIC_* 코드 대신 BROADCAST_CONTENT_NOT_READY(MIC 경로 오용 — 0.38.0 에서 제거) 하나로만 응답합니다. SDK 0.7.0 의 TERMINAL_CODES 는 MIC_* 4종만 판별하므로, 0.38.0 미만 서버에서는 세션이 종착돼도 이 코드가 매칭되지 않아 콜백이 발화하지 않고 자동정리도 일어나지 않습니다(heartbeat 는 계속 폴링만 합니다)
reason: "AUTH_FAILED"(연속 401/403 스트릭)요구 없음서버 wire 코드가 아니라 SDK 가 401/403 연속 4회를 관측해 합성하는 순수 클라이언트측 판별입니다. MIC 관련 서버 변경과 무관하게 모든 api-server 버전에서 동일하게 동작합니다
MicSession.resolvedDeviceCount요구 없음MIC lease 응답 필드는 최초 MIC 프리뷰(0.2x 대)부터 wire 에 존재했습니다. SDK 0.7.0 은 이를 타입으로 노출만 할 뿐 서버 쪽 변경은 없습니다
PhaseSnapshot.devices[](MIC 조인 결과)0.39.0 이상이 버전 미만 서버는 MIC 에서 항상 빈 배열을 반환합니다. skippedAtDispatch(정수, 서버 확장)가 0보다 크면 전 대상이 송출 시점에 skip 되어 정상적으로 빈 것이고, 0이거나 없으면 구버전 서버 응답일 가능성이 있습니다

서버 버전 게이트

서버는 최소 지원 SDK 버전(min-version)을 집행할 수 있습니다. 게이트가 활성화된 환경에서:

SDK동작
0.3.0 이상버전 헤더가 자동으로 전송됩니다. min 이상이면 정상 동작합니다
0.2.x 이하버전 헤더가 없어 모든 요청이 426 으로 거부됩니다. 0.3.0+ 로 업그레이드하세요

0.2.x 는 426 거부를 typed error 로 받지 못하고 UnknownOpenEchoError(code=SDK_VERSION_UNSUPPORTED 보존)로 받습니다.

버전 정책

  • 두 구성물 모두 preview(0.x)입니다. 마이너 업데이트에 깨는 변경이 포함될 수 있으며, 변경 내용은 각 CHANGELOG.md 에 기록됩니다
  • 확장 응답 필드는 optional 로 추가됩니다. 구버전 서버 환경에서는 undefined 로 내려올 수 있으니 커스텀 코드에서 이를 처리하세요

사용 조건

사용·커스텀·재배포 조건은 계약 문서를 따릅니다. 제공된 파일(SDK·partner-app)을 제3자에게 전달하기 전에 반드시 계약 채널로 확인하세요. sdk/THIRD-PARTY-NOTICES.txt 는 SDK 재배포 시 항상 함께 전달해야 합니다.

이 문서가 도움이 되었나요?👍 도움됨👎 개선 필요
GitHub에서 소스 보기Updated 2026-07-27