Android 版 FLEDGE 開發人員指南

Stay organized with collections Save and categorize content based on your preferences.

Android 版 FLEDGE 包含 Custom Audience API 和 Ad Select API。廣告技術平台和廣告客戶可利用這些 API,根據先前的應用程式參與度放送自訂廣告,藉此限制不同應用程式的 ID 共用,並限制使用者與第三方的應用程式互動資訊。

Custom Audience API 以「自訂目標對象」抽象為中心,代表有共通意圖的使用者群組。廣告客戶可以向自訂目標對象登錄使用者,並為相關廣告建立關聯。此資訊會儲存在本機中,並且可用以提供廣告客戶出價、廣告篩選和廣告顯示的相關資訊。

AdChoice API 提供的架構可讓多名開發人員針對自訂目標對象進行本機競價。因此,系統會考慮與自訂目標對象相關的廣告,並針對廣告技術平台傳回裝置的廣告進行額外的處理。

廣告技術平台可以整合這些 API 以實作再行銷,藉此保護使用者隱私。我們計劃在未來的版本中提供更多用途的支援 (包括應用程式安裝廣告)。如要進一步瞭解 Android 版 FLEDGE,請參閱設計提案

本開發人員指南說明如何使用 Android 版 FLEDGE 執行下列操作:

  1. 管理自訂目標對象
  2. 在裝置上設定及執行廣告選擇
  3. 回報廣告曝光次數

事前準備

在開始之前,請先完成下列操作:

  1. 在 Android 裝置上為 Privacy Sandbox 設定開發環境
  2. 將系統映像檔安裝到支援的裝置上,或者設定支援 Android 版 Privacy Sandbox 的模擬器

加入自訂目標對象

「自訂目標對象」代表由廣告客戶應用程式決定,且具有共同意圖或興趣的使用者。應用程式或 SDK 可以使用自訂目標對象來表示特定目標對象,例如曾將商品放入購物車的使用者。如要以非同步的方式建立或加入自訂目標對象,請按照下列步驟操作:

  1. CustomAudienceManager 物件初始化。
  2. 指定買家套件和相關名稱等重要參數以建立 CustomAudience 物件。然後,使用 CustomAudience 物件初始化 JoinCustomAudienceRequest 物件。
  3. 使用 JoinCustomAudienceRequest 物件和相關的 ExecutorOutcomeReceiver 物件呼叫非同步 joinCustomAudience()

Kotlin

val customAudienceManager: CustomAudienceManager =
    context.getSystemService(CustomAudienceManager::class.java)

// Initialize a custom audience.
val audience = CustomAudience.Builder()
    .setBuyer(buyer)
    .setName(name)
    ...
    .build()

// Initialize a custom audience request.
val joinCustomAudienceRequest: JoinCustomAudienceRequest =
    JoinCustomAudienceRequest.Builder().setCustomAudience(audience).build()

// Request to join a custom audience.
customAudienceManager.joinCustomAudience(joinCustomAudienceRequest,
    executor,
    outcomeReceiver)

Java

CustomAudienceManager customAudienceManager =
    context.getSystemService(CustomAudienceManager.class);

// Initialize a custom audience.
CustomAudience audience = new CustomAudience.Builder()
    .setBuyer(buyer)
    .setName(name)
    ...
    .build();

// Initialize a custom audience request.
JoinCustomAudienceRequest joinCustomAudienceRequest =
    new JoinCustomAudienceRequest.Builder().setCustomAudience(audience).build();

// Request to join a custom audience.
customAudienceManager.joinCustomAudience(joinCustomAudienceRequest,
    executor,
    outcomeReceiver);

下列參數的組合可明確識別裝置上的每個 CustomAudience 物件:

  • owner:擁有者應用程式的套件名稱。如果沒有指定,則預設為呼叫應用程式的套件名稱。
  • buyer:管理此自訂目標對象廣告的買家廣告聯播網 ID。
  • name:自訂目標對象的任意名稱或 ID。

使用 CustomAudience 的不同執行個體重複呼叫 joinCustomAudience(),將以比對符合的 owner, buyer,以及 name 參數更新任何現有的 CustomAudience。為保護隱私,API 的結果不會區分「建立」和「更新」。

