為串流提供指定目標參數

您可以選擇提供下列任何一個指定目標參數。

在建立或設定隨選影片 (VOD) 內容來源，或者為動態廣告插播設定直播活動時，您需要指定預設的影片廣告代碼。所有 DAI 串流都會預設使用這個廣告代碼及其參數。廣告代碼參數適用於片中廣告和片頭廣告。如果希望播放器針對特定的串流提出特別要求，可以使用這些選項來設定。

可覆寫的 Ad Manager 廣告代碼參數

跳至特定的參數：

addtl_consent an ciu_szs cust_params description_url gdpr gdpr_consent givn|paln idtype is_lat iu

iu is_lat ltd mpt mpv npa omid_p ppid ptpl ptpln rdid rdid

rdp sdk_apis sid sz tfcd trt vconp vpa vpmute wta

 

覆寫預設廣告代碼

當影片播放器請求串流時，預設廣告代碼會用於您在使用者介面中所指定的目的。不過，您可以在串流請求中覆寫該代碼的某些參數。您只能覆寫下列參數。

瞭解如何使用 IMA SDK 或使用 SSB 覆寫預設廣告代碼。

參數	說明	範例值
iu	目前的廣告單元。 須符合以下格式： /network_id/directory/ad_unit	iu=/6062/video/example_unit
cust_params	應該用於 Ad Manager 廣告活動指定目標的鍵/值組合。有些平台需要進行網址編碼。 使用適用於 HTML5 的 IMA DAI SDK 時，則不需要進行網址編碼，因為系統會自動對該值進行編碼。如果這個參數已在 HTML5 上編碼，就會無法運作。	具有多個鍵/值組合的範例如下： section=sports  page=golf,tennis   SSB 串流：編碼並串連整個 cust_params 值，但不進行雙重編碼。 cust_params=   "section%3Dsports   %26page%3Dgolf%2Ctennis"   Chromecast： 只將值編碼。 streamRequest. adTagParameters = {   "cust_params":   "section=sports&   multi=golf%2Ctennis"};   Roku：編碼並串連整個 cust_params 值，但不進行雙重編碼。 request.adTagParameters =   "cust_params=   section%3Dsports   %26page%3Dgolf%2Ctennis"   iOS 和 tvOS：不將任何部分編碼。 request.adTagParameters = @{   @"cust_params" :   @"section=sports&   multi=golf,tennis"};   Android：不將任何部分編碼。 Map<String, String> adTagParams =   new HashMap<>();   adTagParams.put(   "cust_params",   "ge=0&gr=2");
sz	只要覆寫預設廣告代碼中的 sz 參數，即可為不同的裝置動態變更大小。 請勿在大小後面加上「v」。	sz=400x300
tfcd	替廣告請求設定兒童導向內容標記。 當動態廣告插播請求包含 tfcd=1 時，任何指派給 rdid、idtype 或 is_lat 參數的值都會移除，以符合 COPPA 的規定。	tfcd=1
description_url	這個值應描述網頁上播放的影片。這可以是目前內嵌影片播放器的網頁，也可以是含有影片說明文字的網頁。 您一律必須將 SSB 串流上的 description_url 進行網址編碼，在使用適用於 Roku 的 IMA DAI SDK 時也必須這麼做。使用適用於 HTML5 的 IMA DAI SDK 時，則不需要進行網址編碼，因為系統會自動對該值進行編碼。如果這個參數已在 HTML5 上編碼，就會無法運作。 IMA SDK 不會自動設定這個參數，您必須手動設定。 如果您使用 Ad Exchange，就必須填寫這個欄位。瞭解詳情	經過網址編碼的例子： description_url= http%3A%2F%2Fwww.sample.com %2Fgolf.html 未經編碼的例子： description_url= http://www.sample.com/ golf.html
ppid	發布商提供的 ID (PPID) 可由發布商傳送給系統，用於設定展示頻率上限、目標對象區隔和指定目標、廣告依序輪播，以及其他以目標對象為基礎的跨裝置廣告放送控制項。瞭解詳情	ppid= 12JD92J...
ciu_szs	用英文逗號分隔的隨播廣告大小清單。 只有使用 HTML5 SDK 時，DAI 才支援隨播廣告。	ciu_szs=728x90,300x250
mpt	指出合作夥伴播放器的名稱。這大多會由與 SDK 整合的合作夥伴 (例如 JWPlayer、Brightcove、Ooyala 等) 使用。	mpt=JWPlayer
mpv	指出合作夥伴播放器的版本。此參數是用來表示與 SDK 整合的合作夥伴播放器版本，應與 mpt 一同設定。	mpv=2.1
ptpl	廣告插播範本 ID。 您在 Ad Manager 介面中查看廣告插播範本的設定時，可以在 Ad Manager 網址中找到這個 ID。這會顯示為 break_template_id 參數的值。	ptpl=1234
ptpln	廣告插播範本名稱。這對應於 Ad Manager 中的「名稱」欄位，而不是顯示名稱。	ptpln=my_break_template
an	an 參數是應用程式名稱。 大部分的程式輔助採購影片廣告都需要這個參數，因此這個參數應該套用至行動應用程式和連網電視裝置發出的請求*。 IMA SDK 會自動填入這個參數，但您必須使用 DAI API 和 SSB (非 SDK 環境) 手動指定。 * 雖然應用程式名稱應採用人類可讀的形式，但在 iOS 和 tvOS 中，SDK 無法存取 9 位數的 App Store ID。在這些情況下，SDK 會透過 an 參數 (使用 com.package.publisher 格式) 傳送應用程式套件。	an=sample%20app
ltd	指出是否要讓發布商在未取得 Cookie 或其他本機 ID 的使用同意聲明下，以受限的方式放送廣告。瞭解詳情	ltd=1
rdid idtype is_lat	針對原生應用程式 (一般網站和行動版網站不適用)，SDK 會將用於指定使用者的可重設裝置 ID 傳入您的串流請求，使用的參數包括 rdid、idtype 和 is_lat。在 SSB 串流中，您必須以明確的參數形式傳遞這些參數，就跟在用戶端影片廣告解決方案請求中一樣。 自 iOS 14.5 起，Apple 已淘汰 LAT 信號。Google 則需參考非零的廣告識別碼，瞭解在支援應用程式追蹤透明度的 iOS 版本上，使用者是否同意啟用追蹤功能。因此，系統需要有效的 UserAgent 來取得正確的 OS 版本。	查看可重設裝置 ID 的詳細例子。
trt	將流量指定為購買的流量或其他類型。	未定義的流量類型： trt=0 購買的流量類型： trt=1 自然流量類型： trt=2
vconp	建議依據：MRC影片評估指南 指出播放器是否打算連續播放一組內容影片，類似電視節目。 如果連續播放為「開啟」，則可能的值為 2；如果為「關閉」，則可能的值為 1。 如果狀態不明，請勿設定這個參數。	連續播放「開啟」： vconp=2   連續播放「關閉」： vconp=1
vpa	建議依據：MRC影片評估指南 指出廣告是自動播放還是點擊後才開始播放。 如果頁面會等待使用者動作，則可能的值為 click；如果影片自動播放，則可能的值為 auto。 如果狀態不明，請勿設定這個參數。	自動播放： vpa=auto   點擊： vpa=click
vpmute	建議依據：MRC影片評估指南 指出開始播放廣告影片時，播放器是否設為靜音。 如果設為靜音，可能的值為 1，反之則為 0。 如果狀態不明，請勿設定這個參數。	已靜音： vpmute=1   已取消靜音： vpmute=0
npa	廣告請求的個人化設定。建議您及早在代碼中指定這個參數，以免網址遭到截斷。 只要指定 npa=1，就能將廣告請求標為非個人化。如果略過這個參數，就會預設為放送個人化廣告，	npa=1
omid_p	「OMID 合作夥伴名稱」參數接受使用變數值，指出整合 OMID 評估功能的合作夥伴名稱和合作夥伴版本。 請注意，這個參數僅適用於使用 Open Measurement SDK (OM SDK)，且想透過 Active View 評估的發布商。假如您是使用 IMA SDK，則請勿使用這個參數，因為系統會自動完成相關設定。 如要在使用程式輔助存取權資料庫 (PAL) 時指明 OMID 支援，請務必透過 omidPartnerName 和 omidPartnerVersion API 設定合作夥伴名稱和版本。若您不是使用 PAL 或 IMA，則須設定 omid_p 和 sdk_apis 參數 (兩者皆為支援的 API，也可以納入其他 API 並以半形逗號分隔)。	使用 PAL 時： request.omidPartnerName = 'examplepartnername' request.omidPartnerVersion = '1.0.0.0' 未使用 PAL 時：omid_p=examplepartnername/1.0.0.0&sdk_apis=7
gdpr gdpr_consent	這些欄位是用來透過內送和外寄的 Cookie 同步請求傳遞「資訊公開和同意聲明架構第 2.0 版」同意聲明資訊。	請參閱 GDPR 規格。
givn|paln	如果整合項目使用程式輔助存取權資料庫 (PAL)，影片 Nonce 參數會接受變數字串值。 Nonce 是安全的網址，您不需要對其進行網址編碼。 注意：如果您先前使用舊版 paln 參數提供 Nonce，強烈建議您改用 givn 參數，並停止傳送 paln。請勿同時加入這兩個參數。	如要進一步瞭解傳遞給這個參數的值，請參閱 PAL 的入門指南。
addtl_consent	已獲得使用者同意但未註冊 IAB 的 Google 廣告技術供應商清單。	請參閱額外同意聲明規格。
rdp	您必須特別設定 rdp=1 或只包含 rdp (沒有固定值)，才能限制資料處理。除非啟用「限制資料處理」聯播網設定，否則沒有這個參數或是設為 rdp=0 的廣告請求不會實施限制。	rdp=1
sdk_apis	SDK API 架構參數接受以逗號分隔的常數整數值清單，指出播放器支援的所有 API 架構。 請參閱可能的 API 架構值清單。 這個參數由使用程式輔助存取權資料庫 (PAL) 的發布商使用。如果您在使用 IMA SDK 時嘗試為這個參數設定值，系統會以 IMA SDK 支援的值覆寫這些值。	sdk_apis=2,7,9
sid	這種類型的廣告 ID 可保護隱私權，且只能用於設定展示頻率上限。根據 IAB 的 IFA 指南，這個參數應以 UUID 格式填入。瞭解詳情 如要停止傳遞工作階段 ID，您可以設定 sid=0。	sid=123e4567-e89b-12d3 -a456-426614174000
wta	代表影片播放器是否支援顯示「為什麼會顯示這則廣告？」。 使用 IMA SDK 時，系統會自動支援這項功能。如果不使用 IMA SDK，影片播放器就必須導入 VAST Icon 和 IconClickFallbackImage 支援 (如這份 DAI API 指南所述)。* SSB 不支援 WTA。 如果您使用 Ad Exchange，就必須填寫這個欄位。瞭解詳情 * 除了連網電視裝置以外，不需要支援 IconClickFallbackImage。	支援： wta=1 不支援： wta=0

