Lớp học lập trình về Engage SDK
Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.

1. Giới thiệu

Lần cập nhật gần đây nhất: ngày 14 tháng 5 năm 2025

Engage SDK là gì?

Engage SDK có thể giúp tăng mức độ tương tác của ứng dụng bằng cách đưa nội dung ứng dụng được cá nhân hoá đến vị trí của người dùng trên nhiều nền tảng của Google trên thiết bị. Với Engage SDK, ứng dụng của bạn có thể phân phối nội dung đề xuất và nội dung tiếp tục được cá nhân hoá (1:1) để tương tác với người dùng đã cài đặt trước khi họ mở ứng dụng đó.

Nền tảng nội dung

Bộ sưu tập	Entertainment Space	Cửa hàng Play (sắp ra mắt)

Đưa nội dung của bạn đến thẳng màn hình chính của người dùng bằng tiện ích Cửa hàng Play mới.	Tạo các điểm tiếp xúc mới cho nội dung giải trí trên một số máy tính bảng Android.	Truy cập vào các nền tảng khác, bắt đầu từ Cửa hàng Play vào mùa hè này.

Sản phẩm bạn sẽ tạo ra

Khi hoàn tất lớp học lập trình này, bạn sẽ có một ứng dụng video Android có thể gửi nội dung đến một nền tảng của Google.

Bạn cần có

SDK Android mới nhất.
Android Studio mới nhất
Một thiết bị di động chạy Android 10 trở lên.
Cáp dữ liệu USB để kết nối thiết bị di động với máy tính phát triển.

Kinh nghiệm

Bạn cần có kinh nghiệm về Java hoặc Kotlin.
Bạn cần có kiến thức về phát triển Android.

2. Chạy ứng dụng mẫu

Để bắt đầu, hãy tải mã ứng dụng mẫu xuống để giúp bạn theo dõi lớp học lập trình này.

Sao chép kho lưu trữ nếu bạn đã cài đặt git.

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

Ngoài ra, bạn có thể nhấp vào đường liên kết này để tải mã nguồn xuống và giải nén tệp ZIP đã tải xuống.

Dự án này sử dụng hệ thống xây dựng Gradle. Để tạo dự án này, hãy dùng lệnh tạo gradlew hoặc dùng tính năng "Import Project" (Nhập dự án) trong Android Studio.

Sau khi tải mã xuống, bạn sẽ thấy 2 dự án mẫu.

Đối với nhà phát triển Java – Dùng ứng dụng mẫu read

Ứng dụng này là một thư viện sách cơ bản. Người dùng có thể chọn một cuốn sách trong danh sách rồi bắt đầu đọc cuốn sách đó. Ứng dụng này minh hoạ cách xuất bản dữ liệu Đề xuất và Tiếp tục.

Đối với nhà phát triển Kotlin – Dùng ứng dụng mẫu watch

Ứng dụng này là một thư viện video cơ bản. Người dùng có thể chọn một video trong danh sách rồi bắt đầu xem video đó. Ứng dụng này minh hoạ cách xuất bản dữ liệu Đề xuất và Tiếp tục.

Để xem thêm tài nguyên về việc học cách phát triển Android, hãy truy cập vào Hướng dẫn cho nhà phát triển tại developer.android.com

3. Tạo thực thể

Trong lớp học lập trình này, chúng ta sẽ tham khảo Hướng dẫn tích hợp Engage SDK Read và Hướng dẫn tích hợp Engage SDK Watch cho ứng dụng mẫu read và watch tương ứng.

Thực thể là một đối tượng đại diện cho mỗi nội dung trong một cụm. Mỗi thực thể có thể là sách điện tử, phim hoặc bất kỳ loại nội dung liên quan nào.

Đối với nội dung read, SDK này có những Loại thực thể sau đây

EbookEntity
AudiobookEntity
BookSeriesEntity

Đối với nội dung watch, SDK này có những Loại thực thể sau đây

MovieEntity
TvShowEntity
TvSeasonEntity
TvEpisodeEntity
LiveStreamingVideoEntity
VideoClipEntity

Trong ứng dụng mẫu read, hãy chuyển đến tệp EbookToEntityConverter.java chứa các phương thức tạo EbookEntity để xuất bản.

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

Trong ứng dụng mẫu watch, hãy chuyển đến tệp ItemToEntityConverter.kt chứa các phương thức tạo MovieEntity để xuất bản.

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()

Tương tự như vậy, trong ứng dụng của mình, bạn cũng có thể chuyển đổi các mục dữ liệu riêng thành những Thực thể Engage tương ứng mà bạn muốn xuất bản.

