Engage SDK Shopping: Hướng dẫn tích hợp kỹ thuật của bên thứ ba

Google đang xây dựng một nền tảng trên thiết bị giúp sắp xếp các ứng dụng của người dùng theo ngành dọc, đồng thời đem lại trải nghiệm mới mẻ và chân thực để người dùng khám phá và xem nội dung ứng dụng được cá nhân hoá. Trải nghiệm toàn màn hình này giúp các đối tác nhà phát triển có cơ hội giới thiệu nội dung đa dạng thức hay nhất của họ trên một kênh riêng bên ngoài ứng dụng của họ.

Hướng dẫn này cung cấp cho các đối tác nhà phát triển thông tin về cách tích hợp nội dung mua sắm của họ, sử dụng Engage SDK để điền dữ liệu cho cả khu vực nền tảng mới này và các nền tảng hiện có của Google như Entertainment Space.

Thông tin chi tiết về quy trình tích hợp

Thuật ngữ

Quy trình tích hợp này gồm 5 loại cụm sau: Đề xuất, Nổi bật, Giỏ hàng, Danh sách mua sắm, Đặt hàng lại và Theo dõi đơn đặt hàng mua sắm.

• Cụm Đề xuất hiển thị các đề xuất liên quan đến mua sắm cho từng cá nhân từ từng đối tác nhà phát triển. Những đề xuất này có thể dành riêng cho từng người dùng hoặc cho tất cả người dùng (ví dụ: các mặt hàng thịnh hành). Hãy sử dụng những đề xuất này để hiện sản phẩm, sự kiện, chương trình giảm giá, khuyến mãi, gói thuê bao khi bạn thấy phù hợp.

  Các đề xuất của bạn có cấu trúc như sau:

  • Cụm Đề xuất: Khung hiển thị giao diện người dùng chứa một nhóm các đề xuất từ cùng một đối tác nhà phát triển.

  • ShoppingEntity: Đối tượng đại diện cho một mặt hàng trong một cụm.

• Cụm Nổi bật hiển thị một số thực thể được chọn từ nhiều đối tác nhà phát triển trong một nhóm giao diện người dùng. Sẽ có một cụm Nổi bật duy nhất xuất hiện gần đầu giao diện người dùng và có vị trí ưu tiên phía trên tất cả các cụm Đề xuất. Mỗi đối tác nhà phát triển sẽ được phép thông báo về tối đa 10 thực thể trong cụm Nổi bật.

• Cụm Giỏ hàng cho phép bạn xem trước giỏ hàng của nhiều đối tác nhà phát triển trong một nhóm giao diện người dùng, nhắc họ hoàn tất giỏ hàng chưa thanh toán. Có một cụm Giỏ hàng duy nhất xuất hiện ở gần đầu giao diện người dùng và có vị trí ưu tiên phía trên tất cả các cụm Đề xuất. Mỗi đối tác nhà phát triển được phép thông báo về tối đa 3 thực thể ShoppingCart trong cụm Giỏ hàng.

  Giỏ hàng của bạn có cấu trúc như sau:

  • Cụm Giỏ hàng: Khung hiển thị giao diện người dùng chứa một nhóm bản xem trước giỏ hàng của nhiều đối tác nhà phát triển.

  • ShoppingCart: Đối tượng đại diện cho bản xem trước giỏ hàng của một đối tác nhà phát triển và hiển thị trong cụm Giỏ hàng. ShoppingCart phải cho thấy tổng số mặt hàng trong giỏ hàng và cũng có thể đưa hình ảnh của một số mặt hàng vào giỏ hàng của người dùng.

• Cụm Danh sách mua sắm cho phép xem trước danh sách mua sắm của nhiều đối tác nhà phát triển trong một nhóm giao diện người dùng, nhắc người dùng quay lại ứng dụng tương ứng để cập nhật và hoàn tất danh sách. Có duy nhất một cụm Danh sách mua sắm.

