Engage SDK Codelab

1. 소개

최종 업데이트: 2025년 5월 14일

Engage SDK란 무엇인가요?

Engage SDK를 사용하면 여러 기기 내 Google 표시 경로에서 사용자가 있는 위치에 맞춤 앱 콘텐츠를 제공하여 앱 참여도를 높일 수 있습니다. Engage SDK를 사용하면 앱에서 설치된 사용자가 앱을 열기 전에 맞춤형 (1:1) 추천 및 연속 콘텐츠를 제공하여 사용자의 참여를 유도할 수 있습니다.

콘텐츠 표시 경로

컬렉션

Entertainment Space

Play 스토어(제공 예정)

새로운 Play 스토어 위젯을 사용하여 사용자의 홈 화면에 콘텐츠를 직접 표시합니다.

일부 Android 태블릿에서 엔터테인먼트 콘텐츠의 새로운 터치 포인트를 만듭니다.

올 여름 Play 스토어를 시작으로 더 많은 표시 경로에 액세스합니다.

빌드할 항목

이 Codelab을 완료하면 Google 표시 경로로 콘텐츠를 전송할 수 있는 Android 동영상 앱을 빌드하게 됩니다.

필요한 항목

  • 최신 Android SDK
  • 최신 Android 스튜디오
  • Android 10 이상을 실행하는 휴대기기 1대
  • 휴대기기를 개발용 컴퓨터에 연결하기 위한 USB 데이터 케이블

경험

  • Java 또는 Kotlin 사용 경험이 있어야 합니다.
  • Android 개발에 관한 지식이 있어야 합니다.

2. 샘플 앱 실행

시작하려면 이 Codelab을 따라 하는 데 도움이 되는 샘플 앱 코드를 다운로드하세요.

git을 설치한 경우 저장소를 클론합니다.

git clone https://github.com/googlesamples/engage-sdk-samples.git

또는 이 링크를 클릭하여 소스 코드를 다운로드하고 다운로드한 zip 파일의 압축을 풉니다.

이 프로젝트는 Gradle 빌드 시스템을 사용합니다. 이 프로젝트를 빌드하려면 gradlew 빌드 명령어를 사용하거나 Android 스튜디오에서 Import Project를 사용하세요.

코드를 다운로드하면 두 개의 샘플 프로젝트가 표시됩니다.

  • Java 개발자: read 샘플 앱 사용

이 앱은 기본적인 도서 라이브러리입니다. 사용자는 목록에서 도서를 선택한 후 도서 읽기를 시작할 수 있습니다. 앱은 맞춤 콘텐츠 및 연속 데이터가 게시되는 방식을 보여줍니다.

  • Kotlin 개발자: watch 샘플 앱 사용

이 앱은 기본 동영상 라이브러리입니다. 사용자가 목록에서 동영상을 선택한 다음 동영상 시청을 시작할 수 있습니다. 앱은 맞춤 콘텐츠 및 연속 데이터가 게시되는 방식을 보여줍니다.

Android 개발 학습에 관한 자세한 리소스는 developer.android.com의 개발자 가이드를 참고하세요.

3. 항목 빌드

이 Codelab에서는 read 샘플 앱의 경우 Engage SDK Read 통합 가이드를, watch 샘플 앱의 경우 Engage SDK Watch 통합 가이드를 참고합니다.

항목: 클러스터에 있는 단일 항목을 나타내는 객체입니다. 항목은 eBook, 영화 또는 기타 관련 콘텐츠 유형일 수 있습니다.

read 콘텐츠의 경우 SDK에는 다음과 같은 항목 유형이 있습니다.

  • EbookEntity
  • AudiobookEntity
  • BookSeriesEntity

watch 콘텐츠의 경우 SDK에는 다음과 같은 항목 유형이 있습니다.

  • MovieEntity
  • TvShowEntity
  • TvSeasonEntity
  • TvEpisodeEntity
  • LiveStreamingVideoEntity
  • VideoClipEntity

read 샘플 앱에서, 게시할 EbookEntity를 빌드하는 메서드가 포함된 EbookToEntityConverter.java 파일로 이동합니다.

EbookEntity.Builder entityBuilder = new EbookEntity.Builder()
        .setName("NAME OF EBOOK")
        .addAuthor("AUTHOR NAME")
        .setActionLinkUri(Uri.parse("DEEPLINK URI OF THIS EBOOK"))
        ...
         .build()

watch 샘플 앱에서, 게시할 MovieEntity를 빌드하는 메서드가 포함된 ItemToEntityConverter.kt 파일로 이동합니다.

