تحديد بيانات الجمهور

bookmark_border تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

جلب شريحة جمهور مخصّصة والانضمام إليها

تسمح واجهة برمجة التطبيقات fetchAndJoinCustomAudience للمشترين بتفويض الانضمام إلى شريحة جمهور مخصّصة من خلال الاستفادة من التواجد على الجهاز لشركاء منصّات إدارة الأداء أو منصّات عرض الإعلانات.

لكي يعمل هذا الإجراء، ينشئ المُرسِل على الجهاز (سواء كان منصّة إدارة الأداء أو حِزم تطوير البرامج (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();

ملاحظة مهمة حول جميع المَعلمات الاختيارية هي أنّه في حال ضبطها داخل طلب الجلب، لا يمكن إلغاء بياناتها باستخدام ما يتم إرجاعه من "المشتري"، ما يمنح المُتصل على الجهاز أدوات تحكّم إضافية في نوع شريحة الجمهور المخصّصة التي يتم الاحتفاظ بها.

يجب أن يشير 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
      }
    }
  ]
}

يمكن العثور على مزيد من المعلومات حول كيفية حلّ هذه المشكلة من جانب واجهة برمجة التطبيقات في ملف اقتراح التصميم لتفويض الانضمام إلى هيئة إصدار الشهادات.

الاختبار

بعد تنفيذ طلب Fetch داخل رمز العميل وإعداد نقطة نهاية على جانب منصّة إدارة الأداء الإعلاني لعرض بيانات شريحة الجمهور المخصّصة، يمكنك اختبار تفويض الانضمام إلى شريحة جمهور مخصّصة. قبل تشغيل تطبيقك، عليك تنفيذ الأوامر في صفحة إعداد الاختبار. بعد تنفيذ هذه الطلبات، من المفترض أن تتمكّن من بدء إجراء طلبات بنجاح باستخدام واجهة برمجة التطبيقات Fetch API.

للاطّلاع على مثال على هذه العملية، تمت إضافة طلبات الجلب إلى مستودع "مبادرة حماية الخصوصية" للنماذج على 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 للإشارة إلى نتيجة طلب البيانات من واجهة برمجة التطبيقات.

• يشير ردّ الاتصال 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. اضبط متغيّر 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 إلى نهاية طلب بيانات من واجهة برمجة التطبيقات. للمساعدة في حماية الخصوصية، لا يصنّف نتيجة الخطأ بين الأخطاء الداخلية والوسيطات غير الصالحة. يتمّ استدعاء onResult() دالة الاستدعاء عند اكتمال طلب البيانات من واجهة برمجة التطبيقات، سواء تمّت إزالة شريحة جمهور مخصّصة مطابقة بنجاح أم لا.