กําหนดข้อมูลกลุ่มเป้าหมาย

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

คุณสามารถใช้ Android Protected Audience API เพื่อเข้าร่วมและออกจากกลุ่มเป้าหมายที่กำหนดเองในอุปกรณ์ของผู้ใช้ได้ เมื่อสร้างและเข้าร่วมกลุ่มเป้าหมายที่กำหนดเอง คุณจะมอบสิทธิ์ให้เซิร์ฟเวอร์ซึ่งคุณจะดึงพร็อพเพอร์ตี้กลุ่มเป้าหมายที่กำหนดเองบางส่วนหรือทั้งหมด หรือระบุข้อมูลนี้เมื่อเรียก API โดยตรงก็ได้

กลุ่มเป้าหมายที่กำหนดเอง

การรวมพารามิเตอร์ต่อไปนี้จะระบุออบเจ็กต์ CustomAudienceแต่ละรายการในอุปกรณ์อย่างไม่ซ้ำกัน

• owner: ชื่อแพ็กเกจของแอปที่เป็นเจ้าของ ระบบจะตั้งค่านี้โดยนัยเป็นชื่อแพ็กเกจของแอปที่เรียกใช้
• buyer: ตัวระบุสำหรับเครือข่ายโฆษณาของผู้ซื้อที่จัดการโฆษณาสําหรับกลุ่มเป้าหมายที่กําหนดเองนี้
• name: ชื่อหรือตัวระบุที่กำหนดเองสำหรับกลุ่มเป้าหมายที่กำหนดเอง

นอกจากนี้ ต้องสร้าง CustomAudience โดยใช้พารามิเตอร์ที่จำเป็นต่อไปนี้

• URL การอัปเดตรายวัน: URL HTTPS ที่มีการค้นหาในเบื้องหลังทุกวันเพื่อ อัปเดตสัญญาณการเสนอราคาของผู้ใช้ กลุ่มเป้าหมายที่กำหนดเอง ข้อมูลการเสนอราคาที่เชื่อถือได้ และ แสดงผล URL และข้อมูลเมตาสำหรับโฆษณา
• URL ตรรกะการเสนอราคา: HTTPS URL ที่มีการค้นหาในระหว่างการเลือกโฆษณาเพื่อดึงตรรกะการเสนอราคา JavaScript ของผู้ซื้อ ดูลายเซ็นฟังก์ชันที่จำเป็น ใน JavaScript นี้
• รหัสการแสดงโฆษณา: รหัสที่กำหนดโดยเทคโนโลยีโฆษณาของผู้ซื้อ ซึ่งเป็นการเพิ่มประสิทธิภาพสำหรับการสร้างเพย์โหลดสำหรับ B&A

พารามิเตอร์ที่ไม่บังคับสำหรับออบเจ็กต์ CustomAudience อาจรวมถึง

• เวลาเปิดใช้งาน: กลุ่มเป้าหมายที่กําหนดเองจะเข้าร่วมการเลือกโฆษณา และการอัปเดตรายวันได้หลังจากเวลาเปิดใช้งานเท่านั้น ซึ่งอาจมีประโยชน์ในการดึงดูดผู้ใช้ที่เลิกใช้แอปกลับมา เป็นต้น
• เวลาหมดอายุ: เวลาในอนาคตหลังจากที่ระบบนำกลุ่มเป้าหมายที่กำหนดเองออกจากอุปกรณ์
• สัญญาณการเสนอราคาของผู้ใช้: สตริง JSON ที่มีสัญญาณของผู้ใช้ เช่น ภาษาที่ผู้ใช้ต้องการ ซึ่ง JavaScript ตรรกะการเสนอราคาของผู้ซื้อใช้ เพื่อสร้างราคาเสนอในระหว่างกระบวนการเลือกโฆษณา รูปแบบนี้ช่วยให้แพลตฟอร์มเทคโนโลยีโฆษณา นำโค้ดกลับมาใช้ซ้ำในแพลตฟอร์มต่างๆ และช่วยให้ใช้ฟังก์ชัน JavaScript ได้ง่ายขึ้น
• ข้อมูลการเสนอราคาที่เชื่อถือได้: URL HTTPS และรายการสตริงที่ใช้ในระหว่างกระบวนการเลือกโฆษณาซึ่งดึงสัญญาณการเสนอราคาจากบริการคีย์/ค่าที่เชื่อถือได้
• โฆษณา: รายการออบเจ็กต์ AdData ที่สอดคล้องกับโฆษณาที่ เข้าร่วมในการเลือกโฆษณา ออบเจ็กต์ AdData แต่ละรายการประกอบด้วยข้อมูลต่อไปนี้
  • URL การแสดงผล: HTTPS URL ที่มีการค้นหาเพื่อแสดงโฆษณาสุดท้าย
  • ข้อมูลเมตา: ออบเจ็กต์ JSON ที่แปลงเป็นสตริงซึ่งมีข้อมูลที่ตรรกะการเสนอราคาของผู้ซื้อจะใช้ในระหว่างกระบวนการเลือกโฆษณา
  • ตัวกรองโฆษณา: คลาสที่มีข้อมูลที่จำเป็นทั้งหมดสำหรับการกรองโฆษณาเพื่อกระตุ้นการติดตั้งแอป และการจำกัดความถี่สูงสุดระหว่างการเลือกโฆษณา

