SDK 업데이트 안내 — 0.6.0 → 0.7.0

대상: partner-sdk 0.6.0 을 사용 중인 파트너 개발자 킷: open-echo-partner-kit-0.4.1-sdk-0.7.0 (partner-app 은 0.4.1 그대로 — 앱 코드 무변경)

한 줄 요약

기존 코드는 한 줄도 바꾸지 않아도 됩니다 (breaking 없음, 전부 additive). 0.7.0 은 MIC 방송의 "보이지 않던 것"을 열어줍니다 — 어느 디바이스가 실패했는지, 방송이 서버에서 끝났는지, 몇 대를 대상으로 시작했는지.

업그레이드 절차

1. 킷의 sdk/ 를 교체합니다.
   • npm 사용 시: npm install ./sdk/openecho-partner-sdk-0.7.0.tgz
   • UMD(script 태그) 사용 시: openecho-sdk.0.7.0.umd.js 로 교체 + sri-manifest.json 의 무결성 해시 갱신
2. 확인: import { SDK_VERSION } from "@openecho/partner-sdk" → "0.7.0".
3. 끝. 컴파일·타입 오류 없이 기존 동작이 그대로 유지됩니다.

새로 쓸 수 있는 것

1. 방송 종료 통보 — onSessionEnded (권장)

무엇이 바뀌나

지금까지는 서버에서 MIC 세션이 끝나도(전 대상 조인 실패·최대 시간 초과·다른 곳에서의 정지 등) 클라이언트가 이를 알 수 없었습니다. mic.start() 에 onSessionEnded 콜백을 넘기면 세션 종료를 통지받습니다.

코드 전/후

// 이전 — 세션 종료를 알 방법이 없었습니다
const session = await oe.broadcast.mic.start({
  targetHandle,
  idempotencyKey: crypto.randomUUID(),
});

// 이후 — onSessionEnded 콜백으로 통지받습니다
const session = await oe.broadcast.mic.start({
  targetHandle,
  idempotencyKey: crypto.randomUUID(),
  onSessionEnded: (reason) => {
    // "MIC_JOIN_FAILED"     — 대상 전원이 방에 못 들어옴 (방송 미성립)
    // "MIC_SESSION_EXPIRED" — 최대 방송 시간 초과
    // "MIC_SESSION_ENDED"   — 그 외 서버측 종료 (다른 곳에서의 정지 등, 원인 미구분)
    // "AUTH_FAILED"         — 인증 상실 (연속 401/403)
    console.log("방송 종료:", reason);
  },
});

확인 방법

• 값 집합은 확장될 수 있습니다 — 알 수 없는 값도 "종료됨"으로 처리하세요.
• 여러분이 직접 session.stop() 을 호출한 경우에는 발화하지 않습니다.

2. 디바이스별 조인 결과 — devices[] (api-server 0.39.0+)

무엇이 바뀌나

지금까지 broadcast.subscribe() 의 MIC 스냅샷에서 devices[] 는 항상 빈 배열이었습니다. api-server 0.39.0 이상에서는 MIC 도 devices[] 가 채워져, 어떤 디바이스가 방에 들어왔고 어떤 디바이스가 실패했는지 알 수 있습니다.

코드 전/후

// 이전 — MIC 스냅샷의 devices 는 항상 빈 배열이었습니다
oe.broadcast.subscribe(sessionId, {
  onPhase: (snap) => {
    console.log(snap.phase, snap.devices); // []
  },
});

// 이후 — 대상 디바이스별 조인 결과가 채워집니다
oe.broadcast.subscribe(sessionId, {
  onPhase: (snap) => {
    for (const d of snap.devices ?? []) {
      console.log(d.deviceName, d.status); // "JOINED" | "FAILED" | "TIMEOUT" | "PENDING"
    }
  },
});

확인 방법

• MIC 상태 어휘는 PENDING | JOINED | FAILED | TIMEOUT 입니다(TTS 는 기존대로 PENDING | PLAYING | FAILED | DONE).
• 종료 후에도 각 행은 최종 조인 결과를 유지합니다(실시간 재생 상태가 아닙니다).
• 빈 배열이 나오면 snapshot.skippedAtDispatch 로 원인을 구분하세요. 0 보다 크면 전 대상이 송출 시점에 제외된 것이고, 0 이거나 undefined 면 이 기능을 지원하지 않는 서버 응답일 수 있습니다.
• api-server 0.39.0 미만에서는 MIC devices[] 가 항상 빈 배열입니다.

3. 대상 대수 — session.resolvedDeviceCount

무엇이 바뀌나

지금까지는 방송 대상 디바이스 수를 세션 객체에서 바로 읽을 방법이 없었습니다. mic.start() 가 반환하는 세션 객체에 resolvedDeviceCount 가 추가되어 바로 읽을 수 있습니다.

코드 전/후

// 이전 — 대상 대수를 세션 객체에서 바로 읽을 수 없었습니다
const session = await oe.broadcast.mic.start({
  targetHandle,
  idempotencyKey: crypto.randomUUID(),
});

// 이후 — resolvedDeviceCount 로 바로 읽습니다
const session = await oe.broadcast.mic.start({
  targetHandle,
  idempotencyKey: crypto.randomUUID(),
});
console.log(`대상 ${session.resolvedDeviceCount}대`);

확인 방법

• devices[] 와 조합하면 "2대 중 1대 연결" 같은 진행 표시를 만들 수 있습니다.
• 값은 lease 시점(세션 시작 시점)의 대상 수를 반영합니다.

동작 변경 1건 (주의)

서버 세션 종착 자동 정리

무엇이 바뀌나

0.6.x 까지는 서버에서 세션이 끝나도 아무 일도 일어나지 않았습니다. 마이크가 계속 열려 있고 하트비트가 계속 돌았습니다(결함에 가까운 동작이었습니다). 0.7.0 부터는 종착 감지 시 SDK 가 로컬 자원을 해제하고, 콜백을 등록했다면 onSessionEnded 를 1회 부릅니다.

확인 방법

• 이후의 session.stop() 호출은 안전한 no-op 입니다.
• 기존 앱에 필요한 대응은 없습니다. 죽은 세션의 마이크 점유가 풀리는 개선입니다.

기능별 서버 요구 버전

상세는 COMPATIBILITY.md, 사용 예는 docs/guide/11-broadcast-mic.md("MIC 방송 관찰하기" 절)와 docs/guide/90-enforcement-and-errors.md(MIC 세션 종착 코드 표)를 참고하세요.