Engage SDK Listen: 서드 파티 기술 통합 안내

Google에서는 사용자의 앱을 카테고리별로 정리하고 맞춤형 앱 콘텐츠 소비와 검색을 위한 새로운 몰입형 환경을 제공하는 기기 내 노출 영역을 구축하고 있습니다. 이 전체 화면 환경을 통해 개발자 파트너는 앱 외부의 전용 채널에서 최고의 리치 콘텐츠를 선보일 수 있습니다.

이 가이드에는 개발자 파트너가 Engage SDK를 사용하여 이 새로운 표시 경로 영역과 기존 Google 표시 경로를 모두 채우는 방식으로 오디오 콘텐츠를 통합하는 방법에 관한 안내가 포함되어 있습니다.

통합 세부정보

용어

이 통합에는 맞춤 콘텐츠, 연속, 추천이라는 세 가지 클러스터 유형이 포함되어 있습니다.

  • 맞춤 콘텐츠 클러스터에는 개별 개발자 파트너가 제안하는 읽을 만한 콘텐츠가 맞춤형으로 표시됩니다.

    맞춤 콘텐츠의 구조는 다음과 같습니다.

    • 맞춤 콘텐츠 클러스터: 동일한 개발자 파트너의 맞춤 콘텐츠 그룹이 포함된 UI 뷰입니다.

      그림 1. 단일 파트너의 맞춤 콘텐츠 클러스터를 보여주는 Entertainment Space UI
    • 항목: 클러스터에 있는 단일 항목을 나타내는 객체입니다. 항목은 재생목록, 오디오북, 팟캐스트 등이 될 수 있습니다. 지원되는 항목 유형 목록은 항목 데이터 제공 섹션을 참고하세요.

      그림 2. 단일 파트너의 맞춤 콘텐츠 클러스터 내에 있는 단일 항목을 보여주는 Entertainment Space UI
  • 연속 클러스터에는 사용자가 최근에 참여한 여러 개발자 파트너의 오디오 콘텐츠가 단일 UI 그룹으로 표시됩니다. 각 개발자 파트너는 연속 클러스터에서 최대 10개의 항목을 브로드캐스트할 수 있습니다.

    그림 3. 여러 파트너의 완료되지 않은 맞춤 콘텐츠가 있는 연속 클러스터를 보여주는 Entertainment Space UI(현재 하나의 맞춤 콘텐츠만 표시됨)
  • 추천 클러스터는 여러 개발자 파트너의 선별된 항목을 하나의 UI 그룹으로 보여줍니다. 추천 클러스터는 1개가 표시되며 모든 맞춤 콘텐츠 클러스터보다 높은 우선순위로 UI 상단에 표시됩니다. 각 개발자 파트너는 추천 클러스터에서 최대 10개의 항목을 브로드캐스트할 수 있습니다.

    그림 4. 여러 파트너의 맞춤 콘텐츠가 포함된 추천 클러스터를 보여주는 Entertainment Space UI(현재 하나의 맞춤 콘텐츠만 표시됨)

사전 작업

최소 API 수준: 19

다음과 같이 com.google.android.play:engage 라이브러리를 앱에 추가합니다.

dependencies {
    // Make sure you also include that repository in your project's build.gradle file.
    implementation 'com.google.android.engage:engage-core:1.4.0'
}

요약

설계는 바인드된 서비스의 구현을 기반으로 합니다.

클라이언트가 게시할 수 있는 데이터에는 다음과 같은 다양한 클러스터 유형의 제한이 적용됩니다.

클러스터 유형 클러스터 제한 클러스터의 최대 항목 제한
맞춤 콘텐츠 클러스터 최대 5개 최대 50개
연속 클러스터 최대 1개 최대 10개
추천 클러스터 최대 1개 최대 10개

1단계: 항목 데이터 제공

SDK는 각 항목 유형을 나타내는 여러 항목을 정의했습니다. Listen 카테고리에는 다음 항목이 지원됩니다.

  1. MusicAlbumEntity
  2. MusicArtistEntity
  3. MusicTrackEntity
  4. MusicVideoEntity
  5. PlaylistEntity
  6. PodcastSeriesEntity
  7. PodcastEpisodeEntity
  8. LiveRadioStationEntity
  9. AudiobookEntity

아래 차트에는 각 유형에 사용 가능한 속성과 요구사항이 나와 있습니다.

MusicAlbumEntity

MusicAlbumEntity 객체는 음악 앨범을 나타냅니다(예: 테일러 스위프트의 Midnights).

속성 요구사항 참고
이름 필수 항목 음악 앨범의 제목입니다.
포스터 이미지 필수 항목 이미지를 하나 이상 제공해야 합니다. 자세한 내용은 이미지 사양을 참고하세요.
정보 페이지 URI 필수 항목

음악 앨범에 관한 세부정보를 볼 수 있는 제공업체 앱의 딥 링크입니다.

참고: 기여 분석에 딥 링크를 사용할 수 있습니다. 이 FAQ 참고하기

아티스트 필수 항목 음악 앨범의 아티스트 목록입니다.
재생 URI 선택사항

제공업체 앱에서 앨범 재생을 시작하는 딥 링크입니다.

참고: 기여 분석에 딥 링크를 사용할 수 있습니다. 이 FAQ 참고하기

설명 선택사항 제공되는 경우 200자(영문 기준) 이내여야 합니다.
노래 개수 선택사항 음악 앨범에 있는 노래의 개수입니다.
장르 선택사항 음악 앨범의 장르 목록입니다.
앨범 형식 선택사항

앨범(LP 및 더블 LP 포함)

EP

싱글

믹스 테이프