ดึงข้อมูลและเข้าร่วมกลุ่มเป้าหมายที่กำหนดเอง

fetchAndJoinCustomAudience API ช่วยให้ผู้ซื้อมอบสิทธิ์การเข้าร่วมกลุ่มเป้าหมายที่กำหนดเองได้โดยใช้ประโยชน์จากการแสดงผลในอุปกรณ์ของ MMP หรือ SSP พาร์ทเนอร์

เพื่อให้การทำงานนี้เป็นไปได้ ผู้โทรในอุปกรณ์ (ไม่ว่าจะเป็น MMP หรือ SDK ของ SSP) จะสร้าง fetchAndJoinCustomAudienceRequest ที่มีลักษณะดังนี้

/**
 * @param fetchUri The URL to retrieve the CA from.
 * (optional)@param name The name of the CA to join.
 * (optional)@param activationTime The time when the CA will activate.
 * (optional)@param expirationTime The time when the CA will expire,
    must be a time in the future otherwise this will fail
 * (optional)@param userBiddingSignals The user bidding signals used at auction.
*/

val request = FetchAndJoinCustomAudienceRequest.Builder(fetchUri)
    .setName(name)
    .setActivationTime(activationTime)
    .setExpirationTime(expirationTime)
    .setUserBiddingSignals(userBiddingSignals)
    .build()

/**
 * @param fetchUri The URL to retrieve the CA from.
 * (optional)@param name The name of the CA to join.
 * (optional)@param activationTime The time when the CA will activate.
 * (optional)@param expirationTime The time when the CA will expire,
    must be a time in the future otherwise this will fail
 * (optional)@param userBiddingSignals The user bidding signals used at auction.
*/

FetchAndJoinCustomAudienceRequest request =
 new FetchAndJoinCustomAudienceRequest.Builder(fetchUri)
  .setName(name) //Optional
  .setActivationTime(activationTime) //Optional
  .setExpirationTime(expirationTime) //Optional
  .setUserBiddingSignals(userBiddingSignals) //Optional
  .build();

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

fetchUri ควรชี้ไปยังปลายทางของเซิร์ฟเวอร์ที่ผู้ซื้อดำเนินการ ซึ่งจะแสดงออบเจ็กต์ JSON ของกลุ่มเป้าหมายที่กำหนดเองซึ่งตรงกับรูปแบบที่เห็น ที่นี่

//Return a 200 response with data matching the format of the following in the body
{
  "daily_update_uri": "https://js.example.com/bidding/daily",
  "bidding_logic_uri": "https://js.example.com/bidding",
  "user_bidding_signals": {
    "valid": true,
    "arbitrary": "yes"
  },
  "trusted_bidding_data": {
    "trusted_bidding_uri": "https://js.example.com/bidding/trusted",
    "trusted_bidding_keys": [
      "key1",
      "key2"
    ]
  },
  "ads": [
    {
      "render_uri": "https://js.example.com/render/fetch_and_join_ad1",
      "metadata": {
        "valid": 1
      }
    },
    {
      "render_uri": "https://js.example.com/render/fetch_and_join_ad2",
      "metadata": {
        "valid": 2
      }
    }
  ]
}

ดูข้อมูลเพิ่มเติมเกี่ยวกับวิธีแก้ไขปัญหานี้ในฝั่ง API ได้ในข้อเสนอการออกแบบสำหรับการมอบสิทธิ์การเข้าร่วม CA

การทดสอบ