4. Tạo cụm đề xuất

Giờ đây, khi đã tạo một Thực thể, chúng ta có thể nhóm các thực thể đó lại với nhau trong một Cụm.

Cụm là một tập hợp nội dung được gói lại với nhau. Bạn có thể hình dung các cụm này là khung hiển thị giao diện người dùng chứa một nhóm các mục nội dung của một đối tác nhà phát triển.

Hình.

Giao diện người dùng Entertainment Space hiển thị một cụm Đề xuất có các Thực thể sách điện tử của một đối tác.

Đối với hầu hết các danh mục, bao gồm cả nội dung read và nội dung watch, SDK này có những Loại cụm sau đây

Bạn có thể cá nhân hoá các cụm Đề xuất dựa trên hành vi của người dùng trong ứng dụng và sắp xếp theo chủ đề, chẳng hạn như bản phát hành mới, thông tin giảm giá hoặc chủ đề mà người dùng yêu thích. Mỗi ứng dụng có thể cung cấp tối đa 5 cụm đề xuất cho mỗi người dùng.
Cụm Tiếp tục giúp người dùng tiếp tục nội dung đang xem dở, chẳng hạn như một bộ phim hoặc sách điện tử chưa xem hết, trong một nhóm giao diện người dùng duy nhất chứa nội dung từ nhiều ứng dụng.
Cụm Nổi bật có thể làm nổi bật nội dung chủ chốt của bạn trong một cụm nhiều ứng dụng bằng cách sử dụng một mẫu giao diện người dùng lớn hơn và cao cấp hơn.

Chúng ta sẽ tạo một cụm Đề xuất cho cả nội dung read và watch.

Trong ứng dụng mẫu read, hãy chuyển đến tệp GetRecommendationClusters.java. Tệp này cho thấy ví dụ về cách tạo cụm Đề xuất.

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();

Trong ứng dụng mẫu watch, hãy chuyển đến tệp ClusterRequestFactory.kt. Tệp này cho thấy ví dụ về cách tạo cụm Đề xuất.

// 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. Xuất bản cụm đề xuất

Cho đến giờ, chúng ta đã tìm hiểu cách tạo một Thực thể và cách nhóm các Thực thể này thành một Cụm. Bước tiếp theo là tìm hiểu cách xuất bản cụm đó.

AppEngagePublishClient chịu trách nhiệm kết nối để xuất bản cụm.

Bước 1: Khởi động ứng dụng.

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

// Kotlin version
val client = AppEngagePublishClient(context)

Bước 2: Tạo yêu cầu xuất bản cụm

Trong ứng dụng mẫu read, hãy kiểm tra phương thức setRecommendations trong EngageServiceWorker.java

// 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();

Trong ứng dụng mẫu watch, hãy kiểm tra phương thức constructRecommendationClustersRequest trong ClusterRequestFactory.kt

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

Bước 3: Gọi phương thức publishRecommendationClusters trong AppEngagePublishClient

Trong ứng dụng mẫu read, hãy kiểm tra phương thức setRecommendations trong EngageServiceWorker.java

client.publishRecommendationClusters(publishRequest);

Trong ứng dụng mẫu watch, hãy kiểm tra phương thức publishRecommendations trong EngageServiceWorker.kt

client.publishRecommendationClusters(request)

Sử dụng API isServiceAvailable

Trước khi gọi API xuất bản, bạn phải gọi isServiceAvailable để đảm bảo hệ thống cho phép xuất bản.

Trong ứng dụng mẫu read, hãy kiểm tra phương thức startWork trong EngageServiceWorker.java

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.
    }
}

Trong ứng dụng mẫu watch, hãy kiểm tra phương thức doWork trong EngageServiceWorker.kt

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. Trạng thái xuất bản

Bạn nên dùng API updatePublishStatus để cho biết lý do nội dung không được xuất bản. Việc này giúp Google tránh cảnh báo sai khi ứng dụng của bạn cố ý không xuất bản nội dung, hướng dẫn người dùng thực hiện các biện pháp khắc phục để truy cập vào nội dung của bạn, đồng thời cung cấp thông tin chi tiết cho bạn về tình trạng xuất bản nội dung.

Hãy xem trang web dành cho nhà phát triển để biết mã trạng thái. Ví dụ: nếu không có nội dung nào xuất hiện vì người dùng cần đăng nhập, hãy sử dụng mã NOT_PUBLISHED_REQUIRES_SIGN_IN. Chúng ta sẽ áp dụng mã này trong bước tiếp theo.

Trong ứng dụng mẫu read, hãy kiểm tra phương thức publishAndSetResult trong EngageServiceWorker.kt

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);
            })