음반사 선택사항 앨범과 관련된 음반사 목록입니다.
기기에 다운로드됨 선택사항 음악 앨범이 기기에 다운로드되었는지를 나타내는 부울입니다.
성인용 선택사항

콘텐츠가 성인용인지를 나타내는 부울입니다.

성인용 소재가 포함되어 있거나 보호자 지도 필요 경고가 있는 항목은 TRUE로 설정해야 합니다. 성인용 항목은 'E' 태그와 함께 표시됩니다.

출시일 선택사항 에포크 밀리초 단위의 앨범 출시일입니다.
시간 선택사항 앨범 길이(밀리초)입니다.
최근 참여 시간 선택사항

연속 클러스터의 항목에 권장됩니다. 순위에 사용할 수 있습니다.

에포크 밀리초 단위로 표시합니다.

진행 완료율 선택사항

연속 클러스터의 항목에 권장됩니다.

정수(0~100)로 표시합니다.

MusicArtistEntity

MusicArtistEntity 객체는 음악 아티스트를 나타냅니다(예: 아델).

속성 요구사항 참고
이름 필수 항목 음악 아티스트의 이름입니다.
포스터 이미지 필수 항목 이미지를 하나 이상 제공해야 합니다. 자세한 내용은 이미지 사양을 참고하세요.
정보 페이지 URI 필수 항목

음악 아티스트에 관한 세부정보를 확인할 수 있는 제공업체 앱의 딥 링크입니다.

참고: 기여 분석에 딥 링크를 사용할 수 있습니다. 이 FAQ 참고하기

재생 URI 선택사항

제공업체 앱에서 아티스트의 노래를 재생하기 시작하는 딥 링크입니다.

참고: 기여 분석에 딥 링크를 사용할 수 있습니다. 이 FAQ 참고하기

설명 선택사항 제공되는 경우 200자(영문 기준) 이내여야 합니다.
최근 참여 시간 선택사항

연속 클러스터의 항목에 권장됩니다. 순위에 사용할 수 있습니다.

에포크 밀리초 단위로 표시합니다.

MusicTrackEntity

MusicTrackEntity 객체는 음악 트랙을 나타냅니다(예: 콜드플레이의 Yellow).

속성 요구사항 참고
이름 필수 항목 음악 트랙의 제목입니다.
포스터 이미지 필수 항목 이미지를 하나 이상 제공해야 합니다. 자세한 내용은 이미지 사양을 참고하세요.
재생 URI 필수 항목

제공업체 앱에서 음악 트랙 재생을 시작하는 딥 링크입니다.

참고: 기여 분석에 딥 링크를 사용할 수 있습니다. 이 FAQ 참고하기

정보 페이지 URI 선택사항

음악 트랙에 관한 세부정보를 확인할 수 있는 제공업체 앱의 딥 링크입니다.

참고: 기여 분석에 딥 링크를 사용할 수 있습니다. 이 FAQ 참고하기

설명 선택사항 제공되는 경우 200자(영문 기준) 이내여야 합니다.
시간 선택사항 트랙의 재생 시간(밀리초)입니다.
앨범 선택사항 노래가 속한 앨범의 이름입니다.
아티스트 필수 항목 음악 트랙의 아티스트 목록입니다.
기기에 다운로드됨 선택사항 음악 트랙이 기기에 다운로드되었는지를 나타내는 부울입니다.2
성인용 선택사항

콘텐츠가 성인용인지를 나타내는 부울입니다.

성인용 소재가 포함되어 있거나 보호자 지도 필요 경고가 있는 항목은 TRUE로 설정해야 합니다. 성인용 항목은 'E' 태그와 함께 표시됩니다.

최근 참여 시간 선택사항

연속 클러스터의 항목에 권장됩니다. 순위에 사용할 수 있습니다.

에포크 밀리초 단위로 표시합니다.

진행 완료율 선택사항

연속 클러스터의 항목에 권장됩니다.

정수(0~100)로 표시합니다.

MusicVideoEntity

MusicVideoEntity 객체는 뮤직비디오(예: 위켄드 - Take My Breath(공식 뮤직비디오))를 나타냅니다.

속성 요구사항 참고
이름 필수 항목 뮤직비디오 제목입니다.
포스터 이미지 필수 항목 이미지를 하나 이상 제공해야 합니다. 자세한 내용은 이미지 사양을 참고하세요.
재생 URI 필수 항목

제공업체 앱에서 뮤직비디오 재생을 시작하는 딥 링크입니다.

참고: 기여 분석에 딥 링크를 사용할 수 있습니다. 이 FAQ 참고하기

정보 페이지 URI 선택사항

뮤직비디오에 관한 세부정보를 확인할 수 있는 제공업체 앱의 딥 링크입니다.

참고: 기여 분석에 딥 링크를 사용할 수 있습니다. 이 FAQ 참고하기

시간 선택사항 동영상 재생 시간(밀리초)입니다.
조회수 선택사항 자유 텍스트 형식의 동영상 조회수입니다.
아티스트 선택사항 뮤직비디오 아티스트 목록입니다.
콘텐츠 등급 선택사항 트랙의 콘텐츠 등급 목록입니다.
설명 선택사항 제공되는 경우 200자(영문 기준) 이내여야 합니다.
기기에 다운로드됨 선택사항 뮤직비디오가 기기에 다운로드되었는지를 나타내는 부울입니다.
성인용 선택사항

콘텐츠가 성인용인지를 나타내는 부울입니다.

성인용 소재가 포함되어 있거나 보호자 지도 필요 경고가 있는 항목은 TRUE로 설정해야 합니다. 성인용 항목은 'E' 태그와 함께 표시됩니다.

