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<GetAdSelectionDataOutcomeException> receiver)

รวบรวมข้อมูลกลุ่มเป้าหมายที่กำหนดเองจากอุปกรณ์

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

คงผลการเลือกโฆษณาจากฝั่งเซิร์ฟเวอร์

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

แจ้งบริการว่ามีเหตุการณ์โฆษณาใหม่ที่จะรายงานสำหรับโฆษณาที่เลือกโดย การเรียกใช้การเลือกโฆษณาที่ระบุโดย adSelectionId

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

แจ้งบริการว่ามีการแสดงผลใหม่ที่จะรายงานสำหรับโฆษณาที่เลือกโดย การเรียกใช้การเลือกโฆษณาที่ระบุโดย adSelectionId

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

เลือกโฆษณาจากผลลัพธ์ของการเลือกโฆษณาที่เคยเรียกใช้ก่อนหน้านี้

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

เรียกใช้กระบวนการเลือกโฆษณาบนอุปกรณ์เพื่อเลือกโฆษณารีมาร์เก็ตติ้งสำหรับผู้โทร แอปพลิเคชัน

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

อัปเดตฮิสโตแกรมตัวนับสำหรับโฆษณาที่ก่อนหน้านี้เลือกโดยการเรียกไปยัง selectAds(android.adservices.adselection.AdSelectionConfig, java.util.concurrent.Executor, android.os.OutcomeReceiver)

วิธีการที่รับมา

วิธีการสาธารณะ

รับ

public static AdSelectionManager get (Context context)

การสร้างอินสแตนซ์ของ AdSelectionManager โดยใช้วิธีการจากโรงงาน

พารามิเตอร์
context Context: Context ที่จะใช้ ค่านี้ต้องไม่เป็น null

คิกรีเทิร์น
AdSelectionManager อินสแตนซ์ AdSelectionManager ค่านี้ต้องไม่เป็น null

รับข้อมูลการเลือกโฆษณา

public void getAdSelectionData (GetAdSelectionDataRequest request, 
                Executor executor, 
                OutcomeReceiver<GetAdSelectionDataOutcomeException> receiver)

รวบรวมข้อมูลกลุ่มเป้าหมายที่กำหนดเองจากอุปกรณ์ แสดง BLOB ที่บีบอัดและเข้ารหัสที่ส่งไปยัง เซิร์ฟเวอร์การประมูลเพื่อเลือกโฆษณา สำหรับรายละเอียดเพิ่มเติม โปรดไปที่ การเสนอราคา และคำอธิบายบริการประมูล

โฆษณากลุ่มเป้าหมายที่กำหนดเองต้องมี ad_render_id จึงจะมีสิทธิ์ในการรวบรวม

ดู AdSelectionManager#persistAdSelectionResult วิธีประมวลผลผลลัพธ์ของ การเลือกโฆษณาจะทำงานในฝั่งเซิร์ฟเวอร์พร้อม BLOB ที่สร้างโดย API นี้

ตัวรับเอาต์พุตจะส่งเอาต์พุต ซึ่งอาจเป็น GetAdSelectionDataOutcome สำหรับการเรียกใช้ที่สำเร็จ หรือ Exception จะรวมประเภท มีการส่งข้อยกเว้นและข้อความแสดงข้อผิดพลาดที่เกี่ยวข้อง

หากระบบโยน IllegalArgumentException ไม่ได้ อาจเกิดจากอาร์กิวเมนต์อินพุตที่ไม่ถูกต้อง API ที่ได้รับเพื่อเรียกใช้การเลือกโฆษณา

หากระบบแสดง IllegalStateException พร้อมข้อความแสดงข้อผิดพลาด "ความล้มเหลวของการเลือกโฆษณา" บริการ" แสดงว่าเกิดจากความล้มเหลวภายในของบริการเลือกโฆษณา

หากระบบโยน TimeoutException จะเกิดข้อผิดพลาดก็ต่อเมื่อหมดเวลา ในระหว่างขั้นตอนการเสนอราคา การให้คะแนน หรือการเลือกโดยรวมเพื่อค้นหาโฆษณาที่ชนะการประมูล