• Cụm Đặt hàng lại cho phép xem trước các đơn đặt hàng trước đây từ nhiều đối tác nhà phát triển trong một nhóm giao diện người dùng, nhắc người dùng đặt hàng lại. Có duy nhất một cụm Đặt hàng lại.

  • Cụm Đặt hàng lại phải hiện tổng số mặt hàng trong đơn đặt hàng trước đây của người dùng và cũng phải đưa vào một trong các mục sau:

    • Hình ảnh của X mặt hàng trong đơn đặt hàng trước đây của người dùng.
    • Nhãn của các mặt hàng X trong đơn đặt hàng trước đây của người dùng.

• Cụm Theo dõi đơn đặt hàng mua sắm cho phép xem trước các đơn đặt hàng mua sắm đang chờ xử lý hoặc đã hoàn tất gần đây của nhiều đối tác nhà phát triển trong một nhóm giao diện người dùng, cho phép người dùng theo dõi đơn đặt hàng của họ.

  Có một cụm ShoppingOrderTracking duy nhất xuất hiện gần đầu giao diện người dùng và có vị trí ưu tiên phía trên tất cả các cụm Đề xuất. Mỗi đối tác nhà phát triển được phép thông báo về nhiều mục ShoppingOrderTrackingEntity trong cụm Theo dõi đơn đặt hàng trên Mua sắm.

  • ShoppingOrderTrackingCluster của bạn có cấu trúc như sau:

    • Cụm Theo dõi đơn đặt hàng: Khung hiển thị giao diện người dùng chứa một nhóm bản xem trước tính năng theo dõi đơn đặt hàng của nhiều đối tác nhà phát triển
    • ShoppingOrderTrackingEntity: Đối tượng đại diện cho bản xem trước tính năng theo dõi đơn đặt hàng mua sắm của một đối tác nhà phát triển và hiển thị trong cụm Theo dõi đơn đặt hàng mua sắm. ShoppingOrderTrackingEntity phải cho thấy trạng thái của đơn đặt hàng và thời gian đặt hàng. Bạn nên điền thời gian giao hàng dự kiến cho ShoppingOrderTrackingEntity, vì thông tin này sẽ hiển thị cho người dùng khi được cung cấp.

Chuẩn bị trước

Cấp độ API tối thiểu: 19

Thêm thư viện com.google.android.engage:engage-core vào ứng dụng của bạn:

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

Để biết thêm thông tin, hãy xem bài viết Chế độ hiển thị gói trong Android 11.

Tóm tắt

Thiết kế này dựa trên việc triển khai dịch vụ ràng buộc.

Dữ liệu mà ứng dụng có thể phát hành phải tuân theo các giới hạn sau cho các loại cụm khác nhau:

Bước 1: Cung cấp dữ liệu về thực thể

SDK đã xác định các thực thể khác nhau để đại diện cho từng loại mục. Sau đây là các thực thể được hỗ trợ cho danh mục Mua sắm:

1. ShoppingEntity
2. ShoppingCart
3. ShoppingList
4. Reorder
5. ShoppingOrderTracking

Các biểu đồ bên dưới nêu ra các thuộc tính có sẵn và yêu cầu cho từng loại.

ShoppingEntity

Đối tượng ShoppingEntity đại diện cho một sản phẩm, chương trình khuyến mãi, ưu đãi, gói thuê bao hoặc sự kiện mà các đối tác nhà phát triển muốn phát hành.

ShoppingEntity

ShoppingCart

ShoppingList

ShoppingReorderCluster

ShoppingOrderTrackingCluster

Thông số kỹ thuật của hình ảnh

Dưới đây là thông số kỹ thuật bắt buộc cho thành phần hình ảnh:

Định dạng tệp

PNG, JPG, GIF tĩnh, WebP

Kích thước tệp tối đa

5120 KB

Đề xuất khác

• Khu vực an toàn cho hình ảnh: Đặt nội dung quan trọng của bạn vào phần chiếm 80% trung tâm của hình ảnh.
• Sử dụng nền trong suốt để hình ảnh có thể hiển thị chính xác trong phần cài đặt Giao diện sáng và tối.

Bước 2: Cung cấp dữ liệu Cụm

Bạn nên thực hiện tác vụ xuất bản nội dung trong nền (ví dụ: sử dụng WorkManager) và lên lịch thường xuyên hoặc theo sự kiện (ví dụ: mỗi khi người dùng mở ứng dụng hoặc khi người dùng vừa thêm mặt hàng nào vào giỏ hàng).

