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

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

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

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

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

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

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

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

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

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

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

fetchAndJoinCustomAudience API به خریداران اجازه می دهد تا با استفاده از حضور MMPs یا 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 مخاطب سفارشی را که با قالبی که در اینجا مشاهده می‌شود مطابقت دارد، برمی‌گرداند:

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

برای مشاهده نمونه‌ای از این جریان، تماس‌های واکشی به مخزن نمونه‌های جعبه ایمنی حریم خصوصی در 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);

نتایج joinCustomAudience() را مدیریت کنید

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

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