此外,CustomAudience 必須使用以下必要參數建立:

  • 每日更新網址:每天在背景中查詢的 HTTPS 網址,可更新自訂目標對象的使用者出價信號、受信任的出價資料,以及廣告的顯示網址和中繼資料。
  • 出價邏輯網址:在廣告選擇期間查詢的 HTTPS 網址,以擷取買家的 JavaScript 出價邏輯。請參閱此 JavaScript 中所需的函式簽名

CustomAudience 物件的選用參數可能包括:

  • 啟用時間:自訂目標對象只能於啟用時間過後參與廣告選擇和每日更新。舉例來說,您可以利用此方式吸引很久沒有使用應用程式的使用者進行互動。
  • 到期時間:將自訂目標對象從裝置中移除的未來時間。
  • 使用者出價信號:包含使用者信號 (例如使用者偏好語言) 的 JSON 字串,廣告選擇程序期間,買家的出價邏輯 JavaScript 將會用以產生出價。此格式可協助廣告技術平台在多個平台之間重複使用程式碼,並減少 JavaScript 函式的使用量。
  • 受信任的出價資料:廣告選擇程序期間使用的 HTTPS 網址和字串清安,可從受信任的鍵/值伺服器擷取出價信號。
  • 廣告:與廣告對應,且將參與廣告選擇的 AdData 物件。每個 AdData 物件都由以下項目組成:
    • 顯示網址:要查詢以顯示最終廣告的 HTTPS 網址。
    • 中繼資料:序列化為字串的 JSON 物件,包含在廣告選擇程序中供買家出價邏輯使用的資訊。

以下是 CustomAudience 物件執行個體化的範例:

Kotlin

// Minimal initialization of a CustomAudience object
val customAudience: CustomAudience = CustomAudience.Builder()
    .setBuyer("my.buyer.domain.name")
    .setName("example-custom-audience-name")
    .setDailyUpdateUrl(Uri.parse("https://DAILY_UPDATE_URL"))
    .setBiddingLogicUrl(Uri.parse("https://BIDDING_LOGIC_URL"))
    .build()

Java

// Minimal initialization of a CustomAudience object
CustomAudience customAudience = CustomAudience.Builder()
    .setBuyer("my.buyer.domain.name")
    .setName("example-custom-audience-name")
    .setDailyUpdateUrl(Uri.parse("https://DAILY_UPDATE_URL"))
    .setBiddingLogicUrl(Uri.parse("https://BIDDING_LOGIC_URL"))
    .build();

處理 joinCustomAudience() 結果

非同步 joinCustomAudience() 方法會使用 OutcomeReceiver 物件以指出 API 呼叫的結果。

  • onResult() 回呼代表自訂目標對象已成功建立或更新。
  • onError() 回呼代表兩種可能的條件。

以下是處理 joinCustomAudience() 結果的範例:

Kotlin

var callback: OutcomeReceiver<Void, AdServicesException> =
    object : OutcomeReceiver<Void, AdServicesException> {
    override fun onResult(result: Void) {
        Log.i("CustomAudience", "Completed joinCustomAudience")
    }

    override fun onError(error: AdServicesException) {
        // Handle error
        Log.e("CustomAudience", "Error executing joinCustomAudience", error)
    }
};

Java

OutcomeReceiver callback = new OutcomeReceiver<Void, AdServicesException>() {
    @Override
    public void onResult(@NonNull Void result) {
        Log.i("CustomAudience", "Completed joinCustomAudience");
    }

    @Override
    public void onError(@NonNull AdServicesException error) {
        // Handle error
        Log.e("CustomAudience", "Error executing joinCustomAudience", error);
    }
};

退出自訂目標對象

如果使用者不再滿足特定自訂目標對象的業務條件,應用程式或 SDK 可呼叫 leaveCustomAudience(),從裝置中移除自訂目標對象。如要根據專用參數移除特定的 CustomAudience,請執行下列步驟:

  1. CustomAudienceManager 物件初始化。
  2. 使用自訂目標對象的 owner, buyername 初始化 LeaveCustomAudienceRequest。如要進一步瞭解這些輸入欄位,請參閱「加入自訂目標對象」。
  3. 使用 LeaveCustomAudienceRequest 物件和相關的 ExecutorOutcomeReceiver 物件呼叫非同步 leaveCustomAudience()

Kotlin

val customAudienceManager: CustomAudienceManager =
    context.getSystemService(CustomAudienceManager::class.java)