使用 IMA SDK 覆寫預設廣告代碼

影片播放器使用 IMA SDK 請求 DAI 串流時，可能會傳遞稱為「adTagParameters」的欄位。您可以使用鍵/值組合來設定這個類似字典的結構，並使用上表所列的 Ad Manager 廣告代碼參數做為其中的鍵。

您可以自訂串流，並使用這個結構傳遞與 Ad Manager 廣告請求無關的參數。瞭解如何請求特定的串流變體，以及如何設定廣告休播。

adTagParameters 欄位的導入方式因程式語言或平台而稍有不同。詳情請參閱 iOS、Android、tvOS、Chromecast、HTML5 開發說明文件，或 DAI 播放器和應用程式開發指南中的其他說明文件。

 

透過 SDK 設定 adTagParameters

您在 iOS、tvOS 和 Android 應用程式中透過 SDK 設定 cust_params 或 description_url 時，不應將字串進行網址編碼。您在傳遞 cust_params 時，可以使用「&」將所有鍵/值組合串連成單一字串。

舉例來說，如果要將 cust_params 的值設為 sport=football&city=newyork：

使用未編碼值的 adTagParams 結構會是：

{
  "tfcd": 1,
  "iu": "/987654321/path/to/adunit",
  "cust_params": "sport=football&city=newyork",
  "description_url": "http://www.sample.com/golf.html",
  "ppid": "12JD92JD8078S8J29SDOAKC0EF230337"
}
 

