AdSelectionManager
public
class
AdSelectionManager
extends Object
java.lang.Object | |
↳ | android.adservices.adselection.AdSelectionManager |
AdSelection Manager 為應用程式和廣告 SDK 提供 API 以執行廣告選擇程序,以及回報曝光。
摘要
繼承的方法 | |
---|---|
公用方法
get
public static AdSelectionManager get (Context context)
建立 AdSelectionManager 執行個體的工廠方法。
參數 | |
---|---|
context |
Context :要使用的 Context 不能為 null 。 |
傳回 | |
---|---|
AdSelectionManager |
AdSelectionManager 執行個體
此值不能為 null 。 |
getAdSelectionData
public void getAdSelectionData (GetAdSelectionDataRequest request, Executor executor, OutcomeReceiver<GetAdSelectionDataOutcome, Exception> receiver)
從裝置收集自訂目標對象資料。傳回經過壓縮和加密的 blob,傳送至競價伺服器進行廣告選擇。詳情請參閱出價和競價服務說明。
自訂目標對象廣告必須包含 ad_render_id
,才符合收集資格。
如要瞭解如何處理廣告選擇的結果,以便在伺服器端與這個 API 產生的 blob 搭配運作,請參閱 AdSelectionManager#persistAdSelectionResult
。
接收器會傳遞輸出內容,接收器如果成功執行,就會傳回 GetAdSelectionDataOutcome
,或 Exception
包含擲回的例外狀況類型及對應的錯誤訊息。
如果擲回 IllegalArgumentException
,表示 API 為了執行廣告選擇而收到的無效輸入引數。
如果系統擲回 IllegalStateException
並顯示「AdSelection 服務失敗」錯誤訊息,表示廣告選擇服務發生內部失敗。
如果擲回 TimeoutException
,表示在出價、評分或整體選擇程序找出勝出廣告時發生逾時,就會造成。
如果擲回 LimitExceededException
,是因為呼叫套件超過允許的頻率限制並受節流限制。
如果擲回 SecurityException
,代表呼叫端未獲授權或未要求權限。
需求:AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE
參數 | |
---|---|
request |
GetAdSelectionDataRequest :此值不能為 null 。 |
executor |
Executor :此值不能為 null 。
回呼和事件監聽器會透過這個 Executor 分派,讓您輕鬆控制使用哪一個執行緒。如要透過應用程式的主要執行緒進行事件分派,可以使用 Context.getMainExecutor() 。否則,請提供會傳送至適當執行緒的 Executor 。 |
receiver |
OutcomeReceiver :此值不能為 null 。 |
getTestAdSelectionManager
public TestAdSelectionManager getTestAdSelectionManager ()
傳回 | |
---|---|
TestAdSelectionManager |
此值不能為 null 。 |
持續 AdSelectionResult
public void persistAdSelectionResult (PersistAdSelectionResultRequest request, Executor executor, OutcomeReceiver<AdSelectionOutcome, Exception> receiver)
保留伺服器端的廣告選擇結果。詳情請參閱「出價和競價服務說明」一文
如要瞭解如何產生加密 blob,以便在伺服器端執行廣告選擇,請參閱 AdSelectionManager#getAdSelectionData
。
接收器會傳遞輸出內容,接收器成功執行後會傳回 AdSelectionOutcome
,或 Exception
包含擲回的例外狀況類型及對應的錯誤訊息。
如果擲回 IllegalArgumentException
,表示 API 為了執行廣告選擇而收到的無效輸入引數。
如果系統擲回 IllegalStateException
並顯示「AdSelection 服務失敗」錯誤訊息,表示廣告選擇服務發生內部失敗。
如果擲回 TimeoutException
,表示在出價、評分或整體選擇程序找出勝出廣告時發生逾時,就會造成。
如果擲回 LimitExceededException
,是因為呼叫套件超過允許的頻率限制並受節流限制。
如果擲回 SecurityException
,代表呼叫端未獲授權或未要求權限。
需求:AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE
參數 | |
---|---|
request |
PersistAdSelectionResultRequest :此值不能為 null 。 |
executor |
Executor :此值不能為 null 。
回呼和事件監聽器會透過這個 Executor 分派,讓您輕鬆控制使用哪一個執行緒。如要透過應用程式的主要執行緒進行事件分派,可以使用 Context.getMainExecutor() 。否則,請提供會傳送至適當執行緒的 Executor 。 |
receiver |
OutcomeReceiver :此值不能為 null 。 |
報告事件
public void reportEvent (ReportEventRequest request, Executor executor, OutcomeReceiver<Object, Exception> receiver)
通知服務有新廣告事件,針對由 adSelectionId
識別的廣告選擇所選取的廣告回報。廣告事件是指與指定 adSelectionId
相關聯的廣告發生的任何發生,我們無法保證何時會回報廣告事件。事件回報功能可能會延遲,並可以批次處理。
使用 ReportEventRequest#getKey()
時,服務會擷取已在 registerAdBeacon
中註冊的 reportingUri
。如要進一步瞭解 registerAdBeacon
,請參閱 reportImpression(ReportImpressionRequest, Executor, OutcomeReceiver)
的說明文件。接著,服務會將 ReportEventRequest#getData()
附加至 POST 要求的要求主體,並傳送要求。POST 要求主體會有 text/plain
的 content-type
,資料則會以 charset=UTF-8
傳送。
接收器會傳遞輸出內容,接收器如果成功執行,會傳回空白 Object
;或 Exception
包含擲回的例外狀況類型和對應的錯誤訊息。
如果擲回 IllegalArgumentException
,表示 API 為了回報廣告事件而接收的輸入引數無效。
如果系統擲回 IllegalStateException
並顯示「AdSelection 服務失敗」錯誤訊息,表示廣告選擇服務發生內部失敗。
如果擲回 LimitExceededException
,是因為呼叫套件超過允許的頻率限制並受節流限制。
如果擲回 SecurityException
,代表呼叫端未獲授權或未要求權限。
系統只會盡可能記錄一次事件。
需求:AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE
參數 | |
---|---|
request |
ReportEventRequest :此值不能為 null 。 |
executor |
Executor :此值不能為 null 。 |
receiver |
OutcomeReceiver :此值不能為 null 。 |
reportImpression
public void reportImpression (ReportImpressionRequest request, Executor executor, OutcomeReceiver<Object, Exception> receiver)
通知服務,針對由 adSelectionId
識別的廣告選擇執行,報表有新的曝光需要回報。我們無法保證何時會回報曝光。曝光報表可能會延遲,且報表可以批次處理。
為了計算得標賣家報表網址,服務會從 ReportImpressionRequest.getAdSelectionConfig()
找到的 AdSelectionConfig#getDecisionLogicUri()
擷取賣家的 JavaScript 邏輯。接著,服務會執行賣方 JS 中名為 reportResult
的其中一項函式,並提供裝置端信號以及 ReportImpressionRequest#getAdSelectionConfig()
做為輸入參數。
reportResult
的函式定義如下:
function reportResult(ad_selection_config, render_url, bid, contextual_signals) {
return { 'status': status, 'results': {'signals_for_buyer': signals_for_buyer,
'reporting_url': reporting_url } }; }
為了計算得標買家報表網址,服務會透過買家的 CustomAudience.getBiddingLogicUri()
擷取得標買家的 JavaScript 邏輯。接著,服務會執行買方 JS 中名為 reportWin
的其中一項函式,並提供裝置端信號、由 reportResult
計算的 signals_for_buyer
,以及 ReportImpressionRequest#getAdSelectionConfig()
中的特定欄位做為輸入參數。
reportWin
的函式定義如下:
function reportWin(ad_selection_signals, per_buyer_signals, signals_for_buyer,
contextual_signals, custom_audience_reporting_signals) { return {'status': 0, 'results':
{'reporting_url': reporting_url } }; }
此外,買方和賣方也可以選擇註冊,以便接收特定廣告事件的報表。為此,他們可分別在 reportWin
和 reportResult
中,為買家和賣家叫用平台提供的 registerAdBeacon
函式。
registerBeacon
的函式定義如下:
function registerAdBeacon(beacons)
,其中 beacons
是字串對字串的字典
對於買方/賣方希望在報表中看到的廣告事件,他們都會在 beacons
索引中加入 event_key
: event_reporting_uri
組合,其中 event_key
是該特定事件的 ID。當 SDK 叫用 reportEvent(ReportEventRequest, Executor, OutcomeReceiver)
時,此 event_key
應與 ReportEventRequest#getKey()
相符。此外,每個 event_reporting_uri
都必須正確剖析為 Uri
。這會在 SDK 叫用 reportEvent(ReportEventRequest, Executor, OutcomeReceiver)
時回報的 Uri
。
當買家/賣家新增要接收事件的所有配對組合後,即可叫用 registerAdBeacon(beacons)
,其中 beacons
是其新增組合的字典名稱。
在下列情況中,registerAdBeacon
會擲回 TypeError
:
- 系統會多次呼叫
registerAdBeacon
。如果 reportWin/reportResult 中發生這個錯誤,系統會註冊原始配對組合。 registerAdBeacon
沒有剛好 1 個字典引數。- 1 dict 引數的內容並非所有的
String: String
配對,
輸出內容會由 receiver
傳遞,後者會在成功執行時傳回空白 Object
,Exception
則包含擲回的例外狀況類型和對應的錯誤訊息。
如果擲回 IllegalArgumentException
,表示 API 收到用於回報曝光的無效輸入引數所致。
如果系統擲回 IllegalStateException
並顯示「AdSelection 服務失敗」錯誤訊息,表示廣告選擇服務發生內部失敗。
如果擲回 LimitExceededException
,是因為呼叫套件超過允許的頻率限制並受節流限制。
如果擲回 SecurityException
,代表呼叫端未獲授權或未要求權限。
最多只會記錄一次曝光。
需求:AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE
參數 | |
---|---|
request |
ReportImpressionRequest :此值不能為 null 。 |
executor |
Executor :此值不能為 null 。 |
receiver |
OutcomeReceiver :此值不能為 null 。 |
選取廣告
public void selectAds (AdSelectionFromOutcomesConfig adSelectionFromOutcomesConfig, Executor executor, OutcomeReceiver<AdSelectionOutcome, Exception> receiver)
從先前放送的廣告選擇結果中選取所需廣告。
輸入內容 adSelectionFromOutcomesConfig
是由廣告 SDK 提供,AdSelectionFromOutcomesConfig
物件會透過 Binder 呼叫傳輸。因此,這些物件的總大小受限於 Android IPC 的限制。AdSelectionFromOutcomesConfig
轉移失敗時,系統會擲回 TransactionTooLargeException
。
接收器會傳遞輸出內容,接收器成功執行後會傳回 AdSelectionOutcome
,或 Exception
包含擲回的例外狀況類型及對應的錯誤訊息。
輸入 adSelectionFromOutcomesConfig
包含:
Seller
必須是已註冊的AdTechIdentifier
。否則,系統會擲回IllegalStateException
。List of ad selection ids
應存在,且來自同一個應用程式的selectAds(AdSelectionConfig, Executor, OutcomeReceiver)
呼叫。否則,IllegalArgumentException
輸入驗證會找出違反廣告選擇 ID 的產品資訊。Selection logic URI
,其可遵循 HTTPS 或廣告選擇預先建構結構定義。如果 URI 遵循 HTTPS 結構定義,主機應與
seller
相符。否則,將會擲回IllegalArgumentException
。可藉由預先建構的 URI,將一般預先建構的邏輯換成
selectOutcome
的必要 JavaScript。這個端點的預先建構 URI 應如下所示:ad-selection-prebuilt://ad-selection-from-outcomes/<name>?<script-generation-parameters>
如果傳遞不支援的預先建構 URI,或服務停用了預先建構的 URI 功能,系統會擲回
IllegalArgumentException
。如要瞭解支援的
<name>
和必要的<script-generation-parameters>
,請參閱AdSelectionFromOutcomesConfig.Builder#setSelectionLogicUri
。
如果擲回 IllegalArgumentException
,表示 API 為了執行廣告選擇而收到的無效輸入引數。
如果系統擲回 IllegalStateException
並顯示「AdSelection 服務失敗」錯誤訊息,表示廣告選擇服務發生內部失敗。
如果擲回 TimeoutException
,表示在出價、評分或整體選擇程序找出勝出廣告時發生逾時,就會造成。
如果擲回 LimitExceededException
,是因為呼叫套件超過允許的頻率限制並受節流限制。
如果擲回 SecurityException
,代表呼叫端未獲授權或未要求權限。
需求:AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE
參數 | |
---|---|
adSelectionFromOutcomesConfig |
AdSelectionFromOutcomesConfig :此值不能為 null 。 |
executor |
Executor :此值不能為 null 。
回呼和事件監聽器會透過這個 Executor 分派,讓您輕鬆控制使用哪一個執行緒。如要透過應用程式的主要執行緒進行事件分派,可以使用 Context.getMainExecutor() 。否則,請提供會傳送至適當執行緒的 Executor 。 |
receiver |
OutcomeReceiver :此值不能為 null 。 |
選取廣告
public void selectAds (AdSelectionConfig adSelectionConfig, Executor executor, OutcomeReceiver<AdSelectionOutcome, Exception> receiver)
在裝置上執行廣告選擇程序,為呼叫端應用程式選取再行銷廣告。
輸入內容 adSelectionConfig
是由廣告 SDK 提供,AdSelectionConfig
物件會透過 Binder 呼叫傳輸。因此,這些物件的總大小受限於 Android IPC 的限制。AdSelectionConfig
轉移失敗時,系統會擲回 TransactionTooLargeException
。
輸入內容 adSelectionConfig
包含 Decision Logic Uri
,可遵循 HTTPS 或廣告選擇預先建構的結構定義。
如果 URI 遵循 HTTPS 結構定義,主機應與 seller
相符。否則,系統會擲回 IllegalArgumentException
。
可藉由預先建構的 URI,將一般預先建構的邏輯換成 scoreAds
的必要 JavaScript。這個端點的預先建構 URI 應如下所示:
ad-selection-prebuilt://ad-selection/<name>?<script-generation-parameters>
如果傳遞不支援的預先建構 URI,或服務停用了預先建構的 URI 功能,系統會擲回 IllegalArgumentException
。
如要瞭解支援的 <name>
和必要的 <script-generation-parameters>
,請參閱 AdSelectionConfig.Builder#setDecisionLogicUri
。
接收器會傳遞輸出內容,接收器成功執行後會傳回 AdSelectionOutcome
,或 Exception
包含擲回的例外狀況類型及對應的錯誤訊息。
如果擲回 IllegalArgumentException
,表示 API 為了執行廣告選擇而收到的無效輸入引數。
如果系統擲回 IllegalStateException
並顯示「AdSelection 服務失敗」錯誤訊息,表示廣告選擇服務發生內部失敗。
如果擲回 TimeoutException
,表示在出價、評分或整體選擇程序找出勝出廣告時發生逾時,就會造成。
如果擲回 LimitExceededException
,是因為呼叫套件超過允許的頻率限制並受節流限制。
如果擲回 SecurityException
,代表呼叫端未獲授權或未要求權限。
需求:AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE
參數 | |
---|---|
adSelectionConfig |
AdSelectionConfig :此值不能為 null 。 |
executor |
Executor :此值不能為 null 。
回呼和事件監聽器會透過這個 Executor 分派,讓您輕鬆控制使用哪一個執行緒。如要透過應用程式的主要執行緒進行事件分派,可以使用 Context.getMainExecutor() 。否則,請提供會傳送至適當執行緒的 Executor 。 |
receiver |
OutcomeReceiver :此值不能為 null 。 |
updateAdCounterHistogram
public void updateAdCounterHistogram (UpdateAdCounterHistogramRequest updateAdCounterHistogramRequest, Executor executor, OutcomeReceiver<Object, Exception> outcomeReceiver)
更新先前由呼叫 selectAds(android.adservices.adselection.AdSelectionConfig, java.util.concurrent.Executor, android.os.OutcomeReceiver)
選取的廣告計數器直方圖。
計數器直方圖用於廣告選擇作業,決定候選廣告的展示頻率上限篩選。在廣告選擇期間,系統會將達到或超過展示頻率上限的廣告從出價程序中移除。
只有指定 adSelectionId
的廣告,且最近從同一個呼叫端應用程式發出 FLEDGE 廣告選擇呼叫後,系統才會更新計數器直方圖。
發生下列情況時,系統會透過 outcomeReceiver
傳回 SecurityException
:
- 應用程式未在其資訊清單中宣告正確權限,或
callerAdTechIdentifier
識別的應用程式或實體無權使用此 API。
outcomeReceiver
傳回 IllegalStateException
。如果呼叫超過呼叫應用程式的 API 節流限制,系統就會透過 outcomeReceiver
傳回 LimitExceededException
。
在所有其他失敗情況下,outcomeReceiver
會傳回空白的 Object
。請注意,為了保護使用者隱私,系統不會透過例外狀況傳回內部錯誤。
需求:AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE
參數 | |
---|---|
updateAdCounterHistogramRequest |
UpdateAdCounterHistogramRequest :此值不能為 null 。 |
executor |
Executor :此值不能為 null 。
回呼和事件監聽器會透過這個 Executor 分派,讓您輕鬆控制使用哪一個執行緒。如要透過應用程式的主要執行緒進行事件分派,可以使用 Context.getMainExecutor() 。否則,請提供會傳送至適當執行緒的 Executor 。 |
outcomeReceiver |
OutcomeReceiver :此值不能為 null 。 |