หากระบบส่ง LimitExceededException สาเหตุจะเกิดขึ้นเมื่อแพ็กเกจการโทร เกินขีดจำกัดของอัตราที่อนุญาตและถูกควบคุม

หากระบบโยน SecurityException ให้ โหนดนี้จะเกิดขึ้นเมื่อผู้โทรไม่ได้รับอนุญาต หรือไม่มีการขอสิทธิ์
ต้องใช้ AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE

พารามิเตอร์
request GetAdSelectionDataRequest: ค่านี้ต้องไม่เป็น null

executor Executor: ค่านี้ต้องไม่เป็น null ระบบจะส่งเหตุการณ์ Callback และ Listener ผ่านสิ่งนี้ Executor มอบวิธีง่ายๆ ในการควบคุมชุดข้อความที่ ในการส่งกิจกรรมผ่านชุดข้อความหลักของ คุณสามารถใช้ Context.getMainExecutor() หรือระบุ Executor ที่ส่งไปยังชุดข้อความที่เหมาะสม

receiver OutcomeReceiver: ค่านี้ต้องไม่เป็น null

getTestAdSelectionManager

เพิ่มใน API ระดับ 34
ยังมีในส่วนขยายโฆษณา 4 ด้วย
public TestAdSelectionManager getTestAdSelectionManager ()

คิกรีเทิร์น
TestAdSelectionManager ค่านี้ต้องไม่เป็น null

perAdSelectionผลลัพธ์

public void persistAdSelectionResult (PersistAdSelectionResultRequest request, 
                Executor executor, 
                OutcomeReceiver<AdSelectionOutcomeException> receiver)

คงผลการเลือกโฆษณาจากฝั่งเซิร์ฟเวอร์ สำหรับรายละเอียดเพิ่มเติม โปรดไปที่ การเสนอราคา และคำอธิบายบริการประมูล

ดู AdSelectionManager#getAdSelectionData สำหรับวิธีสร้าง BLOB ที่เข้ารหัสเพื่อ เรียกใช้การเลือกโฆษณาในฝั่งเซิร์ฟเวอร์

ตัวรับส่งสัญญาณเอาต์พุต ซึ่งจะแสดงผล AdSelectionOutcome เพื่อให้การเรียกใช้เสร็จสมบูรณ์ หรือ Exception จะมีประเภทของข้อยกเว้นที่ส่ง ข้อความแสดงข้อผิดพลาดที่เกี่ยวข้อง

หากระบบโยน IllegalArgumentException ไม่ได้ อาจเกิดจากอาร์กิวเมนต์อินพุตที่ไม่ถูกต้อง API ที่ได้รับเพื่อเรียกใช้การเลือกโฆษณา

หากระบบแสดง IllegalStateException พร้อมข้อความแสดงข้อผิดพลาด "ความล้มเหลวของการเลือกโฆษณา" บริการ" แสดงว่าเกิดจากความล้มเหลวภายในของบริการเลือกโฆษณา

หากระบบโยน TimeoutException จะเกิดข้อผิดพลาดก็ต่อเมื่อหมดเวลา ในระหว่างขั้นตอนการเสนอราคา การให้คะแนน หรือการเลือกโดยรวมเพื่อค้นหาโฆษณาที่ชนะการประมูล

หากระบบส่ง LimitExceededException สาเหตุจะเกิดขึ้นเมื่อแพ็กเกจการโทร เกินขีดจำกัดของอัตราที่อนุญาตและถูกควบคุม

หากระบบโยน SecurityException ให้ ข้อผิดพลาดนี้เกิดขึ้นเมื่อผู้โทรไม่ได้รับอนุญาต หรือไม่มีการขอสิทธิ์
ต้องใช้ AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE

พารามิเตอร์
request PersistAdSelectionResultRequest: ค่านี้ต้องไม่เป็น null

executor Executor: ค่านี้ต้องไม่เป็น null ระบบจะส่งเหตุการณ์ Callback และ Listener ผ่านสิ่งนี้ Executor มอบวิธีง่ายๆ ในการควบคุมชุดข้อความที่ ในการส่งกิจกรรมผ่านชุดข้อความหลักของ คุณสามารถใช้ Context.getMainExecutor() หรือระบุ Executor ที่ส่งไปยังชุดข้อความที่เหมาะสม