// Initialize a LeaveCustomAudienceRequest
val leaveCustomAudienceRequest: LeaveCustomAudienceRequest =
    JoinCustomAudienceRequest.Builder()
        .setOwner(owner)
        .setBuyer(buyer)
        .setName(name)
        .build()

// Request to leave a custom audience
customAudienceManager.leaveCustomAudience(
    leaveCustomAudienceRequest,
    executor,
    outcomeReceiver)

Java

CustomAudienceManager customAudienceManager =
    context.getSystemService(CustomAudienceManager.class);

// Initialize a LeaveCustomAudienceRequest
LeaveCustomAudienceRequest leaveCustomAudienceRequest =
    new JoinCustomAudienceRequest.Builder()
        .setOwner(owner)
        .setBuyer(buyer)
        .setName(name)
        .build();

// Request to leave a custom audience
customAudienceManager.leaveCustomAudience(
    leaveCustomAudienceRequest,
    executor,
    outcomeReceiver);

與呼叫 joinCustomAudience() 類似,OutcomeReceiver 會發出 API 呼叫的結尾。為保護隱私,錯誤結果不會區分內部錯誤和無效的引數。API 呼叫完成時,不論是否成功移除相符的自訂目標對象,系統都會呼叫 onResult() 回呼。

執行廣告選擇

如要使用 FLEDGE 選擇廣告,請呼叫 runAdSelection() 方法:

  1. 初始化 AdSelectionManager 物件。
  2. 建立 AdSelectionConfig 物件。
  3. 使用 AdSelectionConfig 物件和相關的 ExecutorOutcomeReceiver 物件呼叫非同步 runAdSelection()

Kotlin

val adSelectionManager: AdSelectionManager =
    context.getSystemService(AdSelectionManager::class.java)

// Initialize AdSelectionConfig
val adSelectionConfig: AdSelectionConfig =
        AdSelectionConfig.Builder()
                .setSeller(seller)
                .setDecisionLogicUrl(decisionLogicUrl)
                .setCustomAudienceBuyers(customAudienceBuyers)
                .setAdSelectionSignals(adSelectionSignals)
                .setSellerSignals(sellerSignals)
                .setPerBuyerSignals(perBuyerSignals)
                .build()

// Run ad selection with AdSelectionConfig
adSelectionManager.runAdSelection(
    adSelectionConfig,
    executor,
    outcomeReceiver)

Java

AdSelectionManager adSelectionManager =
    context.getSystemService(AdSelectionManager.class);

// Initialize AdSelectionConfig
AdSelectionConfig adSelectionConfig =
        new AdSelectionConfig.Builder()
                .setSeller(seller)
                .setDecisionLogicUrl(decisionLogicUrl)
                .setCustomAudienceBuyers(customAudienceBuyers)
                .setAdSelectionSignals(adSelectionSignals)
                .setSellerSignals(sellerSignals)
                .setPerBuyerSignals(perBuyerSignals)
                .build();

// Run ad selection with AdSelectionConfig
adSelectionManager.runAdSelection(
    adSelectionConfig,
    executor,
    outcomeReceiver);

runAdSelection() 方法需要 AdSelectionConfig 輸入內容,您必須在其中指定以下必要參數:

  • 賣家:開始廣告選擇的賣家廣告聯播網 ID。
  • 決策邏輯網址:為了取得賣家廣告聯播網的 JavaScript 邏輯而查詢的 HTTPS 網址。請參閱此 JavaScript 中所需的函式簽名
  • 自訂目標對象買家:買家廣告聯播網的完整 ID 清單,可讓賣家參與廣告選擇流程。 這些買家 ID 會對應至自訂目標對象的 CustomAudience.getBuyer()。

下列參數可選擇性指定更多自訂廣告選項:

  • 廣告選擇信號:序列化為字串的 JSON 物件,包含 CustomAudience.getBiddingLogicUrl() 中買家出價邏輯 JavaScript 所使用的信號。
  • 賣家信號:序列化為字串的 JSON 物件,包含 AdSelectionConfig.getDecisionLogicUrl() 中賣家擷取 JavaScript 決策邏輯所使用的信號。
  • 個別買方信號:序列化為字串的 JSON 物件地圖,包含從 CustomAudience.getBiddingLogicUrl() 擷取的特定買家出價邏輯 JavaScript 所使用的信號,且這些信號由參與自訂目標對象的買家欄位辨識。

