Tích hợp tính năng Xem tiếp trên Android TV

book_path: /distribute/other-docs/_book.yaml project_path: /distribute/other-docs/_project.yaml

Hướng dẫn này trình bày cách tích hợp tính năng Tiếp tục xem vào ứng dụng Android TV bằng Engage SDK.

Chuẩn bị trước

Hoàn thành hướng dẫn Công việc chuẩn bị trong hướng dẫn Bắt đầu sử dụng.

Tích hợp

Lưu ý: Continue Watching API (API Xem tiếp) hoạt động khác với Watch Next API (API Xem tiếp). Thay vì thêm hoặc xoá từng mục, mỗi lần cập nhật, danh sách này sẽ thay thế toàn bộ danh sách các mục "xem tiếp". Điều này có nghĩa là bạn cần gửi tất cả các mặt hàng mà bạn muốn đăng mỗi khi cập nhật. Bạn nên hiển thị nhiều thực thể nhất có thể trong hàng tiếp tục xem, nhưng không được quá 10. Ngoài ra, API mới kết hợp các bước xuất bản danh sách và các mục thành một bước, giúp đơn giản hoá quy trình. Xin lưu ý rằng Google TV có thể không hiển thị tất cả các mục mà bạn gửi, vì Google TV kết hợp danh sách từ nhiều ứng dụng.

Tạo 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. Cụm tiếp tục hỗ trợ các thực thể sau:

Chỉ định URI và hình ảnh áp phích dành riêng cho nền tảng cho các thực thể này.

Ngoài ra, hãy tạo URI phát cho từng nền tảng (chẳng hạn như Android TV, Android hoặc iOS) nếu bạn chưa tạo. Vì vậy, khi người dùng tiếp tục xem trên mỗi nền tảng, ứng dụng sẽ sử dụng một URI phát được nhắm đến để phát nội dung video.

// Required. Set this when you want continue watching entities to show up on
// Google TV
val playbackUriTv = PlatformSpecificUri.Builder()
    .setPlatformType(PlatformType.TYPE_ANDROID_TV)
    .setActionUri(Uri.parse("https://www.example.com/entity_uri_for_tv"))
    .build()

// Required. Set this when you want continue watching entities to show up on
// Google TV Android app, Entertainment Space, Playstore Widget
val playbackUriAndroid = PlatformSpecificUri.Builder()
    .setPlatformType(PlatformType.TYPE_ANDROID_MOBILE)
    .setActionUri(Uri.parse("https://www.example.com/entity_uri_for_android"))
    .build()

// Optional. Set this when you want continue watching entities to show up on
// Google TV iOS app
val playbackUriIos = PlatformSpecificUri.Builder()
    .setPlatformType(PlatformType.TYPE_IOS)
    .setActionUri(Uri.parse("https://www.example.com/entity_uri_for_ios"))
    .build()

val platformSpecificPlaybackUris =
    Arrays.asList(playbackUriTv, playbackUriAndroid, playbackUriIos)

Hình ảnh áp phích cần có URI và kích thước pixel (chiều cao và chiều rộng). Nhắm đến nhiều kiểu dáng bằng cách cung cấp nhiều hình ảnh áp phích, nhưng hãy xác minh rằng tất cả hình ảnh đều duy trì tỷ lệ khung hình 16:9 và chiều cao tối thiểu là 200 pixel để hiển thị chính xác thực thể "Xem tiếp", đặc biệt là trong Không gian giải trí của Google. Hình ảnh có chiều cao dưới 200 pixel có thể không xuất hiện.

val images = Arrays.asList(
    Image.Builder()
        .setImageUri(Uri.parse("http://www.example.com/entity_image1.png"))
        .setImageHeightInPixel(300)
        .setImageWidthInPixel(169)
        .build(),
    Image.Builder()
        .setImageUri(Uri.parse("http://www.example.com/entity_image2.png"))
        .setImageHeightInPixel(640)
        .setImageWidthInPixel(360)
        .build()
    // Consider adding other images for different form factors
)

MovieEntity

Ví dụ này cho thấy cách tạo MovieEntity với tất cả các trường bắt buộc:

