Engage SDK 常見問題

發布常見問題

誰負責管理內容發布工作？

應用程式開發人員會管理內容發布工作，並將要求傳送至 Engage Service。這樣一來，開發合作夥伴就能進一步控管向使用者發布內容的時機和方式，避免頻繁地喚醒合作夥伴應用程式進行內容發布。

開發人員需要發布所有叢集類型嗎？

雖然開發人員可以只發布一個叢集，但我們強烈建議加入更多叢集。否則，開發人員會錯失吸引使用者與內容互動的機會。強烈建議您發布每個類別的所有叢集類型。

應用程式執行期間，開發合作夥伴應多久透過工作管理員發布資料一次？

這由開發合作夥伴決定。Google 建議您每天發布一次或兩次一般推薦內容，並使用事件驅動方法處理購物車、重新訂購和其他接續內容 (例如，將 worker 設為使用者將商品加入購物車或使用者中途停止觀看電影的回呼)。對於社群應用程式，請務必在每次使用應用程式後發布更新的推薦叢集。社群應用程式使用者較感興趣的是最新的推薦內容，理想情況下，他們最多只想看到一次貼文。

開發人員何時應呼叫刪除 API？

只有在沒有可發布的內容時，才應呼叫刪除 API。請勿接連呼叫刪除 API 和發布 API 來取代內容；發布 API 會自動移除先前的內容。

廣播意圖常見問題

為什麼 Android 應用程式開發人員需要註冊廣播意圖？

為了向使用者提供最新內容，您應該使用廣播意圖，在使用者可能不會常使用應用程式時觸發資料同步作業。

無法測試廣播意圖

驗證應用程式不支援使用權限測試廣播意圖。您必須在測試期間移除權限，然後再將 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 時，可能會遇到以下錯誤：

深層連結已與套件名稱建立關聯。使用 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 常見問題

一般問題

什麼是「繼續觀看」2.0 版？

繼續觀看 2.0 (Video Discovery API) 可讓使用者從上次中斷的地方繼續觀看，體驗更上一層樓！這項重大升級可讓觀眾在更多裝置上流暢地繼續觀看內容。想像一下，你在 Google TV 上開始觀看電影，然後在通勤途中輕鬆透過手機繼續觀看，這就是「繼續觀看」2.0 版的強大功能。

這套新系統旨在透過在整個 Google 生態系統中提供流暢無礙的體驗，提升觀眾的參與度和留存率。

使用「繼續觀看 2.0」有哪些優點？

答案：無論觀眾使用何種裝置，都能透過「繼續觀看 2.0」輕鬆繼續觀看內容。運作方式如下：

  • 跨 Google 服務無縫體驗：在 Google TV 上開始觀看，然後在 Android 手機、iPhone 或 Android 平板電腦上繼續觀看。甚至可用於尚未安裝應用程式的裝置！
  • 提高參與度和留存率：繼續觀看 2.0 可協助使用者返回您的應用程式，即使是新裝置也一樣。讓使用者繼續觀看喜愛的節目，可提高他們繼續觀看的機會。
  • 觸及範圍更廣：除了 Google TV 之外，「繼續觀看」2.0 也適用於其他 Android 媒體體驗，例如 Play Cube 和其他 Google 媒體應用程式。
  • 向後相容：如果你已經在使用舊版的「Watch Next」功能，沒問題！Continue Watching 2.0 支援向下相容性，因此現有的整合功能仍可正常運作。

重要注意事項：所有新的「繼續觀看」整合功能都必須使用「繼續觀看」2.0 版。舊版「跨裝置播放下一個」系統正在逐步淘汰。

哪些途徑支援「繼續觀看」2.0 版？

  1. Google TV
  2. Android TV (僅限裝置端，但支援 Engage SDK)
  3. Google TV Android 行動應用程式
  4. Google TV iOS 行動應用程式
  5. Play Cubes
  6. Google 娛樂空間
  7. iOS 裝置 (已整合 REST API)。