val movieBuilder: MovieEntity.Builder =
      MovieEntity.Builder()
        .setName("NAME OF THE MOVIE")
        .addPosterImage(
          Image.Builder()
            .setImageUri(
              Uri.parse("android.resource://movie")
            )
            .setImageWidthInPixel(408)
            .setImageHeightInPixel(960)
            .setImageTheme(ImageTheme.IMAGE_THEME_LIGHT)
            .build()
        )
        .setPlayBackUri(Uri.parse(movie.playbackUri))
        .setReleaseDateEpochMillis(movie.releaseDate)
        .setAvailability(movie.availability)
        .setDurationMillis(movie.durationMillis)
        .addGenre(movie.genre)
          ..
           .build()

마찬가지로 애플리케이션 내에서 자체 데이터 항목을 게시하려는 상응하는 Engage 항목으로 변환할 수도 있습니다.

4. 맞춤 콘텐츠 클러스터 빌드

이제 항목을 빌드했으므로 클러스터에서 함께 그룹화할 수 있습니다.

클러스터는 번들로 묶인 콘텐츠 모음입니다. 클러스터는 단일 개발자 파트너의 콘텐츠 항목 그룹이 포함된 UI 뷰로 시각화할 수 있습니다.

e8ec28fa54ac7eec.png그림

단일 파트너의 eBook 항목이 포함된 맞춤 콘텐츠 클러스터를 보여주는 Entertainment Space UI

read 콘텐츠 및 watch 콘텐츠를 비롯한 대부분의 카테고리의 경우 SDK에는 다음과 같은 클러스터 유형이 있습니다.

  • 맞춤 콘텐츠 클러스터는 앱에서의 사용자 행동을 기반으로 맞춤설정할 수 있으며 신작, 가격 인하, 사용자가 좋아하는 주제와 같은 테마별로 구성할 수 있습니다. 각 앱은 사용자당 최대 5개의 맞춤 콘텐츠 클러스터를 제공할 수 있습니다.
  • 연속 클러스터는 사용자가 여러 앱의 콘텐츠가 포함된 단일 UI 그룹에서 완료되지 않은 영화나 eBook과 같은 진행 중인 콘텐츠를 재개할 수 있도록 지원합니다.
  • 추천 클러스터는 더 크고 고급스러운 UI 템플릿을 사용하여 멀티 앱 클러스터에서 히어로 콘텐츠를 강조 표시할 수 있습니다.

read 및 watch 콘텐츠 모두에 대해 맞춤 콘텐츠 클러스터를 빌드합니다.

read 샘플 앱에서 GetRecommendationClusters.java 파일로 이동합니다. 이 파일에는 맞춤 콘텐츠 클러스터를 빌드하는 방법의 예가 나와 있습니다.

RecommendationCluster.Builder clusterBuilder = new RecommendationCluster.Builder();
// Set the cluster title
clusterBuilder.setTitle("For You");
for (int id : ebookIds) {
  //Create an ebook entity.
  EbookEntity entity = EbookToEntityConverter.convert(id); 
  // Add the ebook entity to the cluster
  clusterBuilder.addEntity(entity);
}
// Build the cluster
return clusterBuilder.build();

watch 샘플 앱에서 ClusterRequestFactory.kt 파일로 이동합니다. 이 파일에는 맞춤 콘텐츠 클러스터를 빌드하는 방법의 예가 나와 있습니다.

// Loads all the movie data 
val recommendationsList = movieDao.loadMovieIsCurrentlyWatching(false)
val recommendationCluster = RecommendationCluster.Builder()
for (item in recommendationsList) {
   //Create a movie entity.
    val movieEntity = ItemToEntityConverter.convertMovie(item)
    // Add the movie entity to the cluster
    recommendationCluster.addEntity(movieEntity)
}
// Build the cluster
return recommendationCluster.build

5. 맞춤 콘텐츠 클러스터 게시

이제 항목을 빌드하고 이러한 항목을 클러스터로 그룹화하는 방법을 알아봤습니다. 다음 단계는 클러스터를 게시하는 방법을 알아보는 것입니다.

AppEngagePublishClient는 클러스터를 게시하기 위한 연결을 설정합니다.

1단계: 클라이언트 초기화

// Java version
AppEngagePublishClient client = new AppEngagePublishClient(context);
// Kotlin version
val client = AppEngagePublishClient(context)

2단계: 클러스터 게시 요청 만들기

read 샘플 앱에서 EngageServiceWorker.javasetRecommendations 메서드를 확인합니다.