receiver OutcomeReceiver: ค่านี้ต้องไม่เป็น null

เหตุการณ์รายงาน

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

แจ้งบริการว่ามีเหตุการณ์โฆษณาใหม่ที่จะรายงานสำหรับโฆษณาที่เลือกโดย การเรียกใช้การเลือกโฆษณาที่ระบุโดย adSelectionId เหตุการณ์โฆษณาคือรายการที่ เกิดขึ้นกับโฆษณาที่เชื่อมโยงกับ adSelectionId ที่ระบุ ไม่มีการรับประกันเกี่ยวกับ เวลาที่ระบบจะรายงานเหตุการณ์โฆษณา การรายงานเหตุการณ์อาจล่าช้าและรายงานอาจ รวมกลุ่มแล้ว

เมื่อใช้ ReportEventRequest#getKey() บริการจะดึงข้อมูล reportingUri ซึ่งจดทะเบียนในregisterAdBeacon ดูรายละเอียดเพิ่มเติมเกี่ยวกับ registerAdBeacon ในเอกสารของ reportImpression(ReportImpressionRequest, Executor, OutcomeReceiver) จากนั้น บริการ จะแนบ ReportEventRequest#getData() เข้ากับเนื้อหาคำขอของคำขอ POST และ ส่งคำขอ ส่วนเนื้อหาของคำขอ POST จะมี content-type เป็น text/plain และจะส่งข้อมูลใน charset=UTF-8

ตัวรับส่งสัญญาณเอาต์พุต ซึ่งจะแสดงผล Object ที่ว่างเปล่าสําหรับ รันสำเร็จ หรือ Exception จะมีประเภทของข้อยกเว้นที่ใส่ และ ที่เกี่ยวข้อง

หากระบบโยน IllegalArgumentException ไม่ได้ อาจเกิดจากอาร์กิวเมนต์อินพุตที่ไม่ถูกต้อง API ที่ได้รับในการรายงานเหตุการณ์โฆษณา

หากระบบแสดง IllegalStateException พร้อมข้อความแสดงข้อผิดพลาด "ความล้มเหลวของการเลือกโฆษณา" บริการ" แสดงว่าเกิดจากความล้มเหลวภายในของบริการเลือกโฆษณา

หากระบบส่ง LimitExceededException สาเหตุจะเกิดขึ้นเมื่อแพ็กเกจการโทร เกินขีดจำกัดของอัตราที่อนุญาตและถูกควบคุม

หากระบบโยน SecurityException ให้ ข้อผิดพลาดนี้เกิดขึ้นเมื่อผู้โทรไม่ได้รับอนุญาต หรือไม่มีการขอสิทธิ์

ระบบจะรายงานกิจกรรมมากที่สุด 1 ครั้งเพื่อพยายามอย่างเต็มที่
ต้องใช้ AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE

พารามิเตอร์
request ReportEventRequest: ค่านี้ต้องไม่เป็น null

executor Executor: ค่านี้ต้องไม่เป็น null

receiver OutcomeReceiver: ค่านี้ต้องไม่เป็น null

รายงานการแสดงผล

เพิ่มใน API ระดับ 34
ยังมีในส่วนขยายโฆษณา 4 ด้วย
public void reportImpression (ReportImpressionRequest request, 
                Executor executor, 
                OutcomeReceiver<ObjectException> receiver)

แจ้งบริการว่ามีการแสดงผลใหม่ที่จะรายงานสำหรับโฆษณาที่เลือกโดย การเรียกใช้การเลือกโฆษณาที่ระบุโดย adSelectionId โดยไม่สามารถรับประกันได้ว่า จะรายงานการแสดงผล การรายงานการแสดงผลอาจมีความล่าช้าและรายงาน รวมกลุ่มแล้ว

บริการจะดึงข้อมูล JavaScript ของผู้ขายเพื่อคำนวณ URL การรายงานของผู้ขายที่ชนะ ตรรกะจาก AdSelectionConfig#getDecisionLogicUri() ที่พบที่ ReportImpressionRequest.getAdSelectionConfig() จากนั้น บริการจะดำเนินการอย่างใดอย่างหนึ่ง ที่พบใน 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 } }; }