使用適用於 HTML5 串流請求編碼值的 adTagParameters 結構會是：

{
  "tfcd": 1,
  "iu": "/987654321/path/to/adunit",
  "cust_params": "sport%3Dfootball%26city%3Dnewyork",
  "description_url": "http%3A%2F%2Fwww.sample.com%2Fgolf.html",
  "ppid": "12JD92JD8078S8J29SDOAKC0EF230337"
}
 

使用適用於 Roku 串流請求編碼值的 adTagParams 結構會是：

request.adTagParams="tfcd=1&iu=/987654321/path/to/adunit&cust_params=sport%3Dfootball%26city%3Dnewyork&description_url=http%3A%2F%2Fwww.sample.com%2Fgolf.html&ppid=12JD92JD8078S8J29SDOAKC0EF230337"

使用 DAI API 覆寫預設廣告代碼 ^{(Beta 版)} 

當影片播放器使用 DAI API 請求動態廣告插播串流時，可以選擇傳遞鍵/值組合，並使用上表所列的 Ad Manager 廣告代碼參數做為其中的鍵。

這些參數應包含在 HTTP POST 要求主體中一併傳送，並且無論是線性/直播和 VOD，格式類型都必須為 application/x‑www‑form‑urlencoded。

您可以自訂串流，並使用這個結構傳遞與 Ad Manager 廣告請求無關的參數。瞭解如何請求特定的串流變體參數和 HMAC 驗證。