AppEngageShoppingClient chịu trách nhiệm xuất bản các cụm mua sắm.

Các API sau sẽ hiện để xuất bản cụm trong ứng dụng:

• isServiceAvailable
• publishRecommendationClusters
• publishFeaturedCluster
• publishShoppingCart
• publishShoppingCarts
• publishShoppingList
• publishShoppingReorderCluster
• publishShoppingOrderTrackingCluster
• publishUserAccountManagementRequest
• updatePublishStatus
• deleteRecommendationsClusters
• deleteFeaturedCluster
• deleteShoppingCartCluster
• deleteShoppingListCluster
• deleteShoppingReorderCluster
• deleteShoppingOrderTrackingCluster
• deleteUserManagementCluster
• deleteClusters

isServiceAvailable

API này được dùng để kiểm tra xem dịch vụ có thể tích hợp và nội dung có hiện trên thiết bị hay không.

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

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 này được dùng để phát hành danh sách đối tượng RecommendationCluster.

Đối tượng RecommendationCluster có thể có các thuộc tính sau:

client.publishRecommendationClusters(
            PublishRecommendationClustersRequest.Builder()
                .addRecommendationCluster(
                    RecommendationCluster.Builder()
                        .addEntity(entity1)
                        .addEntity(entity2)
                        .setTitle("Black Friday Deals")
                        .build())
                .build())

client.publishRecommendationClusters(
            new PublishRecommendationClustersRequest.Builder()
                .addRecommendationCluster(
                    new RecommendationCluster.Builder()
                        .addEntity(entity1)
                        .addEntity(entity2)
                        .setTitle("Black Friday Deals")
                        .build())
                .build());

Khi dịch vụ nhận được yêu cầu, các hành động sau đây sẽ diễn ra trong một giao dịch:

• Mọi dữ liệu hiện có về cụm Đề xuất đều bị xoá.
• Dữ liệu từ yêu cầu được phân tích cú pháp và lưu trữ trong cụm Đề xuất mới.

Trong trường hợp xảy ra lỗi, toàn bộ yêu cầu sẽ bị từ chối và trạng thái hiện tại sẽ được duy trì.

publishFeaturedCluster

API này được dùng để phát hành đối tượng FeaturedCluster.

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

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

Khi dịch vụ nhận được yêu cầu, các hành động sau đây sẽ diễn ra trong một giao dịch:

• Dữ liệu FeaturedCluster hiện có của đối tác nhà phát triển sẽ bị xoá.
• Dữ liệu của yêu cầu được phân tích cú pháp và lưu trữ trong cụm Nổi bật đã cập nhật.

Trong trường hợp xảy ra lỗi, toàn bộ yêu cầu sẽ bị từ chối và trạng thái hiện tại sẽ được duy trì.

publishShoppingCart

API này được dùng để phát hành đối tượng ShoppingCartCluster.

client.publishShoppingCart(
            PublishShoppingCartRequest.Builder()
                .setShoppingCart(
                    ShoppingCart.Builder()
                        ...
                        .build())
                .build())

client.publishShoppingCart(
            new PublishShoppingCartRequest.Builder()
                .setShoppingCart(
                    new ShoppingCart.Builder()
                        ...
                        .build())
                .build())

Khi dịch vụ nhận được yêu cầu, các hành động sau đây sẽ diễn ra trong một giao dịch:

• Dữ liệu ShoppingCart hiện có của đối tác nhà phát triển sẽ bị xoá.
• Dữ liệu của yêu cầu được phân tích cú pháp và lưu trữ trong cụm Giỏ hàng đã cập nhật.

Trong trường hợp xảy ra lỗi, toàn bộ yêu cầu sẽ bị từ chối và trạng thái hiện tại sẽ được duy trì.

publishShoppingCarts

API này dùng để phát hành nhiều đối tượng ShoppingCart. Điều này áp dụng cho đối tác nhà phát triển phát hành giỏ hàng riêng cho mỗi người bán. Thêm tên người bán vào tiêu đề khi sử dụng API này.

