《Android 開發人員指南》中的 FLEDGE

詳閱 Android 版 Privacy Sandbox 說明文件時，請利用「開發人員預覽版」或「Beta 版」按鈕選取您要使用的計畫版本，因為兩者的操作說明可能不盡相同。

提供意見回饋

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 的模擬器。

3. 在終端機中，使用以下 ADB 指令啟用 FLEDGE API 的存取權 (預設為停用)。

     adb shell device_config put adservices ppapi_app_allow_list \"*\"
   

4. 在應用程式資訊清單中加入 ACCESS_ADSERVICES_CUSTOM_AUDIENCE 權限：

     <uses-permission android:name="android.permission.ACCESS_ADSERVICES_CUSTOM_AUDIENCE" />
   

5. 在資訊清單的 <application> 元素中參照廣告服務設定：

     <property android:name="android.adservices.AD_SERVICES_CONFIG"
               android:resource="@xml/ad_services_config" />
   

6. 指定資訊清單所參照的廣告服務 XML 資源，例如 res/xml/ad_services_config.xml。進一步瞭解廣告服務權限和 SDK 存取權控管。

     <ad-services-config>
       <custom-audiences allowAllToAccess="true" />
     </ad-services-config>
   

7. 根據預設，Ad Selection API 會限制競價或曝光報表指令碼可分配的記憶體最大容量。記憶體限制功能需要搭配使用 WebView 105.0.5195.58 以上版本。平台會強制執行版本檢查，如不符合上述版本條件，就無法呼叫 selectAds 和 reportImpression API。您可以透過以下兩種做法進行設定：

   • 做法 1：執行下列 ADB 指令以停用這項檢查：

     adb device_config put fledge_js_isolate_enforce_max_heap_size false
     

   • 做法 2：從 Google Play 商店安裝 WebView Beta 版。這個版本必須等於或高於上述版本。

加入自訂目標對象

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

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

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)

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 物件執行個體化的範例：

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