選擇廣告之後,系統會在內部保留結果、出價和信號,以供日後製作報表時使用。透過 ResultReceiver.onResult() 回呼,您會傳回包含以下內容的 AdSelectionResult:

  • AdData.getRenderUrl() 取得的得標廣告顯示網址。
  • 裝置使用者專屬的廣告選擇 ID。此 ID 用以記錄廣告曝光次數

如果因引數無效、逾時或資源消耗過多等因素而無法成功完成廣告選擇,OutcomeReceiver.onError() 回呼就會提供 AdServicesException

  • 如果廣告選擇以無效引數開始,AdServicesException 會顯示 IllegalArgumentException 做為原因。
  • 所有其他錯誤都會收到 AdServicesException,並以 IllegalStateException 表示原因。

回報廣告曝光

從廣告選擇工作流程中選擇得標的廣告後,就可以使用 AdSelectionManager.reportImpression() 方法,向參與的買家和賣家平台回報曝光次數。如何回報廣告曝光:

  1. 初始化 AdSelectionManager 物件。
  2. 使用廣告選擇 ID 建立 ReportImpressionRequest 物件。
  3. 使用 AdSelectionConfig 物件和相關的 ExecutorOutcomeReceiver 物件呼叫非同步 reportImpression()

Java

AdSelectionManager adSelectionManager =
    context.getSystemService(AdSelectionManager.class);

// Initialize a ReportImpressionRequest
ReportImpressionRequest adSelectionConfig =
        new ReportImpressionRequest.Builder()
                .setAdSelectionId(adSelectionId)
                .setAdSelectionConfig(adSelectionConfig);
                .build();

// Request to report the impression with the ReportImpressionRequest
adSelectionManager.reportImpression(
    reportImpressionRequest,
    executor,
    outcomeReceiver);

Kotlin

val adSelectionManager = context.getSystemService(AdSelectionManager::class.java)

// Initialize a ReportImpressionRequest
val adSelectionConfig: ReportImpressionRequest =
    ReportImpressionRequest.Builder()
        .setAdSelectionId(adSelectionId)
        .setAdSelectionConfig(adSelectionConfig);
        .build()

// Request to report the impression with the ReportImpressionRequest
adSelectionManager.reportImpression(
    reportImpressionRequest,
    executor,
    outcomeReceiver)

使用下列必要參數初始化 ReportImpressionRequest

  • 廣告選擇 ID:裝置使用者裝屬 ID,可識別廣告選擇。
  • 廣告選擇設定:與提供的廣告選擇 ID 辨識的 runAdSelection() 呼叫中使用設定相同的設定。

非同步 reportImpression() 方法會使用 OutcomeReceiver 物件以指出 API 呼叫的結果。

  • onResult() 回呼會指出廣告選擇是否已經完成。
  • onError() 回呼表示可能有以下狀況:
    • 如果呼叫是以無效的輸入引數初始化,AdServicesException 會顯示 IllegalArgumentException 做為原因。
    • 所有其他錯誤都會收到 AdServicesException,並以 IllegalStateException 表示原因。

曝光報表端點

Report Impression API 會向賣家平台和得標買家平台提供的端點發出 HTTPS GET 要求:

買家平台端點:

  • API 會使用自訂目標對象中指定的出價邏輯網址擷取買家的出價邏輯 JavaScript。
  • 叫用 reportResult() JavaScript 函式,然後就應會傳回買家的曝光報表網址。

賣家平台端點:

  • 使用 AdSelectionConfig 物件中指定的 決策邏輯網址擷取賣家的決策邏輯 JavaScript。
  • 叫用 reportWin() JavaScript 函式,然後就應會傳回買家曝光報表網址。

最佳效果曝光報表

reportImpression() 旨在提供最佳的報表。

廣告選擇專用的 JavaScript

廣告選擇工作流程可自動化調度管理買家提供和賣家提供的 JavaScript。

買家提供的 JavaScript 是擷取自自訂目標對象指定的出價邏輯網址。傳回的 JavaScript 應包含下列函式:

賣家提供的 JavaScript 是擷取自廣告選擇 API 的 AdSelectionConfig 參數中指定的決策邏輯網址。傳回的 JavaScript 應包含下列函式:

generateBid()

function generateBid(
   ad,
   auction_signals,
   per_buyer_signals,
   trusted_bidding_signals,
   contextual_signals,
   user_signals,
   custom_audience_signals) {
  return {'status': 0, 'ad': ad, 'bid': ad.metadata.result };
}