ในการคำนวณ URL การรายงานของผู้ซื้อที่ชนะ บริการจะดึงข้อมูลของผู้ซื้อที่ชนะ ลอจิก JavaScript ที่ดึงข้อมูลผ่าน CustomAudience.getBiddingLogicUri() ของผู้ซื้อ จากนั้น บริการ จะดำเนินการกับฟังก์ชันที่พบใน 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 เป็นคำสั่งของสตริงเพื่อ คู่สตริง

สำหรับเหตุการณ์โฆษณาแต่ละรายการที่ผู้ซื้อ/ผู้ขายสนใจในรายงาน ก็จะเพิ่มคู่ event_key: event_reporting_uri ในคำสั่ง beacons โดยที่ event_key เป็นตัวระบุสำหรับเหตุการณ์นั้นๆ event_keyนี้ควรตรงกับ ReportEventRequest#getKey() เมื่อ SDK เรียกใช้ reportEvent(ReportEventRequest, Executor, OutcomeReceiver) นอกจากนี้ event_reporting_uri แต่ละรายการควรแยกวิเคราะห์เป็น Uri อย่างถูกต้อง ช่วงเวลานี้ จะเป็น Uri ที่รายงานเมื่อ SDK เรียกใช้ reportEvent(ReportEventRequest, Executor, OutcomeReceiver)

เมื่อผู้ซื้อ/ผู้ขายเพิ่มการจับคู่ทั้งหมดที่ต้องการรับเหตุการณ์แล้ว ก็จะสามารถ เรียกใช้ registerAdBeacon(beacons) โดยที่ beacons เป็นชื่อของคำสั่งที่ เพิ่มคู่สนทนาแล้ว

registerAdBeacon จะโยน TypeError ในสถานการณ์ต่อไปนี้

  1. เรียก registerAdBeacon มากกว่า 1 ครั้ง หากพบข้อผิดพลาดนี้ reportWin/reportผลลัพธ์ การจับคู่ชุดเดิมจะได้รับการลงทะเบียน
  2. registerAdBeacon ไม่มีอาร์กิวเมนต์ dict 1 รายการ
  3. เนื้อหาของอาร์กิวเมนต์ 1 คำสั่ง 1 ไม่ใช่การจับคู่ String: String ทั้งหมด

เอาต์พุตจะส่งโดย receiver ซึ่งแสดงผล Object ที่ว่างเปล่า เพื่อให้การเรียกใช้เสร็จสมบูรณ์ หรือ Exception จะมีประเภทของข้อยกเว้นที่ส่ง ข้อความแสดงข้อผิดพลาดที่เกี่ยวข้อง

หากระบบโยน IllegalArgumentException ไม่ได้ อาจเกิดจากอาร์กิวเมนต์อินพุตที่ไม่ถูกต้อง API ที่ได้รับเพื่อรายงานการแสดงผล

หากระบบแสดง IllegalStateException พร้อมข้อความแสดงข้อผิดพลาด "ความล้มเหลวของการเลือกโฆษณา" บริการ" แสดงว่าเกิดจากความล้มเหลวภายในของบริการเลือกโฆษณา

หากระบบส่ง LimitExceededException สาเหตุจะเกิดขึ้นเมื่อแพ็กเกจการโทร เกินขีดจำกัดของอัตราที่อนุญาตและถูกควบคุม

หากระบบโยน SecurityException ให้ ข้อผิดพลาดนี้เกิดขึ้นเมื่อผู้โทรไม่ได้รับอนุญาต หรือไม่มีการขอสิทธิ์

ระบบจะรายงานการแสดงผลมากที่สุด 1 ครั้งเพื่อพยายามอย่างเต็มที่
ต้องใช้ AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE

พารามิเตอร์
request ReportImpressionRequest: ค่านี้ต้องไม่เป็น null

executor Executor: ค่านี้ต้องไม่เป็น null

receiver OutcomeReceiver: ค่านี้ต้องไม่เป็น null

เลือกโฆษณา

public void selectAds (AdSelectionFromOutcomesConfig adSelectionFromOutcomesConfig, 
                Executor executor, 
                OutcomeReceiver<AdSelectionOutcomeException> receiver)

