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 코드). 이 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 참조 문서 검토: 사용 가능한 모든 메서드, 요청 및 응답 매개변수, 오류 코드에 관한 자세한 참조 문서를 살펴보세요.