client.publishShoppingCarts(
            PublishShoppingCartClustersRequest.Builder()
                .addShoppingCart(
                    ShoppingCart.Builder()
                        ...
                        .build())
                .build())

client.publishShoppingCarts(
            new PublishShoppingCartClustersRequest.Builder()
                .addShoppingCart(
                    new ShoppingCart.Builder()
                        ...
                        .build())
                .build())

Khi dịch vụ nhận được yêu cầu, các hành động sau đây sẽ diễn ra trong một giao dịch:

• Dữ liệu ShoppingCart hiện có của đối tác nhà phát triển sẽ bị xoá.
• Dữ liệu của yêu cầu được phân tích cú pháp và lưu trữ trong cụm Giỏ hàng đã cập nhật.

Trong trường hợp xảy ra lỗi, toàn bộ yêu cầu sẽ bị từ chối và trạng thái hiện tại sẽ được duy trì.

publishShoppingList

API này được dùng để phát hành đối tượng FoodShoppingList.

client.publishFoodShoppingList(
            PublishFoodShoppingListRequest.Builder()
                .setFoodShoppingList(
                    FoodShoppingListEntity.Builder()
                        ...
                        .build())
                .build())

client.publishFoodShoppingList(
            new PublishFoodShoppingListRequest.Builder()
                .setFoodShoppingList(
                    new FoodShoppingListEntity.Builder()
                        ...
                        .build())
                .build());

Khi dịch vụ nhận được yêu cầu, các hành động sau đây sẽ diễn ra trong một giao dịch:

• Dữ liệu FoodShoppingList hiện có của đối tác nhà phát triển sẽ bị xoá.
• Dữ liệu của yêu cầu được phân tích cú pháp và lưu trữ trong cụm Danh sách mua sắm đã cập nhật.

Trong trường hợp xảy ra lỗi, toàn bộ yêu cầu sẽ bị từ chối và trạng thái hiện tại sẽ được duy trì.

publishShoppingReorderCluster

API này được dùng để phát hành đối tượng ShoppingReorderCluster.

client.publishShoppingReorderCluster(
            PublishShoppingReorderClusterRequest.Builder()
                .setReorderCluster(
                    ShoppingReorderCluster.Builder()
                        ...
                        .build())
                .build())

client.publishShoppingReorderCluster(
            new PublishShoppingReorderClusterRequest.Builder()
                .setReorderCluster(
                    new ShoppingReorderCluster.Builder()
                        ...
                        .build())
                .build());

Khi dịch vụ nhận được yêu cầu, các hành động sau đây sẽ diễn ra trong một giao dịch:

• Dữ liệu ShoppingReorderCluster hiện có của đối tác nhà phát triển sẽ bị xoá.
• Dữ liệu của yêu cầu được phân tích cú pháp và lưu trữ trong cụm Đặt hàng lại đã cập nhật.

Trong trường hợp xảy ra lỗi, toàn bộ yêu cầu sẽ bị từ chối và trạng thái hiện tại sẽ được duy trì.

publishShoppingOrderTrackingCluster

API này được dùng để phát hành đối tượng ShoppingOrderTrackingCluster.

client.publishShoppingOrderTrackingCluster(
            PublishShoppingOrderTrackingClusterRequest.Builder()
                .setShoppingOrderTrackingCluster(
                    ShoppingOrderTrackingCluster.Builder()
                        ...
                        .build())
                .build())

client.publishShoppingOrderTrackingCluster(
            new PublishShoppingOrderTrackingClusterRequest.Builder()
                .setShoppingOrderTrackingCluster(
                    new ShoppingOrderTrackingCluster.Builder()
                        ...
                        .build())
                .build());

Khi dịch vụ nhận được yêu cầu, các hành động sau đây sẽ diễn ra trong một giao dịch:

• Dữ liệu ShoppingOrderTrackingCluster hiện có của đối tác nhà phát triển sẽ bị xoá.
• Dữ liệu của yêu cầu được phân tích cú pháp và lưu trữ trong cụm Theo dõi đơn đặt hàng mua sắm đã cập nhật.

