Nguyên tắc phát hành Engage SDK Cluster

Hướng dẫn này bao gồm bộ nguyên tắc về việc xuất bản cụm mà nhà phát triển có thể dùng khi tích hợp với Engage SDK.

Cụm đề xuất

Tiêu đề cụm

Bạn nên cung cấp tiêu đề cụm duy nhất và phù hợp để đem đến cho người dùng thông tin chi tiết hơn về nội dung của cụm.

Sau đây là một số ví dụ về các tiêu đề cụm phù hợp dựa trên nội dung:

  • Cụm liên quan đến hoạt động mua sắm
    • Ưu đãi chớp nhoáng
    • Mặt hàng phải mua hằng tuần
    • Liên quan đến giao dịch mua Pixel Buds
    • Giày đi mưa nữ
  • Cụm sách về sức khoẻ
    • Sức khỏe, tinh thần và cơ thể
    • Đề xuất liên quan đến sức khoẻ dành cho bạn
    • Bán chạy nhất về nội dung thể dục

Nội dung cụm

Khi phát hành cụm đề xuất, nhà phát triển phải cân nhắc xem người dùng đã đăng nhập vào ứng dụng của nhà phát triển hay chưa.

Khi người dùng đã đăng nhập

Nếu người dùng đã đăng nhập vào ứng dụng của nhà phát triển, bạn nên xuất bản các cụm nội dung được cá nhân hoá hoặc nội dung do người dùng tạo. Vì nội dung do người dùng tạo và nội dung được cá nhân hoá có liên quan hơn đến người dùng, nên khả năng cao là người dùng sẽ truy cập vào ứng dụng của nhà phát triển trên nền tảng Google.

  • Bạn có thể phát hành các đề xuất được cá nhân hoá.
    • Dưới đây là một số ví dụ về các đề xuất được cá nhân hoá:
      • Các lựa chọn hàng đầu dựa trên danh sách video đã xem của người dùng.
      • Sách tương tự sách nằm trong danh sách các cuốn sách đã đọc của người dùng.
      • Các bài hát của nghệ sĩ mà người dùng yêu thích.
  • Bạn có thể phát hành các thư viện nội dung do người dùng tạo.
    • Dưới đây là một số ví dụ về thư viện nội dung do người dùng tạo:
      • Danh sách xem của người dùng trong ứng dụng của nhà phát triển.
      • Danh sách tự báo cáo về nghệ sĩ mà người dùng yêu thích trong ứng dụng của nhà phát triển.
Loại đề xuất Chiến lược làm mới nội dung Nguyên tắc làm mới nội dung
Các đề xuất được cá nhân hoá

Linh động

Bạn nên cập nhật các đề xuất một lần mỗi ngày để người dùng có thể thấy các đề xuất mới hằng ngày.

 Vì người dùng không có kỳ vọng chính xác về nội dung đề xuất, nên chiến lược làm mới nội dung có thể linh động.
Thư viện nội dung do người dùng tạo

Nghiêm ngặt

Bạn nên cập nhật thư viện nội dung khi người dùng thoát khỏi ứng dụng của nhà phát triển.

 Điều quan trọng là nội dung này phải đồng bộ với dữ liệu hiện trên các nền tảng của Google. Nguyên nhân là do không giống như các đề xuất được cá nhân hoá, người dùng mong đợi một nhóm nội dung chính xác. Mọi sự chậm trễ đáng kể trong quá trình phát hành đều sẽ khiến người dùng nhầm lẫn. Do đó, chiến lược làm mới nội dung phải nghiêm ngặt.

Khi người dùng chưa đăng nhập

Nếu người dùng chưa đăng nhập vào ứng dụng của nhà phát triển, thì bạn vẫn nên xuất bản các cụm đề xuất để khuyến khích người dùng truy cập vào ứng dụng của nhà phát triển trên nền tảng của Google.

  • Bạn nên xuất bản các cụm đề xuất không được các nhân hoá.
    • Dưới đây là một số ví dụ về đề xuất không được cá nhân hoá:
      • 10 cuốn sách được đọc nhiều nhất trong năm nay.
      • Các bộ phim mới phát hành.
      • Các podcast thịnh hành.
  • Xuất bản một thẻ đăng nhập.
    • Để khuyến khích người dùng đăng nhập vào ứng dụng của nhà phát triển, nhà phát triển có thể chọn xuất bản một thẻ đăng nhập cùng với cụm đề xuất không được cá nhân hoá. Hãy xem phần bên dưới để biết thêm chi tiết về cách xuất bản Thẻ đăng nhập.
Loại đề xuất Chiến lược làm mới nội dung Nguyên tắc làm mới nội dung
Các đề xuất không được cá nhân hóa

Linh động

