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

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

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

คุณสามารถใช้ Protected Audience API ของ Android เพื่อเข้าร่วมและออกจากกลุ่มเป้าหมายที่กำหนดเองในอุปกรณ์ของผู้ใช้ เมื่อสร้างและเข้าร่วมกลุ่มเป้าหมายที่กําหนดเอง คุณสามารถมอบสิทธิ์ให้เซิร์ฟเวอร์ที่จะดึงข้อมูลพร็อพเพอร์ตี้กลุ่มเป้าหมายที่กําหนดเองบางส่วนหรือทั้งหมด หรือระบุข้อมูลนี้เมื่อเรียกใช้ 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 หรือ SSP SDK) จะสร้าง 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();

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

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 แบบรวม

การทดสอบ

เมื่อใช้การเรียกใช้การดึงข้อมูลภายในโค้ดไคลเอ็นต์และตั้งค่าปลายทางฝั่ง 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() callbacks เมื่อการเรียก API เสร็จสมบูรณ์ ไม่ว่าจะนํากลุ่มเป้าหมายที่ตรงกันออกสําเร็จหรือไม่ก็ตาม