請參閱 DAI API 導入範例。

使用 SSB 覆寫預設廣告代碼

以下是 SSB 預設 VOD 廣告代碼的修改範例。被覆寫的播放器或應用程式傳遞參數會醒目顯示。

隨選影片範例

	示例
基礎 VOD 串流網址	http://dai.google.com/ondemand/hls/content/ <contentid>/vid/<vid>/master.m3u8
(包含指定的廣告單元)	http://dai.google.com/ondemand/hls/content/ <contentid>/vid/<vid>/master.m3u8?iu=/9876/ path/to/adunit
(包含被覆寫的 鍵/值)	http://dai.google.com/ondemand/hls/content/ <contentid>/vid/<vid>/master.m3u8& cust_params=sport%3Dgolf%26section%3Dblog %26anotherKey%3Dvalue1%2Cvalue2
(包含兒童導向內容 宣告)	http://dai.google.com/ondemand/hls/content/ <contentid>/vid/<vid>/master.m3u8?tfcd=1
(同時包含被覆寫的廣告單元、鍵/值、 自訂 description_url 以及兒童導向內容宣告)	http://dai.google.com/ondemand/hls/content/ <contentid>/vid/<vid>/master.m3u8& iu=/9876/path/to/adunit& cust_params=sport%3Dgolf%26section %3Dblog%26anotherKey%3Dvalue1%2Cvalue2& description_url=https://mysite.com/description.html& tfcd=1

 

直播線性串流例子

	示例
基礎直播線性串流網址	https://dai.google.com/linear/hls/event/<asset_key> /master.m3u8
(包含指定的廣告單元)	https://dai.google.com/linear/hls/event/<asset_key> /master.m3u8?iu=/9876/path/to/adunit
(包含被覆寫的鍵/值)	https://dai.google.com/linear/hls/event/<asset_key> /master.m3u8?cust_params=sport%3Dgolf%26section %3Dblog%26otherKey%3Dvalue1%2Cvalue2
(包含兒童導向內容 宣告)	https://dai.google.com/linear/hls/event/<asset_key> /master.m3u8?tfcd=1
(同時包含被覆寫的廣告單元、鍵/值、 自訂 description_url 以及兒童導向內容宣告)	https://dai.google.com/linear/hls/event/<asset_key> /master.m3u8& iu=/9876/path/to/adunit& cust_params=sport%3Dgolf%26section%3Dblog%26otherKey %3Dvalue1%2Cvalue2& description_url=https://mysite.com/description.html& tfcd=1

在特定的直播內容中動態更新指定目標參數

您可以使用 IMA DAI SDK 中的replaceAdTagParameters 方法，在特定使用者觀看串流內容的過程中，動態更新該使用者的指定資料。

如有任何與 DAI 疑難排解或服務中斷相關的問題，請與發布商支援團隊聯絡。