// Initialize the builder
PublishRecommendationClustersRequest.Builder publishRequestBuilder = new PublishRecommendationClustersRequest.Builder();

// Add all Recommendation Clusters
for (RecommendationCluster cluster : clusters) {
   publishRequestBuilder.addRecommendationCluster(cluster);
}
// Build the request    
publishRequestBuilder.build();

watch 샘플 앱에서 ClusterRequestFactory.ktconstructRecommendationClustersRequest 메서드를 확인합니다.

// Initialize the builder
val request = PublishRecommendationClustersRequest.Builder()
// Add all Recommendation Cluster
.addRecommendationCluster(recommendationCluster)
// Build the request    
.build()

3단계: AppEngagePublishClient에서 publishRecommendationClusters 메서드 호출

read 샘플 앱에서 EngageServiceWorker.javasetRecommendations 메서드를 확인합니다.

client.publishRecommendationClusters(publishRequest);

watch 샘플 앱에서 EngageServiceWorker.ktpublishRecommendations 메서드를 확인합니다.

client.publishRecommendationClusters(request)

isServiceAvailable API 사용

publish API를 호출하기 전에 isServiceAvailable을 호출하여 게시가 허용되는지 확인해야 합니다.

read 샘플 앱에서 EngageServiceWorker.javastartWork 메서드를 확인합니다.

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.
          client.publishRecommendationClusters(request)
        } else {
          // Service is not available, do not publish.
        }
    } else {
      // The IPC call itself fails, proceed with error handling logic here,
      // such as retry.
    }
}

watch 샘플 앱에서 EngageServiceWorker.ktdoWork 메서드를 확인합니다.

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.
          client.publishRecommendationClusters(request)
        } else {
          // Service is not available, do not publish.
        }
    } else {
      // The IPC call itself fails, proceed with error handling logic here,
      // such as retry.
    }
}

6. 게시 상태

콘텐츠가 게시되지 않는 이유를 나타내려면 updatePublishStatus API를 사용하는 것이 좋습니다. 이렇게 하면 앱에서 의도적으로 콘텐츠를 게시하지 않는 경우 Google에서 잘못된 알림을 피하고, 사용자에게 콘텐츠에 액세스하기 위한 수정 조치를 취하도록 안내하고, 콘텐츠 게시 상태에 관한 유용한 정보를 제공할 수 있습니다.

상태 코드는 개발자 사이트를 참고하세요. 예를 들어 사용자가 로그인해야 하기 때문에 콘텐츠가 표시되지 않는 경우 NOT_PUBLISHED_REQUIRES_SIGN_IN을 사용합니다. 다음 단계에서 이 코드를 적용합니다.

read 샘플 앱에서 EngageServiceWorker.ktpublishAndSetResult 메서드를 확인합니다.

int publishStatusCode;
              if (loggedInAccount.isPresent()) {
                // If an account is logged in and content is published
                publishStatusCode = AppEngagePublishStatusCode.PUBLISHED;
              } else {
                // If an account is not logged in and no content is published
                publishStatusCode = AppEngagePublishStatusCode.NOT_PUBLISHED_REQUIRES_SIGN_IN;
              }
              setPublishStatus(client, publishStatusCode);
            })

watch 샘플 앱에서 EngageServiceWorker.ktpublishUserAccountManagement 메서드를 확인합니다.

private suspend fun publishUserAccountManagement(): Result {
    val publishTask: Task<Void>
    val statusCode: Int
    if (db.accountDao().isAccountSignedIn()) {
      // If an account is logged in and content is published
statusCode = AppEngagePublishStatusCode.PUBLISHED
    } else {
     // If an account is not logged in and no content is published
      statusCode = AppEngagePublishStatusCode.NOT_PUBLISHED_REQUIRES_SIGN_IN
    }
    return publishAndProvideResult(publishTask, statusCode)
  }

7. Work Manager 및 브로드캐스트 인텐트

Work Manager

WorkManager를 사용하여 백그라운드에서 콘텐츠 게시 작업을 실행하는 것이 좋습니다. 정기적으로(예: 매일) 또는 사용자 이벤트(예: 앱이 열릴 때 또는 사용자가 읽기 세션을 완료한 후)를 기반으로 예약합니다. 아래 예에서는 예약된 게시를 중점적으로 설명합니다.

read 샘플 앱SetEngageState.java 파일에서 queuePeriodicSetEngageStateWorker는 WorkManager를 설정하는 방법의 예를 보여줍니다.

