發布常見問題
誰負責管理內容發布工作？
應用程式開發人員會管理內容發布工作，並將要求傳送至 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 支援的內容實體類型不限於影片，因此這項整合功能不再稱為「影片探索」。
使用 Engage 有哪些好處？
答案：無論觀眾使用何種裝置，都能透過 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 行動應用程式
- Play 收藏
- Google 娛樂空間
- 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。
行動應用程式整合：Engage 的內容會顯示在 Android 和 iOS 版 Google TV 行動應用程式中，讓使用者在電視和行動裝置之間流暢切換。
提高使用者留存率：即使裝置未安裝應用程式或使用者未登入，繼續觀看列中的內容仍可鼓勵使用者重新與應用程式互動，進而提高留存率。
擴展至其他平台：Engage 擴展至其他 Google 媒體平台，例如 Android、Play 收藏、平板電腦，以及 Android 上的其他 Google 媒體應用程式和介面，盡可能提高跨裝置的使用者參與度。
我可以發布至 Continuation 叢集的實體數量上限為何？
每個開發人員合作夥伴在接續叢集中最多只能有 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，我是否可以只使用 accountId，而不使用 profileId 建立 AccountProfile？
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 的組合記錄 ContinueWatching 資料。只要登入同一個 Google 帳戶，任何 Google 裝置都會在「繼續觀看」列中，取得與同一個 accountId 和 profileId 相關聯的最新資料。
是否需要連結帳戶才能導入 Engage？
不需要連結帳戶。這項功能已不再優先使用，所有相關用途將由新的 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 是否會取代「接著看」API？
Engage 可回溯相容於所有支援「接著看」API 的 Android TV 裝置。如要在 Google TV 和其他支援 Engage 的途徑上整合，開發人員應使用 Engage SDK。
測試與整合問題
LastPlayBackPositionTimeMillis 和 duration 有何差異？
LastPlayBackPositionTimeMillis 應反映使用者停止觀看時的播放時間長度 (以毫秒為單位，例如 10 分 5 秒為 605000 毫秒)。不得大於實體的總時間長度。
LastEngagementTime 則是使用者上次與內容互動的時間戳記。
我們應該執行哪些測試案例？
以下是品質確保團隊執行的 Google TV 測試案例。其他介面也可以執行類似的測試案例。
- 觀看長度超過 20 分鐘的影片，時間約 5 分鐘。退出應用程式。影片資訊卡應會顯示在「繼續觀看」列中。注意： 在 CW 中，每個第三方應用程式只會顯示 5 張資訊卡
- 在「繼續觀看」列中選取新顯示的資訊卡，應會從影片中的正確位置繼續播放。注意：無論是新內容或舊內容，都應從上次中斷的位置繼續播放
- 在 GTV 裝置上變更帳戶後，「繼續觀看」列中的卡片應會隨之變更。系統只會顯示目前帳戶的影片。依近期順序排序。第三方應用程式設定檔 CW 將混合。注意：GoogleAccount2 的「繼續觀看」會顯示 GoogleAccount2 觀看過的第三方內容
- 按下「返回」按鈕退出應用程式 > 確認資訊卡顯示在「繼續觀看」列中
- 隱藏「繼續觀看」列中的影片，該影片不應再次顯示。測試隱藏的內容是否在 24 小時後仍保持隱藏狀態，即使在 24 小時後開啟應用程式也一樣。確認隱藏一個項目不會隱藏多個項目。
- 「繼續觀看」列中顯示的內容，附有完整中繼資料：資訊卡圖片、應用程式名稱、標題、電視內容的季別和集數
- 進度列會顯示「查看進度」
- 使用者觀看內容直到片尾字幕，內容不會顯示在「繼續觀看」列
- 確認「繼續觀看」列中沒有未觀看的項目
- 確認 CW 項目是按照觀看活動發生的時間排序，而不是按照上次開啟應用程式的時間或最後一天排序
- 確認「繼續觀看」資訊卡上的集數和季別詳細資料，與觀看的劇集內容相符
- 確認已看完的項目 (播放到片尾字幕或之後) 不會顯示在「繼續觀看」列中
- 在觀看劇集/電影/節目時，中途關閉裝置。「在觀看劇集/電影/節目時，中途關閉裝置。開啟裝置和其他電視，確認 CW 顯示正確的資訊卡、位置和進度列」
- 看完第 1 集後關閉裝置，確認
- 第 1 集消失，且不會重新出現在「繼續觀看」列中 [在第二部裝置上，以及開啟測試裝置時]
- 第 2 集 (如有) 應顯示在「繼續觀看」列中 [在第二部裝置上，以及開啟測試裝置時]
- 情境 1：電視 1：Google 帳戶：媽媽，第三方帳戶/設定檔：帳戶 1/設定檔 1。觀看內容，並確認 CW 資料顯示第三方帳戶 1/設定檔 1 觀看的內容
TV2：Google 帳戶：媽媽。驗證第一個情境的 CW 資料。現在，請以其他帳戶登入第三方應用程式。第三方帳戶/設定檔：account_2/profile_2。觀看內容，並確認 CW 資料顯示 3p account_2/profile_2 觀看的內容
Google 帳戶：mom. 新裝置/未安裝第三方應用程式。在新的裝置上 (恢復原廠設定)，確認 CW 顯示 Google 帳戶上次使用的第三方應用程式資料。注意：如果 GAIA 尚未與其他裝置上的第三方設定檔建立關聯，CW 列不應顯示第三方內容
- Google 帳戶：mom. 新裝置/已安裝第三方應用程式，但未登入。 在新裝置上 (恢復原廠設定)，確認 CW 顯示 Google 帳戶上次使用的第三方應用程式資料。
-
- 注意：如果 Google 帳戶尚未與第三方設定檔建立關聯，「繼續觀看」列不應顯示第三方內容
Google TV iOS 應用程式未顯示接續觀看內容，這是什麼原因？
您必須傳送 iOS 深層連結，內容才會顯示在 iOS 裝置的「繼續觀看」列中。
我應該多久更新一次「繼續觀看」列的內容資訊？我應該頻繁更新嗎？例如每 15 秒更新一次？
不建議頻繁更新。原因如下：
- 效能影響：持續傳送更新會對伺服器造成不必要的負擔，可能導致所有使用者的系統速度變慢。
- 不必要的資料：使用者觀看影片時，播放位置會不斷變更。每隔幾秒傳送一次更新會產生大量多餘資料，對恢復播放沒有幫助。
何時更新「繼續觀看」列的內容資訊：
請著重於擷取使用者觀看進度的重大變化。主要情境如下：
- 暫停或停止播放：使用者暫停或停止觀看時，請傳送更新內容，儲存目前的位置。
- 應用程式關閉或在背景執行：如果使用者在觀看影片時退出應用程式或切換至其他應用程式，請傳送更新來儲存進度。
- 使用者從應用程式的「繼續觀看」列中移除項目時
如何有效率地更新：
請改用影片播放器或應用程式生命週期中的事件來觸發更新，例如：
onPause、onStop：影片播放暫停或停止時。onAppClose、onAppBackgrounded：應用程式關閉或移至背景時。
只要遵循這些規範，就能確保有效運用資源，同時在「繼續觀看」列中為使用者提供流暢體驗。