داده های مخاطب را تعریف کنید

مخاطب سفارشی، گروهی از کاربران با اهداف یا علایق مشترک را نشان می‌دهد که توسط یک برنامه تبلیغ‌کننده تعیین شده است. یک برنامه یا SDK ممکن است از یک مخاطب سفارشی برای نشان دادن یک مخاطب خاص، مانند کسی که اقلامی را در سبد خرید باقی گذاشته است، استفاده کند.

API مخاطب محافظت‌شده اندروید (Android Protected Audience API) می‌تواند برای پیوستن و رها کردن مخاطبان سفارشی در دستگاه کاربر استفاده شود. هنگام ایجاد و پیوستن به یک مخاطب سفارشی، می‌توانید یا آن را به سروری واگذار کنید که از آن برخی یا تمام ویژگی‌های مخاطب سفارشی را دریافت کنید، یا می‌توانید این اطلاعات را هنگام فراخوانی مستقیم API مشخص کنید .

مخاطبان سفارشی

ترکیب پارامترهای زیر به طور منحصر به فرد هر شیء CustomAudience را در یک دستگاه مشخص می‌کند:

• owner : نام بسته‌ی برنامه‌ی مالک. این به طور ضمنی روی نام بسته‌ی برنامه‌ی فراخواننده تنظیم شده است.
• buyer : شناسه شبکه تبلیغاتی خریدار که تبلیغات را برای این مخاطب سفارشی مدیریت می‌کند.
• name : یک نام یا شناسه دلخواه برای مخاطب سفارشی.

علاوه بر این، CustomAudience باید با پارامترهای مورد نیاز زیر ایجاد شود:

• به‌روزرسانی روزانه URL : یک URL HTTPS که روزانه در پس‌زمینه جستجو می‌شود تا سیگنال‌های پیشنهاد قیمت کاربر، داده‌های پیشنهاد قیمت قابل اعتماد و URLها و فراداده‌های مربوط به تبلیغات را به‌روزرسانی کند.
• آدرس اینترنتی منطق پیشنهاد قیمت : یک آدرس اینترنتی HTTPS که هنگام انتخاب تبلیغ برای دریافت منطق پیشنهاد قیمت جاوا اسکریپت خریدار درخواست می‌شود. امضاهای تابع مورد نیاز را در این جاوا اسکریپت مشاهده کنید.
• شناسه‌های رندر تبلیغات : یک شناسه دلخواه که توسط تکنسین تبلیغات خریدار تنظیم می‌شود. این یک بهینه‌سازی برای تولید بار مفید برای B&A است.

پارامترهای اختیاری برای یک شیء CustomAudience می‌تواند شامل موارد زیر باشد:

• زمان فعال‌سازی : یک مخاطب سفارشی فقط می‌تواند پس از زمان فعال‌سازی در انتخاب تبلیغات و به‌روزرسانی‌های روزانه شرکت کند. این می‌تواند برای مثال برای جذب کاربران قدیمی یک برنامه مفید باشد.
• زمان انقضا : زمانی در آینده که پس از آن مخاطب سفارشی از دستگاه حذف می‌شود.
• سیگنال‌های پیشنهاد قیمت کاربر : یک رشته JSON حاوی سیگنال‌های کاربر، مانند زبان ترجیحی کاربر، که منطق پیشنهاد قیمت خریدار از آن استفاده می‌کند و جاوا اسکریپت برای تولید پیشنهادها در طول فرآیند انتخاب تبلیغ از آن استفاده می‌کند. این فرمت به پلتفرم‌های فناوری تبلیغات کمک می‌کند تا از کد در پلتفرم‌های مختلف استفاده مجدد کنند و مصرف در توابع جاوا اسکریپت را آسان‌تر می‌کند.
• داده‌های مناقصه‌ی معتبر : یک URL HTTPS و فهرستی از رشته‌های مورد استفاده در طول فرآیند انتخاب تبلیغ که سیگنال‌های مناقصه را از یک سرویس کلید/مقدار معتبر دریافت می‌کنند.
• تبلیغات : فهرستی از اشیاء AdData مربوط به تبلیغاتی که در انتخاب تبلیغ شرکت می‌کنند. هر شیء AdData شامل موارد زیر است:
  • Render URL : یک URL HTTPS که برای رندر تبلیغ نهایی درخواست می‌شود.
  • فراداده : یک شیء JSON که به صورت رشته‌ای سریالی شده و حاوی اطلاعاتی است که توسط منطق پیشنهاد قیمت خریدار در طول فرآیند انتخاب تبلیغ مصرف می‌شود.
  • فیلترهای تبلیغات : کلاسی که شامل تمام اطلاعات لازم برای فیلتر کردن تبلیغات نصب برنامه و محدود کردن دفعات نمایش در طول انتخاب تبلیغ است.

دریافت و پیوستن به مخاطبان سفارشی

رابط برنامه‌نویسی کاربردی (API) fetchAndJoinCustomAudience به خریداران این امکان را می‌دهد که با استفاده از حضور 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();

نکته مهم در مورد همه پارامترهای اختیاری این است که اگر آنها داخل درخواست واکشی تنظیم شوند، داده‌های آنها نمی‌تواند توسط آنچه از خریدار برگردانده می‌شود، لغو شود و به تماس‌گیرنده روی دستگاه کنترل‌های بیشتری بر روی مخاطبان سفارشی که باید ذخیره شوند، می‌دهد.

fetchUri باید به یک نقطه پایانی سرور که توسط خریدار اداره می‌شود اشاره کند که یک شیء JSON از نوع Custom Audience را برمی‌گرداند که با فرمتی که در اینجا مشاهده می‌شود مطابقت دارد:

//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 برای بازگرداندن داده‌های مخاطب سفارشی، می‌توانید واگذاری عضویت به یک مخاطب سفارشی را آزمایش کنید. قبل از اجرای برنامه، باید دستورات موجود در صفحه تنظیمات Testing را اجرا کنید. پس از اجرای این دستورات، باید بتوانید با موفقیت با استفاده از Fetch API تماس‌ها را برقرار کنید.

برای دیدن نمونه‌ای از این جریان، فراخوانی‌های واکشی به مخزن نمونه‌های Privacy Sandbox در GitHub اضافه شده‌اند.

مستقیماً به مخاطبان سفارشی بپیوندید

اگر از قبل تمام اطلاعات لازم برای ایجاد و پیوستن به یک مخاطب سفارشی را دارید، می‌توانید این کار را مستقیماً با استفاده از فراخوانی ناهمزمان 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);

مدیریت نتایج joinCustomAudio()

متد joinCustomAudience() ناهمزمان از شیء OutcomeReceiver برای ارسال نتیجه فراخوانی API استفاده می‌کند.

• تابع فراخوانی 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 پایان فراخوانی API را اعلام می‌کند. برای کمک به حفظ حریم خصوصی، یک error result تفاوتی بین خطاهای داخلی و آرگومان‌های نامعتبر قائل نمی‌شود. تابع onResult() زمانی فراخوانی می‌شود که فراخوانی API به پایان رسیده باشد، چه مخاطب سفارشی منطبق با موفقیت حذف شده باشد و چه نشده باشد.