본문으로 건너뛰기

권장 사항

AIBuds 기능은 Bluetooth 명령, 기기 Wi-Fi를 사용하는 작업 흐름, AI 서비스, 미디어 처리, 선택적 진단 모듈에 걸쳐 있습니다. 안정적인 연동에서는 각 SDK 호출을 독립된 요청처럼 다루지 않고 이러한 경계를 명확히 드러냅니다.

모듈 경계를 명확히 유지하기​

  • AIBudsFoundation에는 공유 모델, 기능 지원 정보, 값 형식이 포함됩니다.
  • AIBuds는 기기 검색과 연결, 기기 기능 프로토콜을 담당합니다.
  • AI 모듈은 서비스 제공자 설정과 AI 세션 수명 주기를 담당합니다.
  • Logging, AI Dashboard, Live Streaming, Crash Reporter, Video Stabilization은 선택적으로 도입하는 운영 또는 미디어 모듈입니다.
  • 제품에서 전체 SDK 구성을 의도적으로 도입할 때는 AIBudsAllInOne이 적합합니다. 모듈식 제품은 실제 사용하는 모듈만 연동해야 합니다.

제품 정책은 SDK 계층 밖에 두세요. UI 컨트롤러는 조정 담당자에게 작업을 요청하고, 해당 담당자는 완료될 때까지 활성 기기, 콜백, 플레이어, 가져오기 객체 또는 AI 세션을 유지해야 합니다.

SDK 관리 주체 하나 두기​

선택한 모듈은 애플리케이션 수명 주기 동안 한 번만 초기화하고 설정, 델리게이트, 서비스 제공자 선택, 선택적 플러그인 등록을 한곳에서 관리합니다. 초기화의 기준은 설정으로 삼고, 개별 기능 페이지가 또 다른 초기화 경로가 되어서는 안 됩니다.

준비 상태와 기능 지원 여부 확인하기​

연결된 기기가 모든 기능을 구현한다고 볼 수는 없습니다. 작업을 호출하기 전에 다음을 확인하세요.

  1. 대상 기기가 여전히 활성 상태이고 준비되었는지 확인합니다.
  2. DeviceInfoAPI 또는 LiveStreamingAPI처럼 해당 기능 프로토콜을 준수하는지 확인합니다.
  3. 기능별 지원 여부 속성이 있다면 그 값도 확인합니다.
  4. 명령 실패로 지원 여부를 판별하지 말고 사용할 수 없는 상태를 UI에 표시합니다.

재연결하거나 기기를 바꾼 뒤에는 이 조건을 다시 확인하세요. 기능 지원 정보를 계정 전체 제품 설정처럼 캐시하지 마세요.

요청 접수와 작업 완료 구분하기​

많은 콜백은 더 큰 작업의 한 단계만 알립니다. OTA 시작, 기기 모드 진입, RTSP 주소 수신, 미디어 다운로드 완료는 서로 다른 시점입니다.

TEXT
idle -> preparing -> active/progress -> finishing -> completed | failed | cancelled

최종 결과는 문서에 명시된 종료 콜백으로만 판단해야 합니다. 시작 콜백 성공, 진행률 100%, 중간 URL을 전체 작업 성공으로 표시하지 마세요. 특히 OTA, Camera OTA, Media File Import, Live Streaming, AI 녹음, 동시통역, 명시적인 시작 및 중지 기능에서 중요합니다.

정리 작업을 여러 번 호출해도 안전하게 만들기​

오래 실행되는 각 작업 흐름에는 관리 주체와 정리 경로를 하나씩 두세요. 성공, 실패, 취소, 화면 이탈, 연결 해제, 백그라운드 전환 뒤에도 안전하게 실행할 수 있어야 합니다. 일반적인 정리 항목은 다음과 같습니다.

  • 지원되는 경우 기기 세션 중지
  • 로컬 플레이어, 스트리머, 녹음기, 처리기 중지 및 해제
  • 구독 취소와 옵저버 제거
  • 대기 중인 UI 작업 무효화
  • 콜백과 임시 파일 정리
  • 종료 결과에 맞춰 UI 복원

화면이 사라졌다고 해서 미들웨어나 기기 작업도 중지되었다고 가정하지 마세요.

콜백 큐는 보장되지 않는 것으로 처리하기​

API가 큐를 명시적으로 보장하지 않는 한 UIKit 업데이트는 메인 큐로 보내고, 디코딩, 파일 입출력, 파싱처럼 비용이 큰 작업은 메인 큐 밖에서 수행하세요. 다른 SDK 콜백을 동기적으로 기다리느라 SDK 콜백을 차단해서는 안 됩니다.

네트워크 전환에 대비하기​

미디어 파일 가져오기, 카메라 OTA, RTSP 라이브 스트리밍은 기기 핫스팟에 연결할 수 있습니다. iPhone의 인터넷 경로가 바뀔 수 있으며 핫스팟 연결 해제는 Bluetooth 상태와 별개입니다. 현재 단계를 표시하고, 처음 발생한 조치 가능한 오류를 보존하며, 문서화된 안전 지점에서만 다시 시작하세요.

민감한 데이터를 의도적으로 다루기​

AI 대화 내용, 녹음, 번역, 보고서, 로그, 충돌 보고서, 미디어, 대시보드 페이지에는 사용자 데이터가 포함될 수 있습니다.

  • 보관 및 삭제 정책을 정의합니다.
  • 진단 도구는 의도한 빌드와 네트워크로 제한합니다.
  • 로그에서 인증 정보와 식별자를 가립니다.
  • 활성화한 기능에 필요한 권한만 요청합니다.
  • 업로드와 외부 AI 처리를 제품의 개인정보 보호 설계에 명시합니다.
  • 임시 SDK 출력을 실수로 장기 저장소로 옮기지 않습니다.

신뢰할 수 있는 결과와 대체 경로 보존하기​

작업에서 원본과 처리 결과가 함께 만들어지면 파생 파일을 검증할 때까지 원본을 보존하세요. 예를 들어 동영상 흔들림 보정이 실패해도 다운로드한 원본 파일까지 잘못된 것은 아닙니다.

공개 결과 모델과 종료 콜백을 신뢰할 수 있는 상태로 사용하세요. Demo의 문구, 추정한 상태 코드, UI 진행률은 표시를 위한 참고 정보일 뿐 SDK 계약을 대신하지 않습니다.

연동 검토 점검 목록​

  • 초기화와 선택적 플러그인 등록을 한 주체가 담당합니다.
  • 각 기능에서 준비 상태, 프로토콜 준수, 기능 지원 여부를 확인합니다.
  • 중간 콜백과 최종 결과를 구분합니다.
  • UIKit 변경을 메인 큐에서 수행합니다.
  • 오래 실행되는 작업의 정리 로직은 여러 번 호출해도 안전합니다.
  • 핫스팟과 인터넷 경로 변경을 UX에 반영합니다.
  • 선택적 처리 실패 후에도 원본 미디어가 남습니다.
  • 진단 데이터가 제품의 개인정보 보호 정책을 따릅니다.
  • 실제 기기에서 중단, 연결 해제, 재시도, 화면 이탈을 테스트합니다.
  • SDK를 업데이트할 때마다 API Reference와 기능 안내서를 다시 확인합니다.