Bạn nên cập nhật các đề xuất một lần mỗi ngày.

 Vì người dùng không có kỳ vọng chính xác về nội dung đề xuất, nên chiến lược làm mới nội dung có thể linh động.
Thẻ đăng nhập trong các đề xuất

Nghiêm ngặt

Bạn nên cập nhật trạng thái thẻ đăng nhập khi người dùng thoát khỏi ứng dụng của nhà phát triển.

Sau khi người dùng đăng nhập, nhà phát triển phải xoá thẻ đó bằng cách gọi API deleteUserManagementCluster().

Điều quan trọng là trạng thái đăng nhập phải đồng bộ với nền tảng của Google. Người dùng sẽ bị nhầm lẫn khi thấy thẻ đăng nhập trên nền tảng của Google khi họ đã đăng nhập. Do đó, chiến lược làm mới nội dung phải nghiêm ngặt.

Cụm Tiếp tục

Khi phát hành các cụm tiếp tục (continuation cluster), nhà phát triển phải cân nhắc xem người dùng đã đăng nhập vào ứng dụng của nhà phát triển hay chưa.

Khi người dùng đã đăng nhập

  • Nhà phát triển cần phải phát hành các cụm tiếp tục do người dùng tạo.
    • Dưới đây là một số ví dụ về các cụm tiếp tục do người dùng tạo:
      • Tiếp tục Xem từ nơi người dùng đã dừng lại.
      • Tiếp tục Đọc từ nơi người dùng đã dừng lại.
Loại cụm tiếp tục Chiến lược làm mới nội dung Nguyên tắc làm mới nội dung
Các cụm tiếp tục do người dùng tạo

Nghiêm ngặt

Bạn nên cập nhật thư viện nội dung khi người dùng thoát khỏi ứng dụng của nhà phát triển.

 Điều quan trọng là nội dung này phải đồng bộ với dữ liệu hiện trên các nền tảng của Google. Nguyên nhân là do không giống như các đề xuất được cá nhân hoá, người dùng mong đợi một nhóm nội dung chính xác. Mọi sự chậm trễ đáng kể trong quá trình phát hành đều sẽ khiến người dùng nhầm lẫn. Do đó, chiến lược làm mới nội dung phải nghiêm ngặt.

Khi người dùng chưa đăng nhập

Hành trình liên tục chủ yếu dành cho người dùng đã đăng nhập. Tuy nhiên, bạn cũng có thể xuất bản cụm liên tục cho người dùng đã đăng xuất nếu ứng dụng của bạn hỗ trợ phiên khách.

Cụm Quản lý người dùng

Mục đích chính của cụm Quản lý người dùng là nhắc người dùng thực hiện một số thao tác nhất định trên ứng dụng của nhà cung cấp. Thao tác đăng nhập sẽ đưa người dùng đến trang đăng nhập của ứng dụng để ứng dụng có thể xuất bản nội dung (hoặc cung cấp nội dung phù hợp hơn cho cá nhân)

Thẻ đăng nhập

Thuộc tính Yêu cầu Nội dung mô tả
URI hành động Bắt buộc Đường liên kết sâu đến hành động (chẳng hạn như điều hướng đến trang đăng nhập ứng dụng)
Ảnh Không bắt buộc – Nếu không cung cấp thì bạn phải cung cấp Tiêu đề

Hình ảnh hiện trên thẻ

Hình ảnh có tỷ lệ khung hình 16x9 với độ phân giải 1264x712
Tiêu đề Không bắt buộc – Nếu không cung cấp thì bạn phải cung cấp Hình ảnh Tiêu đề trên thẻ
Văn bản hành động Không bắt buộc Văn bản hiện trên CTA (chẳng hạn như Đăng nhập)
Phụ đề Không bắt buộc Phụ đề không bắt buộc trên thẻ

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

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

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

Sau khi người dùng đăng nhập, nhà phát triển phải xoá thẻ đó bằng cách gọi API deleteUserManagementCluster().

Cập nhật trạng thái xuất bản

Nếu vì một lý do kinh doanh nội bộ bất kỳ mà không có cụm nào được xuất bản, bạn nên cập nhật trạng thái xuất bản bằng cách sử dụng API updatePublishStatus. Việc này quan trọng vì:

  • Trong mọi trường hợp, ngay cả khi nội dung được xuất bản (STATUS == PUBLISHED), bạn phải cho biết trạng thái để điền trang tổng quan. Trạng thái rõ ràng này sẽ được trang tổng quan sử dụng để truyền tải tình trạng và các chỉ số khác của quá trình tích hợp.
  • Nếu không có nội dung nào được xuất bản nhưng trạng thái tích hợp không phải là bị lỗi (STATUS == NOT_PUBLISHED), Google có thể tránh kích hoạt cảnh báo trong trang tổng quan về tình trạng của ứng dụng. Phương thức này xác nhận rằng nội dung chưa được xuất bản do tình huống dự kiến theo quan điểm của nhà cung cấp.
  • Theo đó, nhà phát triển có thể cung cấp thông tin chi tiết về thời điểm công bố hoặc không công bố dữ liệu.
  • Google có thể sử dụng các mã trạng thái nhắc người dùng thực hiện một số thao tác trong ứng dụng để họ có thể xem hoặc bỏ qua nội dung ứng dụng.