최근 참여 시간 선택사항

연속 클러스터의 항목에 권장됩니다. 순위에 사용할 수 있습니다.

에포크 밀리초 단위로 표시합니다.

진행 완료율 선택사항

연속 클러스터의 항목에 권장됩니다.

정수(0~100)로 표시합니다.

PlaylistEntity

PlaylistEntity 객체는 음악 재생목록을 나타냅니다(예: 미국 상위 10개 재생목록).

속성 요구사항 참고
이름 필수 항목 재생목록의 제목입니다.
포스터 이미지 필수 항목 이미지를 하나 이상 제공해야 합니다. 자세한 내용은 이미지 사양을 참고하세요.
재생 URI 필수 항목

제공업체 앱에서 음악 재생목록 재생을 시작하는 딥 링크입니다.

참고: 기여 분석에 딥 링크를 사용할 수 있습니다. 이 FAQ 참고하기

정보 페이지 URI 선택사항

음악 재생목록에 관한 세부정보를 확인할 수 있는 제공업체 앱의 딥 링크입니다.

참고: 기여 분석에 딥 링크를 사용할 수 있습니다. 이 FAQ 참고하기

시간 선택사항 재생목록의 재생 시간(밀리초)입니다.
노래 개수 선택사항 음악 재생목록의 노래 개수입니다.
설명 선택사항 제공되는 경우 200자(영문 기준) 이내여야 합니다.
기기에 다운로드됨 선택사항 재생목록이 기기에 다운로드되었는지를 나타내는 부울입니다.
성인용 선택사항

콘텐츠가 성인용인지를 나타내는 부울입니다.

성인용 소재가 포함되어 있거나 보호자 지도 필요 경고가 있는 항목은 TRUE로 설정해야 합니다. 성인용 항목은 'E' 태그와 함께 표시됩니다.

최근 참여 시간 선택사항

연속 클러스터의 항목에 권장됩니다. 순위에 사용할 수 있습니다.

에포크 밀리초 단위로 표시합니다.

진행 완료율 선택사항

연속 클러스터의 항목에 권장됩니다.

정수(0~100)로 표시합니다.

PodcastSeriesEntity

PodcastSeriesEntity 객체는 팟캐스트 시리즈를 나타냅니다(예: This American Life).

속성 요구사항 참고
이름 필수 항목 팟캐스트 시리즈의 제목입니다.
포스터 이미지 필수 항목 이미지를 하나 이상 제공해야 합니다. 자세한 내용은 이미지 사양을 참고하세요.
정보 페이지 URI 필수 항목

팟캐스트 시리즈에 관한 세부정보를 확인할 수 있는 제공업체 앱의 딥 링크입니다.

참고: 기여 분석에 딥 링크를 사용할 수 있습니다. 이 FAQ 참고하기

재생 URI 선택사항

제공업체 앱에서 팟캐스트 시리즈 재생을 시작하는 딥 링크입니다.

참고: 기여 분석에 딥 링크를 사용할 수 있습니다. 이 FAQ 참고하기

에피소드 개수 선택사항 팟캐스트 시리즈의 에피소드 개수입니다.
프로덕션 이름 선택사항 팟캐스트 시리즈의 프로덕션 이름입니다.
호스트 선택사항 팟캐스트 시리즈의 호스트 목록입니다.
장르 선택사항 팟캐스트 시리즈의 장르 목록입니다.
기기에 다운로드됨 선택사항 팟캐스트가 기기에 다운로드되었는지 나타내는 부울입니다.
설명 선택사항 제공되는 경우 200자(영문 기준) 이내여야 합니다.
성인용 선택사항

콘텐츠가 성인용인지를 나타내는 부울입니다.

성인용 소재가 포함되어 있거나 보호자 지도 필요 경고가 있는 항목은 TRUE로 설정해야 합니다. 성인용 항목은 'E' 태그와 함께 표시됩니다.

최근 참여 시간 선택사항

연속 클러스터의 항목에 권장됩니다. 순위에 사용할 수 있습니다.

에포크 밀리초 단위로 표시합니다.

PodcastEpisodeEntity

PodcastEpisodeEntity 객체는 팟캐스트 시리즈를 나타냅니다(예: Spark Bird, 에피소드 754: This American Life).

속성 요구사항 참고
이름 필수 항목 팟캐스트 에피소드의 제목입니다.
포스터 이미지 필수 항목 이미지를 하나 이상 제공해야 합니다. 자세한 내용은 이미지 사양을 참고하세요.
재생 URI 필수 항목

제공업체 앱에서 팟캐스트 에피소드 재생을 시작하는 딥 링크입니다.

참고: 기여 분석에 딥 링크를 사용할 수 있습니다. 이 FAQ 참고하기

프로덕션 시리즈 제목 필수 항목 에피소드가 속한 팟캐스트 시리즈의 이름입니다.
시간 필수 항목 팟캐스트 에피소드의 길이(밀리초)입니다.
게시 날짜 필수 항목 팟캐스트 게시 날짜(단위: 에포크 밀리초)
정보 페이지 URI 선택사항

팟캐스트 에피소드에 관한 세부정보를 확인할 수 있는 제공업체 앱의 딥 링크입니다.

참고: 기여 분석에 딥 링크를 사용할 수 있습니다. 이 FAQ 참고하기