เลือกโฆษณาจากผลลัพธ์ของการเลือกโฆษณาที่เคยเรียกใช้ก่อนหน้านี้

อินพุต adSelectionFromOutcomesConfig มาจาก Ads SDK และออบเจ็กต์ AdSelectionFromOutcomesConfig ได้รับการโอนผ่านการเรียกใช้ Binder ด้วยเหตุนี้ ขนาดทั้งหมดของวัตถุเหล่านี้เชื่อมโยงกับข้อจำกัด IPC ของ Android โอนไม่สำเร็จ AdSelectionFromOutcomesConfig จะขว้าง TransactionTooLargeException

ตัวรับส่งสัญญาณเอาต์พุต ซึ่งจะแสดงผล AdSelectionOutcome เพื่อให้การเรียกใช้เสร็จสมบูรณ์ หรือ Exception จะมีประเภทของข้อยกเว้นที่ส่ง ข้อความแสดงข้อผิดพลาดที่เกี่ยวข้อง

อินพุต adSelectionFromOutcomesConfig ประกอบด้วย:

  • Seller ต้องเป็น AdTechIdentifier ที่จดทะเบียน หรือไม่เช่นนั้น IllegalStateException จะถูกโยน
  • List of ad selection ids ควรมีอยู่และมาจากการโทร selectAds(AdSelectionConfig, Executor, OutcomeReceiver) รายการที่มาจากแอปพลิเคชันเดียวกัน หรือไม่เช่นนั้น IllegalArgumentException เพื่อตรวจสอบความถูกต้องของข้อมูลจะเพิ่มโฆษณาที่ละเมิดข้อมูล รหัสการเลือก
  • Selection logic URI ที่อาจเป็นไปตาม HTTPS หรือการสร้างการเลือกโฆษณาที่สร้างไว้ล่วงหน้า สคีมา

    หาก URI เป็นไปตามสคีมา HTTPS โฮสต์ควรตรงกับ seller ไม่เช่นนั้น ระบบจะโยน IllegalArgumentException ให้

    URI ที่สร้างไว้ล่วงหน้าเป็นวิธีแทนที่ตรรกะที่สร้างไว้ล่วงหน้าทั่วไปสำหรับ JavaScript สำหรับ selectOutcome URI ที่สร้างไว้ล่วงหน้าสำหรับปลายทางนี้ควรเป็นไปตามนี้

    • ad-selection-prebuilt://ad-selection-from-outcomes/<name>?<script-generation-parameters>

    หากมีการส่ง URI ที่สร้างไว้ล่วงหน้าที่ไม่รองรับ หรือมีการปิดใช้ฟีเจอร์ URI ที่สร้างไว้ล่วงหน้า จากนั้น ระบบจะทิ้ง IllegalArgumentException

    ดู AdSelectionFromOutcomesConfig.Builder#setSelectionLogicUri สำหรับการสนับสนุน <name> และต้องใช้ <script-generation-parameters>

หากระบบโยน IllegalArgumentException ไม่ได้ อาจเกิดจากอาร์กิวเมนต์อินพุตที่ไม่ถูกต้อง API ที่ได้รับเพื่อเรียกใช้การเลือกโฆษณา

หากระบบแสดง IllegalStateException พร้อมข้อความแสดงข้อผิดพลาด "ความล้มเหลวของการเลือกโฆษณา" บริการ" แสดงว่าเกิดจากความล้มเหลวภายในของบริการเลือกโฆษณา

หากระบบโยน TimeoutException จะเกิดข้อผิดพลาดก็ต่อเมื่อหมดเวลา ในระหว่างขั้นตอนการเสนอราคา การให้คะแนน หรือการเลือกโดยรวมเพื่อค้นหาโฆษณาที่ชนะการประมูล

หากระบบส่ง LimitExceededException สาเหตุจะเกิดขึ้นเมื่อแพ็กเกจการโทร เกินขีดจำกัดของอัตราที่อนุญาตและถูกควบคุม

หากระบบโยน SecurityException ให้ ข้อผิดพลาดนี้เกิดขึ้นเมื่อผู้โทรไม่ได้รับอนุญาต หรือไม่มีการขอสิทธิ์
ต้องใช้ AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE

