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 포토 앱으로 안내합니다. 사용자는 Google 포토 앱에서 주변 기기에 표시할 미디어 소스 (예: 앨범)를 구성할 수 있습니다.

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

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

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

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

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

  7. 미디어 항목 표시: MediaFile의 baseUrl을 사용하여 주변 기기에 미디어 콘텐츠를 다운로드하고 표시합니다.

중요한 고려사항

기기 한도 및 관리:

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

기기 만들기 및 관리 가이드에는 추가 세부정보가 포함되어 있습니다.

미디어 항목 작업:

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

미디어 항목 나열 및 가져오기 가이드에는 콘텐츠 정책 및 필터링에 관한 정보를 비롯한 추가 세부정보가 포함되어 있습니다.

다음 단계