เมื่อติดตั้งใช้งานการเรียก Fetch ภายในโค้ดฝั่งไคลเอ็นต์และตั้งค่าปลายทางในฝั่ง DSP เพื่อแสดงผลข้อมูลกลุ่มเป้าหมายที่กำหนดเองแล้ว คุณจะทดสอบการมอบสิทธิ์ในการเข้าร่วมกลุ่มเป้าหมายที่กำหนดเองได้ ก่อนที่จะเรียกใช้แอป คุณจะต้อง เรียกใช้คำสั่งในหน้าการตั้งค่าการทดสอบ เมื่อเรียกใช้คำสั่งเหล่านี้แล้ว คุณควรจะเริ่มโทรโดยใช้ Fetch API ได้สำเร็จ

หากต้องการดูตัวอย่างโฟลว์นี้ เราได้เพิ่มการเรียกข้อมูลไปยังที่เก็บตัวอย่าง Privacy Sandbox ใน GitHub

เข้าร่วมกลุ่มเป้าหมายที่กำหนดเองโดยตรง

หากมีข้อมูลทั้งหมดที่จำเป็นต่อการสร้างและเข้าร่วมกลุ่มเป้าหมายที่กำหนดเองอยู่แล้ว คุณก็ทำได้โดยตรงโดยใช้การเรียก Protected Audience API แบบไม่พร้อมกัน หากต้องการสร้างหรือเข้าร่วมกลุ่มเป้าหมายที่กำหนดเองโดยตรง ให้ทำดังนี้

1. เริ่มต้นออบเจ็กต์ CustomAudienceManager
2. สร้างออบเจ็กต์ CustomAudience โดยระบุพารามิเตอร์หลัก เช่น แพ็กเกจของผู้ซื้อและชื่อที่เกี่ยวข้อง จากนั้นเริ่มต้นออบเจ็กต์ JoinCustomAudienceRequest ด้วยออบเจ็กต์ CustomAudience
3. เรียกใช้ joinCustomAudience() แบบอะซิงโครนัสด้วยออบเจ็กต์ JoinCustomAudienceRequest และออบเจ็กต์ Executor และ OutcomeReceiver ที่เกี่ยวข้อง

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

// Minimal initialization of a CustomAudience object
val audience: 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()

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

// Minimal initialization of a CustomAudience object
CustomAudience audience = 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();

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

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

จัดการผลลัพธ์ของ joinCustomAudience()

เมธอด joinCustomAudience() แบบอะซิงโครนัสใช้ออบเจ็กต์ OutcomeReceiver เพื่อส่งสัญญาณผลลัพธ์ของการเรียก API

• การเรียกกลับ onResult() แสดงว่าสร้างหรืออัปเดตกลุ่มเป้าหมายที่กำหนดเองสำเร็จแล้ว
• การเรียกกลับ onError() แสดงถึงเงื่อนไข 2 อย่างที่เป็นไปได้
  • หากเริ่มต้น 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. เริ่มต้น LeaveCustomAudienceRequest ด้วย buyer และ name ของกลุ่มเป้าหมายที่กำหนดเอง อ่านข้อมูลเพิ่มเติมเกี่ยวกับช่องป้อนข้อมูลเหล่านี้ได้ที่ "เข้าร่วมกลุ่มเป้าหมายที่กำหนดเองโดยตรง"
3. เรียกใช้เมธอด leaveCustomAudience() แบบอะซิงโครนัสด้วยออบเจ็กต์ LeaveCustomAudienceRequest รวมถึงออบเจ็กต์ Executor และ OutcomeReceiver ที่เกี่ยวข้อง

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

// Initialize a LeaveCustomAudienceRequest
val leaveCustomAudienceRequest: LeaveCustomAudienceRequest =
    LeaveCustomAudienceRequest.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 LeaveCustomAudienceRequest.Builder()
        .setBuyer(buyer)
        .setName(name)
        .build();

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

OutcomeReceiver จะส่งสัญญาณ สิ้นสุดการเรียก API เช่นเดียวกับการเรียก joinCustomAudience() ผลลัพธ์ข้อผิดพลาดจะไม่แยกความแตกต่างระหว่างข้อผิดพลาดภายในและอาร์กิวเมนต์ที่ไม่ถูกต้องเพื่อช่วยปกป้องความเป็นส่วนตัว ระบบจะเรียกใช้onResult() การเรียกกลับเมื่อการเรียก API เสร็จสมบูรณ์ ไม่ว่าจะนำ กลุ่มเป้าหมายที่กำหนดเองที่ตรงกันออกสำเร็จหรือไม่ก็ตาม