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 âm thanh 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.
Thông tin chi tiết về quy trình tích hợp
Thuật ngữ
Quy trình tích hợp bao gồm 3 loại cụm sau: Đề xuất, Tiếp tục và Nổi bật.
Cụm Đề xuất hiển thị các đề xuất theo từng cá nhân đối với nội dung cần đọc từ một đối tác nhà phát triển.
Các đề xuất của bạn có cấu trúc 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.
Hình 1. Giao diện người dùng Entertainment Space hiển thị một cụm Đề xuất của một đối tác. Thực thể: Một đối tượng đại diện cho mỗi mục trong một cụm. Mỗi thực thể có thể là danh sách phát, sách nói, podcast và nhiều nội dung khác. Xem phần Cung cấp dữ liệu về thực thể để biết danh sách các loại thực thể được hỗ trợ.
Hình 2. Giao diện người dùng Entertainment Space hiển thị một Thực thể duy nhất trong cụm Đề xuất của một đối tác.
Cụm Tiếp tục hiển thị nội dung âm thanh mà người dùng đã tương tác gần đây từ nhiều đối tác nhà phát triển trong một nhóm giao diện người dùng. 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 Tiếp tục.
Hình 3. Giao diện người dùng Entertainment Space hiển thị một cụm Tiếp tục với các đề xuất chưa hoàn tất từ nhiều đối tác (chỉ một nội dung đề xuất đang hiển thị). Cụm Nổi bật hiển thị một số mụ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.
Hình 4. Giao diện người dùng Entertainment Space hiển thị một cụm Nổi bật có các đề xuất của nhiều đối tác (hiện chỉ hiển thị một nội dung đề xuất).
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'
}
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:
Loại cụm | Số cụm tối đa | Số lượng thực thể tối đa trong một cụm |
---|---|---|
Cụm Đề xuất | Tối đa 7 | Tối đa 50 |
Cụm Tiếp tục | Tối đa 1 | Tối đa 20 |
Cụm Nổi bật | Tối đa 1 | Tối đa 20 |
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. Chúng tôi hỗ trợ các thực thể sau cho danh mục Nghe:
MusicAlbumEntity
MusicArtistEntity
MusicTrackEntity
MusicVideoEntity
PlaylistEntity
PodcastSeriesEntity
PodcastEpisodeEntity
LiveRadioStationEntity
AudiobookEntity
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.
MusicAlbumEntity
Đối tượng MusicAlbumEntity
đại diện cho một đĩa nhạc (ví dụ: Midnights của Taylor Swift).
Thuộc tính | Yêu cầu | Ghi chú |
---|---|---|
Tên | Bắt buộc | Tên đĩa nhạc. |
Hình ảnh áp phích | Bắt buộc | Bạn phải cung cấp ít nhất một hình ảnh. Hãy xem Thông số kỹ thuật của hình ảnh để biết hướng dẫn. |
URI trang thông tin | Bắt buộc |
Đường liên kết sâu đến ứng dụng của nhà cung cấp để cung cấp thông tin chi tiết về đĩa nhạc. Lưu ý: Bạn có thể sử dụng đường liên kết sâu để phân bổ. Tham khảo phần Câu hỏi thường gặp này |
Nghệ sĩ | Bắt buộc | Danh sách nghệ sĩ trong đĩa nhạc. |
URI phát | Không bắt buộc |
Một đường liên kết sâu bắt đầu phát đĩa nhạc trong ứng dụng của nhà cung cấp. Lưu ý: Bạn có thể sử dụng đường liên kết sâu để phân bổ. Tham khảo phần Câu hỏi thường gặp này |
Mô tả | Không bắt buộc | Không được vượt quá 200 ký tự nếu cung cấp. |
Số lượng bài hát | Không bắt buộc | Số lượng bài hát trong đĩa nhạc. |
Thể loại | Không bắt buộc | Danh sách các thể loại trong đĩa nhạc. |
Định dạng đĩa nhạc | Không bắt buộc |
ALBUM (Đĩa nhạc, bao gồm cả LP và LP kép) EP (Đĩa mở rộng) SINGLE (Đĩa đơn) Mixtape (Đĩa phối lại) |
Hãng nhạc | Không bắt buộc | Danh sách nhãn nhạc liên kết với đĩa nhạc. |
Đã tải xuống thiết bị | Không bắt buộc | Giá trị boolean cho biết đĩa nhạc có được tải xuống thiết bị hay không. |
Phản cảm | Không bắt buộc |
Giá trị boolean cho biết nội dung có phản cảm hay không Mục có chứa nội dung phản cảm hoặc có cảnh báo về việc tham khảo ý kiến của cha mẹ phải được đặt thành TRUE. Các mục phản cảm sẽ xuất hiện kèm thẻ "E". |
Ngày phát hành | Không bắt buộc | Ngày phát hành đĩa nhạc theo thời gian bắt đầu của hệ thống (mili giây). |
Thời lượng | Không bắt buộc | Thời lượng của đĩa nhạc tính bằng mili giây. |
Thời gian tương tác gần đây nhất | Không bắt buộc |
Nên dùng cho các mục trong cụm Continuation (Tiếp tục). Có thể được dùng để xếp hạng. Trong thời gian bắt đầu của hệ thống (mili giây) |
Phần trăm tiến trình hoàn tất | Không bắt buộc |
Nên dùng cho các mục trong cụm Continuation (Tiếp tục). Số nguyên từ 0 đến 100 |
MusicArtistEntity
Đối tượng MusicArtistEntity
đại diện cho một nghệ sĩ âm nhạc (ví dụ: Adele).
Thuộc tính | Yêu cầu | Ghi chú |
---|---|---|
Tên | Bắt buộc | Tên của nghệ sĩ âm nhạc. |
Hình ảnh áp phích | Bắt buộc | Bạn phải cung cấp ít nhất một hình ảnh. Hãy xem Thông số kỹ thuật của hình ảnh để biết hướng dẫn. |
URI trang thông tin | Bắt buộc |
Đường liên kết sâu đến ứng dụng của nhà cung cấp để cung cấp thông tin chi tiết về nghệ sĩ âm nhạc. Lưu ý: Bạn có thể sử dụng đường liên kết sâu để phân bổ. Tham khảo phần Câu hỏi thường gặp này |
URI phát | Không bắt buộc |
Đường liên kết sâu bắt đầu phát bài hát của nghệ sĩ trong ứng dụng của nhà cung cấp. Lưu ý: Bạn có thể sử dụng đường liên kết sâu để phân bổ. Tham khảo phần Câu hỏi thường gặp này |
Mô tả | Không bắt buộc | Không được vượt quá 200 ký tự nếu cung cấp. |
Thời gian tương tác gần đây nhất | Không bắt buộc |
Nên dùng cho các mục trong cụm Continuation (Tiếp tục). Có thể được dùng để xếp hạng. Trong thời gian bắt đầu của hệ thống (mili giây) |
MusicTrackEntity
Đối tượng MusicTrackEntity
đại diện cho một bản nhạc (ví dụ: Yellow của Coldplay).
Thuộc tính | Yêu cầu | Ghi chú |
---|---|---|
Tên | Bắt buộc | Tên bản nhạc. |
Hình ảnh áp phích | Bắt buộc | Bạn phải cung cấp ít nhất một hình ảnh. Hãy xem Thông số kỹ thuật của hình ảnh để biết hướng dẫn. |
URI phát | Bắt buộc |
Một đường liên kết sâu bắt đầu phát bản nhạc trong ứng dụng của nhà cung cấp. Lưu ý: Bạn có thể sử dụng đường liên kết sâu để phân bổ. Tham khảo phần Câu hỏi thường gặp này |
Nghệ sĩ | Bắt buộc | Danh sách nghệ sĩ trong bản nhạc. |
URI trang thông tin | Không bắt buộc |
Một đường liên kết sâu đến ứng dụng của nhà cung cấp để biết thông tin chi tiết về bản nhạc. Lưu ý: Bạn có thể sử dụng đường liên kết sâu để phân bổ. Tham khảo phần Câu hỏi thường gặp này |
Mô tả | Không bắt buộc | Không được vượt quá 200 ký tự nếu cung cấp. |
Thời lượng | Không bắt buộc | Thời lượng của bản nhạc tính bằng mili giây. |
Đĩa nhạc | Không bắt buộc | Tên của đĩa nhạc chứa bài hát. |
Đã tải xuống thiết bị | Không bắt buộc | Giá trị boolean cho biết bản nhạc có được tải xuống thiết bị hay không. |
Phản cảm | Không bắt buộc |
Giá trị boolean cho biết nội dung có phản cảm hay không Mục có chứa nội dung phản cảm hoặc có cảnh báo về việc tham khảo ý kiến của cha mẹ phải được đặt thành TRUE. Các mục phản cảm sẽ xuất hiện kèm thẻ "E". |
Thời gian tương tác gần đây nhất | Không bắt buộc |
Nên dùng cho các mục trong cụm Continuation (Tiếp tục). Có thể được dùng để xếp hạng. Trong thời gian bắt đầu của hệ thống (mili giây) |
Phần trăm tiến trình hoàn tất | Không bắt buộc |
Nên dùng cho các mục trong cụm Continuation (Tiếp tục). Số nguyên từ 0 đến 100 |
MusicVideoEntity
Đối tượng MusicVideoEntity
đại diện cho một video nhạc (ví dụ: The Weeknd – Take My Breath (Official Music Video)).
Thuộc tính | Yêu cầu | Ghi chú |
---|---|---|
Tên | Bắt buộc | Tên video nhạc. |
Hình ảnh áp phích | Bắt buộc | Bạn phải cung cấp ít nhất một hình ảnh. Hãy xem Thông số kỹ thuật của hình ảnh để biết hướng dẫn. |
URI phát | Bắt buộc |
Một đường liên kết sâu bắt đầu phát video nhạc trong ứng dụng của nhà cung cấp. Lưu ý: Bạn có thể sử dụng đường liên kết sâu để phân bổ. Tham khảo phần Câu hỏi thường gặp này |
URI trang thông tin | Không bắt buộc |
Một đường liên kết sâu đến ứng dụng của nhà cung cấp để xem thông tin chi tiết về video nhạc. Lưu ý: Bạn có thể sử dụng đường liên kết sâu để phân bổ. Tham khảo phần Câu hỏi thường gặp này |
Thời lượng | Không bắt buộc | Thời lượng của video tính bằng mili giây. |
Lượt xem | Không bắt buộc | Số lượt xem video ở định dạng văn bản tự do. |
Nghệ sĩ | Không bắt buộc | Danh sách nghệ sĩ của video nhạc. |
Phân loại nội dung | Không bắt buộc | Danh sách các mức phân loại nội dung của bản nhạc. |
Nội dung mô tả | Không bắt buộc | Không được vượt quá 200 ký tự nếu cung cấp. |
Đã tải xuống thiết bị | Không bắt buộc | Giá trị boolean cho biết video nhạc có được tải xuống thiết bị hay không. |
Phản cảm | Không bắt buộc |
Giá trị boolean cho biết nội dung có phản cảm hay không Mục có chứa nội dung phản cảm hoặc có cảnh báo về việc tham khảo ý kiến của cha mẹ phải được đặt thành TRUE. Các mục phản cảm sẽ xuất hiện kèm thẻ "E". |
Thời gian tương tác gần đây nhất | Không bắt buộc |
Nên dùng cho các mục trong cụm Continuation (Tiếp tục). Có thể được dùng để xếp hạng. Trong thời gian bắt đầu của hệ thống (mili giây) |
Phần trăm tiến trình hoàn tất | Không bắt buộc |
Nên dùng cho các mục trong cụm Continuation (Tiếp tục). Số nguyên từ 0 đến 100 |
PlaylistEntity
Đối tượng PlaylistEntity
đại diện cho một danh sách phát nhạc (ví dụ: Danh sách phát 10 bản nhạc hàng đầu của Hoa Kỳ).
Thuộc tính | Yêu cầu | Ghi chú |
---|---|---|
Tên | Bắt buộc | Tên danh sách phát. |
Hình ảnh áp phích | Bắt buộc | Bạn phải cung cấp ít nhất một hình ảnh. Hãy xem Thông số kỹ thuật của hình ảnh để biết hướng dẫn. |
URI phát | Bắt buộc |
Một đường liên kết sâu bắt đầu phát danh sách phát nhạc trong ứng dụng của nhà cung cấp. Lưu ý: Bạn có thể sử dụng đường liên kết sâu để phân bổ. Tham khảo phần Câu hỏi thường gặp này |
URI trang thông tin | Không bắt buộc |
Một đường liên kết sâu đến ứng dụng của nhà cung cấp để biết thông tin chi tiết về danh sách phát nhạc. Lưu ý: Bạn có thể sử dụng đường liên kết sâu để phân bổ. Tham khảo phần Câu hỏi thường gặp này |
Thời lượng | Không bắt buộc | Thời lượng của danh sách phát tính bằng mili giây. |
Số lượng bài hát | Không bắt buộc | Số lượng bài hát trong danh sách phát nhạc. |
Mô tả | Không bắt buộc | Không được vượt quá 200 ký tự nếu cung cấp. |
Đã tải xuống thiết bị | Không bắt buộc | Giá trị boolean cho biết danh sách phát có được tải xuống thiết bị hay không. |
Phản cảm | Không bắt buộc |
Giá trị boolean cho biết nội dung có phản cảm hay không Mục có chứa nội dung phản cảm hoặc có cảnh báo về việc tham khảo ý kiến của cha mẹ phải được đặt thành TRUE. Các mục phản cảm sẽ xuất hiện kèm thẻ "E". |
Thời gian tương tác gần đây nhất | Không bắt buộc |
Nên dùng cho các mục trong cụm Continuation (Tiếp tục). Có thể được dùng để xếp hạng. Trong thời gian bắt đầu của hệ thống (mili giây) |
Phần trăm tiến trình hoàn tất | Không bắt buộc |
Nên dùng cho các mục trong cụm Continuation (Tiếp tục). Số nguyên từ 0 đến 100 |
PodcastSeriesEntity
Đối tượng PodcastSeriesEntity
đại diện cho một loạt podcast (ví dụ: This American Life).
Thuộc tính | Yêu cầu | Ghi chú |
---|---|---|
Tên | Bắt buộc | Tên loạt podcast. |
Hình ảnh áp phích | Bắt buộc | Bạn phải cung cấp ít nhất một hình ảnh. Hãy xem Thông số kỹ thuật của hình ảnh để biết hướng dẫn. |
URI trang thông tin | Bắt buộc |
Một đường liên kết sâu đến ứng dụng của nhà cung cấp để xem thông tin chi tiết về loạt podcast. Lưu ý: Bạn có thể sử dụng đường liên kết sâu để phân bổ. Tham khảo phần Câu hỏi thường gặp này |
URI phát | Không bắt buộc |
Một đường liên kết sâu bắt đầu phát loạt podcast trong ứng dụng của nhà cung cấp. Lưu ý: Bạn có thể sử dụng đường liên kết sâu để phân bổ. Tham khảo phần Câu hỏi thường gặp này |
Số lượng tập | Không bắt buộc | Số tập trong loạt podcast. |
Tên chương trình | Không bắt buộc | Tên chương trình sản xuất loạt podcast. |
Người dẫn chương trình | Không bắt buộc | Danh sách người dẫn chương trình của loạt podcast. |
Thể loại | Không bắt buộc | Danh sách thể loại của loạt podcast. |
Đã tải xuống thiết bị | Không bắt buộc | Giá trị boolean cho biết podcast có được tải xuống thiết bị hay không. |
Mô tả | Không bắt buộc | Không được vượt quá 200 ký tự nếu cung cấp. |
Phản cảm | Không bắt buộc |
Giá trị boolean cho biết nội dung có phản cảm hay không Mục có chứa nội dung phản cảm hoặc có cảnh báo về việc tham khảo ý kiến của cha mẹ phải được đặt thành TRUE. Các mục phản cảm sẽ xuất hiện kèm thẻ "E". |
Thời gian tương tác gần đây nhất | Không bắt buộc |
Nên dùng cho các mục trong cụm Continuation (Tiếp tục). Có thể được dùng để xếp hạng. Trong thời gian bắt đầu của hệ thống (mili giây) |
PodcastEpisodeEntity
Đối tượng PodcastEpisodeEntity
đại diện cho một loạt podcast (ví dụ: Spark Bird, Tập 754: This American Life).
Thuộc tính | Yêu cầu | Ghi chú |
---|---|---|
Tên | Bắt buộc | Tên tập podcast. |
Hình ảnh áp phích | Bắt buộc | Bạn phải cung cấp ít nhất một hình ảnh. Hãy xem Thông số kỹ thuật của hình ảnh để biết hướng dẫn. |
URI phát | Bắt buộc |
Một đường liên kết sâu bắt đầu phát tập podcast trong ứng dụng của nhà cung cấp. Lưu ý: Bạn có thể sử dụng đường liên kết sâu để phân bổ. Tham khảo phần Câu hỏi thường gặp này |
Tên loạt podcast | Bắt buộc | Tên của loạt podcast chứa tập đó. |
Thời lượng | Bắt buộc | Thời lượng của tập podcast tính bằng mili giây. |
Ngày phát hành | Bắt buộc | Ngày xuất bản podcast (theo thời gian bắt đầu của hệ thống (mili giây)) |
URI trang thông tin | Không bắt buộc |
Một đường liên kết sâu đến ứng dụng của nhà cung cấp để xem thông tin chi tiết về tập podcast. Lưu ý: Bạn có thể sử dụng đường liên kết sâu để phân bổ. Tham khảo phần Câu hỏi thường gặp này |
Tên chương trình | Không bắt buộc | Tên chương trình sản xuất loạt podcast. |
Chỉ mục tập | Không bắt buộc | Chỉ mục của tập trong loạt podcast (chỉ mục đầu tiên là 1). |
Người dẫn chương trình | Không bắt buộc | Danh sách người dẫn chương trình của tập podcast. |
Thể loại | Không bắt buộc | Danh sách thể loại của tập podcast. |
Đã tải xuống thiết bị | Không bắt buộc | Giá trị boolean cho biết tập podcast có được tải xuống thiết bị hay không. |
Mô tả | Không bắt buộc | Không được vượt quá 200 ký tự nếu cung cấp. |
Podcast video | Không bắt buộc | Giá trị boolean cho biết tập podcast có nội dung video hay không |
Phản cảm | Không bắt buộc |
Giá trị boolean cho biết nội dung có phản cảm hay không Mục có chứa nội dung phản cảm hoặc có cảnh báo về việc tham khảo ý kiến của cha mẹ phải được đặt thành TRUE. Các mục phản cảm sẽ xuất hiện kèm thẻ "E". |
Loại nội dung Nghe tiếp theo | Không bắt buộc |
Nên dùng cho các mục trong cụm Tiếp tục TYPE_CONTINUE – Tiếp tục với mục âm thanh chưa hoàn tất. TYPE_NEXT – Tiếp tục với phần mới trong loạt podcast. TYPE_NEW – Mới phát hành. |
Thời gian tương tác gần đây nhất | Không bắt buộc |
Nên dùng cho các mục trong cụm Continuation (Tiếp tục). Có thể được dùng để xếp hạng. Trong thời gian bắt đầu của hệ thống (mili giây) |
Phần trăm tiến trình hoàn tất | Không bắt buộc |
Nên dùng cho các mục trong cụm Continuation (Tiếp tục). Số nguyên từ 0 đến 100 |
LiveRadioStationEntity
Đối tượng LiveRadioStationEntity
đại diện cho một đài phát thanh trực tiếp (ví dụ: 98.1 The Breeze).
Thuộc tính | Yêu cầu | Ghi chú |
---|---|---|
Tên | Bắt buộc | Tên đài phát thanh trực tiếp. |
Hình ảnh áp phích | Bắt buộc | Bạn phải cung cấp ít nhất một hình ảnh. Hãy xem Thông số kỹ thuật của hình ảnh để biết hướng dẫn. |
URI phát | Bắt buộc |
Một đường liên kết sâu bắt đầu phát đài phát thanh trong ứng dụng của nhà cung cấp. Lưu ý: Bạn có thể sử dụng đường liên kết sâu để phân bổ. Tham khảo phần Câu hỏi thường gặp này |
URI trang thông tin | Không bắt buộc |
Một đường liên kết sâu đến ứng dụng của nhà cung cấp để biết thông tin chi tiết về đài phát thanh. Lưu ý: Bạn có thể sử dụng đường liên kết sâu để phân bổ. Tham khảo phần Câu hỏi thường gặp này |
Tần suất sao lưu | Không bắt buộc | Tần số phát sóng của đài phát thanh (ví dụ: "98.1 FM"). |
Tên chương trình | Không bắt buộc | Chương trình hiện tại đang phát trên đài phát thanh. |
Người dẫn chương trình | Không bắt buộc | Danh sách người dẫn chương trình của đài phát thanh. |
Nội dung mô tả | Không bắt buộc | Không được vượt quá 200 ký tự nếu cung cấp. |
Thời gian tương tác gần đây nhất | Không bắt buộc |
Nên dùng cho các mục trong cụm Continuation (Tiếp tục). Có thể được dùng để xếp hạng. Trong thời gian bắt đầu của hệ thống (mili giây) |
AudiobookEntity
Đối tượng AudiobookEntity
đại diện cho một sách nói (ví dụ: sách nói Becoming của Michelle Obama).
Thuộc tính | Yêu cầu | Ghi chú |
---|---|---|
Tên | Bắt buộc | |
Hình ảnh áp phích | Bắt buộc | Bạn phải cung cấp ít nhất một hình ảnh. Hãy xem Thông số kỹ thuật của hình ảnh để biết hướng dẫn. |
Tác giả | Bắt buộc | Bạn phải cung cấp ít nhất 1 tên tác giả. |
Người đọc | Bắt buộc | Bạn phải cung cấp tên của ít nhất một người đọc. |
URI đường liên kết hành động | Bắt buộc |
Đường liên kết sâu đến ứng dụng của nhà cung cấp sách nói. Lưu ý: Bạn có thể sử dụng đường liên kết sâu để phân bổ. Tham khảo phần Câu hỏi thường gặp này |
Ngày phát hành | Không bắt buộc | Trong thời gian bắt đầu của hệ thống (mili giây) nếu được cung cấp. |
Nội dung mô tả | Không bắt buộc | Không được vượt quá 200 ký tự nếu cung cấp. |
Giá tiền | Không bắt buộc | Văn bản tự do |
Thời lượng | Không bắt buộc | Phải là một giá trị dương nếu được cung cấp. |
Thể loại | Không bắt buộc | Danh sách các thể loại liên kết với cuốn sách này. |
Tên bộ sách | Không bắt buộc | Tên của bộ sách nói (ví dụ: Harry Potter. |
Chỉ mục đơn vị của bộ sách | Không bắt buộc | Chỉ mục của sách nói trong bộ sách, trong đó 1 là sách nói đầu tiên trong bộ sách. Ví dụ: Nếu Harry Potter và Tù nhân Azkaban là cuốn sách thứ ba trong bộ sách, thì bạn nên thiết lập giá trị này là 3. |
Kiểu đọc tiếp sách | Không bắt buộc |
TYPE_CONTINUE – Đọc tiếp cuốn đang đọc dở. TYPE_NEXT – Đọc một phần mới của bộ sách. TYPE_NEW – Mới phát hành. |
Thời gian tương tác gần đây nhất | Bắt buộc có điều kiện | Bạn phải cung cấp thông tin này khi mục nằm trong cụm Continuation (Tiếp tục). Tính bằng mili giây thời gian bắt đầu của hệ thống. |
Phần trăm tiến trình hoàn tất | Bắt buộc có điều kiện |
Bạn phải cung cấp thông tin này khi nội dung nằm trong cụm Tiếp tục. Những cuốn sách nói *mới* mua có thể nằm trong cụm Tiếp tục đọc. Giá trị phải lớn hơn 0 và nhỏ hơn 100. |
DisplayTimeWindow – Đặt khoảng thời gian hiện nội dung trên giao diện | ||
Dấu thời gian bắt đầu | Không bắt buộc |
Dấu thời gian bắt đầu của hệ thống mà sau đó nội dung sẽ hiện trên nền tảng. Nếu bạn không đặt giá trị này, thì nội dung sẽ đủ điều kiện hiện trên nền tảng. Tính bằng mili giây thời gian bắt đầu của hệ thống. |
Dấu thời gian kết thúc | Không bắt buộc |
Dấu thời gian bắt đầu của hệ thống mà sau đó nội dung không còn hiện trên nền tảng. Nếu bạn không đặt giá trị này, thì nội dung sẽ đủ điều kiện hiện trên nền tảng. Tính bằng mili giây thời gian bắt đầu của hệ thống. |
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:
Tỷ lệ khung hình | Yêu cầu | Số pixel tối thiểu | Số điểm ảnh đề xuất |
---|---|---|---|
Vuông (1 x 1) | Bắt buộc | 300 x 300 | 1200 x 1200 |
Ngang (1,91 x 1) | Không bắt buộc | 600 x 314 | 1200 x 628 |
Dọc (4 x 5) | Không bắt buộc | 480 x 600 | 960 x 1200 |
Đị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.
Ví dụ
MusicAlbumEntity musicAlbumEntity =
new MusicAlbumEntity.Builder()
.setName(NAME)
.addPosterImage(new Image.Builder()
.setImageUri(Uri.parse("http://www.x.com/image.png"))
.setImageHeightInPixel(960)
.setImageWidthInPixel(408)
.build())
.setPlayBackUri("https://play.google/album/play")
.setInfoPageUri("https://play.google/album/info")
.setDescription("A description of this album.")
.addArtist("Artist")
.addGenre("Genre")
.addMusicLabel("Label")
.addContentRating("Rating")
.setSongsCount(960)
.setReleaseDateEpochMillis(1633032895L)
.setDurationMillis(1633L)
.build();
AudiobookEntity audiobookEntity =
new AudiobookEntity.Builder()
.setName("Becoming")
.addPosterImage(new Image.Builder()
.setImageUri(Uri.parse("http://www.x.com/image.png"))
.setImageHeightInPixel(960)
.setImageWidthInPixel(408)
.build())
.addAuthor("Michelle Obama")
.addNarrator("Michelle Obama")
.setActionLinkUri(
Uri.parse("https://play.google/audiobooks/1"))
.setDurationMillis(16335L)
.setPublishDateEpochMillis(1633032895L)
.setDescription("An intimate, powerful, and inspiring memoir")
.setPrice("$16.95")
.addGenre("biography")
.build();
Bước 2: Cung cấp dữ liệu Cụm
Bạn nên thực hiện công việc phát hành 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).
AppEngagePublishClient
chịu trách nhiệm xuất bản cụm. Có các API sau đây trong ứng dụng:
isServiceAvailable
publishRecommendationClusters
publishFeaturedCluster
publishContinuationCluster
publishUserAccountManagementRequest
updatePublishStatus
deleteRecommendationsClusters
deleteFeaturedCluster
deleteContinuationCluster
deleteUserManagementCluster
deleteClusters
isServiceAvailable
API này dùng để kiểm tra xem dịch vụ có thể tích hợp và nội dung có xuất hiện trên thiết bị hay không.
Kotlin
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. } }
Java
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
.
Kotlin
client.publishRecommendationClusters( PublishRecommendationClustersRequest.Builder() .addRecommendationCluster( RecommendationCluster.Builder() .addEntity(entity1) .addEntity(entity2) .setTitle("Trending music") .build()) .build())
Java
client.publishRecommendationClusters( new PublishRecommendationClustersRequest.Builder() .addRecommendationCluster( new RecommendationCluster.Builder() .addEntity(entity1) .addEntity(entity2) .setTitle("Trending music") .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
RecommendationCluster
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 Đề xuấ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ì.
publishFeaturedCluster
API này được dùng để phát hành danh sách đối tượng FeaturedCluster
.
Kotlin
client.publishFeaturedCluster( PublishFeaturedClusterRequest.Builder() .setFeaturedCluster( FeaturedCluster.Builder() ... .build()) .build())
Java
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ì.
publishContinuationCluster
API này được dùng để phát hành đối tượng ContinuationCluster
.
Kotlin
client.publishContinuationCluster( PublishContinuationClusterRequest.Builder() .setContinuationCluster( ContinuationCluster.Builder() .addEntity(entity1) .addEntity(entity2) .build()) .build())
Java
client.publishContinuationCluster( PublishContinuationClusterRequest.Builder() .setContinuationCluster( ContinuationCluster.Builder() .addEntity(entity1) .addEntity(entity2) .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 cụm Tiếp tục đã 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 –
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) |
Hình ả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() client.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(); 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
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());
deleteRecommendationClusters
API này dùng để xoá nội dung của cụm Recommendation (Đề xuất).
Kotlin
client.deleteRecommendationClusters()
Java
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).
Kotlin
client.deleteFeaturedCluster()
Java
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.
deleteContinuationCluster
API này dùng để xoá nội dung của cụm Continuation (Tiếp tục).
Kotlin
client.deleteContinuationCluster()
Java
client.deleteContinuationCluster();
Khi nhận được yêu cầu, dịch vụ sẽ xoá dữ liệu hiện có khỏi cụm Tiếp tục. 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.
Kotlin
client.deleteUserManagementCluster()
Java
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ể.
Kotlin
client.deleteClusters( DeleteClustersRequest.Builder() .addClusterType(ClusterType.TYPE_FEATURED) .addClusterType(ClusterType.TYPE_RECOMMENDATION) ... .build())
Java
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(
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.
Mã lỗi | Tên lỗi | Lưu ý |
---|---|---|
1 |
SERVICE_NOT_FOUND |
Dịch vụ này không dùng được trên thiết bị đã cho. |
2 |
SERVICE_NOT_AVAILABLE |
Dịch vụ này hoạt động trên thiết bị đã cho, nhưng không hoạt động tại thời điểm gọi (ví dụ: dịch vụ bị vô hiệu hoá một cách rõ ràng). |
3 |
SERVICE_CALL_EXECUTION_FAILURE |
Không thực hiện được tác vụ do có vấn đề về luồng. Trong trường hợp này, bạn có thể thử lại. |
4 |
SERVICE_CALL_PERMISSION_DENIED |
Trình gọi không được phép thực hiện cuộc gọi dịch vụ. |
5 |
SERVICE_CALL_INVALID_ARGUMENT |
Yêu cầu chứa dữ liệu không hợp lệ (ví dụ: nhiều hơn số cụm được phép). |
6 |
SERVICE_CALL_INTERNAL |
Đã xảy ra lỗi bên phía dịch vụ. |
7 |
SERVICE_CALL_RESOURCE_EXHAUSTED |
Cuộc gọi dịch vụ được thực hiện quá thường xuyên. |
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ụngContext.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 extends BroadcastReceiver {
// Trigger recommendation cluster publish when PUBLISH_RECOMMENDATION broadcast
// is received
// Trigger featured cluster publish when PUBLISH_FEATURED broadcast is received
// Trigger continuation cluster publish when PUBLISH_CONTINUATION 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 Continuation Cluster Publish Intent
context.registerReceiver(new AppEngageBroadcastReceiver(),
new IntentFilter(com.google.android.engage.service.Intents.ACTION_PUBLISH_CONTINUATION));
}
- Khai báo tĩnh quá trình triển khai bằng thẻ
<receiver>
trong tệpAndroidManifest.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 đó.
<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.PUBLISH_CONTINUATION" />
</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ọipublishRecommendationClusters
khi nhận được ý định này.com.google.android.engage.action.PUBLISH_FEATURED
Bạn nên bắt đầu lệnh gọipublishFeaturedCluster
khi nhận được ý định này.com.google.android.engage.action.PUBLISH_CONTINUATION
Bạn nên bắt đầu lệnh gọipublishContinuationCluster
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. Nhóm của chúng tôi sẽ trả lời sớm nhất có thể.
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 nội bộ để đảm bảo APK tích hợp hoạt động 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 phát hành 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 và Tiếp tục sẽ được phát hành và hiển thị cho người dùng.