是否有專門用於 Continue Watching 2.0 的 Engage SDK？

是的，Engage SDK 適用於繼續觀看 2.0。必須與 Continue Watching 2.0 整合。

所有人都可使用「繼續觀看」2.0 嗎？

我們正在分階段推出「繼續觀看 2.0」。

  • 搶先體驗：我們會透過搶先體驗計畫 (EAP)，向特定合作夥伴授予存取權。
  • 擴大存取權：我們正在努力讓「繼續觀看」2.0 盡快開放給所有開發人員使用。

為了順利推出，我們已採取保護措施來管理這項作業。這包括 Continue Watching 2.0 端的許可清單，以及 Engage SDK 中的個別檢查。無論您是 EAP 合作夥伴，還是希望盡快加入，請與我們聯絡，我們會在您開始整合 Engage SDK 前設定存取權限。

我們已更新「建立實體」部分的圖片規定。

有了這個新的 API 說明文件，Google 伺服器會從用戶端擷取繼續觀看資料，並反映在所有裝置上嗎？

新版 API 可為繼續觀看功能帶來多項重要優勢，包括：

  • 跨 Google TV 的無縫體驗：使用者可以在一台 Google TV 上開始觀看，然後在登入相同帳戶的任何其他 Google TV 上繼續觀看。這項功能也適用於舊版 Android TV。

  • 行動應用程式整合：「繼續觀看」功能適用於 Android 和 iOS 版 Google TV 行動應用程式，使用者可在電視和行動裝置之間順暢切換。

  • 提升使用者回訪率：即使在未安裝應用程式或使用者未登入的裝置上，繼續觀看功能也會提示使用者再次使用應用程式，進而提升回訪率。

  • 擴展至其他平台：這項整合功能可將「繼續觀看」功能擴展至其他 Google 媒體平台，例如 Android、Play Cube、平板電腦和其他 Android 上的 Google 媒體應用程式和介面，藉此在各裝置上盡可能提高使用者參與度。

我可以發布至接續叢集的實體數量有上限嗎？

每個開發合作夥伴最多可在接續叢集中播送 5 個實體。這項限制適用於 Google TV 的「繼續觀看」列，這是多個媒體供應商共用的空間，用於公平分配內容。

如果我嘗試發布超過 5 個實體，會發生什麼事？

如果超過 5 個實體的上限，EngageSDK 會拒絕您的發布要求。您必須減少要求中的實體數量，才能順利發布。您應該只納入使用者未看完的實體，因此在大多數情況下，這類實體的數量都會很少。如果有超過 5 個這類實體，您可以選擇較新的實體進行發布。

為什麼實體數量有限制？

Google TV 的「繼續觀看」列會顯示不同媒體供應商的內容。限制每個供應商的實體數量，讓使用者能從所有喜愛的來源看到多元化的內容，提供公平且平衡的使用者體驗。

驗證應用程式相關問題

提交應用程式前，是否必須使用驗證應用程式進行測試？

是的，在提交 APK 前，請務必使用驗證應用程式測試應用程式。

雖然我們瞭解您可能對導入方式很有信心，但繼續觀看 2.0 整合功能包含許多複雜的元件。驗證應用程式可做為安全網，及早找出潛在問題，讓您省下寶貴的時間和精力。

這項檢查可快速確認應用程式是否能順利推出，並提供良好的使用者體驗。

事先找出並解決任何問題，就能避免因遭拒而必須重新提交的挫折感。

如要提交 APK，您必須附上螢幕截圖，證明應用程式已通過驗證程序。

#### 整合時，有哪些常見錯誤需要留意？

驗證應用程式旨在找出 Continue Watching 2.0 整合作業的潛在問題。以下是開發人員常犯的錯誤：