프로덕션 이름 선택사항 팟캐스트 시리즈의 프로덕션 이름입니다.
에피소드 색인 선택사항 시리즈의 에피소드 색인입니다(첫 번째 색인은 1).
호스트 선택사항 팟캐스트 에피소드의 호스트 목록입니다.
장르 선택사항 팟캐스트 에피소드의 장르 목록입니다.
기기에 다운로드됨 선택사항 팟캐스트 에피소드가 기기에 다운로드되었는지 나타내는 부울입니다.
설명 선택사항 제공되는 경우 200자(영문 기준) 이내여야 합니다.
동영상 팟캐스트 선택사항 팟캐스트 에피소드에 동영상 콘텐츠가 있는지 나타내는 부울입니다.
성인용 선택사항

콘텐츠가 성인용인지를 나타내는 부울입니다.

성인용 소재가 포함되어 있거나 보호자 지도 필요 경고가 있는 항목은 TRUE로 설정해야 합니다. 성인용 항목은 'E' 태그와 함께 표시됩니다.

다음 유형 듣기 선택사항

연속 클러스터의 항목에 권장됩니다.

TYPE_CONTINUE - 재생이 끝나지 않은 오디오 항목에서 다시 시작합니다.

TYPE_NEXT - 시리즈의 새로운 에피소드에서 계속 진행합니다.

TYPE_NEW - 신규 출시.

최근 참여 시간 선택사항

연속 클러스터의 항목에 권장됩니다. 순위에 사용할 수 있습니다.

에포크 밀리초 단위로 표시합니다.

진행 완료율 선택사항

연속 클러스터의 항목에 권장됩니다.

정수(0~100)로 표시합니다.

LiveRadioStationEntity

LiveRadioStationEntity 객체는 라이브 라디오 채널을 나타냅니다(예: 98.1 The Breeze).

속성 요구사항 참고
이름 필수 항목 라이브 라디오 채널의 제목입니다.
포스터 이미지 필수 항목 이미지를 하나 이상 제공해야 합니다. 자세한 내용은 이미지 사양을 참고하세요.
재생 URI 필수 항목

제공업체 앱에서 라디오 채널 재생을 시작하는 딥 링크입니다.

참고: 기여 분석에 딥 링크를 사용할 수 있습니다. 이 FAQ 참고하기

정보 페이지 URI 선택사항

라디오 채널에 관한 세부정보를 확인할 수 있는 제공업체 앱의 딥 링크입니다.

참고: 기여 분석에 딥 링크를 사용할 수 있습니다. 이 FAQ 참고하기

주파수 선택사항 라디오 채널이 방송되는 주파수입니다(예: '98.1 FM').
프로그램 제목 선택사항 라디오 채널에서 재생 중인 현재 프로그램입니다.
호스트 선택사항 라디오 채널의 호스트 목록입니다.
설명 선택사항 제공되는 경우 200자(영문 기준) 이내여야 합니다.
최근 참여 시간 선택사항

연속 클러스터의 항목에 권장됩니다. 순위에 사용할 수 있습니다.

에포크 밀리초 단위로 표시합니다.

AudiobookEntity

AudiobookEntity 객체는 오디오북(예: 미셸 오바마의 비커밍 오디오북)을 나타냅니다.

속성 요구사항 참고
이름 필수 항목
포스터 이미지 필수 항목 이미지를 하나 이상 제공해야 합니다. 자세한 내용은 이미지 사양을 참고하세요.
저자 필수 항목 저자 이름을 하나 이상 제공해야 합니다.
내레이터 필수 항목 내레이터 이름을 하나 이상 제공해야 합니다.
작업 링크 URI 필수 항목

오디오북 제공업체 앱의 딥 링크입니다.

참고: 기여 분석에 딥 링크를 사용할 수 있습니다. 이 FAQ 참고하기

게시 날짜 선택사항 제공되는 경우 에포크 밀리초 단위로 표시합니다.
설명 선택사항 제공되는 경우 200자(영문 기준) 이내여야 합니다.
요금 선택사항 자유 형식의 텍스트로 표시합니다.
시간 선택사항 제공되는 경우 양수여야 합니다.
장르 선택사항 책과 관련된 장르 목록입니다.
시리즈 이름 선택사항 오디오북이 속한 시리즈 이름입니다(예: 해리 포터).
시리즈 단위 색인 선택사항 시리즈의 오디오북 색인입니다. 여기서 1은 시리즈의 첫 번째 오디오북입니다. 예를 들어 해리 포터와 아즈카반의 죄수가 시리즈의 3번째 책인 경우 3으로 설정해야 합니다.
계속할 도서 유형 선택사항

TYPE_CONTINUE - 다 읽지 않은 도서에서 다시 시작합니다.

TYPE_NEXT - 시리즈의 새로운 에피소드에서 계속 진행합니다.

TYPE_NEW - 신규 출시.

최근 참여 시간 조건부 필수

항목이 연속 클러스터에 있으면 제공해야 합니다.

에포크 밀리초 단위로 표시합니다.

진행 완료율 조건부 필수

항목이 연속 클러스터에 있으면 제공해야 합니다.

*새로* 획득한 오디오북은 연속 읽기 클러스터에 포함될 수 있습니다.

값은 0보다 크고 100보다 작아야 합니다.

DisplayTimeWindow: 노출 영역에 콘텐츠를 표시할 시간 설정
시작 타임스탬프 선택사항

에포크 타임스탬프로, 이후에 콘텐츠가 노출 영역에 표시되어야 합니다.

설정하지 않으면 콘텐츠가 노출 영역에 표시될 수 있습니다.

에포크 밀리초 단위로 표시합니다.

최종 타임스탬프 선택사항

에포크 타임스탬프로, 이후에 콘텐츠가 더 이상 노출 영역에 표시되지 않습니다.

설정하지 않으면 콘텐츠가 노출 영역에 표시될 수 있습니다.

에포크 밀리초 단위로 표시합니다.