// Minimal initialization of a CustomAudience object
CustomAudience customAudience = CustomAudience.Builder()
    .setBuyer(AdTechIdentifier.fromString("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() 回呼代表兩種可能的條件。
  • 如果 JoinCustomAudienceRequest 使用無效的引數進行初始化，AdServicesException 就會顯示 IllegalArgumentException 為原因。
  • 所有其他錯誤都會收到 AdServicesException，並以 IllegalStateException 表示原因。

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

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

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. 使用自訂目標對象的 buyer 和 name 初始化 LeaveCustomAudienceRequest。如要進一步瞭解這些輸入欄位，請參閱「加入自訂目標對象」。
3. 使用 LeaveCustomAudienceRequest 物件和相關的 Executor 及 OutcomeReceiver 物件呼叫非同步 leaveCustomAudience()。

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

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

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

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

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

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

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

執行廣告選擇

如要使用 FLEDGE 選擇廣告，請呼叫 selectAds() 方法：

1. 初始化 AdSelectionManager 物件。
2. 建構 AdSelectionConfig 物件。
3. 使用 AdSelectionConfig 物件和相關的 Executor 及 OutcomeReceiver 物件呼叫非同步 selectAds()。

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.selectAds(
    adSelectionConfig,
    executor,
    outcomeReceiver)

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.selectAds(
    adSelectionConfig,
    executor,
    outcomeReceiver);

selectAds() 方法需要 AdSelectionConfig 輸入內容，您必須在其中指定以下必要參數：

• 賣方：賣方廣告聯播網 ID，這用於指出啟動廣告選擇程序的賣方廣告聯播網。
• 決策邏輯網址：為了取得賣家廣告聯播網的 JavaScript 邏輯而查詢的 HTTPS 網址。請留意這個 JavaScript 必須包含的函式簽章。
• 自訂目標對象買家：買家廣告聯播網的完整 ID 清單，可讓賣家參與廣告選擇流程。 這些買家 ID 會對應至自訂目標對象的 CustomAudience.getBuyer()。

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

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

選擇廣告之後，結果、出價和信號將保留在系統中，供之後回報使用。在 OutcomeReceiver.onResult() 回呼中，您會取得一個 AdSelectionOutcome，其中包含：

• 從 AdData.getRenderUrl() 取得的得標廣告顯示網址。
• 裝置使用者專屬的廣告選擇 ID。這個 ID 的作用是回報廣告曝光。

如果廣告選擇程序因為引數無效、逾時或資源消耗過多等因素而未能順利完成，OutcomeReceiver.onError() 回呼就會提供 AdServicesException 以指出下列行為：

• 如果用於啟動廣告選擇程序的引數無效，AdServicesException 會指出 IllegalArgumentException 是錯誤原因。
• 發生其他錯誤時，收到的 AdServicesException 則會指出 IllegalStateException 是錯誤原因。

回報廣告曝光次數

透過廣告選擇工作流程選出得標的廣告後，您可以使用 AdSelectionManager.reportImpression() 方法向參與的買方和賣方平台回報曝光。如何回報廣告曝光：

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

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

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。
• 廣告選擇設定：與提供的廣告選擇 ID 辨識的 selectAds() 呼叫中使用設定相同的設定。

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

• onResult() 回呼會指出廣告選擇是否已經完成。
• onError() 回呼代表可能發生下列情況：
  • 如果呼叫是因為輸入無效引數才初始化，AdServicesException 會指出 IllegalArgumentException 是錯誤原因。
  • 發生其他錯誤時，收到的 AdServicesException 則會指出 IllegalStateException 是錯誤原因。

曝光回報端點

曝光回報 API 會向賣方平台和得標買方平台提供的端點發出 HTTPS GET 要求：

買方平台端點：

• API 使用自訂目標對象中指定的出價邏輯網址擷取買方的出價邏輯 JavaScript。
• 叫用 reportResult() JavaScript 函式，該函式應傳回買方的曝光回報網址。

賣家平台端點：

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

最佳效果曝光報表

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

每日背景更新

建立自訂目標對象時，應用程式或 SDK 可以初始化自訂目標對象的中繼資料。此外，平台也可以透過每日背景更新程序，更新自訂目標對象的下列中繼資料內容。

• 使用者出價信號
• 受信任的出價資料
• AdData 清單

這項程序會根據自訂目標對象中定義的每日更新網址進行查詢，而網址可能會傳回 JSON 回應。

• JSON 回應可能包含需要更新的任何受支援中繼資料欄位。
• 每個 JSON 欄位都會經過獨立驗證。用戶端會忽略任何格式錯誤的欄位，因此不會在回應中更新該特定欄位。
• 空白的 HTTP 回應或空白的 JSON 物件「{}」會導致無法更新中繼資料。
• 回應訊息的大小上限為 10 KB。
• 所有 URI 都必須使用 HTTPS。
• trusted_bidding_uri 必須和買方使用相同的 ETLD+1。

範例：每日背景更新的 JSON 回應

{
    "user_bidding_signals" : { ... },  // Valid JSON object
    "trusted_bidding_data" : {
        "trusted_bidding_uri" : 'example-dsp1-key-value-service.com',
        "trusted_bidding_keys" : [ 'campaign123', 'campaign456', ... ]
    },
    'ads' : [
        {
            "render_uri" : 'www.example-dsp1.com/.../campaign123.html',
            'metadata' : { ... }  // Valid JSON object
        },
        {
            "render_uri" : 'www.example-dsp1.com/.../campaign456.html',
            'metadata' : { ... }  // Valid JSON object
        },
        ...
    ]
}

一般來說，這項背景擷取作業每 24 小時會執行一次。在測試期間，您可以執行以下指令手動觸發這項工作：

adb shell cmd jobscheduler run -f com.google.android.adservices.api 9

廣告選擇專用的 JavaScript

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

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

• generateBid()
• reportResult()

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

• scoreAd()
• reportWin()

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

  詳細說明：

  • owner, buyer 和 name 是取自屬性的字串，且名稱與參與廣告選擇的自訂目標對象相同
  • activation_time 和 expiration_time 是自訂目標對象啟用和到期的時間，以 Unix Epoch 紀元時間起算的秒數表示。
  • ca_user_bidding_signals 是 CustomAudience 建立時在 userBiddingSignals 欄位中指定的 JSON 字串
  • trusted_bidding_signals, contextual_signals 和 user_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 物件，代表 selectAds 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：請參閱 scoreAd 的說明文件
• signals_for_buyer：reportResult 傳回的 JSON 物件
• contextual_signals, custom_audience_signals：請參閱 generateBid 的說明文件

輸出內容：

• status: 0 為成功，非零為失敗
• results：JSON 物件，包含以下項目
  • reporting_url：平台向賣方回報曝光所用的網址

測試

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

必要條件

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

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

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

HTTPS 端點

如要測試廣告選擇和曝光回報程序，您必須設定 7 個可讓測試裝置或模擬器存取的 HTTPS 端點：

1. 提供出價邏輯 JavaScript 的買方端點。
2. 提供出價信號的端點。
3. 提供決策邏輯 JavaScript 的賣家端點。
4. 提供評分信號的端點。
5. 得標買家曝光報表端點。
6. 賣家曝光報表端點。
7. 為自訂目標對象提供每日更新內容的端點。

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

覆寫遠端擷取 JavaScript

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

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

<application
  android:debuggable="true">

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

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

您可以單獨覆寫賣方或買方指定擷取的 JavaScript，但對於未覆寫的 JavaScript，您需要透過 HTTPS 端點來處理相關作業。如要瞭解如何設定伺服器來處理這些情況，請參閱 README。

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

覆寫賣方 JavaScript

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

1. 初始化 AdSelectionManager 物件。
2. 從 AdSelectionManager 物件取得 TestAdSelectionManager 的參照。
3. 建構 AdSelectionConfig 物件。
4. 使用 AdSelectionConfig 物件和 String 建構 AddAdSelectionOverrideRequest 代表您打算當做覆寫使用的 JavaScript。
5. 使用 AddAdSelectionOverrideRequest 物件和相關的 Executor 及 OutcomeReceiver 物件呼叫非同步 overrideAdSelectionConfigRemoteInfo()。

val testAdSelectionManager: TestAdSelectionManager =
  context.getSystemService(AdSelectionManager::class.java).getTestAdSelectionManager()

// 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
testAdSelectionManager.overrideAdSelectionConfigRemoteInfo(
    request,
    executor,
    outComeReceiver)

TestAdSelectionManager testAdSelectionManager =
  context.getSystemService(AdSelectionManager.class).getTestAdSelectionManager();

// 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
testAdSelectionManager.overrideAdSelectionConfigRemoteInfo(
    request,
    executor,
    outComeReceiver);

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

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

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

onResult() 回呼表示已成功套用覆寫值。日後對 selectAds() 的呼叫將使用您傳遞用於覆寫的判斷和回報邏輯。

onError() 回呼代表兩種可能情況：

• 如果嘗試使用無效引數進行覆寫，AdServiceException 會指出 IllegalArgumentException 是錯誤原因。
• 如果嘗試覆寫時，應用程式未執行偵錯模式，但已啟用開發人員選項，AdServiceException 會指出 IllegalStateException 是錯誤原因。

重設賣方覆寫值

本節假設您已覆寫賣方 JavaScript，並已取得上一節所用 TestAdSelectionManager 和 AdSelectionConfig 的參照。

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

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

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

// Resets overrides for all AdSelectionConfigs
testAdSelectionManager.resetAllAdSelectionConfigRemoteOverrides(
    outComeReceiver);

重設賣方覆寫值後，對 selectAds() 的呼叫就會使用 AdSelectionConfig 中儲存的 decisionLogicUrl 來嘗試擷取需要的 JavaScript。

如果呼叫 resetAllAdSelectionConfigRemoteOverrides() 失敗，OutComeReceiver.onError() 回呼會提供 AdServiceException。若應用程式未執行偵錯模式，但已啟用開發人員選項，當系統嘗試移除覆寫資料時，AdServiceException 就會指出 IllegalStateException 是錯誤原因。

覆寫買方 JavaScript

1. 請按照步驟加入自訂目標對象
2. 根據要覆寫的自訂目標對象，使用相應的「買方」和「名稱」值建構 AddCustomAudienceOverrideRequest，並建構用於覆寫的出價邏輯和資料
3. 使用 AddCustomAudienceOverrideRequest 物件和相關的 Executor 及 OutcomeReceiver 物件呼叫非同步 overrideCustomAudienceRemoteInfo()。

val testCustomAudienceManager: TestCustomAudienceManager =
  context.getSystemService(CustomAudienceManager::class.java).getTestCustomAudienceManager()

// Join custom audience

// Build the AddCustomAudienceOverrideRequest
val request = AddCustomAudienceOverrideRequest.Builder()
    .setBuyer(buyer)
    .setName(name)
    .setBiddingLogicJs(biddingLogicJS)
    .setTrustedBiddingSignals(trustedBiddingSignals)
    .build()

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

TestCustomAudienceManager testCustomAudienceManager =
  context.getSystemService(CustomAudienceManager.class).getTestCustomAudienceManager();

// Join custom audience

// Build the AddCustomAudienceOverrideRequest
AddCustomAudienceOverrideRequest request =
    AddCustomAudienceOverrideRequest.Builder()
        .setBuyer(buyer)
        .setName(name)
        .setBiddingLogicJs(biddingLogicJS)
        .setTrustedBiddingSignals(trustedBiddingSignals)
        .build();

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

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

此外，您還可以指定兩個額外參數：

• biddingLogicJs：這個 JavaScript 包含在選擇廣告時使用的買方邏輯。請留意這個 JavaScript 必須包含的函式簽章。
• trustedBiddingSignals：選擇廣告時使用的出價信號。如果是測試用途，這個值可以是空白字串。

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

onResult() 回呼表示已成功套用覆寫值。後續對 selectAds() 的呼叫將使用您傳遞用於覆寫的判斷和回報邏輯。

onError() 回呼代表兩種可能情況。

• 如果嘗試使用無效引數進行覆寫，AdServiceException 會指出 IllegalArgumentException 是錯誤原因。
• 如果嘗試覆寫時，應用程式未執行偵錯模式，但已啟用開發人員選項，AdServiceException 會指出 IllegalStateException 是錯誤原因。

重設買方覆寫值

本節假設您已覆寫買方 JavaScript，且已取得上一節中所用 TestCustomAudienceManager 的參照。

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

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

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

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

重設買方覆寫值後，後續對 selectAds() 的呼叫就會使用 CustomAudience 中儲存的 biddingLogicUrl 和 trustedBiddingData 來嘗試擷取需要的 JavaScript。

如果呼叫 resetCustomAudienceRemoteInfoOverride() 失敗，OutComeReceiver.onError() 回呼會提供 AdServiceException。若應用程式未執行偵錯模式，但已啟用開發人員選項，當系統嘗試移除覆寫資料時，AdServiceException 就會指出 IllegalStateException 是錯誤原因。

設定回報伺服器

使用遠端擷取覆寫功能時，您仍須設定伺服器，讓裝置或模擬器能存取該伺服器來回應回報事件。傳回 200 的簡單端點就足以進行測試。GitHub 存放區包含 OpenAPI 服務定義，您可以將這些定義部署至支援的模擬或微服務平台。如需瞭解詳情，請參考 README 專案。

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

要測試的功能

• 根據先前的使用者動作，加入/退出及設定自訂目標對象。
• 透過遠端代管的 JavaScript 在裝置上啟動廣告選擇程序。
• 觀察應用程式與自訂目標對象設定之間的關聯如何影響廣告選擇結果。
• 在廣告選擇完成後回報曝光。

限制

下表列出了 FLEDGE 處理程序的限制，這些限制可能根據意見回饋有所調整。如要查看開發中的功能，請參閱版本資訊。

回報錯誤和問題

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