所有內容類型 (電影、電視劇集、直播、短片)：

  • 缺少連結：請務必為內容提供有效的平台專屬 URI (連結)。這些連結會告訴系統，在各個平台上要到哪裡才能找到你的內容。
  • 缺少標題：請務必為所有內容加上標題。這有助於使用者辨識自己觀看的內容。
  • 圖片顯示比例：確認與內容相關的所有圖片顯示比例皆接近 16:9。這樣可確保圖片在不同螢幕上正確顯示。

電視劇集：

  • 完整的單集資訊：請務必加入節目名稱、集數和季別。這有助於整理劇集，並讓使用者在系列節目中瀏覽。
  • 準確的播放位置：請仔細檢查上次播放位置是否小於或等於該集數的總長度。這可確保使用者從正確的位置繼續觀看。

電影：

  • 準確的播放位置：與電視劇集類似，請確認上次播放的位置正確無誤。

直播影片：

  • 直播主資訊：請在直播中加入直播主名稱。

短片：

  • 創作者資訊：指定短片的創作者。

提醒您：驗證應用程式會標示這些問題，讓您在提交應用程式前予以修正，進而節省時間，並確保使用者享有更流暢的體驗。

帳戶和個人資料問題

我的應用程式使用匿名使用者登入功能。是否仍需要 AccountProfile 才能使用 Continue Watching 2.0？

AccountProfile 適用於使用個別使用者帳戶的應用程式。不過，我們瞭解您應用程式等部分應用程式可能會使用匿名登入功能。以下說明繼續觀看 2.0 版在此情境中的運作方式：

  • 技術上來說，您必須使用 AccountProfile，但即使應用程式沒有使用者帳戶系統，您還是可以整合 Continue Watching 2.0。
  • 僅限於裝置端使用：繼續觀看 2.0 的跨裝置功能仰賴於在不同裝置上識別使用者。由於匿名登入不提供此資訊，因此這項功能僅限於使用者目前的裝置。
  • 設定方式：如要設定這項功能，您必須停用跨裝置同步處理功能。這樣一來，接續觀看項目就只會顯示在開始觀看內容的特定裝置上。

總結來說，雖然您可以將「繼續觀看 2.0」與匿名登入整合，但使用者只能在同一部裝置上繼續觀看內容。

即使應用程式同時支援 accountId 和 profileId，我是否可以只使用 accountId 來使用 AccountProfile？

AccountProfile 需要同時具備 accountId 和 profileId，才能正常運作。原因如下：

  • 一致的識別資訊：accountId 可識別使用者，而 profileId 可區分該使用者帳戶中的不同設定檔 (如適用)。提供這兩項資訊，可確保「繼續觀看」功能能正確追蹤及顯示各個個人資料的內容。
  • 避免錯誤：在不同 API 呼叫中使用不一致的 accountId 和 profileId，可能會導致非預期的行為和錯誤。舉例來說，如果在新增內容至「繼續觀看」時同時使用這兩個參數，但在刪除內容時只使用 accountId，系統可能無法正確識別及移除指定項目。

是否需要使用 profileId 才能使用 Continue Watching 2.0？

  • 必須提供 accountId。這可在多部裝置上識別使用者。
  • profileId 對於提供良好的使用者體驗至關重要。雖然從技術層面來說，profileId 屬於選用值，但如果您的服務支援多個設定檔 (許多串流服務都支援)，強烈建議您使用 profileId。為什麼這麼重要？由於沒有 profileId，繼續觀看功能可能會顯示同一帳戶中其他個人資料的內容。這可能會讓使用者感到困惑和沮喪。
  • 簡而言之：提供 profileId 可確保「繼續觀看」功能能準確反映每位使用者的觀看記錄。除非您的應用程式不支援帳戶內的設定檔概念，否則應提供設定檔。

Google 如何使用自家的 profileId？

如果服務提供不同的個人資料來觀看內容，系統會使用 accountId 和 profileId 將裝置上觀看的內容與裝置上已登入的 Google 帳戶建立關聯。Google 會根據 accountId-profileId 組合記錄 ContinueWatching 資料。任何登入相同 Google 帳戶的 Google 裝置，都會從「繼續觀看」列中的相同關聯 accountId-profileId 取得最新更新的資料。