이미지 사양

이미지 확장 소재의 필수 사양은 다음과 같습니다.

가로세로 비율 요구사항 최소 픽셀 권장 픽셀
정사각형(1x1) 필수 항목 300x300 1200x1200
가로 모드(1.91x1) 선택사항 600x314 1200x628
세로 모드(4x5) 선택사항 480x600 960x1200

파일 형식

PNG, JPG, 정적 GIF, WebP

최대 파일 크기

5120KB

추가 권장사항

  • 이미지 안전 영역: 중요한 콘텐츠를 이미지의 중앙 80%에 배치합니다.

MusicAlbumEntity musicAlbumEntity =
        new MusicAlbumEntity.Builder()
            .setName(NAME)
             .addPosterImage(new Image.Builder()
                  .setImageUri(Uri.parse("http://www.x.com/image.png"))
                  .setImageHeightInPixel(960)
                  .setImageWidthInPixel(408)
                  .build())
            .setPlayBackUri("https://play.google/album/play")
            .setInfoPageUri("https://play.google/album/info")
            .setDescription("A description of this album.")
            .addArtist("Artist")
            .addGenre("Genre")
            .addMusicLabel("Label")
            .addContentRating("Rating")
            .setSongsCount(960)
            .setReleaseDateEpochMillis(1633032895L)
            .setDurationMillis(1633L)
            .build();
AudiobookEntity audiobookEntity =
        new AudiobookEntity.Builder()
            .setName("Becoming")
            .addPosterImage(new Image.Builder()
                 .setImageUri(Uri.parse("http://www.x.com/image.png"))
                 .setImageHeightInPixel(960)
                 .setImageWidthInPixel(408)
                  .build())
            .addAuthor("Michelle Obama")
            .addNarrator("Michelle Obama")
            .setActionLinkUri(
               Uri.parse("https://play.google/audiobooks/1"))
            .setDurationMillis(16335L)
            .setPublishDateEpochMillis(1633032895L)
            .setDescription("An intimate, powerful, and inspiring memoir")
            .setPrice("$16.95")
            .addGenre("biography")
            .build();

2단계: 클러스터 데이터 제공

콘텐츠 게시 작업을 백그라운드에서 실행하고(예: WorkManager 사용) 정기적으로 또는 이벤트를 기반으로 예약하는 것이 좋습니다(예: 사용자가 앱을 열 때마다 또는 사용자가 장바구니에 상품을 추가했을 때).

AppEngagePublishClient는 클러스터 게시를 담당합니다. 클라이언트에서 사용할 수 있는 API는 다음과 같습니다.

  • isServiceAvailable
  • publishRecommendationClusters
  • publishFeaturedCluster
  • publishContinuationCluster
  • publishUserAccountManagementRequest
  • updatePublishStatus
  • deleteRecommendationsClusters
  • deleteFeaturedCluster
  • deleteContinuationCluster
  • deleteUserManagementCluster
  • deleteClusters

isServiceAvailable

이 API는 서비스를 통합에 사용할 수 있는지, 콘텐츠를 기기에 표시할 수 있는지 확인하는 데 사용됩니다.

Kotlin


client.isServiceAvailable.addOnCompleteListener { task ->
    if (task.isSuccessful) {
        // Handle IPC call success
        if(task.result) {
          // Service is available on the device, proceed with content
          // publish calls.
        } else {
          // Service is not available, no further action is needed.
        }
    } else {
      // The IPC call itself fails, proceed with error handling logic here,
      // such as retry.
    }
}

Java


client.isServiceAvailable().addOnCompleteListener(task - > {
    if (task.isSuccessful()) {
        // Handle success
        if(task.getResult()) {
          // Service is available on the device, proceed with content publish
          // calls.
        } else {
          // Service is not available, no further action is needed.
        }
    } else {
      // The IPC call itself fails, proceed with error handling logic here,
      // such as retry.
    }
});

publishRecommendationClusters

이 API는 RecommendationCluster 객체 목록을 게시하는 데 사용됩니다.

Kotlin


client.publishRecommendationClusters(
            PublishRecommendationClustersRequest.Builder()
                .addRecommendationCluster(
                    RecommendationCluster.Builder()
                        .addEntity(entity1)
                        .addEntity(entity2)
                        .setTitle("Trending music")
                        .build())
                .build())

Java


client.publishRecommendationClusters(
            new PublishRecommendationClustersRequest.Builder()
                .addRecommendationCluster(
                    new RecommendationCluster.Builder()
                        .addEntity(entity1)
                        .addEntity(entity2)
                        .setTitle("Trending music")
                        .build())
                .build());

서비스가 요청을 수신하면 다음 작업이 한 트랜잭션 내에서 발생합니다.

  • 개발자 파트너의 기존 RecommendationCluster 데이터가 삭제됩니다.
  • 요청 데이터가 파싱되어, 업데이트된 맞춤 콘텐츠 클러스터에 저장됩니다.

오류가 발생하면 전체 요청이 거부되고 기존 상태가 유지됩니다.

publishFeaturedCluster

이 API는 FeaturedCluster 객체 목록을 게시하는 데 사용됩니다.

Kotlin


client.publishFeaturedCluster(
            PublishFeaturedClusterRequest.Builder()
                .setFeaturedCluster(
                    FeaturedCluster.Builder()
                        ...
                        .build())
                .build())

Java


client.publishFeaturedCluster(
            new PublishFeaturedClusterRequest.Builder()
                .setFeaturedCluster(
                    new FeaturedCluster.Builder()
                        ...
                        .build())
                .build());