Trong trường hợp xảy ra lỗi, toàn bộ yêu cầu sẽ bị từ chối và trạng thái hiện tại sẽ được duy trì.

publishUserAccountManagementRequest

API này dùng để xuất bản thẻ Đăng nhậ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)

Siêu dữ liệu sau đây là một phần của Thẻ đăng nhập –

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

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

Khi dịch vụ nhận được yêu cầu, các hành động sau đây sẽ diễn ra trong một giao dịch:

• Dữ liệu UserAccountManagementCluster hiện có của đối tác nhà phát triển sẽ bị xoá.
• Dữ liệu của yêu cầu được phân tích cú pháp và lưu trữ trong cụm UserAccountManagementCluster đã cập nhật.

Trong trường hợp xảy ra lỗi, toàn bộ yêu cầu sẽ bị từ chối và trạng thái hiện tại sẽ được duy trì.

updatePublishStatus

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

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

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

deleteRecommendationClusters

API này dùng để xoá nội dung của cụm Recommendation (Đề xuất).

client.deleteRecommendationClusters()

client.deleteRecommendationClusters();

Khi nhận được yêu cầu, dịch vụ sẽ xoá dữ liệu hiện có khỏi cụm Đề xuất. Trong trường hợp xảy ra lỗi, toàn bộ yêu cầu sẽ bị từ chối và trạng thái hiện tại vẫn giữ nguyên.

deleteFeaturedCluster

API này dùng để xoá nội dung của cụm Featured (Nổi bật).

client.deleteFeaturedCluster()

client.deleteFeaturedCluster();

Khi nhận được yêu cầu, dịch vụ sẽ xoá dữ liệu hiện có khỏi cụm Nổi bật. Trong trường hợp xảy ra lỗi, toàn bộ yêu cầu sẽ bị từ chối và trạng thái hiện tại vẫn giữ nguyên.

deleteShoppingCartCluster

API này dùng để xoá nội dung của cụm Giỏ hàng.

client.deleteShoppingCartCluster()

client.deleteShoppingCartCluster();

Khi nhận được yêu cầu này, dịch vụ sẽ xoá dữ liệu hiện có khỏi cụm Giỏ hàng. Trong trường hợp xảy ra lỗi, toàn bộ yêu cầu sẽ bị từ chối và trạng thái hiện tại vẫn giữ nguyên.

deleteShoppingListCluster

API này dùng để xoá nội dung của cụm Danh sách mua sắm.

client.deleteShoppingListCluster()

client.deleteShoppingListCluster();

Khi nhận được yêu cầu, dịch vụ sẽ xoá dữ liệu hiện có khỏi cụm Danh sách mua sắm. Trong trường hợp xảy ra lỗi, toàn bộ yêu cầu sẽ bị từ chối và trạng thái hiện tại vẫn giữ nguyên.

deleteShoppingReorderCluster

API này dùng để xoá nội dung của cụm Đặt hàng lại trong danh mục Mua sắm.

client.deleteShoppingReorderCluster()

client.deleteShoppingReorderCluster();

Khi nhận được yêu cầu, dịch vụ sẽ xoá dữ liệu hiện có khỏi cụm Đặt hàng lại trong danh mục Mua sắm. Trong trường hợp xảy ra lỗi, toàn bộ yêu cầu sẽ bị từ chối và trạng thái hiện tại vẫn giữ nguyên.

deleteShoppingOrderTrackingCluster

API này dùng để xoá nội dung của cụm Theo dõi đơn đặt hàng trong danh mục Mua sắm.

client.deleteShoppingOrderTrackingCluster()

client.deleteShoppingOrderTrackingCluster();

Khi nhận được yêu cầu, dịch vụ sẽ xoá dữ liệu hiện có khỏi cụm Theo dõi đơn đặt hàng trong danh mục Mua sắm. Trong trường hợp xảy ra lỗi, toàn bộ yêu cầu sẽ bị từ chối và trạng thái hiện tại vẫn giữ nguyên.

deleteUserManagementCluster

API này dùng để xoá nội dung của cụm UserAccountManagement.

client.deleteUserManagementCluster()

client.deleteUserManagementCluster();