พารามิเตอร์
adSelectionFromOutcomesConfig AdSelectionFromOutcomesConfig: ค่านี้ต้องไม่เป็น null

executor Executor: ค่านี้ต้องไม่เป็น null ระบบจะส่งเหตุการณ์ Callback และ Listener ผ่านสิ่งนี้ Executor มอบวิธีง่ายๆ ในการควบคุมชุดข้อความที่ ในการส่งกิจกรรมผ่านชุดข้อความหลักของ คุณสามารถใช้ Context.getMainExecutor() หรือระบุ Executor ที่ส่งไปยังชุดข้อความที่เหมาะสม

receiver OutcomeReceiver: ค่านี้ต้องไม่เป็น null

เลือกโฆษณา

เพิ่มใน API ระดับ 34 แล้ว
public void selectAds (AdSelectionConfig adSelectionConfig, 
                Executor executor, 
                OutcomeReceiver<AdSelectionOutcomeException> receiver)

เรียกใช้กระบวนการเลือกโฆษณาบนอุปกรณ์เพื่อเลือกโฆษณารีมาร์เก็ตติ้งสำหรับผู้โทร แอปพลิเคชัน

อินพุต adSelectionConfig มาจาก Ads SDK และออบเจ็กต์ AdSelectionConfig ได้รับการโอนผ่านการเรียกใช้ Binder ด้วยเหตุนี้ ขนาดรวม ของออบเจ็กต์เหล่านี้เป็นไปตามข้อจำกัด Android IPC หากโอน AdSelectionConfig ไม่สำเร็จ จะทำให้ได้ TransactionTooLargeException

อินพุต adSelectionConfig มี Decision Logic Uri ที่ติดตามได้ สคีมา HTTPS หรือสคีมาการเลือกโฆษณาที่สร้างไว้ล่วงหน้า

หาก URI เป็นไปตามสคีมา HTTPS โฮสต์ควรตรงกับ seller หรือไม่เช่นนั้น จะมีการขว้าง IllegalArgumentException

URI ที่สร้างไว้ล่วงหน้าเป็นวิธีแทนที่ตรรกะที่สร้างไว้ล่วงหน้าทั่วไปสำหรับ JavaScript สำหรับ scoreAds URI ที่สร้างไว้ล่วงหน้าสำหรับปลายทางนี้ควรเป็นไปตามนี้

  • ad-selection-prebuilt://ad-selection/<name>?<script-generation-parameters>

หากมีการส่ง URI ที่สร้างไว้ล่วงหน้าที่ไม่รองรับ หรือมีการปิดใช้ฟีเจอร์ URI ที่สร้างไว้ล่วงหน้า จากนั้น ระบบจะทิ้ง IllegalArgumentException

ดูAdSelectionConfig.Builder#setDecisionLogicUriสำหรับ<name>ที่รองรับและ ต้องใช้ <script-generation-parameters>

ตัวรับส่งสัญญาณเอาต์พุต ซึ่งจะแสดงผล AdSelectionOutcome เพื่อให้การเรียกใช้เสร็จสมบูรณ์ หรือ Exception จะมีประเภทของข้อยกเว้นที่ส่ง ข้อความแสดงข้อผิดพลาดที่เกี่ยวข้อง

หากระบบโยน IllegalArgumentException ไม่ได้ อาจเกิดจากอาร์กิวเมนต์อินพุตที่ไม่ถูกต้อง API ที่ได้รับเพื่อเรียกใช้การเลือกโฆษณา

หากระบบแสดง IllegalStateException พร้อมข้อความแสดงข้อผิดพลาด "ความล้มเหลวของการเลือกโฆษณา" บริการ" แสดงว่าเกิดจากความล้มเหลวภายในของบริการเลือกโฆษณา

หากระบบโยน TimeoutException จะเกิดข้อผิดพลาดก็ต่อเมื่อหมดเวลา ในระหว่างขั้นตอนการเสนอราคา การให้คะแนน หรือการเลือกโดยรวมเพื่อค้นหาโฆษณาที่ชนะการประมูล