서비스가 요청을 수신하면 다음 작업이 한 트랜잭션 내에서 발생합니다.

  • 개발자 파트너의 기존 FeaturedCluster 데이터가 삭제됩니다.
  • 요청 데이터가 파싱되어, 업데이트된 추천 클러스터에 저장됩니다.

오류가 발생하면 전체 요청이 거부되고 기존 상태가 유지됩니다.

publishContinuationCluster

이 API는 ContinuationCluster 객체를 게시하는 데 사용됩니다.

Kotlin


client.publishContinuationCluster(
            PublishContinuationClusterRequest.Builder()
                .setContinuationCluster(
                    ContinuationCluster.Builder()
                        .addEntity(entity1)
                        .addEntity(entity2)
                        .build())
                .build())

Java


client.publishContinuationCluster(
            PublishContinuationClusterRequest.Builder()
                .setContinuationCluster(
                    ContinuationCluster.Builder()
                        .addEntity(entity1)
                        .addEntity(entity2)
                        .build())
                .build())

서비스가 요청을 수신하면 다음 작업이 한 트랜잭션 내에서 발생합니다.

  • 개발자 파트너의 기존 ContinuationCluster 데이터가 삭제됩니다.
  • 요청 데이터가 파싱되어, 업데이트된 연속 클러스터에 저장됩니다.

오류가 발생하면 전체 요청이 거부되고 기존 상태가 유지됩니다.

publishUserAccountManagementRequest

이 API는 로그인 카드를 게시하는 데 사용됩니다. 로그인 작업은 앱이 콘텐츠를 게시하거나 더 맞춤설정된 콘텐츠를 제공할 수 있도록 사용자를 앱의 로그인 페이지로 안내합니다.

다음 메타데이터는 로그인 카드의 일부입니다.

속성 요구사항 설명
작업 URI 필수 작업으로 연결되는 딥 링크(앱 로그인 페이지로 이동)
이미지 선택사항 - 제공되지 않은 경우 제목을 입력해야 합니다.

카드에 표시된 이미지

해상도 1264x712의 16x9 가로세로 비율 이미지

제목 선택사항 - 제공되지 않은 경우 이미지를 제공해야 합니다. 카드상의 제목
작업 텍스트 선택사항 CTA에 표시된 텍스트(로그인)
부제 선택사항 카드의 부제목(선택사항)

Kotlin


var SIGN_IN_CARD_ENTITY =
      SignInCardEntity.Builder()
          .addPosterImage(
              Image.Builder()
                  .setImageUri(Uri.parse("http://www.x.com/image.png"))
                  .setImageHeightInPixel(500)
                  .setImageWidthInPixel(500)
                  .build())
          .setActionText("Sign In")
          .setActionUri(Uri.parse("http://xx.com/signin"))
          .build()

client.publishUserAccountManagementRequest(
            PublishUserAccountManagementRequest.Builder()
                .setSignInCardEntity(SIGN_IN_CARD_ENTITY)
                .build());

Java


SignInCardEntity SIGN_IN_CARD_ENTITY =
      new SignInCardEntity.Builder()
          .addPosterImage(
              new Image.Builder()
                  .setImageUri(Uri.parse("http://www.x.com/image.png"))
                  .setImageHeightInPixel(500)
                  .setImageWidthInPixel(500)
                  .build())
          .setActionText("Sign In")
          .setActionUri(Uri.parse("http://xx.com/signin"))
          .build();

client.publishUserAccountManagementRequest(
            new PublishUserAccountManagementRequest.Builder()
                .setSignInCardEntity(SIGN_IN_CARD_ENTITY)
                .build());

서비스가 요청을 수신하면 다음 작업이 한 트랜잭션 내에서 발생합니다.

  • 개발자 파트너의 기존 UserAccountManagementCluster 데이터가 삭제됩니다.
  • 요청 데이터가 파싱되어, 업데이트된 UserAccountManagementCluster 클러스터에 저장됩니다.

오류가 발생하면 전체 요청이 거부되고 기존 상태가 유지됩니다.

updatePublishStatus

내부적인 이유로 어떠한 클러스터도 게시되지 않는 경우 updatePublishStatus API를 사용하여 게시 상태를 업데이트할 것을 적극 권장합니다. 이는 다음과 같은 이유로 중요합니다.

  • 콘텐츠가 게시되는 경우에도(STATUS == PUBLISHED) 모든 시나리오에서 상태를 제공하는 것은 이 명시적 상태를 사용하여 통합의 상태 및 기타 측정항목을 전달하는 대시보드를 채우는 데 중요합니다.
  • 게시된 콘텐츠는 없지만 통합 상태가 손상되지 않은 경우(STATUS == NOT_PUBLISHED) Google은 앱 상태 대시보드에서 알림을 트리거하지 않을 수 있습니다. 이는 제공업체의 관점에서 예상되는 상황으로 인해 콘텐츠가 게시되지 않음을 확인합니다.
  • 이를 통해 개발자는 데이터가 게시되는 시점과 게시되지 않는 시점에 관한 유용한 정보를 제공할 수 있습니다.
  • Google에서는 상태 코드를 사용하여 사용자가 앱에서 특정 작업을 하도록 유도할 수 있습니다. 따라서 사용자가 앱 콘텐츠를 보거나 극복할 수 있습니다.

적합한 게시 상태 코드 목록은 다음과 같습니다.

// Content is published
AppEngagePublishStatusCode.PUBLISHED,

// Content is not published as user is not signed in
AppEngagePublishStatusCode.NOT_PUBLISHED_REQUIRES_SIGN_IN,

// Content is not published as user is not subscribed
AppEngagePublishStatusCode.NOT_PUBLISHED_REQUIRES_SUBSCRIPTION,

