您可以使用本文所述的函式和信號建立自訂出價指令碼,在通知自訂出價模型時,準確反映您希望改善的主要成效指標 (KPI)。
本文討論的主題
語法規則
您可以使用第一方資料通知自訂出價指令碼,藉此提升曝光價值。Display & Video 360 支援下列來源的第一方資料:
- Floodlight:詳情請參閱使用 Floodlight 資料的指令碼範例。
- 曝光層級資料:詳情請參閱使用曝光層級資料的指令碼範例。
- Google Analytics:詳情請參閱使用 Google Analytics 資料的指令碼範例。
建立自訂出價指令碼時,請使用下列語法規則:
- 以方括號
[ ]
括住所有條件 - 逗號
,
也代表「and」
範例
criteria_a
和 criteria_b
的值皆為 true
時,criteria1
才會傳回「true」。criteria2
則只要 criteria_a
的值為 true
,就會傳回 true
:([criteria_a, criteria_b], <分數>), #criteria1
([criteria_a], <分數>) #criteria2
])
註解
您可以使用註解提供指令碼的相關資訊。例如,您可以新增註解說明指令碼的用途。
新增註解時,您可以使用下列語法:
- 如要新增單行註解,請使用
#
。 - 如要新增多行註解,請使用
"""
或'''
括住註解。
範例
# 這是單行註解
"""
這是多行註解
"""
'''
這也是多行註解
'''
運算子
您可以在指令碼中使用下列運算子:
- 算術運算子:
+
、-
、*
、/
、%
、**
、//
- 指派運算子:
=
、+=
、-=
、*=
、/=
、%=
、**=
、//=
- 比較運算子:
==
、!=
、<
、>
、>=
、<=
- 邏輯運算子:
and
、or、not - 隸屬運算子:in、not in
隸屬運算子
您可以在指令碼中使用隸屬運算子 (in 和 not in),檢查欄位是否含有特定元素。
in
:如果欄位含有特定元素,系統會傳回 true。not in
:如果欄位不含特定元素,系統會傳回 true。
範例
if 123 in channel_id: #檢查頻道 ID 是否含有 123
return y
比較運算子
您可以使用比較運算子在模型中納入或排除元素。
範例 1
# 排除日期
if date == 20180711:
return None
訓練自訂出價模型時,您可以根據系統是否傳回 None
,找出要排除的曝光。只要使用會傳回 None
的陳述式,即可在訓練自訂出價模型時找出要排除的曝光。
範例 2
以下指令碼會從自訂出價模型中排除廣告類型:
# 排除分類 (ad_type == 1 代表影片)
if ad_type != 1:
return None
可用的函式和信號
您可以在自訂出價指令碼中使用下列函式。表格包含以下資訊:
- 欄位:您在指令碼中使用的函式或信號名稱。
- 類型:輸出的資料類型。自訂出價支援以下資料類型:
- 布林值:包含
true
或false
值。 - 二進位值:包含二進位資料。
- 倍精準度浮點值:包含浮點數值,例如
1.0
。 - 整數清單:包含一組整數。
- 整數:包含正整數或負整數,例如
1
或-1
。 - 字串:包含長度為 0 以上的 UTF-8 字元。比方說,
country_code
會輸出“US”
字串。
- 布林值:包含
- 詳細資料:包含其他資訊和範例連結。
如需詳細資訊,請前往 Display & Video 360 API 或下載結構化資料檔案 (SDF)。
函式
Display & Video 360 自訂出價支援以下函式:
這些函式會接受一或多個信號,在自訂出價指令碼中準確反映您的主要成效指標 (KPI)。
類別 | 函式 | 類型 | 詳細資料 |
---|---|---|---|
匯總函式 | first_match_aggregate |
倍精準度浮點值 | 找出陣列中第一個傳回 true 的條件,然後傳回指派給該條件的權重值。 |
max_aggregate |
倍精準度浮點值 | 找出傳回 true 的條件,然後傳回指派給該條件的最高權重值。 |
|
sum_aggregate |
倍精準度浮點值 | 找出所有傳回 true 的條件,將指派給這些條件的所有值加總,然後傳回加總結果。 |
|
轉換函式 |
|
布林值(x) |
傳回布林值: |
|
浮點值(x) |
轉換數字或字串資料類型:傳回浮點值。 範例: |
|
|
整數(x) |
轉換數字或字串資料類型,然後傳回整數。 範例: |
|
|
str(<物件>) |
轉換資料類型,然後傳回字串。 範例: |
|
數學函式 |
|
log(x[, <底數>]) |
使用單一引數:傳回 x 的自然對數 (底數為 e)。 使用兩個引數:傳回 x 以指定數值為底數的對數,計算方式為 log(x)/log(<底數>)。 |
信號
Display & Video 360 自訂出價函式可接受以下信號類別的資料:
- 維度變數:指令碼中用於根據變數計算分數的信號。
- 轉換:指令碼中用於根據轉換結果計算分數的信號。
- Google Analytics:指令碼中用於根據 Google Analytics 4 資料計算分數的信號。
維度變數
類別 |
信號 |
類型 |
詳細資料 |
一般 |
|
整數 |
Display & Video 360 中的廣告主 ID。 |
---|---|---|---|
|
整數 |
Display & Video 360 中的廣告訂單 ID。 |
|
|
整數 |
Display & Video 360 中的委刊項 ID。 |
|
日期/時間 |
|
整數 |
曝光發生的日期。 格式:yyyymmdd |
|
整數 |
表示曝光發生日期為當週星期幾的數字代碼。
|
|
|
整數 |
曝光發生的時間 (小時),採用瀏覽器當地時區 (24 小時制)。 有效值:0 - 23 |
|
|
整數 |
曝光發生的日期,採用世界協調時間 (UTC)。 格式:yyyymmdd |
|
|
整數 |
曝光發生的時間 (小時),採用世界協調時間 (UTC) 和 24 小時制。 有效值:0 - 23 |
|
地區 |
|
整數 |
城市 ID。 如要產生 city_id,請使用 Display & Video 360 API 或下載 SDF 中繼資料。 |
|
字串 |
國家/地區代碼。 您可以下載國家/地區代碼對照表 PDF 檔案做為參考。 |
|
|
整數 |
國家/地區 ID。 您可以下載國家/地區 ID 對照表 PDF 檔案做為參考。 |
|
|
整數 |
指定行銷區域 (DMA) ID。 |
|
|
字串 |
郵遞區號。 如要查看可用的郵遞區號清單,請使用 Display & Video 360 API 或下載 SDF 中繼資料。 |
|
廣告素材 (一般) |
|
整數 |
代表廣告格式的數字代碼:
|
|
整數 |
廣告素材的高度 (以像素為單位)。 注意:僅適用於多媒體廣告素材。 |
|
|
整數 |
Display & Video 360 中顯示的廣告素材 ID。 |
|
|
整數 |
廣告素材的寬度 (以像素為單位)。 注意:僅適用於多媒體廣告素材。 |
|
電腦系統 |
|
整數 |
瀏覽器 ID。 |
|
整數 |
瀏覽器所使用時區與 GMT-12 時區之間的時差 (分鐘)。 範例: 1320 表示瀏覽器時區為 GMT+10 |
|
|
整數 |
代表裝置類型的數字代碼:
|
|
|
整數 |
代表廣告放送環境的數字代碼。
|
|
|
整數 |
網際網路服務供應商 (ISP) ID。 |
|
|
字串 |
瀏覽器的語言設定。 |
|
|
整數 |
行動裝置製造商 ID。 |
|
mobile_model_id |
整數 |
行動裝置型號 ID。 |
|
|
整數 |
系統在曝光發生時偵測到的網路速度 (以數字代碼表示):
|
|
|
整數 |
作業系統 ID。 |
|
放送 (一般) |
|
整數 |
代表廣告刊登位置的數字代碼:
|
|
整數清單 |
網頁類別 ID。 如要查看完整的類別 ID 對照表,請前往 AdWords API 參考資料。 |
|
|
整數清單 |
Display & Video 360 中的頻道 ID。 |
|
|
字串 |
注意:連網電視委刊項不支援 domain 信號。如果是連網電視委刊項,請使用 根網域名稱 (由網域名稱和頂層網域組成)。 範例:如果網址為 http://www.domain.com,根網域是 domain.com。 |
|
|
整數 |
廣告交易平台 ID。 |
|
|
整數 |
網站 ID。 |
|
Active View |
|
布林值 |
如果 Active View 可在廣告放送時評估曝光,系統會傳回 有些因素可能會導致系統無法計算曝光次數。如果無法評估曝光,系統會傳回 |
|
布林值 |
Active View 偵測到使用者觀看您的廣告時,會傳回 1 代表 true。如果沒有,則會傳回 0 代表 false。 |
|
事件 |
|
布林值 |
如果使用者點選廣告,系統會傳回 |
|
整數 |
廣告出現在畫面上的時間 (以秒為單位)。 |
|
影片 |
|
布林值 |
注意:只有即時出價 (RTB) 影片支援這個信號。 如果使用者在觀看影片時開啟音效,這個信號會傳回 |
|
布林值 |
注意:只有即時出價 (RTB) 影片支援這個信號。 如果使用者在觀看影片期間開啟音效,這個信號會傳回 |
|
|
布林值 |
注意:僅適用於影片廣告類型。系統不會標示非影片曝光次數。 如果使用者完整播放影片,這個信號會傳回 |
|
|
整數 |
影片播放器在顯示第一個畫面時的高度 (以像素為單位)。 |
|
|
整數 |
代表指定影片廣告空間 (以影片播放器大小為指定依據) 的數字代碼。
如要瞭解詳情,請參閱「指定影片」一文。 |
|
|
整數 |
影片播放器在顯示第一個畫面時的寬度 (以像素為單位)。 |
|
|
二進位數 |
如果使用者在播放期間調整影片播放器大小,這個信號會傳回 |
|
|
布林值 |
注意:只有即時出價 (RTB) 影片支援這個信號。 如果使用者完整觀看影片,這個信號會傳回 |
|
video_content_duration_bucket |
整數 |
注意:僅適用於影片廣告類型。系統不會標示非影片曝光次數。
數字代碼代表影片的值區,用於根據長度將影片分類,且會排除上限範圍。 範例如果是長度為 1 分鐘的影片:
|
|
video_genre_ids |
整數清單 |
注意:僅適用於影片廣告類型。系統不會標示非影片曝光次數。 代表影片類型 ID 清單,用於根據相關音訊和影片廣告空間群組指定廣告。 進一步瞭解指定類型。 |
|
video_livestream |
布林值 |
注意:僅適用於影片廣告類型。系統不會標示非影片曝光次數。 如果是直播影片,系統會傳回true ,否則傳回 false 。 |
轉換
類別 |
信號 |
類型 |
詳細資料 |
轉換信號 |
|
倍精準度浮點值 |
ID 組合的轉換事件總數。您可以使用自己的模式。如要使用最終接觸歸因,請輸入 0 做為歸因模式 ID。 |
---|---|---|---|
|
倍精準度浮點值 |
從 Floodlight 銷售代碼追蹤的活動取得收益值。您可以使用自己的模式。如要使用最終接觸歸因,請輸入 0 做為歸因模式 ID。 |
|
|
倍精準度浮點值 |
歸因於指定 ID 組合的轉換總數。您可以使用自己的模式。如要使用最終接觸歸因,請輸入 0 做為歸因模式 ID。 |
|
|
字串 |
曝光的最新歸因轉換自訂變數字串值。如果沒有任何轉換或未設定字串值,系統會傳回 |
|
|
整數 |
在 count_micros 為正數的情況下取得功勞為正職的最新轉換,進而取得「num」Floodlight 變數 (如果有的話)。如果沒有,系統會傳回 |
|
|
字串 |
在 |
影片類型對照表
類型 ID |
類型名稱 |
2 |
/成人 |
3 |
/藝術與娛樂 |
317 |
/藝術與娛樂/漫畫與動畫/動畫與漫畫 |
319 |
/藝術與娛樂/漫畫與動畫/卡通 |
1108 |
/藝術與娛樂/娛樂產業/影視產業/影視獎項 |
569 |
/藝術與娛樂/活動與節目表 |
1273 |
/藝術與娛樂/活動與節目表/運動賽事直播 |
895 |
/藝術與娛樂/幽默/現場喜劇 |
1097 |
/藝術與娛樂/電影/動作冒險片 |
1099 |
/藝術與娛樂/電影/動作冒險片/西部片 |
1095 |
/藝術與娛樂/電影/喜劇片 |
615 |
/藝術與娛樂/電影/恐怖片 |
1105 |
/藝術與娛樂/電影/音樂歌舞片 |
1310 |
/藝術與娛樂/電影/浪漫愛情片 |
616 |
/藝術與娛樂/電影/科幻與奇幻片 |
1096 |
/藝術與娛樂/電影/驚悚、犯罪與懸疑片 |
35 |
/藝術與娛樂/音樂與音訊 |
449 |
/藝術與娛樂/非主流/神秘學與超自然 |
23 |
/藝術與娛樂/表演藝術 |
894 |
/藝術與娛樂/表演藝術/表演與舞台劇 |
581 |
/藝術與娛樂/表演藝術/舞蹈 |
1185 |
/藝術與娛樂/表演藝術/歌劇 |
358 |
/藝術與娛樂/電視與影片/電視節目 |
1047 |
/藝術與娛樂/電視與影片/電視節目/電視喜劇 |
1411 |
/藝術與娛樂/電視與影片/電視節目/電視紀錄片與紀實 |
1193 |
/藝術與娛樂/電視與影片/電視節目/電視劇 |
1111 |
/藝術與娛樂/電視與影片/電視節目/電視劇/電視犯罪與法律節目 |
357 |
/藝術與娛樂/電視與影片/電視節目/電視劇/電視連續劇 |
1110 |
/藝術與娛樂/電視與影片/電視節目/適合闔家觀賞的節目 |
1050 |
/藝術與娛樂/電視與影片/電視節目/電視遊戲節目 |
1049 |
/藝術與娛樂/電視與影片/電視節目/電視實境節目 |
1112 |
/藝術與娛樂/電視與影片/電視節目/電視科幻與奇幻節目 |
1410 |
/藝術與娛樂/電視與影片/電視節目/電視選秀與綜藝節目 |
1048 |
/藝術與娛樂/電視與影片/電視節目/電視談話性節目 |
24 |
/藝術與娛樂/視覺藝術與設計 |
47 |
/汽車與交通工具 |
1191 |
/汽車與交通工具/自行車與配件 |
1405 |
/汽車與交通工具/自行車與配件/越野自行車 |
273 |
/汽車與交通工具/車輛交通工具 (按類型)/摩托車 |
148 |
/汽車與交通工具/車輛交通工具 (按類型)/越野車 |
185 |
/美容與健身/時尚與風格 |
94 |
/美容與健身/健身 |
241 |
/美容與健身/健身/健美 |
1418 |
/美容與健身/健身/健身指導與個人訓練課程 |
46 |
/工商業/農業與林業 |
5 |
/電腦與電子產品 |
122 |
/餐飲/烹飪與食譜 |
39 |
/遊戲/紙牌遊戲 |
924 |
/遊戲/紙牌遊戲/撲克牌與賭場遊戲 |
924 |
/遊戲/紙牌遊戲/撲克牌與賭場遊戲 |
41 |
/遊戲/電腦與電玩遊戲 |
698 |
/遊戲/賭博/運動投注/賽馬與賽狗 |
939 |
/遊戲/桌上球類運動/撞球 |
940 |
/遊戲/桌上球類運動/乒乓球 |
45 |
/保健 |
284 |
/興趣與休閒/手工藝 |
688 |
/興趣與休閒/戶外活動 |
462 |
/興趣與休閒/戶外活動/釣魚 |
461 |
/興趣與休閒/戶外活動/打獵與射擊 |
461 |
/興趣與休閒/戶外活動/打獵與射擊 |
461 |
/興趣與休閒/戶外活動/打獵與射擊 |
999 |
/興趣與休閒/休閒飛行活動 |
678 |
/興趣與休閒/特殊場合/假日與節慶活動 |
459 |
/興趣與休閒/水上活動/划船 |
11 |
/家居與園藝 |
158 |
/家居與園藝/居家修繕 |
966 |
/法律與政府/政府/州/省與地方政府 |
75 |
/法律與政府/法律 |
366 |
/法律與政府/軍事 |
16 |
/新聞 |
784 |
/新聞/商業新聞 |
396 |
/新聞/政治 |
1201 |
/新聞/政治/意見與評論 |
1077 |
/新聞/運動新聞 |
785 |
/新聞/科技新聞 |
63 |
/新聞/氣象 |
113 |
/人文與社會/種族與認同團體/女同性戀、男同性戀、雙性戀與跨性別 |
58 |
/人文與社會/家庭與人際關係/家庭/親子教養 |
59 |
/人文與社會/宗教與信仰 |
870 |
/人文與社會/自我成長與勵志 |
57 |
/人文與社會/社會議題與宣導/公益與慈善 |
82 |
/人文與社會/社會議題與宣導/環保生活與環境問題 |
886 |
/寵物與動物/寵物/狗 |
888 |
/寵物與動物/寵物/馬 |
119 |
/寵物與動物/野生動物 |
119 |
/寵物與動物/野生動物 |
690 |
/參考資料/一般參考資料/傳記與名言 |
694 |
/參考資料/一般參考資料/說明、DIY 與專業內容 |
433 |
/參考資料/人文學科/歷史 |
1288 |
/參考資料/人文學科/歷史/軍事史 |
174 |
/科學 |
18 |
/購物 |
64 |
/購物/古董與收藏品 |
292 |
/購物/拍賣 |
69 |
/購物/消費者資源 |
1666 |
/運動/動物運動 |
568 |
/運動/動物運動/馬術 |
515 |
/運動/搏擊運動/拳擊 |
516 |
/運動/搏擊運動/武術 |
1674 |
/運動/搏擊運動/格鬥術/綜合格鬥 |
512 |
/運動/格鬥/摔角 |
1681 |
/運動/搏擊運動/摔角/職業摔角 |
554 |
/運動/極限運動 |
1206 |
/運動/極限運動/直線競速與街頭競速 |
1000 |
/運動/個人運動 |
1016 |
/運動/個人運動/保齡球 |
458 |
/運動/個人運動/自行車 |
261 |
/運動/個人運動/高爾夫 |
519 |
/運動/個人運動/體操 |
262 |
/運動/個人運動/球拍運動 |
1376 |
/運動/個人運動/球拍運動/網球 |
541 |
/運動/個人運動/跑步與健行 |
1126 |
/運動/個人運動/溜冰運動 |
518 |
/運動/個人運動/田徑 |
513 |
/運動/國際運動競賽/奧運 |
180 |
/運動/賽車 |
1595 |
/運動/賽車/汽車競速 |
1596 |
/運動/賽車/摩托車競速 |
1001 |
/運動/團體運動 |
258 |
/運動/團體運動/美式足球 |
259 |
/運動/團體運動/棒球 |
264 |
/運動/團體運動/籃球 |
534 |
/運動/團體運動/啦啦隊 |
296 |
/運動/團體運動/板球 |
1017 |
/運動/團體運動/手球 |
260 |
/運動/團體運動/曲棍球 |
517 |
/運動/團體運動/英式橄欖球 |
294 |
/運動/團體運動/足球 |
699 |
/運動/團體運動/排球 |
118 |
/運動/水上運動 |
1593 |
/運動/水上運動/衝浪 |
1594 |
/運動/水上運動/游泳 |
265 |
/運動/冬季運動 |
1149 |
/運動/冬季運動/溜冰 |
1148 |
/運動/冬季運動/滑雪與雪板滑雪 |
67 |
/旅遊與交通 |
Google Analytics
類別 | 信號 | 類型 | 詳細資料 |
---|---|---|---|
Google Analytics 4 |
|
布林值 |
在資源 ID 和轉換事件已歸因的情況下,假如指定曝光至少有一個轉換,系統就會傳回 true 。如果沒有,系統會傳回 false 。 |
|
整數 |
如果資源 ID 和轉換事件的功勞已歸給指定曝光,系統會傳回轉換次數。 | |
|
倍精準度浮點值 |
如果資源 ID 和轉換事件的功勞已歸給指定曝光,系統會傳回指派給轉換的最高值。 如果最高轉換值為0 或沒有已歸因的轉換,系統會傳回 0 。 |
|
|
倍精準度浮點值 |
注意:適用於使用美元的 Google Analytics 4 帳戶。 如果資源 ID 和轉換 ID 的功勞已歸給指定曝光,系統會傳回指派給轉換的最高值。 如果最高轉換值為 |
|
|
倍精準度浮點值 |
如果資源 ID 和轉換事件的功勞已歸給指定曝光,系統會傳回指派給轉換的權重值總和。 如果最高轉換值為 |
|
|
倍精準度浮點值 |
注意:適用於使用美元的 Google Analytics 4 帳戶。 如果資源 ID 和轉換事件的功勞已歸給指定曝光,系統會傳回指派給轉換的權重值總和。 如果最高轉換值為 |
限制
自訂出價指令碼不支援以下操作/項目:
- 傳送已命名的引數,例如:
func(arg1 = “abc”, arg2 = “def”)
- 下標和配量,例如:
userlists[1:3]
- 參照屬性,例如:
domain.length
- 變數和函式名稱可以來自預先定義的集合
- 遞迴
- 進階自訂變數指派:
- 多重指派
- 增量指派
- 加註指派
以下是自訂變數指派不支援的語法範例
_a, _b = 1, 2
_a, _b = _b, _a
_a = _b = 2
_idx += 1
- 不支援的關鍵字:
global
、nonlocal
和exec
關鍵字class
和類別定義def
和函式定義Import
和 import from 關鍵字lambda
和 lambda 支援break
continue
yield
raise
assert
try
finally
except
async
await
del
Pass
ellipsis
- 不支援的迴圈:
for
和while
迴圈
- 不支援的運算子:
*
和**
(用於非算術陳述式時)<<
和>>
等移位運算子- 位元運算子
@
修飾符is
、not is
等身分運算子