Engage SDK 常見問題

發布常見問題

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

應用程式開發人員會管理內容發布工作，並將要求傳送至 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 常見問題

一般問題

什麼是「繼續觀看 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 Cubes 和其他 Google 媒體應用程式。
  • 向下相容：如果您已使用舊版「待播清單」功能，「繼續觀看」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 Entertainment Space
  7. iOS 裝置 (整合 REST API)。

Engage SDK 是否適用於「繼續觀看 2.0」？

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

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

「繼續觀看 2.0」功能會分階段推出。

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

為確保順利推出，我們已採取防護措施來管理推出作業。這包括「繼續觀看 2.0」端的允許清單，以及 Engage SDK 內的個別檢查。無論您是 EAP 合作夥伴，還是即將加入，請與我們聯絡，以便在您開始整合 Engage SDK 前，設定存取權。

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

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

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

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

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

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

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

我可以發布到延續叢集的實體數量上限是多少？

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

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

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

為什麼實體數量設有限制？

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

驗證應用程式相關問題

提交應用程式前，是否一定要先使用驗證應用程式測試？

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

我們瞭解您可能對實作方式很有信心，但「繼續觀看 2.0」整合功能包含許多複雜的元件。驗證應用程式就像安全網，可及早發現潛在問題，從長遠來看，能為您節省寶貴的時間和精力。

這項檢查可確保順利發布，並提供優質的使用者體驗。

事先找出並解決問題，即可避免遭到拒絕和重新提交，省去麻煩。

提交 APK 時，請附上螢幕截圖，證明應用程式已通過驗證程序。

整合期間應留意哪些常見錯誤？

驗證應用程式的設計目的是要找出「繼續觀看」2.0 整合功能可能發生的問題。以下是開發人員常犯的錯誤：

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

  • 缺少連結：請確認你為內容提供有效的平台專屬 URI (連結)。這些連結會告訴系統在各個平台上尋找你內容的位置。
  • 缺少標題：別忘了為所有內容加上標題。這有助於使用者辨識觀看的內容。
  • 圖片顯示比例：確認與內容相關聯的所有圖片顯示比例都接近 16:9。確保圖片在不同螢幕上都能正確顯示。

電視劇集：

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

電影：

  • 準確的播放位置：與電視節目類似，請確認上次播放位置是否正確。

直播影片：

  • 廣播者資訊：直播活動應包含廣播者名稱。

短片：

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

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

帳戶和個人資料問題

我的應用程式使用匿名使用者登入，繼續觀看 2.0 是否仍需要 AccountProfile？

AccountProfile 適用於使用個別使用者帳戶的應用程式。不過我們瞭解，部分應用程式 (例如您的應用程式) 可能會採用匿名登入方式。在這個情境中，「繼續觀看 2.0」的運作方式如下：

  • 從技術上來說，您必須提供 AccountProfile，但即使應用程式沒有使用者帳戶系統，仍可整合「繼續觀看」2.0。
  • 僅限在裝置上使用：繼續觀看 2.0 的跨裝置功能需要識別不同裝置的使用者。由於匿名登入不會提供這項資訊，這項功能僅限使用者目前的裝置使用。
  • 如何設定：如要設定這項功能，請停用跨裝置同步功能。這樣可確保「繼續觀看」項目只會顯示在開始觀看內容的特定裝置上。

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

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

AccountProfile 需要 accountId 和 profileId 才能正常運作。 原因如下：

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

繼續觀看 2.0 是否需要 profileId？

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

Google 如何使用他們那邊的 profileId？

如果服務提供不同的設定檔來觀看內容，accountId 和 profileId 會用來將裝置上觀看的內容與裝置上登入的 Google 帳戶建立關聯。Google 會根據 accountId-profileId 組合記錄 ContinueWatching 資料。只要登入同一個 Google 帳戶，任何 Google 裝置的「繼續觀看」列都會顯示來自相同關聯帳戶 ID/設定檔 ID 的最新更新資料。

實作「繼續觀看」2.0 時，是否需要連結帳戶？

不需要連結帳戶。這項 API 的優先順序已降低，所有相關用途都將由新的裝置授權 API 涵蓋。

跨裝置同步處理問題

如果使用者同意「跨裝置同步」，系統就會將他們觀看的內容儲存到 Google TV 伺服器，讓他們在任何已登入帳戶的裝置上，都能無縫接續上次的進度。如果未取得同意聲明，觀看記錄只會儲存在目前裝置上。

我們可以將「在裝置間同步」設為 false 嗎？

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

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

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