val movieEntity = MovieEntity.Builder()
   .setWatchNextType(WatchNextType.TYPE_CONTINUE)
   .setName("Movie name")
   .addPlatformSpecificPlaybackUri(platformSpecificPlaybackUris)
   .addPosterImages(images)
   // Timestamp in millis for sample last engagement time 12/1/2023 00:00:00
   .setLastEngagementTimeMillis(1701388800000)
   // Suppose the duration is 2 hours, it is 72000000 in milliseconds
   .setDurationMills(72000000)
   // Suppose last playback offset is 1 hour, 36000000 in milliseconds
   .setLastPlayBackPositionTimeMillis(36000000)
   .build()

Khi bạn cung cấp các thông tin như thể loại và mức phân loại nội dung, Google TV có thể giới thiệu nội dung của bạn theo nhiều cách linh hoạt hơn và kết nối nội dung đó với những người xem phù hợp.

val genres = Arrays.asList("Action", "Science fiction")
val rating1 = RatingSystem.Builder().setAgencyName("MPAA").setRating("PG-13").build()
val contentRatings = Arrays.asList(rating1)
val movieEntity = MovieEntity.Builder()
    ...
    .addGenres(genres)
    .addContentRatings(contentRatings)
    .build()

Các thực thể sẽ tự động vẫn có sẵn trong 60 ngày, trừ phi bạn chỉ định thời gian hết hạn ngắn hơn. Chỉ đặt thời gian hết hạn tuỳ chỉnh nếu bạn cần xoá thực thể trước khoảng thời gian mặc định này.

// Set the expiration time to be now plus 30 days in milliseconds
val expirationTime = DisplayTimeWindow.Builder()
    .setEndTimestampMillis(now().toMillis()+2592000000).build()
val movieEntity = MovieEntity.Builder()
    ...
    .addAvailabilityTimeWindow(expirationTime)
    .build()

TvEpisodeEntity

Ví dụ này cho thấy cách tạo TvEpisodeEntity với tất cả các trường bắt buộc:

val tvEpisodeEntity = TvEpisodeEntity.Builder()
    .setWatchNextType(WatchNextType.TYPE_CONTINUE)
    .setName("Episode name")
    .addPlatformSpecificPlaybackUri(platformSpecificPlaybackUris)
    .addPosterImages(images)
    // Timestamp in millis for sample last engagement time 12/1/2023 00:00:00
    .setLastEngagementTimeMillis(1701388800000)
    .setDurationMills(72000000) // 2 hours in milliseconds
    // 45 minutes and 15 seconds in milliseconds is 2715000
    .setLastPlayBackPositionTimeMillis(2715000)
    .setEpisodeNumber("2")
    .setSeasonNumber("1")
    .setShowTitle("Title of the show")
    .build()

Chuỗi số tập (chẳng hạn như "2") và chuỗi số phần (chẳng hạn như "1") sẽ được mở rộng thành dạng thức phù hợp trước khi xuất hiện trên thẻ xem tiếp. Xin lưu ý rằng đây phải là một chuỗi số, đừng đặt "e2", "tập 2", "s1" hoặc "mùa 1".

Nếu một chương trình truyền hình cụ thể chỉ có một phần, hãy đặt số phần là 1.

Để tối đa hoá cơ hội cho người xem tìm thấy nội dung của bạn trên Google TV, hãy cân nhắc cung cấp thêm dữ liệu như thể loại, mức phân loại nội dung và khung giờ có sẵn, vì những thông tin này có thể cải thiện các lựa chọn hiển thị và lọc.

val genres = Arrays.asList("Action", "Science fiction")
val rating1 = RatingSystem.Builder().setAgencyName("MPAA").setRating("PG-13").build()
val contentRatings = Arrays.asList(rating1)
val tvEpisodeEntity = TvEpisodeEntity.Builder()
    ...
    .addGenres(genres)
    .addContentRatings(contentRatings)
    .setSeasonTitle("Season Title")
    .setShowTitle("Show Title")
    .build()

VideoClipEntity

Sau đây là ví dụ về cách tạo VideoClipEntity với tất cả các trường bắt buộc.

VideoClipEntity đại diện cho một đoạn video do người dùng tạo, chẳng hạn như video trên YouTube.

