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

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

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

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

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

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

นอกจากนี้ คุณต้องสร้าง CustomAudience ด้วยพารามิเตอร์ที่จำเป็น ต่อไปนี้

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

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

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

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

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

เพื่อให้ API นี้ทำงานได้ ผู้เรียกในอุปกรณ์ (ไม่ว่าจะเป็น 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 นี้ทำงานได้ใน ข้อเสนอการออกแบบสำหรับการมอบสิทธิ์การเข้าร่วมกลุ่มเป้าหมายที่กำหนดเอง

การทดสอบ

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

หากต้องการดูตัวอย่างโฟลว์นี้ เราได้เพิ่มการเรียก Fetch ลงในที่เก็บตัวอย่าง 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);

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