系統會在使用者層級 (設定檔或帳戶層級) 收集同意聲明。取得同意聲明後，即可將根據參與度產生的「繼續觀看」酬載傳送至任何位置，讓 Google 在使用者透過任何裝置與部分或後續參與的實體互動時，反映使用者無所不在的續播狀態 (不必在每個裝置或平台上重新要求同意聲明)。合作夥伴會傳送與設定檔 ID (已存放在 Android 裝置上) 相關聯的使用者最新續看狀態 (依規格)。

REST API 問題

是否有 REST API 說明文件？

REST API 預計於 2025 年 3 月推出，相關說明請參閱「繼續觀看 2.0」開發人員文件。

舊版「接著看」問題

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

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

測試與整合問題

LastPlayBackPositionTimeMillis 和 duration 有何不同？

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

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

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

以下是 Google TV 的測試案例，由我們的 QA 團隊執行。您也可以在其他介面上執行類似的測試案例。

  1. 觀看長度超過 20 分鐘的影片約 5 分鐘。退出應用程式。影片資訊卡應會顯示在「繼續觀看」列中。注意：在 CW 中，每個第三方應用程式只會顯示 5 張資訊卡
  2. 在「繼續觀看」列中選取新顯示的資訊卡，影片應會從正確的時間點繼續播放。注意：新舊內容都會從上次停止播放的位置繼續播放
  3. 變更 Google TV 裝置上的帳戶後，「繼續觀看」列中的影視內容應該也會隨之變更。系統只會顯示目前帳戶的影片。目前依近期順序排序。第三方應用程式設定檔 CW 會混雜在一起。注意：GoogleAccount2 的 CW 會顯示 GoogleAccount2 參與觀看的第三方內容
  4. 使用「返回」按鈕離開應用程式 > 確認「繼續觀看」列中顯示資訊卡
  5. 隱藏「繼續觀看」列中的影片，隱藏內容超過 24 小時後，即使應用程式在 24 小時後開啟，也不應再次顯示。確認隱藏一個項目不會隱藏多個項目。
  6. 「繼續觀看」中的內容提供完整中繼資料：資訊卡圖片、應用程式名稱、電視內容的標題和季別集數
  7. 進度列會顯示「檢查進度」
  8. 使用者觀看內容直到片尾字幕結束，但內容不會顯示在「繼續觀看」中
  9. 確認「繼續觀看」列中沒有未觀看的項目
  10. 確認 CW 項目是依據觀看活動發生時間排序，而非依據應用程式上次開啟時間或上次日期
  11. 確認 CW 卡片上的集數和季別詳細資料，與在集數內容中觀看的內容相符
  12. 確認已完成 (片尾或之後的項目) 的項目不會顯示在「繼續觀看」中
  13. 在觀看集數/電影/節目時關閉裝置。「在觀看集數/電影/節目到一半時關閉裝置。確認裝置開啟時，以及在其他電視上，CW 會在正確位置顯示正確的卡片和進度列
  14. 完整觀看第 1 集後關閉裝置，確認
  15. 第 1 集上架後，不會再顯示在「繼續觀看」列中 [在第二部裝置上，以及開啟測試裝置時]
    1. 第 2 集 (如有) 應會顯示在「繼續觀看」列中 [在第二部裝置上，以及開啟測試裝置時]
  16. 情境一：TV1：Google 帳戶：媽媽，第三方帳戶 / 設定檔：帳戶 1/profile_1。觀看內容，並確認 CW 資料顯示 3P 帳戶 1/設定檔 1 觀看的內容

  17. TV2：Google 帳戶：媽媽。驗證第一個情境的 CW 資料。現在請以其他帳戶登入第三方應用程式。第三方帳戶 / 設定檔： account_2 / profile_2。觀看內容，並確認 CW 資料顯示 3p 帳戶 2/設定檔 2 觀看的內容

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

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

我們發現 Google TV iOS 應用程式未顯示「繼續觀看」內容，請問發生了什麼事？

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

我應該多久更新一次「繼續觀看」資訊？我應該頻繁更新「繼續觀看」資訊嗎？例如每 15 秒更新一次？

不建議經常更新。原因如下：

  • 效能影響：持續傳送更新會對伺服器造成不必要的負擔，可能導致系統效能降低。
  • 不必要的資料：使用者觀看影片時，播放位置會不斷變更。每隔幾秒傳送更新會產生大量多餘資料，對繼續播放沒有幫助。

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

請著重擷取使用者觀看進度的重大變化。以下是主要情境：

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

如何有效更新：

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

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

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