AdSelectionManager

public class AdSelectionManager
extends Object

java.lang.Object
   ↳ android.adservices.adselection.AdSelectionManager

AdSelection Manager 提供的 API 可供應用程式和廣告 SDK 執行廣告選擇程序以及 報表曝光次數。

摘要

公用方法

static AdSelectionManager get(Context context)

建立 AdSelectionManager 執行個體的工廠方法。

void getAdSelectionData(GetAdSelectionDataRequest request, Executor executor, OutcomeReceiver<GetAdSelectionDataOutcome, Exception> receiver)

從裝置收集自訂目標對象資料。

TestAdSelectionManager getTestAdSelectionManager()
void persistAdSelectionResult(PersistAdSelectionResultRequest request, Executor executor, OutcomeReceiver<AdSelectionOutcome, Exception> receiver)

保留來自伺服器端的廣告選擇結果。

void reportEvent(ReportEventRequest request, Executor executor, OutcomeReceiver<Object, Exception> receiver)

通知服務有新的廣告事件，可以回報 adSelectionId 識別的廣告選擇執行作業。

void reportImpression(ReportImpressionRequest request, Executor executor, OutcomeReceiver<Object, Exception> receiver)

通知服務，根據 adSelectionId 識別的廣告選擇執行作業。

void selectAds(AdSelectionFromOutcomesConfig adSelectionFromOutcomesConfig, Executor executor, OutcomeReceiver<AdSelectionOutcome, Exception> receiver)

從先前執行廣告選擇的結果中選取廣告。

void selectAds(AdSelectionConfig adSelectionConfig, Executor executor, OutcomeReceiver<AdSelectionOutcome, Exception> receiver)

在裝置上執行廣告選擇程序，為呼叫端選擇再行銷廣告 應用程式。

void updateAdCounterHistogram(UpdateAdCounterHistogramRequest updateAdCounterHistogramRequest, Executor executor, OutcomeReceiver<Object, Exception> outcomeReceiver)

更新先前呼叫 selectAds(android.adservices.adselection.AdSelectionConfig, java.util.concurrent.Executor, android.os.OutcomeReceiver) 所選取廣告的計數器直方圖。

繼承方法

公用方法

get

已加至 API 級別 34
也已納入 Ad Services Extensions 6 
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，才能收集。

請參閱 AdSelectionManager#persistAdSelectionResult，瞭解如何處理 廣告選擇程序會在伺服器端與這個 API 產生的 blob 執行。

接收器會傳遞輸出內容，接收器會傳回 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

已加至 API 級別 34
也已納入 Ad Services Extensions 4 
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。

reportEvent

public void reportEvent (ReportEventRequest request, 
                Executor executor, 
                OutcomeReceiver<Object, Exception> receiver)

通知服務有新的廣告事件，可以回報 adSelectionId 識別的廣告選擇執行作業。廣告事件是指 會發生在與指定 adSelectionId 相關聯的廣告上。無法保證 系統記錄廣告事件的時段。事件報表可能會延遲產生 。

使用 ReportEventRequest#getKey()，服務就會擷取 reportingUri (在 registerAdBeacon 註冊)。如要進一步瞭解「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。

報表曝光

已加至 API 級別 34
也已納入 Ad Services Extensions 4 
public void reportImpression (ReportImpressionRequest request, 
                Executor executor, 
                OutcomeReceiver<Object, Exception> receiver)

通知服務，根據 adSelectionId 識別的廣告選擇執行作業。無法保證 的曝光數。曝光報表可能會延遲產生 。

服務會擷取賣方的 JavaScript，以便計算勝出賣方報表網址 來自 ReportImpressionRequest.getAdSelectionConfig() 的 AdSelectionConfig#getDecisionLogicUri() 邏輯。接著，服務會執行 在賣方 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 的其中一項函式，以提供 裝置端信號、signals_for_buyer (依 reportResult) 以及特定 ] 欄位做為輸入參數。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 } }; }

此外，買方和賣方可以選擇註冊，以便接收 廣告事件。做法是叫用平台提供的 registerAdBeacon 函式 在 reportWin 和 reportResult 中，分別適用於買方和賣方。

registerBeacon 的函式定義如下：

function registerAdBeacon(beacons)，其中 beacons 是下列字串的字典 字串組合

對於買方/賣方想取得報表的每一個廣告事件，他們會在 beacons 字典中加入 event_key：event_reporting_uri 組合，其中 event_key 是該特定事件的 ID。這部event_key應該相符 當 SDK 叫用 reportEvent(ReportEventRequest, Executor, OutcomeReceiver) 時為 ReportEventRequest#getKey()。此外， 每個 event_reporting_uri 都應該正確剖析為 Uri。這個 是 SDK 叫用 reportEvent(ReportEventRequest, Executor, OutcomeReceiver) 時回報的 Uri。

買方/賣方新增想接收活動的所有配對後，即可 叫用 registerAdBeacon(beacons)，其中 beacons 是其字典名稱 已把這組配對新增至。

在下列情況下，registerAdBeacon 會擲回 TypeError：

  1. 重複呼叫 registerAdBeacon。如果發生此錯誤 reportWin/reportResult，系統會登錄原始配對組合
  2. registerAdBeacon 沒有剛好 1 個字典引數。
  3. 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 包含：

如果擲回 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。

選取廣告

已加至 API 級別 34 
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，或 服務，則系統會擲回 IllegalArgumentException。

請參閱 AdSelectionConfig.Builder#setDecisionLogicUri，瞭解支援的 <name> 和 必要值為 <script-generation-parameters>。

輸出內容會由接收器傳遞，接收器會傳回 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：

  1. 應用程式未在資訊清單中宣告正確的權限；或
  2. 「callerAdTechIdentifier」識別的應用程式或實體未獲得授權 才能使用 API
，瞭解如何調查及移除這項存取權。 如果呼叫達成，系統會透過 outcomeReceiver 傳回 IllegalStateException 這類行為並非來自包含前景活動的應用程式。

如果呼叫，透過 outcomeReceiver 傳回 LimitExceededException 超出呼叫應用程式的 API 節流範圍。

在所有其他失敗情況下，outcomeReceiver 會傳回空白的 Object。請注意，為了保護使用者隱私，系統不會透過 例外狀況。
系統需求：AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE

參數
updateAdCounterHistogramRequest UpdateAdCounterHistogramRequest：此值不能為 null。
executor Executor：此值不能為 null。 回呼和事件監聽器事件會透過這個 Executor，可讓您輕鬆控制 如何透過應用程式的主執行緒分派事件 可以使用 Context.getMainExecutor()。 否則，請提供會調度至適當執行緒的 Executor。
outcomeReceiver OutcomeReceiver：此值不能為 null。