輸入參數:

  • ad:採用以下格式的變異格是的 JSON 物件:ad = { 'render_url': url, 'metadata': json_metadata }
  • auction_signals, per_buyer_signals:JSON 物件,這些物件會在競價設定物件中指定
  • custom_audience_signals:平台產生的 JSON 物件。此 JSON 物件的格式如下:

    var custom_audience_signals = {
      "owner":"ca_owner",
      "buyer":"ca_buyer",
      "name":"ca_name",
      "activation_time":"ca_activation_time_epoch_ms",
      "expiration_time":"ca_expiration_time_epoch_ms",
      "user_bidding_signals":"ca_user_bidding_signals"
    }
    

    where:

    • owner, buyername 是取自屬性的字串,且名稱與參與廣告選擇的自訂目標對象相同
    • activation_timeexpiration_time 是自訂目標對象啟用和到期的時間,以 Unix Epoch 紀元時間起算的秒數表示。
    • ca_user_bidding_signals 是建立時,在 CustomAudienceuserBiddingSignals 欄位中指定的 JSON 字串
    • trusted_bidding_signals, contextual_signalsuser_signals 是 JSON 物件。這些物件目前是以空白物件的形式傳遞,且會在日後推出的版本中加入內容。這種格式並非由平台強制執行,而是由廣告技術管理。

成果:

  • ad:出價參考的廣告。允許使用指令碼以回傳有不同中繼資料的廣告複本。廣告的 render_url 屬性應該不會改變。
  • bid:代表這則廣告出價的浮點值
  • status:整數值,可能如下:
    • 0:成功執行
    • 1:(或任何非零值) 任何輸入信號無效時。如果產生的出價傳回非零值,則所有 CA 廣告的出價程序都會失效

scoreAd()

function scoreAd(
  ad,
  bid,
  ad_selection_config,
  seller_signals,
  trusted_scoring_signals,
  contextual_signal,
  user_signal,
  custom_audience_signal) {
    return {'status': 0, 'score': score };
}

輸入參數:

  • 請參閱ad說明文件generateBid
  • bid:廣告出價的值
  • ad_selection_config:JSON 物件,代表 runAdSelection API 的 AdSelectionConfig 參數。格式為:

    var ad_selection_config = {
      'seller': 'seller',
      'decision_logic_url': 'url_of_decision_logic',
      'custom_audience_buyers': ['buyer1', 'buyer2'],
      'auction_signals': auction_signals,
      'per_buyer_signals': per_buyer_signals,
      'contextual_ads': [ad1, ad2]
    }
    
  • seller_signals:讀取自 sellerSignals AdSelectionConfig API 參數的 JSON 物件

  • trusted_scoring_signal:讀取自 AdSelectionConfig API 參數中的 adSelectionSignals 欄位

  • contextual_signals, user_signals:JSON 物件。這些物件目前是以空白物件的形式傳遞,且會在日後推出的版本中加入內容。這種格式並非由平台強制執行,而是由廣告技術管理

  • per_buyer_signals:讀取自 AdSelectionConfig API 參數中 perBuyerSignal 對應讀取的 JSON 物件,做為目前自訂目標對象買家的索引鍵。如果對應內容未包含特定買家的任何項目,則為空白。

輸出內容:

  • score:代表這則廣告評分值的浮點值
  • status:整數值,可能如下:
    • 0:成功執行
    • 1:如果 customAudienceSignals 無效
    • 2:如果 AdSelectionConfig 無效
    • 3:如果任何其他信號無效
    • 任何非零的值都會導致程序失敗,且此值將決定擲回例外狀況的類型

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 }
   };
}

輸入參數:

  • ad_selection_config:請參閱 scoreAds 的說明文件
  • render_url:得標廣告的顯示網址
  • bid:得標廣告的出價
  • contextual_signals:請參閱 generateBid 的說明文件

輸出內容:

  • status: 0 為成功,非零為失敗
  • results:JSON 物件,包含以下項目:
    • signals_for_buyer:要傳遞至 reportWin 函式的 JSON 物件
    • reporting_url:平台會為了向買家通知曝光而使用的網址

reportWin()

function reportWin(
   ad_selection_signals,
   per_buyer_signals,
   signals_for_buyer,
   contextual_signals,
   custom_audience_signals) {
   return {'status': 0, 'results': {'reporting_url': reporting_url } };
}