// Content is not published as user location is ineligible
AppEngagePublishStatusCode.NOT_PUBLISHED_INELIGIBLE_LOCATION,

// Content is not published as there is no eligible content
AppEngagePublishStatusCode.NOT_PUBLISHED_NO_ELIGIBLE_CONTENT,

// Content is not published as the feature is disabled by the client
// Available in v1.3.1
AppEngagePublishStatusCode.NOT_PUBLISHED_FEATURE_DISABLED_BY_CLIENT,

// Content is not published as the feature due to a client error
// Available in v1.3.1
AppEngagePublishStatusCode.NOT_PUBLISHED_CLIENT_ERROR,

// Content is not published as the feature due to a service error
// Available in v1.3.1
AppEngagePublishStatusCode.NOT_PUBLISHED_SERVICE_ERROR,

// Content is not published due to some other reason
// Reach out to engage-developers@ before using this enum.
AppEngagePublishStatusCode.NOT_PUBLISHED_OTHER

로그인하지 않은 사용자로 인해 콘텐츠가 게시되지 않은 경우 로그인 카드를 게시하는 것이 좋습니다. 어떠한 이유로든 제공업체가 로그인 카드를 게시할 수 없는 경우 상태 코드 NOT_PUBLISHED_REQUIRES_SIGN_IN을 사용하여 updatePublishStatus API를 호출하는 것이 좋습니다.

Kotlin


client.updatePublishStatus(
   PublishStatusRequest.Builder()
     .setStatusCode(AppEngagePublishStatusCode.NOT_PUBLISHED_REQUIRES_SIGN_IN)
     .build())

Java


client.updatePublishStatus(
    new PublishStatusRequest.Builder()
        .setStatusCode(AppEngagePublishStatusCode.NOT_PUBLISHED_REQUIRES_SIGN_IN)
        .build());

deleteRecommendationClusters

이 API는 맞춤 콘텐츠 클러스터의 콘텐츠를 삭제하는 데 사용됩니다.

Kotlin


client.deleteRecommendationClusters()

Java


client.deleteRecommendationClusters();

서비스가 요청을 수신하면 맞춤 콘텐츠 클러스터에서 기존 데이터를 삭제합니다. 오류가 발생하면 전체 요청이 거부되고 기존 상태가 유지됩니다.

deleteFeaturedCluster

이 API는 추천 클러스터의 콘텐츠를 삭제하는 데 사용됩니다.

Kotlin


client.deleteFeaturedCluster()

Java


client.deleteFeaturedCluster();

서비스가 요청을 수신하면 추천 클러스터에서 기존 데이터를 삭제합니다. 오류가 발생하면 전체 요청이 거부되고 기존 상태가 유지됩니다.

deleteContinuationCluster

이 API는 연속 클러스터의 콘텐츠를 삭제하는 데 사용됩니다.

Kotlin


client.deleteContinuationCluster()

Java


client.deleteContinuationCluster();

서비스가 요청을 수신하면 연속 클러스터에서 기존 데이터를 삭제합니다. 오류가 발생하면 전체 요청이 거부되고 기존 상태가 유지됩니다.

deleteUserManagementCluster

이 API는 UserAccountManagement 클러스터의 콘텐츠를 삭제하는 데 사용됩니다.

Kotlin


client.deleteUserManagementCluster()

Java


client.deleteUserManagementCluster();

서비스가 요청을 수신하면 UserAccountManagement 클러스터에서 기존 데이터를 삭제합니다. 오류가 발생하면 전체 요청이 거부되고 기존 상태가 유지됩니다.

deleteClusters

이 API는 특정 클러스터 유형의 콘텐츠를 삭제하는 데 사용됩니다.

Kotlin


client.deleteClusters(
    DeleteClustersRequest.Builder()
      .addClusterType(ClusterType.TYPE_FEATURED)
      .addClusterType(ClusterType.TYPE_RECOMMENDATION)
      ...
      .build())

Java


client.deleteClusters(
            new DeleteClustersRequest.Builder()
                .addClusterType(ClusterType.TYPE_FEATURED)
                .addClusterType(ClusterType.TYPE_RECOMMENDATION)
                ...
                .build());

서비스가 요청을 수신하면 지정된 클러스터 유형과 일치하는 모든 클러스터에서 기존 데이터가 삭제됩니다. 클라이언트는 하나 이상의 클러스터 유형을 전달하도록 선택할 수 있습니다. 오류가 발생하면 전체 요청이 거부되고 기존 상태가 유지됩니다.

오류 처리

후속 작업을 실행하여 성공적인 작업을 복구하고 다시 제출할 수 있도록 게시 API의 작업 결과를 수신 대기하는 것이 좋습니다.

client.publishRecommendationClusters(
              new PublishRecommendationClustersRequest.Builder()
                  .addRecommendationCluster(...)
                  .build())
          .addOnCompleteListener(
              task -> {
                if (task.isSuccessful()) {
                  // do something
                } else {
                  Exception exception = task.getException();
                  if (exception instanceof AppEngageException) {
                    @AppEngageErrorCode
                    int errorCode = ((AppEngageException) exception).getErrorCode();
                    if (errorCode == AppEngageErrorCode.SERVICE_NOT_FOUND) {
                      // do something
                    }
                  }
                }
              });

오류는 AppEngageException으로 반환되며 원인은 오류 코드로 포함됩니다.