是否必須連結帳戶才能導入「繼續觀看」2.0 版？

不需要連結帳戶。這項 API 的優先順序正在降低，所有相關用途都將由新的 Device Entitlements API 涵蓋。

跨裝置同步處理問題

使用者同意「跨裝置同步」後，他們正在觀看的內容就會儲存在 Google TV 伺服器中，讓他們在任何已登入的裝置上，都能無縫接續觀看。未經同意的情況下，觀看記錄會保留在目前裝置的本機。

我們可以將「在所有裝置上保持同步」設為「否」嗎？

UserConsentToSyncAcrossDevices 標記可控制是否要跨裝置 (電視、手機、平板電腦等) 同步處理使用者的 ContinuationCluster 資料。如果此標記設為 false，則只會在同一部裝置上繼續觀看。

為充分運用跨裝置功能，我們強烈建議您的應用程式取得使用者同意，並將 SyncAcrossDevices 設為 true。

裝置嗎？非 Android 裝置會將哪些資料點分享給第三方伺服器？

同意聲明是在使用者層級 (設定檔或帳戶層級) 收集。取得同意聲明後，系統就能在任何裝置上，根據使用者與部分或下一個參與實體的互動，在任何地方傳送持續觀看酬載，讓 Google 反映使用者的 Ubiquitous 續播狀態。如此一來，您就不必在每個裝置或平台上重新要求同意聲明。合作夥伴會傳送與設定檔 ID (已儲存在 Android 裝置上) 相關聯的使用者最新繼續觀看狀態 (依規格說明)。

REST API 問題

是否有 REST API 的說明文件？

REST API 的推出時間表為 2025 年 3 月，詳情請參閱「Continue Watching 2.0」開發人員說明文件。

舊版「接下來請看」問題

Video Discovery API 是否會取代 Watch Next API？

在支援 Watch Next API 的所有 Android TV 裝置上，Video Discovery API 都會提供回溯相容性。所有開發人員都應使用 Video Discovery API (繼續觀看 2.0) 發布至「繼續觀看」列。

測試和整合問題

LastPlayBackPositionTimeMillis 和 duration 有何差異？

LastPlayBackPositionTimeMillis 應反映使用者停止觀看的播放時間長度 (以毫秒為單位)，10 分 5 秒為 605000 毫秒)。不得超過實體的總時間。

而 LastEngagementTime 則是使用者上次與內容互動時的時間戳記。

我們應該執行哪些測試案例？