輸入參數:

  • ad_selection_signals, per_buyer_signals:請參閱 scoreAds 的說明文件
  • signals_for_buyerreportResult 傳回的 JSON 物件
  • contextual_signals, custom_audience_signals:請參閱 generateBid 的說明文件

輸出內容:

  • status: 0 為成功,非零為失敗
  • results:JSON 物件,包含以下項目:
    • reporting_url:平台為了向賣家通知曝光而使用的網址

測試

為了協助您開始使用 FLEDGE,我們在 GitHub 上提供了 Kotlin 和 Java 的範例應用程式。

必要條件

在選擇廣告以及製作曝光報表時,FLEDGE 需要一些 JavaScript。 在測試環境中提供這個 JavaScript 的方法有兩種:

  • 執行內含傳回 JavaScript 的必要 HTTP 的端點的伺服器
  • 提供來自本機來源的必要程式碼,以覆寫遠端擷取

無論採用哪一種方法,都需要設定 HTTPS 端點來處理曝光報表。

HTTPS 端點

若要測試廣告選擇和曝光報表,您必須設定 4 個測試裝置或模擬器可存取的 HTTPS 端點:

  1. 提供出價邏輯 JavaScript 的買家端點。
  2. 提供決策邏輯 JavaScript 的賣家端點。
  3. 得標買家曝光報表端點。
  4. 賣家曝光報表端點。

為了方便您起見,GitHub 存放區提供基本的 JavaScript 程式碼可供您進行測試。其中也包含 OpenAPI 服務定義,可部署至支援的模擬或微服務平台。詳情請參閱專案 README

覆寫遠端擷取 JavaScript

這項功能用於端對端測試。如要覆寫遠端擷取功能,應用程式必須在偵錯模式中執行,並啟用開發人員選項。

如要為您的應用程式啟用偵錯模式,請將以下程式碼新增至 AndroidManifest.xml 的應用程式屬性:

<application
  android:debuggable="true">

如需如何使用這些覆寫的範例,請參閱 GitHub 上的「FLEDGE 範例應用程式」。

您必須自行新增 JavaScript 來處理廣告選擇日常安排,例如出價、評分決策和報表。您可以在 GitHub 存放區中找到處理所有必要要求的基本 JavaScript 程式碼範例。FLEDGE 範例應用程式示範如何讀取該檔案中的程式碼,並準備將其用做覆寫。

您可以獨立覆寫賣方和買方 JavaScript 擷取,不過必須具備 HTTPS 端點才能提供任何覆寫的 JavaScript。如要瞭解如何設定處理這些情況的伺服器,請參閱「README」。

您只能覆寫擷取您的套件擁有的自訂目標對象的 JavaScript。

覆寫賣方 JavaScript

如要設定賣方 JavaScript 的覆寫值,請按照下方程式碼範例所示:

  1. 初始化 AdSelectionManager 物件。
  2. 建立 AdSelectionConfig 物件。
  3. 使用 AdSelectionConfig 物件和 String 建構 AddAdSelectionOverrideRequest 代表您打算當做覆寫使用的 JavaScript。
  4. 使用 AddAdSelectionOverrideRequest 物件和相關的 ExecutorOutcomeReceiver 物件呼叫非同步 overrideAdSelectionConfigRemoteInfo()

Kotlin

val adSelectionManager: AdSelectionManager =
    context.getSystemService(AdSelectionManager::class.java)

// Initialize AdSelectionConfig =
val adSelectionConfig = new AdSelectionConfig.Builder()
    .setSeller(seller)
    .setDecisionLogicUrl(decisionLogicUrl)
    .setCustomAudienceBuyers(customAudienceBuyers)
    .setAdSelectionSignals(adSelectionSignals)
    .setSellerSignals(sellerSignals)
    .setPerBuyerSignals(perBuyerSignals)
    .build()

// Initialize AddAddSelectionOverrideRequest
val request = AddAdSelectionOverrideRequest.Builder()
    .setAdSelectionConfig(adSelectionConfig)
    .setDecisionLogicJs(decisionLogicJS)
    .build()

// Run the call to override the JavaScript for the given AdSelectionConfig
// Note that this only takes effect in apps marked as debuggable
adSelectionManager.overrideAdSelectionConfigRemoteInfo(
    request,
    executor,
    outComeReceiver)

Java