오류 코드 참고
SERVICE_NOT_FOUND 지정된 기기에서 서비스를 사용할 수 없습니다.
SERVICE_NOT_AVAILABLE 서비스는 특정 기기에서 사용할 수 있지만 호출 시점에는 사용할 수 없습니다(예: 명시적으로 사용 중지됨).
SERVICE_CALL_EXECUTION_FAILURE 스레딩 문제로 인해 작업을 실행할 수 없습니다. 이 경우 재시도할 수 있습니다.
SERVICE_CALL_PERMISSION_DENIED 호출자가 서비스를 호출할 수 없습니다.
SERVICE_CALL_INVALID_ARGUMENT 요청에 잘못된 데이터가 포함되어 있습니다(예: 허용된 클러스터 수를 초과함).
SERVICE_CALL_INTERNAL 서비스 측에 오류가 있습니다.
SERVICE_CALL_RESOURCE_EXHAUSTED 서비스 호출이 너무 자주 이루어집니다.

3단계: 브로드캐스트 인텐트 처리

작업을 통해 게시 콘텐츠 API를 호출하는 것 외에도 콘텐츠 게시 요청을 수신하도록 BroadcastReceiver를 설정해야 합니다.

브로드캐스트 인텐트의 목표는 주로 앱 재활성화 및 데이터 동기화 강제입니다. 브로드캐스트 인텐트는 자주 전송되지 않도록 설계되었습니다. 이는 참여 서비스에서 콘텐츠가 오래되었을 수 있다고 판단할 때만(예: 1주일) 트리거됩니다. 이렇게 하면 애플리케이션이 장기간 실행되지 않은 경우에도 사용자에게 새로운 콘텐츠 환경을 제공할 수 있습니다.

BroadcastReceiver는 다음 두 가지 방법으로 설정해야 합니다.

  • Context.registerReceiver()를 사용하여 BroadcastReceiver 클래스의 인스턴스를 동적으로 등록합니다. 이렇게 하면 여전히 메모리에 있는 애플리케이션의 통신이 가능해집니다.
class AppEngageBroadcastReceiver extends BroadcastReceiver {
// Trigger recommendation cluster publish when PUBLISH_RECOMMENDATION broadcast
// is received

// Trigger featured cluster publish when PUBLISH_FEATURED broadcast is received

// Trigger continuation cluster publish when PUBLISH_CONTINUATION broadcast is
// received
}

public static void registerBroadcastReceivers(Context context) {

context = context.getApplicationContext();

// Register Recommendation Cluster Publish Intent
context.registerReceiver(new AppEngageBroadcastReceiver(),
new IntentFilter(com.google.android.engage.service.Intents.ACTION_PUBLISH_RECOMMENDATION));

// Register Featured Cluster Publish Intent
context.registerReceiver(new AppEngageBroadcastReceiver(),
new IntentFilter(com.google.android.engage.service.Intents.ACTION_PUBLISH_FEATURED));


// Register Continuation Cluster Publish Intent
context.registerReceiver(new AppEngageBroadcastReceiver(),
new IntentFilter(com.google.android.engage.service.Intents.ACTION_PUBLISH_CONTINUATION));

}
  • AndroidManifest.xml 파일에서 <receiver> 태그를 사용하여 구현을 정적으로 선언합니다. 이를 통해 애플리케이션이 실행 중이 아닐 때 브로드캐스트 인텐트를 수신할 수 있고, 애플리케이션이 콘텐츠를 게시할 수 있습니다.
<application>
   <receiver
      android:name=".AppEngageBroadcastReceiver"
      android:exported="true"
      android:enabled="true">
      <intent-filter>
         <action android:name="com.google.android.engage.action.PUBLISH_RECOMMENDATION" />
      </intent-filter>
      <intent-filter>
         <action android:name="com.google.android.engage.action.PUBLISH_FEATURED" />
      </intent-filter>
      <intent-filter>
         <action android:name="com.google.android.engage.action.PUBLISH_CONTINUATION" />
      </intent-filter>
   </receiver>
</application>

다음 인텐트가 서비스에 의해 전송됩니다.

  • com.google.android.engage.action.PUBLISH_RECOMMENDATION 이 인텐트를 수신할 때 publishRecommendationClusters 호출을 시작하는 것이 좋습니다.
  • com.google.android.engage.action.PUBLISH_FEATURED 이 인텐트를 수신할 때 publishFeaturedCluster 호출을 시작하는 것이 좋습니다.
  • com.google.android.engage.action.PUBLISH_CONTINUATION 이 인텐트를 수신할 때 publishContinuationCluster 호출을 시작하는 것이 좋습니다.

통합 워크플로

통합 완료 후 통합 확인에 관한 단계별 안내는 Engage 개발자 통합 워크플로를 참고하세요.

FAQ

FAQ에 관해서는 Engage SDK 관련 자주 묻는 질문(FAQ)을 참고하세요.

문의

통합 과정에서 궁금한 점이 있으면 engage-developers@google.com으로 문의해 주세요. 지원팀에서 최대한 빨리 답변해 드리겠습니다.

다음 단계

이 통합을 완료한 후 단계는 다음과 같습니다.

  • engage-developers@google.com으로 Google의 테스트를 받을 준비가 된 통합 APK를 첨부하여 이메일을 보냅니다.
  • Google에서는 내부적으로 검증 및 검토를 실행하여 통합이 예상대로 작동하는지 확인합니다. 변경이 필요한 경우 Google에서는 필요한 세부정보를 알려 드립니다.
  • 테스트가 완료되고 아무것도 변경할 필요가 없으면 Google에서는 업데이트된 통합 APK를 Play 스토어에 게시할 수 있음을 알려 드립니다.
  • 업데이트된 APK가 Play 스토어에 게시되었음을 Google에서 확인한 후에는 맞춤 콘텐츠, 추천, 연속 클러스터가 게시되고 사용자에게 표시됩니다.