val videoClipEntity = VideoClipEntity.Builder()
    .setPlaybackUri(Uri.parse("https://www.example.com/uri_for_current_platform"))
    .setWatchNextType(WatchNextType.TYPE_CONTINUE)
    .setName("Video clip name")
    .addPlatformSpecificPlaybackUri(platformSpecificPlaybackUris)
    .addPosterImages(images)
    // Timestamp in millis for sample last engagement time 12/1/2023 00:00:00
    .setLastEngagementTimeMillis(1701388800000)
    .setDurationMills(600000) //10 minutes in milliseconds
    .setLastPlayBackPositionTimeMillis(300000) //5 minutes in milliseconds
    .addContentRating(contentRating)
    .build()

Bạn có thể tuỳ ý đặt người tạo, hình ảnh người tạo, thời gian tạo tính bằng mili giây hoặc khoảng thời gian có sẵn .

LiveStreamingVideoEntity

Sau đây là ví dụ về cách tạo một LiveStreamingVideoEntity với tất cả các trường bắt buộc.

val liveStreamingVideoEntity = LiveStreamingVideoEntity.Builder()
    .setPlaybackUri(Uri.parse("https://www.example.com/uri_for_current_platform"))
    .setWatchNextType(WatchNextType.TYPE_CONTINUE)
    .setName("Live streaming name")
    .addPlatformSpecificPlaybackUri(platformSpecificPlaybackUris)
    .addPosterImages(images)
    // Timestamp in millis for sample last engagement time 12/1/2023 00:00:00
    .setLastEngagementTimeMillis(1701388800000)
    .setDurationMills(72000000) //2 hours in milliseconds
    .setLastPlayBackPositionTimeMillis(36000000) //1 hour in milliseconds
    .addContentRating(contentRating)
    .build()

Bạn có thể tuỳ ý đặt thời gian bắt đầu, đài truyền hình, biểu tượng đài truyền hình hoặc khung thời gian có sẵn cho thực thể phát trực tiếp.

Để biết thông tin chi tiết về các thuộc tính và yêu cầu, hãy xem tài liệu tham khảo API.

Cung cấp dữ liệu cụm Tiếp tục

AppEngagePublishClient chịu trách nhiệm xuất bản cụm Tiếp tục. Bạn sử dụng phương thức publishContinuationCluste để xuất bản một đối tượng ContinuationCluster.

Đảm bảo bạn khởi động ứng dụng và kiểm tra xem dịch vụ có hoạt động hay không như mô tả trong Hướng dẫn bắt đầu.