// Create a work manager
WorkManager workManager = WorkManager.getInstance(appContext);

// Set up a periodic work request for 24 hrs.
PeriodicWorkRequest publishRequest =
        new PeriodicWorkRequest.Builder(
                EngageServiceWorker.class, /* repeatInterval= */ 24, TimeUnit.HOURS)
            .setInputData(clusterToPublishData)
            .build();
// Add the work request to queue
workManager.enqueueUniquePeriodicWork(
        publishWorkName, ExistingPeriodicWorkPolicy.CANCEL_AND_REENQUEUE, publishRequest);

watch 샘플 앱Publisher.kt에 있는 periodicallyCallEngageServiceWorker는 WorkManager를 설정하는 방법의 예를 보여줍니다.

// Set up a periodic work request for 24 hrs.
val workRequest = PeriodicWorkRequestBuilder<EngageServiceWorker>(
          repeatInterval = 24,
          repeatIntervalTimeUnit = TimeUnit.HOURS
        )
        .setInputData(workDataOf(PUBLISH_TYPE to publishType))
        .build()

// Create a work manager and add the work request to queue
WorkManager.getInstance(context)
.enqueueUniquePeriodicWork(
workerName,
ExistingPeriodicWorkPolicy.CANCEL_AND_REENQUEUE,
workRequest
)

브로드캐스트 인텐트

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

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

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

  • Context.registerReceiver()를 사용하여 BroadcastReceiver 클래스의 인스턴스를 동적으로 등록합니다. 이렇게 하면 여전히 메모리에 있는 애플리케이션의 통신이 가능해집니다.

read 샘플 앱에서 MainActivity.java 파일을 열어 다음을 확인합니다.

private void registerReceiver() {
    BroadcastReceiver publishReceiver = new EngageServiceBroadcastReceiver();
    IntentFilter filter = new IntentFilter();
    filter.addAction(Intents.ACTION_PUBLISH_RECOMMENDATION);
    filter.addAction(Intents.ACTION_PUBLISH_FEATURED);
    filter.addAction(Intents.ACTION_PUBLISH_CONTINUATION);
    int flags = ContextCompat.RECEIVER_EXPORTED;
    ContextCompat.registerReceiver(getApplicationContext(), publishReceiver, filter, flags);
  }
  • AndroidManifest.xml 파일에서 <receiver> 태그를 사용하여 구현을 정적으로 선언합니다. 이를 통해 애플리케이션이 실행 중이 아닐 때 브로드캐스트 인텐트를 수신할 수 있고, 애플리케이션이 콘텐츠를 게시할 수 있습니다.

read 샘플 앱에서 AndroidManifest.xml 파일을 열어 다음을 확인합니다.

<receiver
        android:name=".publish.EngageServiceBroadcastReceiver"
        android:exported="true">
      <intent-filter>
        <action android:name="com.google.android.engage.action.PUBLISH_RECOMMENDATION" />
        <action android:name="com.google.android.engage.action.PUBLISH_FEATURED" />
        <action android:name="com.google.android.engage.action.PUBLISH_CONTINUATION" />
             </intent-filter>
 </receiver>

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

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

8. 테스트에 인증 앱 사용

통합을 확인하려면 인증 앱을 다운로드하여 사용합니다.

인증 앱에는 각 클러스터가 별도의 행으로 표시되어야 합니다.

  • 데이터를 게시하는 패키지의 이름을 입력합니다.

d1ad850cd02991d.png

  • 클러스터의 모든 항목이 게시되는지 확인합니다.

3953d00488212411.png

  • 항목의 모든 필드가 게시되는지 확인합니다. 행의 각 항목에서 개발자는 포스터 이미지를 클릭하여 인텐트를 확인할 수 있습니다.

23cd19224397adf3.png

브로드캐스트 인텐트 흐름 확인

인증 앱을 사용하여 브로드캐스트 인텐트를 확인하고 UI 상단의 버튼을 클릭하여 브로드캐스트 전송 로직을 트리거합니다.

9cb0b5315057fbe1.png

9. 축하합니다

이제 Android 앱에 Engage SDK를 추가하는 방법을 알게 되었습니다.

자세한 내용은 Engage SDK 개발자 가이드 및 비즈니스 사이트를 참고하세요.

리소스

게시되는 콘텐츠 유형에 따라 SDK에는 다양한 유형의 항목 클래스가 포함됩니다. 아래에 나열된 각 카테고리의 통합 가이드에서 사용 가능한 항목 목록을 확인할 수 있습니다.