AdSelectionManager adSelectionManager: AdSelectionManager =
    context.getSystemService(AdSelectionManager.class);

// Initialize AdSelectionConfig =
AdSelectionConfig adSelectionConfig = new AdSelectionConfig.Builder()
    .setSeller(seller)
    .setDecisionLogicUrl(decisionLogicUrl)
    .setCustomAudienceBuyers(customAudienceBuyers)
    .setAdSelectionSignals(adSelectionSignals)
    .setSellerSignals(sellerSignals)
    .setPerBuyerSignals(perBuyerSignals)
    .build();

// Initialize AddAddSelectionOverrideRequest
AddAdSelectionOverrideRequest request = AddAdSelectionOverrideRequest.Builder()
    .setAdSelectionConfig(adSelectionConfig)
    .setDecisionLogicJs(decisionLogicJS)
    .build();

// Run the call to override the JavaScript for the given AdSelectionConfig
// Note that this only takes effect in apps marked as debuggable
adSelectionManager.overrideAdSelectionConfigRemoteInfo(
    request,
    executor,
    outComeReceiver);

如要進一步瞭解 AdSelectionConfig 中每個欄位代表的意義,請參閱「執行廣告選擇」一節。主要差異在於「decisionLogicUrl」可以設為預留位置值,系統會忽略該值。

如要覆寫廣告選擇期間使用的 JavaScript,decisionLogicJs 必須包含適當的賣方端函式簽章。如需如何以字串形式讀取 JavaScript 檔案的範例,請參閱 GitHub 上的「FLEDGE 範例應用程式」。

非同步 overrideAdSelectionConfigRemoteInfo() 方法會使用 OutcomeReceiver 物件以指出 API 呼叫的結果。

onResult() 回呼表示已成功套用覆寫值。日後對 runAdSelection() 的呼叫將使用您曾傳遞的任何的報表與邏輯做為覆寫。

onError() 回呼代表兩種可能的條件。

  • 如果嘗試以無效的引數執行覆寫,AdServiceException 會顯示 IllegalArgumentException 做為原因。
  • 如果在已啟用開發人員選項但應用程式未執行偵錯模式時嘗試覆寫,AdServiceException 會顯示 IllegalStateException 為原因。

重設賣方覆寫值

本節假設您已覆寫賣方 JavaScript,並已參考前一節使用過的 AdSelectionManagerAdSelectionConfig

如何重設所有 AdSelectionConfigs 的覆寫值:

  1. 使用相關的 OutcomeReceiver 物件呼叫非同步 resetAllAdSelectionConfigRemoteOverrides() 方法。

Kotlin

// Resets overrides for all AdSelectionConfigs
adSelectionManager.resetAllAdSelectionConfigRemoteOverrides(
    outComeReceiver)

Java

// Resets overrides for all AdSelectionConfigs
adSelectionManager.resetAllAdSelectionConfigRemoteOverrides(
    outComeReceiver)

重設賣方覆寫值後,日後呼叫 runAdSelection() 時,系統將使用儲存在 AdSelectionConfig 中的任何 decisionLogicUrl 以嘗試擷取必要的 JavaScript。

如果呼叫 resetAllAdSelectionConfigRemoteOverrides() 失敗,OutComeReceiver.onError() 回呼會提供 AdServiceException。如果在已啟用開發人員選項但應用程式未執行偵錯模式時,嘗試移除覆寫值,則 AdServiceException 會顯示 IllegalStateException 做為原因。

覆寫買方 JavaScript

  1. 請按照步驟加入自訂目標對象
  2. 使用要覆寫的自訂目標對象的「擁有者」、「買方」和「名稱」 來建立 AddCustomAudienceOverrideRequest,除了要當做覆寫值的出價邏輯和資料。
  3. 使用 AddCustomAudienceOverrideRequest 物件和相關的 ExecutorOutcomeReceiver 物件呼叫非同步 overrideCustomAudienceRemoteInfo()

Kotlin

val customAudienceManager: CustomAudienceManager =
    context.getSystemService(CustomAudienceManager::class.java)

// Join custom audience

// Build the AddCustomAudienceOverrideRequest
val request = AddCustomAudienceOverrideRequest.Builder()
    .setOwner(owner)
    .setBuyer(buyer)
    .setName(name)
    .setBiddingLogicJs(biddingLogicJS)
    .setTrustedBiddingData(trustedBiddingData)
    .build()