Khi nhận được yêu cầu, dịch vụ sẽ xoá dữ liệu hiện có khỏi cụm UserAccountManagement. Trong trường hợp xảy ra lỗi, toàn bộ yêu cầu sẽ bị từ chối và trạng thái hiện tại vẫn giữ nguyên.

deleteClusters

API này dùng để xoá nội dung của một loại cụm cụ thể.

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

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

Khi nhận được yêu cầu, dịch vụ sẽ xoá dữ liệu hiện có khỏi tất cả các cụm khớp với loại cụm đã chỉ định. Ứng dụng có thể chọn truyền một hoặc nhiều loại cụm. Trong trường hợp xảy ra lỗi, toàn bộ yêu cầu sẽ bị từ chối và trạng thái hiện tại sẽ được duy trì.

Xử lý lỗi

Bạn nên nghe kết quả tác vụ từ các API phát hành để có thể thực hiện thao tác tiếp theo nhằm khôi phục và gửi lại tác vụ thành công.

client.publishRecommendationClusters(
        PublishRecommendationClustersRequest.Builder()
          .addRecommendationCluster(..)
          .build())
      .addOnCompleteListener { task ->
        if (task.isSuccessful) {
          // do something
        } else {
          val exception = task.exception
          if (exception is AppEngageException) {
            @AppEngageErrorCode val errorCode = exception.errorCode
            if (errorCode == AppEngageErrorCode.SERVICE_NOT_FOUND) {
              // do something
            }
          }
        }
      }

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

Lỗi được trả về dưới dạng AppEngageException với nguyên nhân được đưa vào dưới dạng mã lỗi.

Bước 3: Xử lý ý định truyền tin

Ngoài việc thực hiện lệnh gọi API nội dung phát hành 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 phát hành 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 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ớ.

class AppEngageBroadcastReceiver : BroadcastReceiver(){
  // Trigger recommendation cluster publish when PUBLISH_RECOMMENDATION
  // broadcast is received
  // Trigger featured cluster publish when PUBLISH_FEATURED broadcast is
  // received
  // Trigger shopping cart cluster publish when PUBLISH_SHOPPING_CART broadcast
  // is received
  // Trigger shopping list cluster publish when PUBLISH_SHOPPING_LIST broadcast
  // is received
  // Trigger reorder cluster publish when PUBLISH_REORDER_CLUSTER broadcast is
  // received
  // Trigger shopping order tracking cluster publish when
  // PUBLISH_SHOPPING_ORDER_TRACKING_CLUSTER broadcast is received
}

fun registerBroadcastReceivers(context: Context){
  var  context = context
  context = context.applicationContext

// Register Recommendation Cluster Publish Intent
  context.registerReceiver(AppEngageBroadcastReceiver(),
                           IntentFilter(Intents.ACTION_PUBLISH_RECOMMENDATION))

// Register Featured Cluster Publish Intent
  context.registerReceiver(AppEngageBroadcastReceiver(),
                           IntentFilter(Intents.ACTION_PUBLISH_FEATURED))

// Register Shopping Cart Cluster Publish Intent
  context.registerReceiver(AppEngageBroadcastReceiver(),
                           IntentFilter(Intents.ACTION_PUBLISH_SHOPPING_CART))

// Register Shopping List Cluster Publish Intent
  context.registerReceiver(AppEngageBroadcastReceiver(),
                           IntentFilter(Intents.ACTION_PUBLISH_SHOPPING_LIST))

// Register Reorder Cluster Publish Intent
  context.registerReceiver(AppEngageBroadcastReceiver(),
                           IntentFilter(Intents.ACTION_PUBLISH_REORDER_CLUSTER))

// Register Shopping Order Tracking Cluster Publish Intent
  context.registerReceiver(AppEngageBroadcastReceiver(),
                           IntentFilter(Intents.ACTION_PUBLISH_SHOPPING_ORDER_TRACKING_CLUSTER))
}

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 shopping cart cluster publish when PUBLISH_SHOPPING_CART broadcast is
// received

// Trigger shopping list cluster publish when PUBLISH_SHOPPING_LIST broadcast is
// received

