Ambient API 시작하기

Ambient API를 사용하면 애플리케이션이 대기 모드 기기를 사용자의 Google 포토 계정에 연결하고 선택한 사진을 표시할 수 있습니다.

Ambient API 흐름

다음은 Ambient API가 기기를 연결한 후 미디어 항목을 검색하고 표시하는 방식을 설명한 내용입니다.

  1. 기존 기기 확인 (권장): 새 기기를 만들기 전에 현재 사용자의 기기가 이미 있는지 확인하는 것이 좋습니다. 애플리케이션은 내부 사용자와 사용자가 앱을 통해 만드는 기기의 Google 제공 deviceId 간에 매핑을 유지해야 합니다. 사용자의 deviceId가 발견되면 필요한 경우 승인 토큰을 새로고침할 수 있습니다.

  2. OAuth 2.0 승인 시작 (선택적으로 기기 생성): 승인 코드를 요청하여 TV 및 제한된 입력 기기용 OAuth 2.0 흐름을 시작합니다.

  3. 새 기기 만들기: 앱이 CreateDevice를 호출하고 유효한 v4 UUID를 제공하여 사용자의 Google 포토 계정에 기기를 만듭니다.

    기기 생성에 성공하면 API는 Google에서 할당한 deviceId가 포함된 AmbientDevice 객체를 반환합니다. 애플리케이션에서 이 deviceId를 저장하고 사용자와 연결하는 것이 중요합니다.

  4. settingsUri 표시: AmbientDevice 객체에는 settingsUri가 포함됩니다. 이 URI를 사용자에게 표시합니다(일반적으로 QR 코드로 표시). 사용자는 휴대기기를 사용하여 이 QR 코드를 스캔할 수 있습니다. 이 URI는 사용자를 Google 포토 앱으로 안내합니다. 여기에서 화면 보호 모드 기기에 표시할 미디어 소스 (예: 앨범)를 구성할 수 있습니다.

  5. mediaSourcesSet 폴링: 애플리케이션은 주기적으로 GetDevice 메서드를 호출하여 deviceId를 제공하여 대기 모드 기기의 상태를 확인해야 합니다. AmbientDevice 응답에서 mediaSourcesSet 필드를 모니터링합니다. 처음에는 false입니다.

    사용자가 Google 포토 앱에서 미디어 소스를 선택하면 이 필드가 true로 변경됩니다.

    AmbientDevice 응답에는 pollInterval가 포함된 pollingConfig가 포함되며 이를 폴링 빈도의 가이드라인으로 사용해야 합니다.

  6. 미디어 항목 검색: mediaSourcesSet가 true를 반환하면 애플리케이션에서 사용자가 선택한 미디어 항목을 가져오기 시작할 수 있습니다.

    ListMediaItems 메서드를 호출하여 deviceId를 제공합니다. API는 AmbientMediaItem 객체 목록이 포함된 ListMediaItemsResponse를 반환합니다. 각 AmbientMediaItem에는 id, createTime, 추가 메타데이터가 포함된 MediaFile 객체와 같은 세부정보가 포함됩니다. MediaFile에는 미디어 항목의 실제 바이트를 가져오는 데 사용할 수 있는 baseUrl가 포함되어 있습니다. 추가 baseUrl 매개변수에 관한 자세한 내용은 미디어 항목 나열 및 검색 가이드를 참고하세요.

  7. 미디어 항목 표시: MediaFile의 baseUrl를 사용하여 미디어 콘텐츠를 다운로드하고 화면 보호 모드 기기에 표시합니다.

중요한 고려사항

기기 한도 및 관리:

  • 기기 한도: 애플리케이션 사용자당 기기 100대의 한도가 적용됩니다.
  • 기기 활동 및 토큰: 기기 및 사용자 승인 토큰의 수명 주기를 관리해야 합니다. 기기가 활성 상태로 유지되는 기간과 기기가 비활성 상태가 되거나 토큰이 만료되는 경우 토큰 갱신 또는 재승인을 처리하는 방법을 고려하세요.

기기 만들기 및 관리 가이드에서 자세한 내용을 확인하세요.

미디어 항목 작업:

  • 미디어 항목 사용: 필요한 인증 또는 매개변수를 포함하여 baseUrl를 사용하여 미디어 항목 콘텐츠를 올바르게 가져오고 처리하는 방법을 이해합니다.
  • 오류 처리: 기기의 NOT_FOUND, 미디어 소스가 설정되지 않은 경우의 FAILED_PRECONDITION, 기기 한도에 도달한 경우의 RESOURCE_EXHAUSTED와 같은 시나리오를 비롯하여 API 호출에 대한 강력한 오류 처리를 구현합니다.

미디어 항목 나열 및 가져오기 가이드에서 자세한 내용을 확인하세요.

다음 단계

  • 애플리케이션 구성: 필요한 사용자 인증 정보가 있고 TV 및 제한된 입력 기기용 OAuth 2.0에 맞게 애플리케이션을 구성했는지 확인합니다.
  • Ambient API 참조 문서 검토: 사용 가능한 모든 메서드, 요청 및 응답 매개변수, 오류 코드에 관한 상세 참조 문서를 살펴보세요.