Dưới đây là danh sách mã trạng thái xuất bản đủ điều kiện:

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

Nếu nội dung chưa được xuất bản do người dùng chưa đăng nhập, thì bạn nên xuất bản Thẻ đăng nhập. Nếu vì một lý do bất kỳ mà nhà cung cấp không thể xuất bản Thẻ đăng nhập, bạn nên gọi API updatePublishStatus kèm theo mã trạng thái NOT_PUBLISHED_REQUIRES_SIGN_IN

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

WorkManager dành cho việc xuất bản cụm

Bạn nên sử dụng WorkManager để xuất bản các cụm đề xuất vì đây là giải pháp nên dùng cho công việc trong nền khi việc thực thi phải vừa mang tính cơ hội vừa được đảm bảo.

  • WorkManager thực hiện công việc trong nền sớm nhất có thể.
  • WorkManager xử lý logic để bắt đầu công việc theo nhiều điều kiện, ngay cả khi người dùng rời khỏi ứng dụng của bạn.

Khi người dùng rời khỏi ứng dụng, bạn nên bắt đầu một công việc trong nền mà phát hành các cụm tiếp tục cùng với các cụm đề xuất. Một vị trí tốt để xử lý logic này là Activity.onStop(), (được gọi khi người dùng rời khỏi ứng dụng).

Bạn nên sử dụng PeriodicWorkRequest để lên lịch công việc định kỳ là phát hành các cụm 24 giờ một lần. Bằng cách áp dụng chính sách CANCEL_AND_REENQUEUE để kích hoạt công việc, nhà phát triển có thể đảm bảo rằng WorkManager gửi dữ liệu cập nhật mỗi khi người dùng rời khỏi ứng dụng. Điều này giúp người dùng không nhìn thấy dữ liệu lỗi thời.

Ví dụ sau minh hoạ việc này:

// Define the PublishClusters Worker requiring input
public class PublishClusters extends Worker {

   public PublishClusters(Context appContext, WorkerParameters workerParams) {
       super(appContext, workerParams);
   }

   @NonNull
   @Override
   public Result doWork() {
       // publish clusters
   }
   ...
}

public static void schedulePublishClusters(Context appContext) {
// Create a PeriodicWorkRequest to schedule a recurring job to update
// clusters at a regular interval
PeriodicWorkRequest publishClustersEntertainmentSpace =
// Define the time for the periodic job
       new PeriodicWorkRequest.Builder(PublishClusters.class, 24, TimeUnit.HOURS)
// Set up a tag for the worker.
// Tags are Unique identifier, which can be used to identify that work
// later in order to cancel the work or observe its progress.
          .addTag("Publish Clusters to Entertainment Space")
          .build();

// Trigger Periodic Job, this will ensure that the periodic job is triggered
// only once since we have defined a uniqueWorkName
WorkManager.getInstance(appContext).enqueueUniquePeriodicWork(
// uniqueWorkName
     "publishClustersEntertainmentSpace",
// If a work with the uniqueWorkName is already running, it will cancel the
// existing running jobs and replace it with the new instance.
// ExistingPeriodicWorkPolicy#CANCEL_AND_REENQUEUE
     ExistingPeriodicWorkPolicy.CANCEL_AND_REENQUEUE,
// Recurring Work Request
publishClustersEntertainmentSpace);

}

Xử lý ý định truyền tin

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

Tuy nhiên, các nhà phát triển phải cẩn thận để không chỉ dựa vào thông báo truyền tin, vì các thông báo này chỉ được kích hoạt trong một số trường hợp nhất định – chủ yếu để kích hoạt lại ứng dụng và buộc đồng bộ hoá dữ liệu. Chúng chỉ được kích hoạt khi Dịch vụ Engage xác định rằng nội dung có thể đã lỗi thời. 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 sử dụng trong một thời gian dài.

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

  • Tự động đăng ký một thực thể của lớp BroadcastReceiver bằng cách sử dụng Context.registerReceiver(). Điều này cho phép giao tiếp từ các ứng dụng vẫn còn trong bộ nhớ.
  • Khai báo tĩnh quá trình triển khai bằng thẻ <receiver> trong tệp AndroidManifest.xml. Điều 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 phát hành nội dung đó.