หากระบบส่ง LimitExceededException สาเหตุจะเกิดขึ้นเมื่อแพ็กเกจการโทร เกินขีดจำกัดของอัตราที่อนุญาตและถูกควบคุม

หากระบบโยน SecurityException ให้ ข้อผิดพลาดนี้เกิดขึ้นเมื่อผู้โทรไม่ได้รับอนุญาต หรือไม่มีการขอสิทธิ์
ต้องใช้ AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE

พารามิเตอร์
adSelectionConfig AdSelectionConfig: ค่านี้ต้องไม่เป็น null

executor Executor: ค่านี้ต้องไม่เป็น null ระบบจะส่งเหตุการณ์ Callback และ Listener ผ่านสิ่งนี้ Executor มอบวิธีง่ายๆ ในการควบคุมชุดข้อความที่ ในการส่งกิจกรรมผ่านชุดข้อความหลักของ คุณสามารถใช้ Context.getMainExecutor() หรือระบุ Executor ที่ส่งไปยังชุดข้อความที่เหมาะสม

receiver OutcomeReceiver: ค่านี้ต้องไม่เป็น null

อัปเดตAdCounterHistogram

public void updateAdCounterHistogram (UpdateAdCounterHistogramRequest updateAdCounterHistogramRequest, 
                Executor executor, 
                OutcomeReceiver<ObjectException> outcomeReceiver)

อัปเดตฮิสโตแกรมตัวนับสำหรับโฆษณาที่ก่อนหน้านี้เลือกโดยการเรียกไปยัง selectAds(android.adservices.adselection.AdSelectionConfig, java.util.concurrent.Executor, android.os.OutcomeReceiver)

ฮิสโตแกรมตัวนับจะใช้ในการเลือกโฆษณาเพื่อแจ้งการกรองความถี่สูงสุด โฆษณาที่เป็นตัวเลือกที่โฆษณาที่มีการแสดงผลตรงกับหรือเกินความถี่สูงสุดจะถูกนำออกจากโฆษณา ระหว่างการเลือกโฆษณา

ฮิสโตแกรมตัวนับสามารถอัปเดตได้เฉพาะโฆษณาที่ระบุโดย adSelectionId ที่ระบุ ซึ่งแสดงผลจากการเรียกการเลือกโฆษณา FLEDGE ครั้งล่าสุดจากแอปผู้โทรเดียวกัน

ระบบจะแสดงผล SecurityException ผ่าน outcomeReceiver ในกรณีต่อไปนี้

  1. แอปไม่ได้ประกาศสิทธิ์ที่ถูกต้องในไฟล์ Manifest หรือ
  2. แอปหรือนิติบุคคลที่ระบุโดย callerAdTechIdentifier ไม่ได้รับอนุญาต เพื่อใช้ API
ระบบจะส่งคืน IllegalStateException ผ่านทาง outcomeReceiver หากการเรียกเกิดขึ้น ไม่ได้มาจากแอปที่มีกิจกรรมเบื้องหน้า

ระบบจะแสดงผล LimitExceededException ผ่าน outcomeReceiver หากการโทร เกินการควบคุม API ของแอปที่เรียกใช้

ในกรณีอื่นๆ ทั้งหมดที่ดำเนินการไม่สำเร็จ outcomeReceiver จะส่งกลับ Object ที่ว่างเปล่า โปรดทราบว่า เพื่อปกป้องความเป็นส่วนตัวของผู้ใช้ ข้อผิดพลาดภายในจะไม่ส่งกลับผ่าน ข้อยกเว้น
ต้องใช้ AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE

พารามิเตอร์
updateAdCounterHistogramRequest UpdateAdCounterHistogramRequest: ค่านี้ต้องไม่เป็น null

executor Executor: ค่านี้ต้องไม่เป็น null ระบบจะส่งเหตุการณ์ Callback และ Listener ผ่านสิ่งนี้ Executor มอบวิธีง่ายๆ ในการควบคุมชุดข้อความที่ ในการส่งกิจกรรมผ่านชุดข้อความหลักของ คุณสามารถใช้ Context.getMainExecutor() หรือระบุ Executor ที่ส่งไปยังชุดข้อความที่เหมาะสม

outcomeReceiver OutcomeReceiver: ค่านี้ต้องไม่เป็น null