client.publishContinuationCluster(
    PublishContinuationClusterRequest
        .Builder()
        .setContinuationCluster(
            ContinuationCluster.Builder()
                .setAccountProfile(accountProfile)
                .addEntity(movieEntity1)
                .addEntity(movieEntity2)
                .addEntity(tvEpisodeEntity1)
                .addEntity(tvEpisodeEntity2)
                .setSyncAcrossDevices(true)
                .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 ContinuationCluster 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 ContinuationCluster đã 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ì.

API xuất bản là các API chèn và cập nhật; sẽ thay thế nội dung hiện tại. Nếu cần cập nhật một thực thể cụ thể trong cụm tiếp tục, bạn sẽ cần xuất bản lại tất cả các thực thể.

Bạn chỉ nên cung cấp dữ liệu về cụm nội dung tiếp theo cho tài khoản người lớn. Chỉ xuất bản khi hồ sơ tài khoản thuộc về người lớn.

Đồng bộ hoá trên nhiều thiết bị

Cờ SyncAcrossDevices kiểm soát việc dữ liệu ContinuationCluster của người dùng có được đồng bộ hoá trên các thiết bị như TV, điện thoại, máy tính bảng, v.v. hay không. Theo mặc định, tính năng đồng bộ hoá trên nhiều thiết bị sẽ bị tắt.

Giá trị:

true: Dữ liệu cụm tiếp tục được chia sẻ trên tất cả các thiết bị của người dùng để mang lại trải nghiệm xem liền mạch. Bạn nên dùng lựa chọn này để có trải nghiệm tốt nhất trên nhiều thiết bị.
false: Dữ liệu cụm tiếp tục chỉ được phép lưu trữ trên thiết bị hiện tại.

Yêu cầu đồng ý

Ứng dụng đa phương tiện phải cung cấp một chế độ cài đặt rõ ràng để bật hoặc tắt tính năng đồng bộ hoá trên nhiều thiết bị. Giải thích lợi ích cho người dùng, lưu lựa chọn ưu tiên của người dùng một lần và áp dụng lựa chọn đó trong publishContinuationCluster cho phù hợp.

// Example to allow cross device syncing.
client.publishContinuationCluster(
    PublishContinuationClusterRequest
        .Builder()
        .setContinuationCluster(
            ContinuationCluster.Builder()
                .setAccountProfile(accountProfile)
                .setSyncAcrossDevices(true)
                .build()
        )
        .build()
)

Để khai thác tối đa tính năng trên nhiều thiết bị, hãy xác minh rằng ứng dụng có được sự đồng ý của người dùng và bật SyncAcrossDevices thành true. Nhờ đó, nội dung có thể đồng bộ hoá liền mạch trên các thiết bị, mang lại trải nghiệm tốt hơn cho người dùng và tăng mức độ tương tác. Ví dụ: một đối tác đã triển khai tính năng này nhận thấy số lượt nhấp vào nút "xem tiếp" tăng 40% vì nội dung của họ xuất hiện trên nhiều thiết bị.

Xoá dữ liệu Khám phá qua video

Để xoá dữ liệu của người dùng khỏi máy chủ Google TV theo cách thủ công trước khi hết khoảng thời gian lưu giữ tiêu chuẩn là 60 ngày, hãy sử dụng phương thức deleteClusters. Khi nhận được yêu cầu, dịch vụ sẽ xoá tất cả dữ liệu hiện có về hoạt động khám phá video cho hồ sơ tài khoản hoặc cho toàn bộ tài khoản.

Liệt kê DeleteReason xác định lý do xoá dữ liệu. Đoạn mã sau đây sẽ xoá dữ liệu xem tiếp khi người dùng đăng xuất.


// If the user logs out from your media app, you must make the following call
// to remove continue watching data from the current google TV device,
// otherwise, the continue watching data will persist on the current
// google TV device until 60 days later.
client.deleteClusters(
    DeleteClustersRequest.Builder()
        .setAccountProfile(AccountProfile())
        .setReason(DeleteReason.DELETE_REASON_USER_LOG_OUT)
        .setSyncAcrossDevices(true)
        .build()
)

Thử nghiệm

Sử dụng ứng dụng xác minh để xác minh rằng quá trình tích hợp Engage SDK đang hoạt động chính xác.

Sau khi bạn gọi API xuất bản, hãy xác nhận rằng dữ liệu của bạn đang được xuất bản chính xác bằng cách kiểm tra ứng dụng xác minh. Cụm tiếp tục của bạn sẽ xuất hiện dưới dạng một hàng riêng biệt trong giao diện của ứng dụng.

Kiểm thử các thao tác sau trong ứng dụng của bạn:
- Đăng nhập.
- Chuyển đổi giữa các hồ sơ(nếu có).
- Bắt đầu, sau đó tạm dừng video hoặc quay lại trang chủ.
- Đóng ứng dụng trong khi video đang phát.
- Xoá một mục khỏi hàng "Tiếp tục xem" (nếu được hỗ trợ).
Sau mỗi thao tác, hãy xác nhận rằng ứng dụng của bạn đã gọi API publishContinuationClusters và dữ liệu được hiển thị chính xác trong ứng dụng xác minh.
Ứng dụng xác minh sẽ hiển thị dấu kiểm màu xanh lục "Mọi thứ đều ổn" cho các thực thể được triển khai đúng cách.

Hình 1. Xác minh thành công ứng dụng
Ứng dụng xác minh sẽ gắn cờ mọi thực thể có vấn đề.

Hình 2. Lỗi ứng dụng xác minh
Để khắc phục các thực thể có lỗi, hãy dùng điều khiển từ xa của TV để chọn và nhấp vào thực thể trong ứng dụng xác minh. Các vấn đề cụ thể sẽ xuất hiện và được đánh dấu bằng màu đỏ để bạn xem xét (xem ví dụ bên dưới).

Hình 3. Thông tin chi tiết về lỗi ứng dụng xác minh