以下是品質確保團隊執行的 Google TV 測試案例。您也可以在其他介面上執行類似的測試案例。

  1. 觀看長度超過 20 分鐘的影片約 5 分鐘。退出應用程式。資訊卡應顯示在「繼續觀看」列中。注意：在 CW 中，每個第三方應用程式最多只能顯示 5 張資訊卡
  2. 選取「繼續觀看」列中新出現的資訊卡後，系統應會從影片中正確的位置繼續播放影片。注意：任何新內容或舊內容都應從上次停止播放的位置繼續播放
  3. 在 GTV 裝置上變更帳戶後，繼續觀看列中的資訊卡應會隨之變更。系統只會顯示目前帳戶的影片。依最近的順序排列。第三方應用程式設定檔 CW 將會混合。注意：GoogleAccount2 的 CW 會顯示 GoogleAccount2 曾觀看的第三方內容
  4. 使用「返回」按鈕離開應用程式 > 驗證卡片會顯示在「繼續觀看」列
  5. 隱藏「繼續觀看」列中的影片，如果隱藏的內容在 24 小時後仍處於隱藏狀態，甚至在應用程式在 24 小時後開啟後仍處於隱藏狀態，則不應再顯示。確認隱藏一個項目不會隱藏多個項目。
  6. 「繼續觀看」中的內容可用性，含完整中繼資料：資訊卡圖片、應用程式名稱、標題、電視內容的季別和集數
  7. 進度列中顯示「Check Progress」
  8. 使用者觀看內容至結尾字幕 - 內容未顯示在「繼續觀看」中
  9. 確認「繼續觀看」列中沒有未觀看的項目
  10. 確認 CW 項目是依照觀看活動發生的時間排序，而非應用程式上次開啟或上次使用日期
  11. 確認 CW 資訊卡中的劇集和季別資料，與劇集內容中觀看的內容相符
  12. 確認已完成的項目 (片尾字幕或之後的項目) 不會顯示在「繼續觀看」中
  13. 在觀看劇集/電影/節目到一半時關閉裝置。「在觀看劇集/電影/節目到一半時關閉裝置。確認開啟裝置和其他電視時，CW 會在正確的位置顯示正確的資訊卡和進度列
  14. 在看完第 1 集後關閉裝置，並確認
  15. 第一集下架，且不會再出現在「繼續觀看」列中 [在第二部裝置上，以及在開啟測試裝置時]
    1. 第 2 集 (如有) 應顯示在「繼續觀看」列中 [在第二部裝置上，以及在開啟測試裝置時]
  16. 第一種情況：TV1：Google 帳戶：媽媽、3P 帳戶 / 設定檔：帳戶 1/profile_1。觀看內容並驗證 CW 資料是否顯示 3P account_1/profile_1 觀看的內容

  17. TV2：GoogleAccount: mom. 驗證第一個情境中的 CW 資料。接著，以其他帳戶登入第三方應用程式。3p 帳戶 / 設定檔：account_2 / profile_2。觀看內容並驗證 CW 資料是否顯示 3p account_2/profile_2 觀看的內容

  18. GoogleAccount：mom. 未安裝新的裝置外殼 /第三方應用程式。在新的裝置上(FDR 裝置)，驗證 CW 會顯示 GoogleAccount 上次使用的第三方應用程式資料。注意：如果 GAIA 尚未與其他裝置上的第三方設定檔建立關聯，CW 列不應顯示第三方內容

    1. GoogleAccount：mom. 安裝新裝置 /第三方應用程式，但未登入。在新的裝置上(FDR 裝置)，Verify CW 會顯示 GoogleAccount 上次使用的第三方應用程式資料。
    1. 注意：如果 Google 帳戶尚未與第三方個人資料建立關聯，則「繼續觀看」列不應顯示第三方內容

Google TV iOS 應用程式中沒有顯示「繼續觀看」功能，發生什麼問題？

您必須傳送 iOS 深層連結，才能在 iOS 裝置上顯示「繼續觀看」功能。

我應該多久更新一次「繼續觀看」資訊？我是否應該經常更新「繼續觀看」資訊，例如每 15 秒更新一次？

否，我們不建議頻繁更新。原因如下：

  • 效能影響：持續傳送更新會對我們的伺服器造成不必要的負擔，可能會讓系統速度變慢。
  • 不必要的資料：使用者正在觀看時，播放位置會不斷變更。每隔幾秒就傳送更新會產生大量重複資料，這對恢復播放功能沒有幫助。

更新「繼續觀看」資訊的時機：

請專注於擷取使用者觀看進度中的重大變化。以下是主要情況：

  • 播放已暫停或停止：當使用者暫停或停止觀看時，請傳送更新內容，儲存使用者目前的位置。
  • 應用程式已關閉或處於背景狀態：如果使用者在觀看影片時退出應用程式或切換至其他應用程式，請傳送更新內容來儲存進度。
  • 使用者從應用程式內的「繼續觀看」列中移除項目時

如何有效更新：

請利用影片播放器或應用程式生命週期中的事件，觸發更新，而非依時更新。例如：

  • onPause、onStop：影片播放暫停或停止時。
  • onAppClose、onAppBackgrounded：應用程式關閉或移至背景時。

遵循這些規範，即可確保資源使用效率，同時為使用者提供流暢的「繼續觀看」體驗。