Tính năng Tiếp tục xem tận dụng cụm Tiếp tục để hiển thị các video đang xem dở và các tập tiếp theo cần xem trong cùng một phần chương trình truyền hình, từ nhiều ứng dụng trong một nhóm giao diện người dùng. Bạn có thể giới thiệu các thực thể của họ trong cụm tiếp tục này. Hãy làm theo hướng dẫn này để tìm hiểu cách nâng cao mức độ tương tác của người dùng thông qua trải nghiệm Tiếp tục xem bằng Engage SDK.
Bước 1: Chuẩn bị
Trước khi bắt đầu, hãy hoàn tất các bước sau:
Đảm bảo ứng dụng của bạn nhắm đến API cấp 19 trở lên để tích hợp tính năng này
Thêm thư viện
com.google.android.engagevào ứng dụng của bạn:Có các SDK riêng biệt để sử dụng trong quá trình tích hợp: một SDK cho ứng dụng di động và một SDK cho ứng dụng TV.
Thiết bị di động
dependencies { implementation 'com.google.android.engage:engage-core:1.5.5 }TV
dependencies { implementation 'com.google.android.engage:engage-tv:1.0.2 }Đặt môi trường dịch vụ Engage thành môi trường phát hành chính thức trong tệp
AndroidManifest.xml.Thiết bị di động
<meta-data android:name="com.google.android.engage.service.ENV" android:value="PRODUCTION"> </meta-data>TV
<meta-data android:name="com.google.android.engage.service.ENV" android:value="PRODUCTION"> </meta-data>Thêm quyền cho
WRITE_EPG_DATAcho tệp apk dành cho TV<uses-permission android:name="com.android.providers.tv.permission.WRITE_EPG_DATA" />Đảm bảo việc phát hành nội dung đáng tin cậy bằng cách sử dụng dịch vụ nền, chẳng hạn như
androidx.work, để lên lịch.Để mang đến trải nghiệm xem liền mạch, hãy phát hành dữ liệu tiếp tục xem khi những sự kiện sau đây xảy ra:
- Lần đăng nhập đầu tiên: Khi người dùng đăng nhập lần đầu tiên, việc phát hành dữ liệu của họ sẽ đảm bảo nhật ký xem của họ có sẵn ngay lập tức.
- Tạo hoặc chuyển đổi hồ sơ (Ứng dụng nhiều hồ sơ): Nếu ứng dụng của bạn hỗ trợ nhiều hồ sơ, hãy phát hành dữ liệu khi người dùng tạo hoặc chuyển đổi hồ sơ. Điều này đảm bảo mỗi người dùng đều có trải nghiệm được cá nhân hoá.
- Video bị gián đoạn khi phát: Để giúp người dùng tiếp tục từ nơi họ đã dừng, hãy phát hành dữ liệu khi họ tạm dừng hoặc dừng một video hoặc khi ứng dụng thoát trong khi phát.
- Cập nhật khay Tiếp tục xem (Nếu được hỗ trợ): Khi người dùng xoá một mục khỏi khay Tiếp tục xem, hãy phản ánh thay đổi đó bằng cách phát hành dữ liệu đã cập nhật. Điều này giúp đảm bảo khay vẫn phù hợp và được cá nhân hoá.
- Tỷ lệ xem hết video:
- Đối với phim, hãy xoá phim đã xem xong khỏi khay Tiếp tục xem. Nếu bộ phim thuộc một loạt phim, hãy thêm bộ phim tiếp theo để người dùng tiếp tục hứng thú.
- Đối với các tập, hãy xoá tập đã xem hết và thêm tập tiếp theo trong chương trình truyền hình dài tập (nếu có) để khuyến khích người dùng tiếp tục xem.
Tích hợp
AccountProfile
Để mang đến trải nghiệm "tiếp tục xem" phù hợp với bạn trên Google TV, hãy cung cấp thông tin tài khoản và hồ sơ. Sử dụng AccountProfile để cung cấp:
Mã tài khoản: Giá trị nhận dạng duy nhất đại diện cho tài khoản của người dùng trong ứng dụng. Đây có thể là mã tài khoản thực tế hoặc phiên bản được làm rối mã nguồn một cách thích hợp.
Mã hồ sơ (không bắt buộc): Nếu ứng dụng của bạn hỗ trợ nhiều hồ sơ trong một tài khoản, hãy cung cấp giá trị nhận dạng duy nhất cho hồ sơ người dùng cụ thể (lại là giá trị thực hoặc được làm rối mã nguồn).
// If your app only supports account
val accountProfile = AccountProfile.Builder()
.setAccountId("your_users_account_id")
.build()
// If your app supports both account and profile
val accountProfile = AccountProfile.Builder()
.setAccountId("your_users_account_id")
.setProfileId("your_users_profile_id")
.build()
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 URI phát được nhắm mục tiêu để 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 đảm bảo 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ể "Tiếp tục xem", đặc biệt là trong Entertainment Space của Google. Hình ảnh có chiều cao dưới 200 pixel có thể không hiển thị.
Image image1 = new Image.Builder()
.setImageUri(Uri.parse("http://www.example.com/entity_image1.png");)
.setImageHeightInPixel(300)
.setImageWidthInPixel(169)
.build()
Image image2 = new Image.Builder()
.setImageUri(Uri.parse("http://www.example.com/entity_image2.png");)
.setImageHeightInPixel(640)
.setImageWidthInPixel(360)
.build()
// And other images for different form factors.
val images = Arrays.asList(image1, image2)
MovieEntity
Ví dụ này cho biết 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()
Việc cung cấp thông tin chi tiết như thể loại và điểm xếp hạng nội dung giúp Google TV giới thiệu nội dung của bạn theo cách linh động 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 được duy trì 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 = new DisplayTimeWindow.Builder()
.setEndTimestampMillis(now().toMillis()+2592000000).build()
val movieEntity = MovieEntity.Builder()
...
.addAvailabilityTimeWindow(expirationTime)
.build()
TvEpisodeEntity
Ví dụ này cho biết 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ích hợp trước khi hiển thị trên thẻ tiếp tục xem. Xin lưu ý rằng các giá trị này phải là một chuỗi số, đừng đặt "e2", "episode 2", "s1" hoặc "season 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ăng tối đa khả năng 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, điểm xếp hạng nội dung và khung giờ phát sóng, vì những thông tin chi tiết này có thể cải thiện chế độ hiển thị và các lựa chọn 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 có 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 nhà sáng tạo, hình ảnh nhà sáng 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 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 khoảng thời gian phát sóng 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 phát hành cụm Tiếp tục.
Bạn sử dụng phương thức publishContinuationCluster() để phát hành đối tượng ContinuationCluster.
Trước tiên, bạn nên sử dụng isServiceAvailable() để kiểm tra xem dịch vụ có thể tích hợp hay không.
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
ContinuationClusterhiệ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 phát hành 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 ContinuationCluster, bạn sẽ cần phát hành lại tất cả các thực thể.
Bạn chỉ nên cung cấp dữ liệu ContinuationCluster cho tài khoản người lớn. Chỉ xuất bản khi AccountProfile thuộc về người lớn.
Đồng bộ hoá trên nhiều thiết bị
Cờ SyncAcrossDevices
Cờ này 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ị của họ (TV, điện thoại, máy tính bảng, v.v.) hay không. Giá trị mặc định là false, nghĩa là tính năng đồng bộ hoá trên nhiều thiết bị bị tắt theo mặc định.
Giá trị:
- true: Dữ liệu ContinuationCluster được chia sẻ trên tất 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 chọn tuỳ chọn này để có trải nghiệm tốt nhất trên nhiều thiết bị.
- false: Dữ liệu ContinuationCluster bị hạn chế ở 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 chế độ cài đặt rõ ràng để bật/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 và lưu trữ lựa chọn ưu tiên của người dùng một lần, sau đó á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ị của chúng tôi, hãy đảm bảo ứng dụng của bạn có được sự đồng ý của người dùng và bật SyncAcrossDevices thành true. Điều này cho phép nội dung đồ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 đã tăng 40% số lượt nhấp vào nút "tiếp tục xem" 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á 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 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 client.deleteClusters(). Sau khi nhận được yêu cầu, dịch vụ sẽ xoá tất cả dữ liệu hiện có về việc khám phá video cho hồ sơ tài khoản hoặc cho toàn bộ tài khoản.
Enum DeleteReason xác định lý do xoá dữ liệu.
Mã sau đây xoá dữ liệu tiếp tục xem khi đă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(
new 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 để đảm bảo quá trình tích hợp Engage SDK đang hoạt động chính xác. Ứng dụng Android này cung cấp các công cụ giúp bạn xác minh dữ liệu và xác nhận rằng ý định truyền tin đang được xử lý đúng cách.
Sau khi bạn gọi API phát hành, hãy xác nhận rằng dữ liệu của bạn đang được phát hành chính xác bằng cách kiểm tra ứng dụng xác minh. Cụm tiếp tục sẽ hiển thị dưới dạng một hàng riêng biệt trong giao diện của ứng dụng.
- Đảm bảo rằng Cờ Engage Service KHÔNG được đặt thành bản phát hành chính thức trong tệp kê khai Android của ứng dụng.
- Cài đặt và mở ứng dụng Engage Verify
- Nếu
isServiceAvailablelàfalse, hãy nhấp vào nút "Bật/tắt" để bật. - Nhập tên gói của ứng dụng để tự động xem dữ liệu đã xuất bản sau khi bạn bắt đầu phát hành.
- Kiểm thử các thao tác này trong ứng dụng:
- Đăng nhập.
- Chuyển đổi giữa các hồ sơ(nếu có).
- Bắt đầu, sau đó tạm dừng một video hoặc quay lại trang chủ.
- Đóng ứng dụng trong khi phát video.
- Xoá một mục khỏi hàng "Tiếp tục xem" (nếu được hỗ trợ).
- Sau mỗi hành động, 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 "All Good" (Đã kiểm tra) màu xanh lục cho các thực thể được triển khai chính xác.
Hình 1. Xác minh ứng dụng thành cô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 sự cố về các thực thể, 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 xác minh ứng dụng