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

يمثّل الجمهور المخصّص مجموعة من المستخدمين لديهم نوايا أو اهتمامات مشتركة يحدّدها تطبيق أحد المعلِنين. ويمكن أن يستخدم تطبيق أو حزمة SDK جمهورًا مخصّصًا للإشارة إلى شريحة جمهور معيّنة، مثل مستخدم ترك سلعًا في سلة التسوّق.

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

الجماهير المخصّصة

يحدّد مزيج المَعلمات التالية بشكلٍ فريد كل كائن CustomAudience على الجهاز:

• ‫owner: اسم حزمة التطبيق المالك، ويتم ضبطه ضمنيًا على اسم حزمة التطبيق الذي يستدعي الخدمة.
• ‫buyer: معرّف لشبكة إعلانات المشترين التي تدير الإعلانات لشرائح الجمهور المخصّصة هذه.
• name: اسم أو معرّف عشوائي لشرائح الجمهور المخصّصة.

بالإضافة إلى ذلك، يجب إنشاء CustomAudience باستخدام المَعلمات المطلوبة التالية:

• عنوان URL للتعديل اليومي: هو عنوان URL بتنسيق HTTPS يتم الاستعلام عنه يوميًا في الخلفية من أجل تعديل إشارات عروض الأسعار للمستخدمين في شريحة جمهور مخصّصة، وبيانات عروض الأسعار الموثوقة، وعرض عناوين URL والبيانات الوصفية للإعلانات.
• عنوان URL لمنطق عروض الأسعار: هو عنوان URL يستخدم HTTPS ويتم طلبه أثناء اختيار الإعلان لجلب منطق عروض الأسعار المستند إلى JavaScript الخاص بالمشتري. اطّلِع على توقيعات الدوال المطلوبة في JavaScript هذا.
• معرّفات عرض الإعلانات: معرّف عشوائي يحدّده مقدّم تكنولوجيا الإعلان التابع للمشتري، وهو تحسين لإنشاء الحمولة لعملية العرض والشراء.

قد تتضمّن المَعلمات الاختيارية لكائن CustomAudience ما يلي:

• وقت التفعيل: لا يمكن أن تشارك شريحة الجمهور المخصّصة في اختيار الإعلانات والتعديلات اليومية إلا بعد وقت تفعيلها. ويمكن أن يكون ذلك مفيدًا لجذب المستخدمين غير النشطين في تطبيق معيّن، على سبيل المثال.
• وقت انتهاء الصلاحية: هو وقت مستقبلي تتم بعده إزالة شريحة الجمهور المخصّصة من الجهاز.
• إشارات عروض أسعار المستخدم: هي سلسلة JSON تحتوي على إشارات المستخدم، مثل اللغة المفضّلة لدى المستخدم، والتي يستهلكها JavaScript الخاص بمنطق عروض الأسعار لدى المعلِن من أجل إنشاء عروض أسعار أثناء عملية اختيار الإعلان. يساعد هذا التنسيق منصات تكنولوجيا الإعلان في إعادة استخدام الرمز البرمجي على مستوى المنصات ويسهّل استخدامه في دوال JavaScript.
• بيانات عروض الأسعار الموثوقة: هي عنوان URL بتنسيق HTTPS وقائمة سلاسل تُستخدَم أثناء عملية اختيار الإعلانات لجلب إشارات عروض الأسعار من خدمة موثوقة تستند إلى مفتاح/قيمة.
• الإعلانات: قائمة بعناصر AdData تتوافق مع الإعلانات التي تشارك في عملية اختيار الإعلانات. يتكوّن كل عنصر AdData مما يلي:
  • عنوان URL للعرض: هو عنوان URL يستخدم HTTPS ويتم إرسال طلب بحث إليه لعرض الإعلان النهائي.
  • البيانات الوصفية: هي عنصر JSON يتم تسلسله كسلسلة تحتوي على معلومات تستهلكها منطق عروض أسعار المشترين أثناء عملية اختيار الإعلان.
  • فلاتر الإعلانات: فئة تحتوي على جميع المعلومات اللازمة لفلترة الإعلانات التي تحثّ على تثبيت التطبيقات وتحديد عدد مرّات الظهور أثناء اختيار الإعلان.

استرداد شريحة جمهور مخصّصة ودمجها

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

لكي ينجح ذلك، يجب أن ينشئ المتصل على الجهاز (سواء كان ذلك حزمة تطوير برامج تابعة لمنصة قياس أو منصة عرض) 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
      }
    }
  ]
}

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

الاختبار

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

للاطّلاع على مثال على هذا المسار، تمت إضافة عمليات جلب إلى مستودع عيّنات "مبادرة حماية الخصوصية" على GitHub.

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

إذا كانت لديك كل المعلومات التي تحتاج إليها لإنشاء شريحة جمهور مخصّصة والانضمام إليها، يمكنك إجراء ذلك مباشرةً باستخدام طلب غير متزامن لواجهة برمجة تطبيقات Protected Audience. لإنشاء شريحة جمهور مخصّصة أو الانضمام إليها مباشرةً، اتّبِع الخطوات التالية:

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