// Run the call to override JavaScript for the given custom audience
customAudienceManager.overrideCustomAudienceRemoteInfo(
    request,
    executor,
    outComeReceiver)

Java

CustomAudienceManager customAudienceManager: CustomAudienceManager =
    context.getSystemService(CustomAudienceManager.class);

// Join custom audience

// Build the AddCustomAudienceOverrideRequest
AddCustomAudienceOverrideRequest request =
    AddCustomAudienceOverrideRequest.Builder()
        .setOwner(owner)
        .setBuyer(buyer)
        .setName(name)
        .setBiddingLogicJs(biddingLogicJS)
        .setTrustedBiddingData(trustedBiddingData)
        .build();

// Run the call to override JavaScript for the given custom audience
customAudienceManager.overrideCustomAudienceRemoteInfo(
    request,
    executor,
    outComeReceiver);

「擁有者」、「買家」和「名字」 的值與用來建立自訂目標對象的值相同。進一步瞭解這些欄位

此外,您還可以指定兩個額外參數:

  • biddingLogicJs:會保留買方在選取廣告時會用到的邏輯的 JavaScript。請參閱此 JavaScript 中所需的函式簽名
  • trustedBiddingData:選擇廣告時使用的出價信號。測試時,可以留空。

非同步 overrideCustomAudienceRemoteInfo() 方法會使用 OutcomeReceiver 物件以指出 API 呼叫的結果。

onResult() 回呼表示已成功套用覆寫值。日後對 runAdSelection() 的呼叫將使用您曾傳遞的任何的出價與報表邏輯做為覆寫。

onError() 回呼代表兩種可能的條件。

  • 如果嘗試以無效的引數執行覆寫,AdServiceException 會顯示 IllegalArgumentException 做為原因。
  • 如果在已啟用開發人員選項但應用程式未執行偵錯模式時嘗試覆寫,AdServiceException 會顯示 IllegalStateException 為原因。

重設買方覆寫

本節假設您已覆寫買方 JavaScript,且已參照上一節中使用的 CustomAudienceManager

如要重設所有自訂目標對象的覆寫值,請按照下列步驟操作:

  1. 使用相關的 ExecutorOutcomeReceiver 物件呼叫非同步的 resetAllCustomAudienceOverrides() 方法。

Kotlin

// Resets overrides for all custom audiences
customAudienceManager.resetCustomAudienceRemoteInfoOverride(
    executor,
    outComeReceiver)

Java

// Resets overrides for all custom audiences
customAudienceManager.resetCustomAudienceRemoteInfoOverride(
    executor,
    outComeReceiver)

重設買方覆寫值後,日後呼叫 runAdSelection() 時,系統將使用儲存在 CustomAudience 中的任何 biddingLogicUrltrustedBiddingData 以嘗試擷取必要的 JavaScript。

如果呼叫 resetCustomAudienceRemoteInfoOverride() 失敗,OutComeReceiver.onError() 回呼會提供 AdServiceException。如果在已啟用開發人員選項但應用程式未執行偵錯模式時,嘗試移除覆寫值,則 AdServiceException 會顯示 IllegalStateException 做為原因。

設定回報伺服器

使用遠端擷取覆寫功能時,仍須設定裝置或模擬器可以存取的伺服器,以回應報報表事件。傳回 200 的簡單端點就足以進行測試。GitHub 存放區包含 OpenAPI 服務定義,可部署至支援的模擬或微服務平台。詳情請參閱專案「README」檔案。

尋找 OpenAPI 定義時,找出 reporting-server.json。 這個檔案含有會傳回 200 的簡易端點,代表 HTTP 回應代碼。這個端點在 runAdSelection() 期間會使用,並向 FLEDGE 發出信號表示曝光報表成功完成。

要測試的功能

  • 加入/退出,並根據先前的使用者動作來設定自訂目標對象。
  • 透過遠端託管的 JavaScript 啟動裝置廣告選擇。
  • 觀察應用程式與自訂目標對象設定的關聯對於廣告選擇結果有何影響。
  • 廣告選擇後執行曝光報表。

限制

如需目前正在設計的功能清單,請參閱版本資訊

回報錯誤和問題

您的意見回饋對 Android 版 Privacy Sandbox 至關重要!如果您發現了任何問題,或希望針對 Android 版 Privacy Sandbox 提出改進意見,請告訴我們