已新增至 API 級別 34
Ad Services Extensions 4 也已納入
摘要：方法 | 沿用的方法

AdSelectionManager

public class AdSelectionManager
extends Object

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

AdSelection Manager 為應用程式和廣告 SDK 提供 API 以執行廣告選擇程序，以及回報曝光。

摘要

公用方法

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，才符合收集資格。

如要瞭解如何處理廣告選擇的結果，以便在伺服器端與這個 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

已加至 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。

報告事件

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

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

  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，或服務停用了預先建構的 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：

  1. 應用程式未在其資訊清單中宣告正確權限，或
  2. 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。