// Trigger reorder cluster publish when PUBLISH_REORDER_CLUSTER broadcast is
// received

// Trigger reorder cluster publish when PUBLISH_SHOPPING_ORDER_TRACKING_CLUSTER
// 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 Shopping Cart Cluster Publish Intent
context.registerReceiver(new AppEngageBroadcastReceiver(),
new IntentFilter(com.google.android.engage.shopping.service.Intents.ACTION_PUBLISH_SHOPPING_CART));

// Register Shopping List Cluster Publish Intent
context.registerReceiver(new AppEngageBroadcastReceiver(),
new IntentFilter(com.google.android.engage.shopping.service.Intents.ACTION_PUBLISH_SHOPPING_LIST));

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

// Register Shopping Order Tracking Cluster Publish Intent
context.registerReceiver(new AppEngageBroadcastReceiver(),
new IntentFilter(com.google.android.engage.shopping.service.Intents.ACTION_PUBLISH_SHOPPING_ORDER_TRACKING_CLUSTER));

}

• 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 xuất bản nội dung đó.

<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.shopping.PUBLISH_SHOPPING_CART" />
      </intent-filter>
      <intent-filter>
         <action android:name="com.google.android.engage.action.shopping.PUBLISH_SHOPPING_LIST" />
      </intent-filter>
      <intent-filter>
         <action android:name="com.google.android.engage.action.shopping.PUBLISH_REORDER_CLUSTER" />
      </intent-filter>
      <intent-filter>
         <action android:name="com.google.android.engage.action.shopping.PUBLISH_SHOPPING_ORDER_TRACKING_CLUSTER" />
      </intent-filter>
   </receiver>
</application>

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

• 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.shopping.PUBLISH_SHOPPING_CART Bạn nên bắt đầu lệnh gọi publishShoppingCart khi nhận được ý định này.
• com.google.android.engage.action.shopping.PUBLISH_SHOPPING_LIST Bạn nên bắt đầu lệnh gọi publishShoppingList khi nhận được ý định này.
• com.google.android.engage.action.shopping.PUBLISH_REORDER_CLUSTER Bạn nên bắt đầu lệnh gọi publishReorderCluster khi nhận được ý định này.
• com.google.android.engage.action.shopping.PUBLISH_SHOPPING_ORDER_TRACKING_CLUSTER Bạn nên bắt đầu lệnh gọi publishShoppingOrderTrackingCluster khi nhận được ý định này.

Quy trình tích hợp

Để được hướng dẫn từng bước về cách xác minh quy trình tích hợp sau khi hoàn tất, hãy xem Quy trình tích hợp dành cho nhà phát triển Engage.

Câu hỏi thường gặp

Hãy xem mục Câu hỏi thường gặp về Engage SDK để biết các câu hỏi thường gặp.

Liên hệ

Hãy liên hệ với engage-developers@google.com nếu bạn có câu hỏi trong quá trình tích hợp. Đội ngũ của chúng tôi sẽ phản hồi trong thời gian sớm nhất có thể.

Các bước tiếp theo

Sau khi bạn hoàn tất quá trình tích hợp này, các bước tiếp theo sẽ như sau:

• Gửi email đến engage-developers@google.com và đính kèm APK tích hợp sẵn sàng cho Google kiểm thử.
• Google sẽ xác minh và xem xét trong phạm vi nội bộ để đảm bảo quá trình tích hợp diễn ra như mong đợi. Nếu cần thay đổi, Google sẽ liên hệ với bạn để yêu cầu bạn cung cấp mọi thông tin chi tiết cần thiết.
• Khi quá trình kiểm thử hoàn tất và bạn không cần thay đổi gì, Google sẽ liên hệ với bạn để thông báo rằng bạn có thể bắt đầu xuất bản APK tích hợp mới nhất lên Cửa hàng Play.
• Sau khi Google xác nhận rằng APK mới nhất của bạn đã được phát hành lên Cửa hàng Play, các cụm Đề xuất, Nổi bật, Giỏ hàng, Danh sách mua sắm, Cụm đặt hàng lại và Cụm theo dõi đơn đặt hàng mua sắm có thể được xuất bản và người dùng có thể thấy chúng.