發布常見問題
誰負責管理內容發布工作？
應用程式開發人員會管理內容發布工作，並將要求傳送至 Engage Service。這樣一來，開發合作夥伴就能進一步控管向使用者發布內容的時機和方式，避免頻繁地喚醒合作夥伴應用程式進行內容發布。
開發人員需要發布所有叢集類型嗎？
雖然開發人員可以只發布一個叢集，但我們強烈建議加入更多叢集。否則，開發人員會錯失吸引使用者與內容互動的機會。強烈建議您發布每個類別的所有叢集類型。
應用程式執行期間，開發合作夥伴應多久透過工作管理員發布資料一次？
這由開發合作夥伴決定。Google 建議一般推薦內容每天發布一到兩次，購物車、重新訂購和其他續訂內容則採用事件驅動方法 (例如在使用者將商品加入購物車或暫停電影時，啟動工作者)。對於社交應用程式，每次使用應用程式後，都必須發布更新的建議叢集。社群應用程式使用者對最新推薦內容的興趣較高，最好是每則貼文只顯示一次。
開發人員何時應呼叫刪除 API？
只有在沒有可發布的內容時，才應呼叫刪除 API。請勿接連呼叫刪除 API 和發布 API 來取代內容；發布 API 會自動移除先前的內容。
廣播意圖常見問題
為什麼 Android 應用程式開發人員需要註冊廣播意圖？
為了向使用者提供最新內容，您應該使用廣播意圖，在使用者可能不會常使用應用程式時觸發資料同步作業。
無法測試廣播意圖
驗證應用程式不支援使用權限測試廣播意圖。測試時必須移除權限，並在步驟 6 將 SDK 切換為正式版前，重新新增權限。
不允許背景執行作業
註冊廣播意圖時，可能會遇到以下錯誤：
Background execution not allowed: receiving Intent
{ act=com.google.android.engage.action.PUBLISH_RECOMMENDATION .. }
您需要以動態方式註冊廣播接收器。
class AppEngageBroadcastReceiver extends BroadcastReceiver {
// Trigger recommendation cluster publish when PUBLISH_RECOMMENDATION 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,
com.google.android.engage.service.BroadcastReceiverPermissions.BROADCAST_REQUEST_DATA_PUBLISH_PERMISSION,
/*scheduler=*/null));
...
}
工作流程常見問題
整合此 SDK 時，可能會遇到以下錯誤：
應用程式、叢集、實體層級的驗證錯誤
應用程式、叢集和實體層級的摘要會顯示驗證錯誤計數。這些錯誤表示缺少必填欄位或提供的值無效。相關欄位下方會以紅色顯示錯誤訊息。請先修正所有驗證錯誤並檢查是否正確，再分享 APK。
測試深層連結
深層連結已與套件名稱建立關聯。使用 ADB 工具測試深層連結是不錯的方法。
adb shell am start -W -a android.intent.action.VIEW -d <DEEPLINK URI> <PACKAGE NAME>
如何評估整合帶來的影響？
深層連結是追蹤歸因的好方法。深層連結網址除了能將使用者導向應用程式外，也可納入其他追蹤參數，例如「http://xx/deeplink?source_tag=engage」。
開發人員可以自行新增追蹤參數，並提供歸因分析，評估影響程度。
Engage for TV 2.0 常見問題
一般問題
什麼是 Engage？
Engage 讓「從上次中斷的地方繼續」體驗更上一層樓！這項重大升級可讓觀眾在更多裝置上無縫接續觀看內容。想像一下，你先在 Google TV 上觀看電影，然後在通勤途中輕鬆地用手機繼續觀看，這就是 Engage 的強大功能。
這項新系統旨在提供流暢無礙的體驗，讓觀眾在整個 Google 生態系統中都能輕鬆互動，進而提升參與度和留存率。
Video Discovery API 與 Engage 是否相同？
是的，兩者相同。Engage SDK 是一個程式庫，支援「繼續觀看」列。「參與度」支援的內容實體類型比影片多，因此整合功能不再稱為「影片探索」。
使用 Engage 有哪些好處？
答：無論觀眾使用哪種裝置，都能透過「參與度」功能輕鬆接續觀看你的內容。運作方式如下：
- 跨 Google 服務無縫接軌：在 Google TV 上開始觀看，然後在 Android 手機、iPhone 或 Android 平板電腦上繼續觀看。即使裝置尚未安裝應用程式，也能使用這項功能！
- 提高參與度和留存率：Engage 可協助使用者返回應用程式，即使是使用新裝置也沒問題。使用者可以繼續觀看喜愛的節目，因此更有可能繼續觀看。
- 觸及範圍更廣：除了 Google TV，Engage 也適用於其他 Android 媒體體驗，例如 Play 收藏和其他 Google 媒體應用程式。
- 回溯相容：如果您已使用舊版「稍後觀看」功能，請放心！Engage 支援回溯相容，因此現有的整合功能仍可正常運作。
重要注意事項：所有新的「繼續觀看」整合功能都必須使用 Engage。舊版「跨裝置播放下一個」系統即將淘汰。
哪些平台支援 Engage？
- Google TV
- Android TV (僅限裝置端，但支援 Engage SDK)
- Google TV Android 行動應用程式
- Google TV iOS 行動應用程式
- 播放收藏內容
- Google Entertainment Space
- iOS 裝置 (整合 REST API)。
Engage SDK 是否適用於「繼續觀看」功能？
可以，Engage SDK 支援「繼續觀看」列的內容，但必須與 Engage 整合。
所有人都能使用 Engage 嗎？
Engage 會分階段推出。
- 搶先體驗：我們最初會透過搶先體驗計畫 (EAP)，授予特定合作夥伴存取權。
- 擴大存取權：我們正努力讓所有開發人員都能使用 Engage，敬請期待。
為確保順利推出，我們已採取防護措施來管理推出作業，包括在 Engage 端建立許可清單，以及在 Engage SDK 中進行個別檢查。無論您是 EAP 合作夥伴，還是即將加入，都請與我們聯絡，以便在您開始整合 Engage SDK 前設定存取權。
建議提供多大的圖片？
有了這份新的 API 說明文件，Google 伺服器是否會從用戶端提取「繼續觀看」資料，並反映在所有裝置上？
新版 API 針對「繼續觀看」列的內容進行大幅改良，包括：
在 Google TV 上享受無縫體驗：使用者可以在一部 Google TV 上開始觀看內容，然後在登入相同帳戶的任何其他 Google TV 上繼續觀看。這項功能也適用於舊版 Android TV。
整合行動應用程式：在 Android 和 iOS 裝置上，Google TV 行動應用程式會顯示 Engage 的內容，讓使用者在電視和行動裝置之間輕鬆切換。
提升使用者留存率：即使在未安裝應用程式或使用者未登入的裝置上，繼續觀看列中的內容也能吸引使用者再次使用應用程式，進而提升留存率。
擴展至其他平台：參與度廣告活動會擴展至其他 Google 媒體平台，例如 Android、Play 收藏、平板電腦，以及 Android 上的其他 Google 媒體應用程式和途徑，盡可能提高使用者在各裝置上的參與度。
我可以發布到延續叢集的實體數量上限是多少？
每個開發合作夥伴最多可在接續叢集中播送 5 個實體。這項限制是為了在 Google TV 的「繼續觀看」列中公平分配內容，因為這是多個媒體供應商共用的空間。
如果嘗試發布超過 5 個實體，會發生什麼事？
如果超過 5 個實體，Engage SDK 會拒絕發布要求。您必須減少要求中的實體數量，才能順利發布。您應只納入使用者停止觀看的實體，因此在大多數情況下，這類實體只會有幾個。如果這類實體超過 5 個，您可以選擇發布最近的實體。
為什麼實體數量設有限制？
Google TV 的「繼續觀看」列會顯示各種媒體供應商的內容，但每個供應商的實體數量有限，確保使用者能從所有喜愛的來源看到多元的內容，進而獲得公平且均衡的使用者體驗。
驗證應用程式相關問題
提交應用程式前，是否必須先使用驗證應用程式測試？
是，提交 APK 前，請務必先使用驗證應用程式測試應用程式。
我們瞭解您可能對導入作業很有把握，但 Engage 整合包含許多複雜的元件。驗證應用程式可做為安全網，及早發現潛在問題，從長遠來看，可為您節省寶貴的時間和精力。
這項檢查就像快速健康檢查，有助於確保順利發布，並提供優質的使用者體驗。
事先找出並解決問題，即可避免遭到拒絕和重新提交的挫敗感。
提交 APK 時，請附上螢幕截圖，證明應用程式已通過驗證程序。
整合期間應留意哪些常見錯誤？
驗證應用程式的設計宗旨，是為了找出 Engage 整合的潛在問題。以下是開發人員經常遇到的常見錯誤：
所有內容類型 (電影、電視節目、直播、短片)：
- 缺少連結：請確認你為內容提供有效的平台專屬 URI (連結)。這些連結會告知系統在各個平台上尋找內容的位置。
- 缺少標題：請務必為所有內容加上標題，方便使用者辨識觀看的內容。
- 圖片顯示比例：確認與內容相關聯的所有圖片顯示比例都接近 16:9。確保圖片在不同螢幕上都能正確顯示。
電視劇集：
- 完整劇集資訊：請務必加入節目名稱、劇集和季別號碼。這有助於整理集數，並讓使用者在系列中瀏覽。
- 準確的播放位置：請再次確認上次播放位置是否小於或等於集數總長度。確保使用者從正確的位置繼續觀看。
電影：
- 準確的播放位置：與電視節目類似，請確認上次播放位置是否正確。
直播影片：
- 廣播者資訊：直播活動應包含廣播者名稱。
短片：
- 創作者資訊：指定短片的創作者。
提醒您，驗證應用程式會標示這些問題，讓您在提交應用程式前修正問題，節省時間並確保使用者享有更流暢的體驗。
帳戶和個人資料問題
我的應用程式使用匿名使用者登入，Engage 仍需要 AccountProfile 嗎？
AccountProfile適用於使用個別使用者帳戶的應用程式。
不過，我們瞭解部分應用程式 (例如您的應用程式) 可能依賴匿名登入。
在這種情況下，Engage 的運作方式如下：
AccountProfile在技術上是必要條件，但即使應用程式沒有使用者帳戶系統，您仍可整合 Engage。- 僅限在裝置端使用：Engage 的跨裝置功能需要辨識不同裝置上的使用者，由於匿名登入不會提供這項資訊，這項功能僅限使用者目前的裝置使用。
- 如何設定：如要設定這項功能，請停用跨裝置同步功能，確保接續項目只會顯示在開始觀看內容的特定裝置上。
總結：雖然您可以將 Engage 與匿名登入功能整合，但使用者只能在同一部裝置上繼續觀看內容。
即使應用程式同時支援 accountId 和 profileId，我是否仍可只使用 AccountProfile 和 accountId，而不使用 profileId？
AccountProfile 需要 accountId 和 profileId 才能正常運作。
原因如下：
- 一致的識別資訊：
accountId用於識別使用者，profileId則用於區分使用者帳戶中的不同設定檔 (如適用)。同時提供這兩項資訊，可確保 Engage 準確追蹤及顯示每個設定檔的內容。 - 避免發生錯誤：在不同 API 呼叫中不一致地使用
accountId和profileId，可能會導致非預期的行為和錯誤。舉例來說，如果您在將內容新增至 Engage 時同時加入這兩者，但刪除內容時只使用accountId，系統可能無法正確識別並移除預期項目。
使用 Engage 時是否需要 profileId？
accountId為必填欄位，用於識別跨裝置的使用者。profileId是提供良好使用者體驗的關鍵。雖然技術上是選用項目，但如果服務支援多個設定檔 (例如許多串流服務)，強烈建議使用profileId。為什麼這點很重要？ 如果沒有profileId，繼續觀看列可能會顯示同一帳戶中其他設定檔的內容。這可能會導致使用者感到困惑和沮喪。- 簡而言之：提供
profileId可確保「繼續觀看」列顯示的內容，能準確反映每位使用者的觀看記錄。除非您的應用程式不支援帳戶中的設定檔概念，否則請提供這項資訊。
Google 如何使用profileId？
如果服務提供不同的觀看內容設定檔，系統會使用 accountId 和 profileId，將裝置上觀看的內容與裝置上登入的 Google 帳戶建立關聯。Google 會根據 accountId 和 profileId 的組合記錄「繼續觀看」資料。任何登入相同 Google 帳戶的 Google 裝置，都會在「繼續觀看」列中，從相同關聯的 accountId 和 profileId 取得最新更新資料。
導入 Engage 時是否需要連結帳戶？
不需要連結帳戶。這項 API 的優先順序已降低，所有相關用途都將由新的 Device Entitlements API 涵蓋。
跨裝置同步問題
使用者同意後，「跨裝置同步」是什麼意思？
如果使用者同意「在裝置間同步」，他們觀看的內容就會儲存到 Google TV 伺服器，讓他們在任何已登入帳戶的裝置上，都能無縫接續觀看。如果未取得同意聲明，觀看記錄只會儲存在目前的裝置上。
我們可以將「在所有裝置上保持同步」設為 false 嗎？
setUserConsentToSyncAcrossDevices 旗標可控管使用者裝置 (電視、手機、平板電腦等) 間的 ContinuationCluster 資料是否同步。如果將這個旗標設為 false，系統只會在同一部裝置上顯示「繼續觀看」內容。
為充分運用跨裝置功能，我們強烈建議應用程式取得使用者同意聲明，並將 SyncAcrossDevices 設為 true。
如何在非 Android 裝置上取得使用者同意聲明，以分享觀看記錄
裝置？非 Android 裝置會將哪些資料點分享至第三方伺服器？
系統會在使用者層級 (設定檔或帳戶層級) 收集同意聲明。取得同意聲明後，即可將根據參與度產生的「繼續觀看」酬載傳送至任何位置，讓 Google 在使用者部分或下次參與的所有實體上，反映使用者在任何裝置上的無所不在續播狀態 (不必在每個裝置或平台上重新要求同意聲明)。合作夥伴會傳送與設定檔 ID (已存放在 Android 裝置上) 相關聯的使用者最新續看狀態 (依據規格)。
REST API 問題
是否有 REST API 說明文件？
REST API 預計於 2025 年 3 月推出，詳情請參閱 Engage 開發人員說明文件。
舊版「接下來請看」問題
Engage 會取代 Watch Next API 嗎？
所有支援 Watch Next API 的 Android TV 裝置，都可回溯相容 Engage。如要在 Google TV 和其他支援 Engage 的途徑上整合內容，開發人員應使用 Engage SDK。
測試與整合問題
LastPlayBackPositionTimeMillis 和 duration 有何不同？
LastPlayBackPositionTimeMillis 應反映使用者停止觀看時的播放時間長度 (以毫秒為單位)，例如 10 分 5 秒的長度應為 605000 毫秒。這個值絕不能大於實體的總長度。
而 LastEngagementTime 則是使用者上次與內容互動的時間戳記。
我們應該執行哪些測試案例？
以下是我們 QA 執行的 Google TV 測試案例。您也可以在其他介面上執行類似的測試案例。
- 觀看長度超過 20 分鐘的影片約 5 分鐘，然後離開應用程式。繼續觀看列中應會顯示影片資訊卡。注意：繼續觀看列中每個第三方應用程式只會顯示 5 張資訊卡。
- 選取「繼續觀看」列中新顯示的資訊卡，影片應會從上次的播放位置繼續播放。注意：新舊內容都會從上次的播放位置繼續播放
- 變更 Google TV 裝置上的帳戶後，繼續觀看列中的卡片應該也會隨之變更。系統只會顯示目前帳戶的影片。目前依近期順序排序。第三方應用程式設定檔 CW 會混雜在一起。注意：GoogleAccount2 的 CW 會顯示 GoogleAccount2 參與觀看的第三方內容
- 使用「返回」按鈕離開應用程式 > 確認「繼續觀看」列中顯示資訊卡
- 隱藏「繼續觀看」列中的影片，確認影片不會再次顯示。測試隱藏的內容是否會在 24 小時後仍處於隱藏狀態，即使應用程式在 24 小時後開啟也一樣。確認隱藏一個項目不會隱藏多個項目。
- 「繼續觀看」列中的內容提供完整中繼資料：資訊卡圖片、應用程式名稱、標題、電視內容的季別集數
- 進度列會顯示「檢查進度」
- 使用者觀看內容直到片尾字幕結束，但內容不會顯示在「繼續觀看」列中
- 確認「繼續觀看」列中沒有未觀看的項目
- 確認 CW 項目是否依觀看活動發生時間排序，而非依應用程式上次開啟時間或上次日期排序
- 確認 CW 資訊卡上的劇集和季別詳細資料，與在劇集內容中觀看的內容相符
- 確認已完成的項目 (片尾或片尾後) 不會顯示在「繼續觀看」列中
- 在觀看劇集/電影與電視節目時關閉裝置。在觀看劇集/電影與電視節目到一半時關閉裝置。確認開啟裝置和其他電視時，CW 會在正確位置顯示正確的資訊卡和進度列
- 完整觀看第 1 集後關閉裝置，確認
- 第 1 集發布後，不會再顯示在「繼續觀看」列中 [在第二部裝置上，以及開啟測試裝置時]
- 第 2 集 (如有)，應會顯示在「繼續觀看」列中 [在第二部裝置上，以及開啟測試裝置時]
- 情境一：TV1：Google 帳戶：媽媽，第三方帳戶 / 設定檔：帳戶 1/設定檔 1。觀看內容，並確認 CW 資料顯示 3P 帳戶 1/設定檔 1 觀看的內容
TV2：Google 帳戶：媽媽。驗證第一個情境的 CW 資料。現在請以其他帳戶登入第三方應用程式。第三方帳戶 / 設定檔：account_2/profile_2。觀看內容，並確認 CW 資料顯示 3p 帳戶 2/設定檔 2 觀看的內容
Google 帳戶：媽媽。新裝置案例 /未安裝第三方應用程式。在新裝置上(還原原廠設定)，驗證 CW 是否顯示 Google 帳戶上次使用的第三方應用程式資料。注意：如果 GAIA 尚未與其他裝置上的第三方設定檔建立關聯，CW 列就不應顯示第三方內容
- Google 帳戶：媽媽。新裝置充電盒 /已安裝第三方應用程式，但未登入。在新裝置上(還原原廠設定)，驗證 CW 會顯示 Google 帳戶上次使用的第三方應用程式資料。
-
- 注意：如果 Google 帳戶尚未與第三方設定檔建立關聯，「繼續觀看」列就不應顯示第三方內容
Google TV iOS 應用程式未顯示續播內容，這是怎麼回事？
如要在 iOS 裝置的「繼續觀看」列中顯示內容，請傳送 iOS 深層連結。
我應該多久更新一次「繼續觀看」列的內容資訊？是否應該頻繁更新，例如每 15 秒更新一次？
不建議經常更新。原因如下：
- 效能影響：持續傳送更新會對伺服器造成不必要的負擔，可能導致系統效能降低。
- 不必要的資料：使用者觀看影片時，播放位置會不斷變更。每隔幾秒傳送更新會產生大量多餘資料，對繼續播放沒有幫助。
何時更新「繼續觀看」列的內容資訊：
請著重於擷取使用者觀看進度的重大變化。以下是主要情境：
- 暫停或停止播放：使用者暫停或停止觀看時，請傳送更新內容，儲存目前的位置。
- 應用程式關閉或在背景執行：如果使用者在觀看影片時離開應用程式或切換到其他應用程式，請傳送更新來儲存進度。
- 使用者從應用程式的「繼續觀看」媒體列中移除項目時
如何有效率地更新：
請改用影片播放器或應用程式生命週期中的事件觸發更新，而非定時更新。例如：
onPause、onStop：影片播放暫停或停止時。onAppClose、onAppBackgrounded：應用程式關閉或移至背景時。
只要遵循這些規範，就能確保資源得到有效運用，同時為使用者提供流暢的「繼續觀看」列體驗。