Trong ứng dụng mẫu watch, hãy kiểm tra phương thức publishUserAccountManagement trong EngageServiceWorker.kt

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 và ý định truyền tin

Work Manager

Bạn nên thực thi tác vụ xuất bản nội dung trong nền (bằng WorkManager). Lên lịch thường xuyên (ví dụ: hằng ngày) và/hoặc dựa trên các sự kiện của người dùng (ví dụ: khi ứng dụng mở ra hoặc sau khi người dùng kết thúc một phiên đọc). Các ví dụ bên dưới tập trung vào một tác vụ xuất bản được lên lịch.

Trong ứng dụng mẫu read, queuePeriodicSetEngageStateWorker trong tệp SetEngageState.java cho thấy ví dụ về cách thiết lập 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);

Trong ứng dụng mẫu watch, periodicallyCallEngageServiceWorker trong Publisher.kt cho thấy ví dụ về cách thiết lập 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
)

Ý định truyền tin

Ngoài việc thực hiện lệnh gọi API xuất bản nội dung thông qua một tác vụ, bạn cũng phải thiết lập BroadcastReceiver để nhận yêu cầu xuất bản nội dung.

Mục tiêu của ý định truyền tin chủ yếu là để kích hoạt lại ứng dụng và buộc đồng bộ hoá dữ liệu. Ý định truyền tin không được thiết kế để gửi quá thường xuyên. Lệnh này chỉ được kích hoạt khi Dịch vụ Engage xác định nội dung có thể đã lỗi thời (ví dụ: một tuần trước). Bằng cách đó, bạn có thể yên tâm hơn rằng người dùng sẽ có trải nghiệm nội dung mới mẻ, ngay cả khi ứng dụng không được dùng trong một thời gian dài.

Bạn phải thiết lập BroadcastReceiver theo 2 cách sau đây:

Tự động đăng ký một thực thể của lớp BroadcastReceiver bằng cách sử dụng Context.registerReceiver(). Việc này cho phép giao tiếp từ các ứng dụng vẫn còn trong bộ nhớ.

Mở tệp MainActivity.java trong ứng dụng mẫu read để kiểm tra những nội dung sau đây:

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);
  }

Khai báo tĩnh quá trình triển khai bằng thẻ <receiver> trong tệp AndroidManifest.xml. Việc này cho phép ứng dụng nhận được ý định truyền tin khi ứng dụng không chạy, đồng thời cho phép ứng dụng xuất bản nội dung đó.

Mở tệp AndroidManifest.xml trong ứng dụng mẫu read để kiểm tra những nội dung sau đây:

<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>

Dịch vụ sẽ gửi các ý định sau đây:

com.google.android.engage.action.PUBLISH_RECOMMENDATION Bạn nên bắt đầu lệnh gọi publishRecommendationClusters khi nhận được ý định này.
com.google.android.engage.action.PUBLISH_FEATURED Bạn nên bắt đầu lệnh gọi publishFeaturedCluster khi nhận được ý định này.
com.google.android.engage.action.PUBLISH_CONTINUATION Bạn nên bắt đầu lệnh gọi publishContinuationCluster khi nhận được ý định này.

8. Dùng ứng dụng xác minh để kiểm thử

Tải và dùng ứng dụng xác minh để xác minh quá trình tích hợp

Ứng dụng xác minh sẽ hiển thị từng cụm dưới dạng một hàng riêng biệt.

Nhập tên gói đang xuất bản dữ liệu.

Xác minh rằng tất cả các thực thể trong cụm đã được phát hành.

Xác minh rằng tất cả các trường trong thực thể đều được phát hành. Đối với mỗi mục trong hàng, nhà phát triển có thể nhấp vào hình ảnh áp phích để xác minh ý định.

Xác minh luồng ý định truyền tin

Khi dùng ứng dụng xác minh để xác minh ý định truyền tin, hãy nhấp vào nút ở đầu giao diện người dùng để kích hoạt logic truyền tin.

9. Xin chúc mừng

Giờ đây, bạn đã biết cách thêm Engage SDK vào ứng dụng Android.

Để biết thêm thông tin chi tiết, hãy xem hướng dẫn cho nhà phát triển về Engage SDK và Trang web dành cho doanh nghiệp.

Tài nguyên

Dựa trên loại nội dung đang được xuất bản, SDK này chứa nhiều loại lớp Thực thể. Bạn có thể xem danh sách các thực thể có sẵn trong hướng dẫn tích hợp cho từng ngành dọc nêu bên dưới –

Lớp học lập trình về Engage SDK Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.