সুরক্ষিত শ্রোতা API বিকাশকারীর নির্দেশিকা৷

অ্যান্ড্রয়েড ডকুমেন্টেশনের প্রাইভেসি স্যান্ডবক্স পড়ার সময়, আপনি যে প্রোগ্রাম সংস্করণটি ব্যবহার করছেন তা নির্বাচন করতে ডেভেলপার প্রিভিউ বা বিটা বোতামটি ব্যবহার করুন, কারণ নির্দেশাবলী ভিন্ন হতে পারে।

অ্যান্ড্রয়েডের প্রোটেক্টেড অডিয়েন্স API (পূর্বে FLEDGE নামে পরিচিত) এর মধ্যে রয়েছে কাস্টম অডিয়েন্স API এবং বিজ্ঞাপন নির্বাচন API। বিজ্ঞাপন প্রযুক্তি প্ল্যাটফর্ম এবং বিজ্ঞাপনদাতারা পূর্ববর্তী অ্যাপ এনগেজমেন্টের উপর ভিত্তি করে কাস্টমাইজড বিজ্ঞাপন পরিবেশন করতে এই API ব্যবহার করতে পারেন যা অ্যাপ জুড়ে শনাক্তকারীর ভাগাভাগি সীমিত করে এবং তৃতীয় পক্ষের সাথে ব্যবহারকারীর অ্যাপ ইন্টারঅ্যাকশন তথ্য ভাগাভাগি সীমিত করে।

কাস্টম অডিয়েন্স এপিআই "কাস্টম অডিয়েন্স" বিমূর্তকরণের উপর কেন্দ্রীভূত, যা সাধারণ উদ্দেশ্য সম্পন্ন ব্যবহারকারীদের একটি গোষ্ঠীকে প্রতিনিধিত্ব করে। একজন বিজ্ঞাপনদাতা একজন ব্যবহারকারীকে একটি কাস্টম অডিয়েন্সের সাথে নিবন্ধন করতে পারেন এবং এর সাথে প্রাসঙ্গিক বিজ্ঞাপন যুক্ত করতে পারেন। এই তথ্য স্থানীয়ভাবে সংরক্ষণ করা হয় এবং বিজ্ঞাপনদাতার বিড, বিজ্ঞাপন ফিল্টারিং এবং বিজ্ঞাপন রেন্ডারিং সম্পর্কে অবহিত করতে ব্যবহার করা যেতে পারে।

বিজ্ঞাপন নির্বাচন API এমন একটি কাঠামো প্রদান করে যা একাধিক ডেভেলপারকে স্থানীয়ভাবে একটি কাস্টম দর্শকের জন্য নিলাম পরিচালনা করতে দেয়। এটি অর্জনের জন্য, সিস্টেমটি কাস্টম দর্শকের সাথে সম্পর্কিত প্রাসঙ্গিক বিজ্ঞাপনগুলি বিবেচনা করে এবং একটি বিজ্ঞাপন প্রযুক্তি প্ল্যাটফর্ম ডিভাইসে ফেরত পাঠানো বিজ্ঞাপনগুলিতে অতিরিক্ত প্রক্রিয়াকরণ করে।

বিজ্ঞাপন প্রযুক্তি প্ল্যাটফর্মগুলি ব্যবহারকারীর গোপনীয়তা রক্ষা করে এমন পুনঃবিপণন বাস্তবায়নের জন্য এই API গুলিকে একীভূত করতে পারে। ভবিষ্যতের প্রকাশের জন্য অ্যাপ ইনস্টল বিজ্ঞাপন সহ অতিরিক্ত ব্যবহারের ক্ষেত্রে সহায়তার পরিকল্পনা করা হয়েছে। ডিজাইন প্রস্তাবনায় Android-এ Protected Audience API সম্পর্কে আরও জানুন।

এই নির্দেশিকাটি বর্ণনা করে যে কীভাবে Android-এ Protected Audience API-এর সাথে কাজ করে নিম্নলিখিত কাজগুলি করতে হয়:

  1. কাস্টম দর্শকদের পরিচালনা করুন
  2. একটি ডিভাইসে বিজ্ঞাপন নির্বাচন সেট আপ এবং চালান
  3. বিজ্ঞাপনের ছাপ রিপোর্ট করুন

শুরু করার আগে

শুরু করার আগে, নিম্নলিখিতগুলি সম্পন্ন করুন:

  1. অ্যান্ড্রয়েডে প্রাইভেসি স্যান্ডবক্সের জন্য আপনার ডেভেলপমেন্ট পরিবেশ সেট আপ করুন ।
  2. হয় একটি সমর্থিত ডিভাইসে একটি সিস্টেম ইমেজ ইনস্টল করুন অথবা একটি এমুলেটর সেট আপ করুন যাতে Android-এ প্রাইভেসি স্যান্ডবক্সের জন্য সমর্থন অন্তর্ভুক্ত থাকে।

  3. একটি টার্মিনালে, নিম্নলিখিত adb কমান্ডের সাহায্যে Protected Audience API (ডিফল্টরূপে নিষ্ক্রিয়) অ্যাক্সেস সক্ষম করুন ।

      adb shell device_config put adservices ppapi_app_allow_list \"*\"

  4. একটি টার্মিনালে, নিম্নলিখিত adb কমান্ডগুলি ব্যবহার করে বীকন রিপোর্টিং সক্ষম করুন।

     adb shell device_config put adservices fledge_beacon_reporting_metrics_enabled true
 adb shell device_config put adservices fledge_register_ad_beacon_enabled true

  5. আপনার অ্যাপ ম্যানিফেস্টে একটি ACCESS_ADSERVICES_CUSTOM_AUDIENCE অনুমতি অন্তর্ভুক্ত করুন:

      <uses-permission android:name="android.permission.ACCESS_ADSERVICES_CUSTOM_AUDIENCE" />

  6. আপনার ম্যানিফেস্টের <application> এলিমেন্টে একটি বিজ্ঞাপন পরিষেবা কনফিগারেশন উল্লেখ করুন:

      <property android:name="android.adservices.AD_SERVICES_CONFIG"
            android:resource="@xml/ad_services_config" />

  7. আপনার ম্যানিফেস্টে উল্লেখিত বিজ্ঞাপন পরিষেবা XML রিসোর্স নির্দিষ্ট করুন, যেমন res/xml/ad_services_config.xml । ​​বিজ্ঞাপন পরিষেবার অনুমতি এবং SDK অ্যাক্সেস নিয়ন্ত্রণ সম্পর্কে আরও জানুন ।

      <ad-services-config>
    <custom-audiences allowAllToAccess="true" />
  </ad-services-config>

  8. ডিফল্টরূপে, বিজ্ঞাপন নির্বাচন API একটি নিলাম বা ইম্প্রেশন রিপোর্টিং স্ক্রিপ্ট দ্বারা বরাদ্দ করা সর্বোচ্চ মেমোরির পরিমাণের উপর সীমা আরোপ করে। মেমোরি সীমাবদ্ধতা বৈশিষ্ট্যের জন্য WebView সংস্করণ 105.0.5195.58 বা তার বেশি প্রয়োজন। প্ল্যাটফর্মটি একটি সংস্করণ পরীক্ষা জোরদার করে এবং যদি এটি সন্তুষ্ট না হয় তবে selectAds এবং reportImpression API গুলিতে কল করা ব্যর্থ হয়। এটি সেট আপ করার জন্য দুটি বিকল্প রয়েছে:

    • বিকল্প ১: এই চেকটি নিষ্ক্রিয় করতে নিম্নলিখিত adb কমান্ডটি চালান:

      adb device_config put fledge_js_isolate_enforce_max_heap_size false

    • বিকল্প ২: গুগল প্লে স্টোর থেকে ওয়েবভিউ বিটা ইনস্টল করুন। এটি অবশ্যই পূর্বে উল্লিখিত সংস্করণের সমান বা তার চেয়ে বেশি হতে হবে।

একটি কাস্টম দর্শকদের সাথে যোগ দিন

একটি কাস্টম অডিয়েন্স হল এমন কিছু ব্যবহারকারীর দল যাদের অভিন্ন উদ্দেশ্য বা আগ্রহ থাকে, যেমনটি একটি বিজ্ঞাপনদাতা অ্যাপ নির্ধারণ করে। একটি অ্যাপ বা SDK একটি নির্দিষ্ট অডিয়েন্সকে নির্দেশ করার জন্য একটি কাস্টম অডিয়েন্স ব্যবহার করতে পারে, যেমন এমন কেউ যিনি শপিং কার্টে জিনিস রেখে গেছেন। অ্যাসিঙ্ক্রোনাসভাবে একটি কাস্টম অডিয়েন্স তৈরি করতে বা যোগদান করতে, নিম্নলিখিতগুলি করুন:

  1. CustomAudienceManager অবজেক্টটি আরম্ভ করুন।
  2. ক্রেতার প্যাকেজ এবং প্রাসঙ্গিক নামের মতো গুরুত্বপূর্ণ প্যারামিটারগুলি নির্দিষ্ট করে একটি CustomAudience অবজেক্ট তৈরি করুন। তারপর, CustomAudience অবজেক্ট দিয়ে JoinCustomAudienceRequest অবজেক্টটি ইনিশিয়ালাইজ করুন।
  3. JoinCustomAudienceRequest অবজেক্ট এবং প্রাসঙ্গিক Executor এবং OutcomeReceiver অবজেক্টের সাহায্যে অ্যাসিঙ্ক্রোনাস joinCustomAudience() কল করুন।

কোটলিন 

val customAudienceManager: CustomAudienceManager =
    context.getSystemService(CustomAudienceManager::class.java)

// Initialize a custom audience.
val audience = CustomAudience.Builder()
    .setBuyer(buyer)
    .setName(name)
    ...
    .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);

// Initialize a custom audience.
CustomAudience audience = new CustomAudience.Builder()
    .setBuyer(buyer)
    .setName(name)
    ...
    .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);

নিম্নলিখিত প্যারামিটারগুলির সমন্বয় একটি ডিভাইসের প্রতিটি CustomAudience অবজেক্টকে অনন্যভাবে সনাক্ত করে:

  • owner : মালিক অ্যাপের প্যাকেজ নাম। এটি পরোক্ষভাবে কলার অ্যাপের প্যাকেজ নামে সেট করা আছে।
  • buyer : ক্রেতা বিজ্ঞাপন নেটওয়ার্কের জন্য শনাক্তকারী যা এই কাস্টম দর্শকদের জন্য বিজ্ঞাপন পরিচালনা করে।
  • name : কাস্টম দর্শকদের জন্য একটি ইচ্ছামত নাম বা শনাক্তকারী।

CustomAudience এর ভিন্ন উদাহরণ ব্যবহার করে বারবার joinCustomAudience() কল করলে বিদ্যমান CustomAudience সাথে owner, buyer এবং name প্যারামিটারের মিল আপডেট হয়। গোপনীয়তা রক্ষা করতে, API-এর ফলাফল "creation" এবং "update"-এর মধ্যে পার্থক্য করে না।

অতিরিক্তভাবে, CustomAudience অবশ্যই এই প্রয়োজনীয় পরামিতিগুলি ব্যবহার করে তৈরি করতে হবে:

একটি CustomAudience অবজেক্টের জন্য ঐচ্ছিক প্যারামিটারগুলির মধ্যে অন্তর্ভুক্ত থাকতে পারে:

  • সক্রিয়করণের সময় : একটি কাস্টম দর্শক শুধুমাত্র বিজ্ঞাপন নির্বাচন এবং দৈনিক আপডেটে অংশগ্রহণ করতে পারে তার সক্রিয়করণের সময় শেষ হওয়ার পরে। উদাহরণস্বরূপ, এটি একটি অ্যাপের ল্যাপসড ব্যবহারকারীদের সাথে যুক্ত করার জন্য কার্যকর হতে পারে।
  • মেয়াদ শেষ হওয়ার সময় : ভবিষ্যতের একটি সময় যার পরে ডিভাইস থেকে কাস্টম দর্শকদের সরিয়ে ফেলা হবে।
  • ব্যবহারকারীর বিডিং সিগন্যাল : একটি JSON স্ট্রিং যাতে ব্যবহারকারীর সিগন্যাল থাকে, যেমন ব্যবহারকারীর পছন্দের লোকেল, যা ক্রেতার বিডিং লজিক জাভাস্ক্রিপ্ট বিজ্ঞাপন নির্বাচন প্রক্রিয়ার সময় বিড তৈরি করতে ব্যবহার করে। এই ফর্ম্যাটটি বিজ্ঞাপন প্রযুক্তি প্ল্যাটফর্মগুলিকে প্ল্যাটফর্ম জুড়ে কোড পুনঃব্যবহার করতে সহায়তা করে এবং জাভাস্ক্রিপ্ট ফাংশনগুলিতে ব্যবহার সহজ করে।
  • বিশ্বস্ত বিডিং ডেটা : একটি HTTPS URL এবং বিজ্ঞাপন নির্বাচন প্রক্রিয়ার সময় ব্যবহৃত স্ট্রিংগুলির একটি তালিকা যা একটি বিশ্বস্ত কী/মান পরিষেবা থেকে বিডিং সংকেত আনে।
  • বিজ্ঞাপন : বিজ্ঞাপন নির্বাচনে অংশগ্রহণকারী বিজ্ঞাপনগুলির সাথে সম্পর্কিত AdData অবজেক্টের একটি তালিকা। প্রতিটি AdData অবজেক্টে থাকে:
    • রেন্ডার URL : একটি HTTPS URL যা চূড়ান্ত বিজ্ঞাপন রেন্ডার করার জন্য জিজ্ঞাসা করা হয়।
    • মেটাডেটা : বিজ্ঞাপন নির্বাচন প্রক্রিয়ার সময় ক্রেতার বিডিং লজিকের ব্যবহারের জন্য তথ্য সম্বলিত একটি JSON অবজেক্টকে স্ট্রিং হিসেবে সিরিয়ালাইজ করা হয়।
    • বিজ্ঞাপন ফিল্টার : একটি ক্লাস যেখানে বিজ্ঞাপন নির্বাচনের সময় অ্যাপ ইনস্টল বিজ্ঞাপন ফিল্টারিং এবং ফ্রিকোয়েন্সি ক্যাপিংয়ের জন্য প্রয়োজনীয় সমস্ত তথ্য রয়েছে।

এখানে একটি CustomAudience অবজেক্ট ইনস্ট্যান্সিয়েশনের একটি উদাহরণ দেওয়া হল:

কোটলিন 

// Minimal initialization of a CustomAudience object
val customAudience: 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()

জাভা 

// Minimal initialization of a CustomAudience object
CustomAudience 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();

joinCustomAudience() ফলাফল পরিচালনা করুন

অ্যাসিঙ্ক্রোনাস joinCustomAudience() পদ্ধতিটি API কলের ফলাফল সিগন্যাল করার জন্য 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. কাস্টম অডিয়েন্সের buyer এবং name দিয়ে LeaveCustomAudienceRequest আরম্ভ করুন। এই ইনপুট ফিল্ডগুলি সম্পর্কে আরও জানতে, " Join a custom audience " পড়ুন।
  3. LeaveCustomAudienceRequest অবজেক্ট এবং প্রাসঙ্গিক Executor এবং OutcomeReceiver অবজেক্ট ব্যবহার করে অ্যাসিঙ্ক্রোনাস leaveCustomAudience() পদ্ধতিটি কল করুন।

কোটলিন 

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 কলের সমাপ্তির সংকেত দেয়। গোপনীয়তা রক্ষা করতে, একটি ত্রুটি ফলাফল অভ্যন্তরীণ ত্রুটি এবং অবৈধ আর্গুমেন্টের মধ্যে পার্থক্য করে না। API কল সম্পন্ন হলে onResult() কলব্যাক কল করা হয়, মিলিত কাস্টম অডিয়েন্স সফলভাবে সরানো হোক বা না হোক।

বিজ্ঞাপন নির্বাচন চালান

বিজ্ঞাপন নির্বাচন করার জন্য Protected Audience API ব্যবহার করতে, selectAds() পদ্ধতিটি কল করুন:

  1. একটি AdSelectionManager অবজেক্ট আরম্ভ করুন।
  2. একটি AdSelectionConfig অবজেক্ট তৈরি করুন।
  3. AdSelectionConfig অবজেক্ট এবং প্রাসঙ্গিক Executor এবং OutcomeReceiver অবজেক্ট ব্যবহার করে অ্যাসিঙ্ক্রোনাস selectAds() পদ্ধতিটি কল করুন।

কোটলিন 

val adSelectionManager: AdSelectionManager =
  context.getSystemService(AdSelectionManager::class.java)

// Initialize AdSelectionConfig
val adSelectionConfig: AdSelectionConfig =
  AdSelectionConfig.Builder().setSeller(seller)
    .setDecisionLogicUrl(decisionLogicUrl)
    .setCustomAudienceBuyers(customAudienceBuyers)
    .setAdSelectionSignals(adSelectionSignals)
    .setSellerSignals(sellerSignals)
    .setPerBuyerSignals(perBuyerSignals)
    .setBuyerContextualAds(
      Collections.singletonMap(
        contextualAds.getBuyer(), contextualAds
      )
    ).build()

// Run ad selection with AdSelectionConfig
adSelectionManager.selectAds(
  adSelectionConfig, executor, outcomeReceiver
)

জাভা 

AdSelectionManager adSelectionManager =
    context.getSystemService(AdSelectionManager.class);

// Initialize AdSelectionConfig
AdSelectionConfig adSelectionConfig =
  new AdSelectionConfig.Builder()
    .setSeller(seller)
    .setDecisionLogicUrl(decisionLogicUrl)
    .setCustomAudienceBuyers(customAudienceBuyers)
    .setAdSelectionSignals(adSelectionSignals)
    .setSellerSignals(sellerSignals)
    .setPerBuyerSignals(perBuyerSignals)
    .setBuyerContextualAds(
      Collections.singletonMap(contextualAds.getBuyer(), contextualAds)
    )
    .build();

// Run ad selection with AdSelectionConfig
adSelectionManager.selectAds(adSelectionConfig, executor, outcomeReceiver);

selectAds() পদ্ধতির জন্য একটি AdSelectionConfig ইনপুট প্রয়োজন, যেখানে আপনাকে নিম্নলিখিত প্রয়োজনীয় প্যারামিটারগুলি নির্দিষ্ট করতে হবে:

  • বিক্রেতা : বিজ্ঞাপন নির্বাচন শুরু করা বিক্রেতা বিজ্ঞাপন নেটওয়ার্কের জন্য শনাক্তকারী।
  • ডিসিশন লজিক URL : বিক্রেতার বিজ্ঞাপন নেটওয়ার্কের জাভাস্ক্রিপ্ট লজিক পেতে জিজ্ঞাসা করা একটি HTTPS URL।
    • HTTPS URL : বিক্রেতার বিজ্ঞাপন নেটওয়ার্কের জাভাস্ক্রিপ্ট লজিক পেতে জিজ্ঞাসা করা হয়েছে। প্রয়োজনীয় ফাংশন স্বাক্ষর দেখুন।
    • প্রি-বিল্ট URI : যা FLEDGE এর বিজ্ঞাপন নির্বাচন ফর্ম্যাট অনুসরণ করে। যদি একটি অসমর্থিত বা ত্রুটিপূর্ণ প্রি-বিল্ট URI পাস করা হয়, তাহলে IllegalArgumentException থ্রো করা হয়।
  • কাস্টম অডিয়েন্স বায়ার্স : ক্রেতা বিজ্ঞাপন নেটওয়ার্কগুলির জন্য শনাক্তকারীর একটি সম্পূর্ণ তালিকা যা বিক্রেতা বিজ্ঞাপন নির্বাচন প্রক্রিয়ায় অংশগ্রহণের অনুমতি দেয়। এই ক্রেতা শনাক্তকারী অংশগ্রহণকারী কাস্টম CustomAudience.getBuyer() এর সাথে সঙ্গতিপূর্ণ।

আরও কাস্টমাইজড বিজ্ঞাপন নির্বাচনের জন্য নিম্নলিখিত প্যারামিটারগুলি ঐচ্ছিকভাবে নির্দিষ্ট করা যেতে পারে:

  • বিজ্ঞাপন নির্বাচন সংকেত : একটি JSON অবজেক্ট, যা স্ট্রিং হিসেবে সিরিয়ালাইজ করা হয়েছে, যাতে ক্রেতা বিডিং লজিক দ্বারা ব্যবহৃত সংকেত থাকে। CustomAudience.getBiddingLogicUrl() থেকে জাভাস্ক্রিপ্ট সংগ্রহ করা হয়েছে।
  • বিক্রেতা সংকেত : একটি JSON অবজেক্ট, যা স্ট্রিং হিসেবে সিরিয়ালাইজ করা হয়েছে, যাতে AdSelectionConfig.getDecisionLogicUrl() থেকে বিক্রেতার আনা জাভাস্ক্রিপ্ট সিদ্ধান্ত লজিক দ্বারা ব্যবহৃত সংকেত থাকে।
  • প্রতি ক্রেতা সংকেত : JSON অবজেক্টের একটি মানচিত্র, যা স্ট্রিং হিসাবে সিরিয়াল করা হয়েছে, যাতে নির্দিষ্ট ক্রেতাদের বিডিং লজিক দ্বারা ব্যবহৃত সংকেত থাকে। CustomAudience.getBiddingLogicUrl() থেকে জাভাস্ক্রিপ্ট সংগ্রহ করা হয়েছে, যা অংশগ্রহণকারী কাস্টম দর্শকদের ক্রেতা ক্ষেত্র দ্বারা চিহ্নিত করা হয়।
  • প্রাসঙ্গিক বিজ্ঞাপন: সুরক্ষিত দর্শক নিলামের বাইরে অনুষ্ঠিত নিলামের সময় ক্রেতাদের কাছ থেকে সরাসরি সংগ্রহ করা বিজ্ঞাপন প্রার্থীদের একটি সংগ্রহ।

একবার একটি বিজ্ঞাপন নির্বাচন করা হলে, ফলাফল, বিড এবং সংকেতগুলি প্রতিবেদনের জন্য অভ্যন্তরীণভাবে স্থায়ী থাকে। OutcomeReceiver.onResult() কলব্যাক একটি AdSelectionOutcome প্রদান করে যার মধ্যে রয়েছে:

  • AdData.getRenderUrl() থেকে প্রাপ্ত বিজয়ী বিজ্ঞাপনের জন্য একটি রেন্ডার URL।
  • ডিভাইস ব্যবহারকারীর জন্য অনন্য একটি বিজ্ঞাপন নির্বাচন আইডি। এই আইডিটি বিজ্ঞাপনের ছাপ রিপোর্ট করার জন্য ব্যবহৃত হয়।

যদি অবৈধ আর্গুমেন্ট, টাইমআউট, অথবা অতিরিক্ত রিসোর্স ব্যবহারের মতো কারণে বিজ্ঞাপন নির্বাচন সফলভাবে সম্পন্ন না হয়, তাহলে OutcomeReceiver.onError() কলব্যাক নিম্নলিখিত আচরণ সহ একটি AdServicesException প্রদান করে:

  • যদি বিজ্ঞাপন নির্বাচন অবৈধ আর্গুমেন্ট দিয়ে শুরু করা হয়, তাহলে AdServicesException একটি IllegalArgumentException কারণ হিসেবে নির্দেশ করে।
  • অন্য সকল ত্রুটির জন্য একটি AdServicesException পাওয়া যায় যার কারণ হিসেবে একটি IllegalStateException থাকে।

প্রাসঙ্গিক বিজ্ঞাপন

সুরক্ষিত দর্শকরা সুরক্ষিত নিলামে প্রাসঙ্গিক বিজ্ঞাপন অন্তর্ভুক্ত করতে পারে। প্রাসঙ্গিক বিজ্ঞাপনগুলিকে বিজ্ঞাপন প্রযুক্তি সার্ভারে নির্বাচন করতে হবে এবং সুরক্ষিত দর্শক API-এর বাইরে ডিভাইসে ফেরত পাঠাতে হবে। এরপর AdSelectionConfig ব্যবহার করে প্রাসঙ্গিক বিজ্ঞাপনগুলিকে নিলামে অন্তর্ভুক্ত করা যেতে পারে যেখানে তারা ডিভাইস বিজ্ঞাপনের মতোই কাজ করে, যার মধ্যে নেতিবাচক বিজ্ঞাপন ফিল্টারিংয়ের যোগ্যতাও অন্তর্ভুক্ত। সুরক্ষিত দর্শক নিলাম সম্পন্ন হয়ে গেলে, আপনাকে reportImpression() ব্যবহার করতে হবে। এটি একটি ডিভাইসে বিজয়ী বিজ্ঞাপন পেতে ইম্প্রেশন রিপোর্টিংয়ের মতো একই প্যাটার্নে বিজয়ী প্রাসঙ্গিক বিজ্ঞাপনে reportWin() কল করে। প্রতিটি প্রাসঙ্গিক বিজ্ঞাপনের জন্য একজন ক্রেতা, একটি বিড, রিপোর্টিং লজিকের একটি লিঙ্ক, একটি রেন্ডার URL এবং বিজ্ঞাপন মেটাডেটা প্রয়োজন।

অ্যাপে প্রাসঙ্গিক বিজ্ঞাপন স্থাপন করতে, লক্ষ্য অ্যাপটিকে একটি ContextualAds অবজেক্ট তৈরি করতে হবে:

কোটলিন 

val contextualAds: ContextualAds =
  Builder().setBuyer(AdTechIdentifier.fromString(mBiddingLogicUri.getHost()))
    //Pass in your valid app install ads
    .setDecisionLogicUri(mContextualLogicUri)
    .setAdsWithBid(appInstallAd)
    .build()

জাভা 

ContextualAds contextualAds = new ContextualAds.Builder()
  .setBuyer(AdTechIdentifier.fromString(mBiddingLogicUri.getHost()))
  .setDecisionLogicUri(mContextualLogicUri)
  //Pass in your valid app install ads
  .setAdsWithBid(appInstallAd)
  .build();

আপনার AdSelectionConfig তৈরি করার সময় ContextualAds অবজেক্টটি পাস করা যেতে পারে:

কোটলিন 

// Create a new ad
val noFilterAd: AdData = Builder()
  .setMetadata(JSONObject().toString())
  .setRenderUri(Uri.parse(baseUri + NO_FILTER_RENDER_SUFFIX))
  .build()
val noFilterAdWithBid = AdWithBid(noFilterAd, NO_FILTER_BID)
contextualAds.getAdsWithBid().add(noFilterAdWithBid)

জাভা 

// Create a new ad
AdData noFilterAd = new AdData.Builder()
  .setMetadata(new JSONObject().toString())
  .setRenderUri(Uri.parse(baseUri + NO_FILTER_RENDER_SUFFIX))
  .build();
AdWithBid noFilterAdWithBid = new AdWithBid(noFilterAd, NO_FILTER_BID);
contextualAds.getAdsWithBid().add(noFilterAdWithBid);

অ্যাপ ইনস্টল বিজ্ঞাপন ফিল্টারিং

অ্যাপ ইনস্টল বিজ্ঞাপন ফিল্টারিং আপনাকে ডিভাইসে ইতিমধ্যেই ইনস্টল করা অ্যাপগুলির জন্য ইনস্টলেশন বিজ্ঞাপন ফিল্টার করতে সাহায্য করে।

এই প্রক্রিয়ার প্রথম ধাপ হল কোন বিজ্ঞাপনদাতারা ইনস্টল করা প্যাকেজে ফিল্টার করার ক্ষমতা রাখে তা নির্ধারণ করা। আপনি যে অ্যাপটিকে বিজ্ঞাপন দিয়ে টার্গেট করতে চান তাতে এটি ঘটতে হবে।

কোটলিন 

//Create a request for setting the app install advertisers
val adtech = AdTechIdentifier.fromString("your.enrolled.uri")
val adtechSet = setOf(adtech)
val request = SetAppInstallAdvertisersRequest(adtechSet)

//Set the app install advertisers in the ad selection manager
mAdSelectionManager.setAppInstallAdvertisers(
  request,
  mExecutor,
  object : OutcomeReceiver<Any?, Exception?>() {
    fun onResult(@NonNull ignoredResult: Any?) {
      Log.v("[your tag]", "Updated app install advertisers")
    }

    fun onError(@NonNull error: Exception?) {
      Log.e("[your tag]", "Failed to update app install advertisers", error)
    }
  })

জাভা 

//Create a request for setting the app install advertisers
AdTechIdentifier adtech = AdTechIdentifier.fromString("your.enrolled.uri");
Set<AdTechIdentifier> adtechSet = Collections.singleton(adtech);
SetAppInstallAdvertisersRequest request = new SetAppInstallAdvertisersRequest(adtechSet);

//Set the app install advertisers in the ad selection manager
mAdSelectionManager.setAppInstallAdvertisers(
  request,
  mExecutor,
  new OutcomeReceiver<Object, Exception>() {
    @Override
    public void onResult(@NonNull Object ignoredResult) {
      Log.v("[your tag]", "Updated app install advertisers");
    }

    @Override
    public void onError(@NonNull Exception error) {
      Log.e("[your tag]", "Failed to update app install advertisers", error);
    }
  });

পূর্ববর্তী কোডটি কার্যকর হলে, পাস করা বিজ্ঞাপনদাতারা তাদের বিড জেনারেশনের সময় আপনার দ্বারা নির্দিষ্ট করা ইনস্টল করা অ্যাপগুলি ফিল্টার করে বের করতে সক্ষম হবেন। যদি আপনার কোনও বিজ্ঞাপনদাতাকে এই অ্যাপের ইনস্টল স্ট্যাটাসে অ্যাক্সেস থেকে সরাতে হয়, তাহলে বিজ্ঞাপনদাতার তথ্য সরিয়ে এই কোডটি আবার চালান।

পরবর্তী ধাপ হল প্রকাশক অ্যাপের ভেতরে বিজ্ঞাপন ফিল্টারিং সেট আপ করা। প্রকাশক অ্যাপের ভেতরে বিজ্ঞাপন পরিবেশনকারী পক্ষ (সম্ভবত সরবরাহ-সাইড SDK হতে পারে) তাদের AdFilters অবজেক্টটি শুরু করতে হবে যেখানে তারা কোন অ্যাপের সাথে সম্পর্কিত বিজ্ঞাপনগুলি ফিল্টার আউট করতে চায় সে সম্পর্কে তথ্য থাকবে:

কোটলিন 

// Instantiate AdFilters object with package names.
val filters: AdFilters = Builder().setAppInstallFilters(
    Builder().setPackageNames(setOf("example.target.app")).build()
  ).build()

জাভা 

// Instantiate AdFilters object with package names.
AdFilters filters = new AdFilters.Builder()
.setAppInstallFilters(
  new AppInstallFilters.Builder()
  .setPackageNames(Collections.singleton("example.target.app"))
  .build())
.build();

চাহিদা-সাইড প্রকাশকরা তাদের কাস্টম দর্শকদের মধ্যে থাকা বিজ্ঞাপনগুলির জন্য একটি AdFilter সেট করতে পারেন।

একটি নতুন AdData অবজেক্ট তৈরি করার সময়ও AdFilters পাস করা যেতে পারে:

কোটলিন 

// Instantiate an AdData object with the AdFilters created in the
// previous example.
val appInstallAd: AdData =
  Builder().setMetadata("{ ... }") // Valid JSON string
    .setRenderUri(Uri.parse("www.example-dsp1.com/.../campaign123.html"))
    .setAdFilters(filters).build()

জাভা 

// Instantiate an AdData object with the AdFilters created in the
// previous example.
AdData appInstallAd = new AdData.Builder()
.setMetadata("{ ... }") // Valid JSON string
.setRenderUri(Uri.parse("www.example-dsp1.com/.../campaign123.html"))
    .setAdFilters(filters)
    .build();

ফ্রিকোয়েন্সি ক্যাপ ফিল্টারিং

ফ্রিকোয়েন্সি ক্যাপ ফিল্টারিং বিজ্ঞাপন প্রযুক্তিবিদদের একটি বিজ্ঞাপন দেখানোর সংখ্যা সীমিত করতে সক্ষম করে। ফ্রিকোয়েন্সি ক্যাপ ফিল্টারিং বিজ্ঞাপনের অতিরিক্ত এক্সপোজার হ্রাস করে এবং একটি নির্দিষ্ট বিজ্ঞাপন প্রচারণার জন্য বিকল্প বিজ্ঞাপন নির্বাচনকে অপ্টিমাইজ করে।

ফ্রিকোয়েন্সি ক্যাপ ফিল্টারের দুটি প্রধান উপাদান রয়েছে: বিজ্ঞাপন ইভেন্টের ধরণ এবং বিজ্ঞাপন কাউন্টার কী। যে ধরণের বিজ্ঞাপন ইভেন্ট ব্যবহার করা যেতে পারে তা হল:

  • Win : একটি Win ইভেন্ট ইঙ্গিত দেয় যে বিজ্ঞাপনটি একটি নিলামে জিতেছে। Win ইভেন্টগুলি Protected Audience API দ্বারা স্বয়ংক্রিয়ভাবে আপডেট হয় এবং ডেভেলপার সরাসরি কল করতে পারে না। Win ডেটা শুধুমাত্র একটি নির্দিষ্ট কাস্টম দর্শকের মধ্যে থাকা বিজ্ঞাপনগুলিতে দৃশ্যমান।
  • ইমপ্রেশন : reportImpression থেকে আলাদা, একজন অন-ডিভাইস কলার (SSP বা MMP) updateAdCounterHistogram() ব্যবহার করে কোডের নির্দিষ্ট বিন্দুতে ইমপ্রেশন ইভেন্ট আহ্বান করে। ইমপ্রেশন ইভেন্টগুলি একটি নির্দিষ্ট DSP-এর সমস্ত বিজ্ঞাপনে দৃশ্যমান হয় এবং একই কাস্টম দর্শকদের বিজ্ঞাপনের মধ্যে সীমাবদ্ধ থাকে না।
  • View : ইভেন্টটি ডিভাইসের কলার (SSP বা MMP) দ্বারা updateAdCounterHistogram() কল ব্যবহার করে নির্বাচিত কোডের একটি বিন্দুতে আহ্বান করা হয়। View ইভেন্টগুলি একটি নির্দিষ্ট DSP-এর সমস্ত বিজ্ঞাপনে দৃশ্যমান এবং একই কাস্টম অডিয়েন্সের বিজ্ঞাপনগুলিতে সীমাবদ্ধ নয়।
  • Click : ইভেন্টটি ডিভাইসের কলার (SSP বা MMP) দ্বারা updateAdCounterHistogram() কল ব্যবহার করে নির্বাচিত কোডের একটি বিন্দুতে আহ্বান করা হয়। ক্লিক ইভেন্টগুলি একটি নির্দিষ্ট DSP-এর সমস্ত বিজ্ঞাপনে দৃশ্যমান হয় এবং একই কাস্টম অডিয়েন্সের বিজ্ঞাপনগুলিতে সীমাবদ্ধ নয়।

প্রকাশক অ্যাপে, ডিভাইসে উপস্থিতি থাকা একটি SSP বা MMP বিজ্ঞাপন ইভেন্টগুলিকে আহ্বান করে। যখন updateAdCounterHistogram() কল করা হয়, তখন একটি ফ্রিকোয়েন্সি ক্যাপ ফিল্টারের কাউন্টার বৃদ্ধি করা হয় যাতে ভবিষ্যতের নিলামগুলিতে ব্যবহারকারীর একটি নির্দিষ্ট বিজ্ঞাপনের এক্সপোজার সম্পর্কে আপ টু ডেট তথ্য থাকে। বিজ্ঞাপন ইভেন্টের ধরণগুলি সংশ্লিষ্ট ব্যবহারকারীর ক্রিয়াকলাপের সাথে জোর করে আবদ্ধ করা হয় না এবং এটি কলারদের তাদের ইভেন্ট সিস্টেম গঠনে সহায়তা করার জন্য প্রদত্ত নির্দেশিকা। কোনও ইভেন্টের সময় বিজ্ঞাপন কাউন্টার বৃদ্ধি করতে, অন-ডিভাইস অভিনেতা বিজয়ী বিজ্ঞাপন নিলামের বিজ্ঞাপন নির্বাচন আইডি সরবরাহ করে।

বিজ্ঞাপন কাউন্টার কীগুলি ক্রেতা বিজ্ঞাপন প্রযুক্তিবিদ দ্বারা নির্ধারিত 32-বিট স্বাক্ষরিত পূর্ণসংখ্যা, এবং এগুলি DSP দ্বারা সংজ্ঞায়িত বিজ্ঞাপনের একটি নির্দিষ্ট সেটের সাথে সঙ্গতিপূর্ণ। যেহেতু বিজ্ঞাপন কাউন্টার কীগুলি কেবলমাত্র একটি নির্দিষ্ট DSP-এর অন্তর্গত বিজ্ঞাপনগুলির মধ্যে সীমাবদ্ধ, তাই এই কীগুলি অন্য বিজ্ঞাপন প্রযুক্তিবিদদের হিস্টোগ্রামের সাথে ওভারল্যাপ না করেই নির্বাচন করা যেতে পারে। ভবিষ্যতের নিলাম থেকে বিজ্ঞাপনগুলি ফিল্টার করার জন্য DSP-নির্দিষ্ট শনাক্তকারীগুলিকে DSP-নির্দিষ্ট করতে বা একটি নির্দিষ্ট কাস্টম দর্শকদের মধ্যে বৃদ্ধি করতে বিজ্ঞাপন কাউন্টার কীগুলি ব্যবহার করা হয়।

নির্দিষ্ট ক্রেতার বিজ্ঞাপন প্রযুক্তির অন্যান্য বিজ্ঞাপনের সাথে তাদের মিথস্ক্রিয়ার উপর ভিত্তি করে, ব্যবহারকারীর কাছে আকর্ষণীয় বিজ্ঞাপনগুলিকে অগ্রাধিকার দেওয়ার জন্য কাউন্টার কী ব্যবহার করা যেতে পারে। উদাহরণস্বরূপ, যে বিজ্ঞাপনটি বিজ্ঞাপন নিলাম, ভিউ এবং ক্লিক জয়ের মাধ্যমে উচ্চ স্তরের আকর্ষণ অর্জন করেছে, তা একটি অনুমানিত ডেটা পয়েন্ট উপস্থাপন করে। এই বিষয়টি আরও স্পষ্ট করার জন্য: বাম-হাতি গল্ফ ক্লাবগুলির জন্য একটি বিজ্ঞাপন ইঙ্গিত দিতে পারে যে ব্যবহারকারী ডান-হাতি গল্ফ ক্লাবগুলিতে আগ্রহী হবেন না। বাম-হাতি বিজ্ঞাপনগুলিতে নির্ধারিত কাউন্টার কীগুলির জন্য একটি ফ্রিকোয়েন্সি ক্যাপ ফিল্টার সেট ডান-হাতি ক্লাবগুলির বিজ্ঞাপনগুলিকে ফিল্টার করতে পারে।

আপনার নিলামে ফ্রিকোয়েন্সি ক্যাপিং ব্যবহার করতে, আপনাকে প্রথমে KeyedFrequencyCap অবজেক্ট তৈরি করতে হবে:

কোটলিন 

// Value used when incrementing frequency counter
val adCounterKey = 123

// Frequency cap exceeded after 2 counts
val keyedFrequencyCapForImpression: KeyedFrequencyCap = Builder(
  adCounterKey, 2, Duration.ofSeconds(10)
).build()

// Frequency cap exceeded after 1 counts
val keyedFrequencyCapForImpression: KeyedFrequencyCap = Builder(
  adCounterKey, 1, Duration.ofSeconds(10)
).build()

জাভা 

// Value used when incrementing frequency counter
int adCounterKey = 123;

// Frequency cap exceeded after 2 counts
KeyedFrequencyCap keyedFrequencyCapForImpression =
  new KeyedFrequencyCap.Builder(
    adCounterKey, 2, Duration.ofSeconds(10)
  ).build();

// Frequency Cap exceeded after 1 counts
KeyedFrequencyCap keyedFrequencyCapForClick =
  new KeyedFrequencyCap.Builder(
    adCounterKey, 1, Duration.ofSeconds(10)
  ).build();

KeyedFrequencyCap অবজেক্ট তৈরি হয়ে গেলে, আপনি সেগুলিকে একটি AdFilters অবজেক্টে পাস করতে পারেন।

কোটলিন 

val filters: AdFilters = Builder()
  .setFrequencyCapFilters(
    Builder()
      .setKeyedFrequencyCapsForImpressionEvents(
        ImmutableObject.of(keyedFrequencyCapForImpression)
      )
      .setKeyedFrequencyCapsForClickEvents(
        ImmutableObject.of(keyedFrequencyCapForClick)
      )
  ).build()

জাভা 

AdFilters filters = new AdFilters.Builder()
    .setFrequencyCapFilters(new FrequencyCapFilters.Builder()
        .setKeyedFrequencyCapsForImpressionEvents(
            ImmutableObject.of(keyedFrequencyCapForImpression)
        )
        .setKeyedFrequencyCapsForClickEvents(
            ImmutableObject.of(keyedFrequencyCapForClick)
        )
    ).build();

যখন AdFilters অবজেক্টটি ফ্রিকোয়েন্সি ক্যাপ ফিল্টার দিয়ে পূর্ণ করা হয়, তখন কাস্টম অডিয়েন্স তৈরি করার সময় এটি পাস করা যেতে পারে:

কোটলিন 

// Initialize a custom audience.
val audience: CustomAudience = Builder()
  .setBuyer(buyer)
  .setName(name)
  .setAds(
    listOf(
      Builder()
        .setRenderUri(renderUri)
        .setMetadata(JSONObject().toString())
        .setAdFilters(filters)
        .setAdCounterKeys(adCounterKeys)
        .build()
    )
  ).build()

জাভা 

// Initialize a custom audience.
CustomAudience audience = new CustomAudience.Builder()
    .setBuyer(buyer)
    .setName(name)
    .setAds(Collections.singletonList(new AdData.Builder()
        .setRenderUri(renderUri)
        .setMetadata(new JSONObject().toString())
        .setAdFilters(filters)
        .setAdCounterKeys(adCounterKeys)
        .build()))
    .build();

যখন ফ্রিকোয়েন্সি ক্যাপ ফিল্টারগুলি একটি কাস্টম দর্শকদের মধ্যে প্রয়োগ করা হয়, তখন SSP প্রয়োজনীয় ক্লিক, ভিউ বা ইম্প্রেশন ইভেন্টগুলি আহ্বান করতে পারে।

কোটলিন 

val callerAdTech: AdTechIdentifier = mAdSelectionConfig.getSeller()

val request: UpdateAdCounterHistogramRequest = Builder(
  adSelectionId,
  FrequencyCapFilters.AD_EVENT_TYPE_CLICK,  //CLICK, VIEW, or IMPRESSION
  callerAdTech
).build()

জাভা 

AdTechIdentifier callerAdTech = mAdSelectionConfig.getSeller();

UpdateAdCounterHistogramRequest request =
  new UpdateAdCounterHistogramRequest.Builder(
      adSelectionId,
      FrequencyCapFilters.AD_EVENT_TYPE_CLICK, //CLICK, VIEW, or IMPRESSION
      callerAdTech
).build();

যেসব বিজ্ঞাপন পূর্বনির্ধারিত ফ্রিকোয়েন্সি ক্যাপ ফিল্টার সীমা অতিক্রম করেছে, সেগুলি নিলাম থেকে ফিল্টার করা হয়। ডিভাইসে নিলামের জন্য বিডিং লজিক কার্যকর হওয়ার আগে এবং বিডিং এবং নিলাম পরিষেবা নিলামের জন্য পেলোড তৈরি হওয়ার সাথে সাথে ফিল্টারিং করা হয়। এই টুলকিটটি বিজ্ঞাপন প্রযুক্তিবিদদের তাদের কাস্টম দর্শকদের মধ্যে ব্যবহারকারীদের এবং বিজ্ঞাপনের মধ্যে মিথস্ক্রিয়া ব্যবহার করে বিজ্ঞাপন লক্ষ্যবস্তুতে ফোকাস করার নমনীয়তা দেয় এবং বিজ্ঞাপনের অতিরিক্ত এক্সপোজার কমিয়ে দেয়।

নেটওয়ার্ক কল ছাড়াই প্রাসঙ্গিক বিজ্ঞাপন ফিল্টারিং

যদি ডিভাইসে কোনও পুনঃবিপণনের চাহিদা না থাকে, তাহলে আপনি নেটওয়ার্ক কল ছাড়াই প্রাসঙ্গিক বিজ্ঞাপনের জন্য বিজ্ঞাপন নির্বাচন চালাতে পারেন। পূর্বনির্ধারিত URI এবং বিড সহ প্রাসঙ্গিক বিজ্ঞাপনের তালিকা সহ, প্ল্যাটফর্মটি বিডিং লজিক, বিডিং সিগন্যাল এবং স্কোরিং সিগন্যাল পুনরুদ্ধার এড়িয়ে যেতে পারে। সর্বোচ্চ বিড সহ প্রাসঙ্গিক বিজ্ঞাপন নির্বাচন করতে প্ল্যাটফর্মটি একটি পূর্বনির্ধারিত URI ব্যবহার করে।

ল্যাটেন্সি উন্নত করার জন্য, বিজ্ঞাপন প্রযুক্তিবিদরা এমন একটি বিজ্ঞাপন নির্বাচন প্রবাহ চালাতে পারেন যাতে নেটওয়ার্ক কল ছাড়াই বিজ্ঞাপন ফিল্টারিং কার্যকারিতা সহ শুধুমাত্র প্রাসঙ্গিক বিজ্ঞাপন অন্তর্ভুক্ত থাকে। সিগন্যাল স্কোর করার জন্য পূর্বনির্মিত URI ব্যবহার করে এটি অর্জন করা হয়। scoreAds বাস্তবায়নের তালিকার জন্য সমর্থিত পূর্বনির্মিত URI ব্যবহারের কেস এবং নাম বিভাগটি দেখুন।

নেটওয়ার্ক কল ছাড়াই বিজ্ঞাপন নির্বাচন চালানোর জন্য:

  1. বিজ্ঞাপন ফিল্টারিং সেট আপ করুন
  2. আপনার প্রাসঙ্গিক বিজ্ঞাপন তৈরি করুন

  3. নিম্নলিখিতগুলি ব্যবহার করে একটি AdSelectionConfig অবজেক্ট তৈরি করুন:

    1. ক্রেতাদের একটি খালি তালিকা
    2. সর্বোচ্চ দর নির্বাচন করার জন্য একটি পূর্বনির্মিত URI
    3. প্রাসঙ্গিক বিজ্ঞাপন
    4. স্কোরিং সিগন্যালের জন্য একটি খালি URI। খালি URI ইঙ্গিত দেয় যে আপনি স্কোরিংয়ের জন্য বিশ্বস্ত সিগন্যাল আনার পদ্ধতি ব্যবহার করতে চান না: 
    Uri prebuiltURIScoringUri = Uri.parse("ad-selection-prebuilt://ad-selection/highest-bid-wins/?reportingUrl=your.registered.uri/reporting");
// Initialize AdSelectionConfig
AdSelectionConfig adSelectionConfig =
  new AdSelectionConfig.Builder()
    .setSeller(seller)
    .setDecisionLogicUri(prebuiltURIScoringUri)
    .setCustomAudienceBuyers(Collections.emptyList())
    .setAdSelectionSignals(adSelectionSignals)
    .setSellerSignals(sellerSignals)
    .setPerBuyerSignals(perBuyerSignals)
    .setBuyerContextualAds(buyerContextualAds)
    .setTrustedScoringSignalsUri(Uri.EMPTY)
    .build();

  4. বিজ্ঞাপন নির্বাচন চালান: 

    adSelectionManager.selectAds(
    adSelectionConfig,
    executor,
    outcomeReceiver);

পূর্বনির্মিত URI ব্যবহার করার সময় আপনার নিজস্ব রিপোর্টিং জাভাস্ক্রিপ্ট চালান

আজকাল, প্রাইভেসি স্যান্ডবক্স প্ল্যাটফর্মে শুধুমাত্র পূর্বনির্মিত URI-এর জন্য একটি মৌলিক রিপোর্টিং জাভাস্ক্রিপ্ট বাস্তবায়ন উপলব্ধ। যদি আপনি কম ল্যাটেন্সি বিজ্ঞাপন নির্বাচনের জন্য পূর্বনির্মিত URI ব্যবহার করার সময় আপনার নিজস্ব রিপোর্টিং জাভাস্ক্রিপ্ট চালাতে চান, তাহলে আপনি বিজ্ঞাপন নির্বাচন এবং প্রতিবেদন চালানোর মধ্যে DecisionLogicUri ওভাররাইড করতে পারেন।

  1. পূর্বনির্ধারিত URI ব্যবহার করে প্রাসঙ্গিক বিজ্ঞাপনের জন্য বিজ্ঞাপন নির্বাচন চালানোর ধাপগুলি চালান

  2. রিপোর্টিং চালানোর আগে আপনার AdSelectionConfig এর একটি কপি তৈরি করুন। 

    adSelectionConfigWithYourReportingJS = adSelectionConfig.cloneToBuilder()
  // Replace <urlToFetchYourReportingJS> with your own URL:
  .setDecisionLogicUri(Uri.parse(<urlToFetchYourReportingJS>))
  .build();

  3. ইম্প্রেশন রিপোর্টিং চালান 

    // adSelectionId is from the result of the previous selectAds run
ReportImpressionRequest request = new ReportImpressionRequest(
  adSelectionId,
  adSelectionConfigWithYourReportingJS);
adSelectionManager.reportImpression(
  request,
  executor,
  outcomeReceiver);

ওয়াটারফল মেডিটেশন চালান

ওয়াটারফল মেডিয়েশনের জন্য একাধিক থার্ড-পার্টি SDK (3P নেটওয়ার্ক) একটি ফার্স্ট-পার্টি SDK মেডিয়েশন নেটওয়ার্ক দ্বারা পরিচালিত হতে হবে। ওয়াটারফল মেডিয়েশন একইভাবে করা হয়, নিলামটি ডিভাইসে করা হোক বা বিডিং ও অকশন সার্ভিসেস (B&A) তে চালানো হোক না কেন।

3P নেটওয়ার্ক

3P নেটওয়ার্কগুলিকে এমন একটি অ্যাডাপ্টার সরবরাহ করতে হবে যা মধ্যস্থতা নেটওয়ার্ককে নিলাম পরিচালনার জন্য প্রয়োজনীয় পদ্ধতিগুলি ব্যবহার করতে দেয়:

  • বিজ্ঞাপন নির্বাচন চালান
  • ইম্প্রেশন রিপোর্ট করুন

এখানে একটি মধ্যস্থতা নেটওয়ার্ক অ্যাডাপ্টারের একটি উদাহরণ দেওয়া হল:

কোটলিন 

class NetworkAdaptor {
    private val adSelectionManager : AdSelectionManager

    init {
        adSelectionManager = context.getSystemService(AdSelectionManager::class.java)
    }

    fun selectAds() {...}

    fun reportImpressions() {...}
}

জাভা 

class NetworkAdaptor {
    AdSelectionManager adSelectionManager;

    public NetworkAdaptor() {
        AdSelectionManager adSelectionManager =
            context.getSystemService(AdSelectionManager.class);
    }

    public void selectAds() {...}

    public void reportImpressions() {...}
}

প্রতিটি SDK-এর নিজস্ব বিজ্ঞাপন নির্বাচন পরিষেবা পরিচালক এবং ক্লায়েন্ট থাকে, এবং তাদের নিজস্ব selectAds এবং reportImpressions বাস্তবায়নও থাকে। SDK প্রদানকারীরা ডিভাইসে নিলামের জন্য বিজ্ঞাপন নির্বাচন কীভাবে চালাবেন তার বিভাগগুলি অথবা B&A নিলামের জন্য B&A ব্যাখ্যাকারী দেখতে পারেন। বিজ্ঞাপনের ইমপ্রেশন কীভাবে রিপোর্ট করবেন তা অনুসরণ করুন (রিপোর্টিংয়ের জন্য একক SSP ইমপ্রেশন রিপোর্টিং অনুসরণ করে)।

মধ্যস্থতা নেটওয়ার্ক

3P নেটওয়ার্কের মতো, মধ্যস্থতা নেটওয়ার্কগুলির selectAds এবং reportImpression বাস্তবায়ন প্রয়োজন। আরও তথ্যের জন্য বিজ্ঞাপন নির্বাচন কীভাবে চালাবেন এবং বিজ্ঞাপনের ইমপ্রেশন কীভাবে রিপোর্ট করবেন সে সম্পর্কে বিভাগগুলি পড়ুন।

মধ্যস্থতা নেটওয়ার্কগুলি মধ্যস্থতা শৃঙ্খল পরিচালনা এবং নিজেদেরকে মধ্যস্থতা শৃঙ্খলে স্থাপনের জন্য দায়ী। পরবর্তী বিভাগে এই প্রক্রিয়াটি কীভাবে সেট আপ এবং সম্পাদন করতে হয় তা আলোচনা করা হয়েছে।

মধ্যস্থতা চেইন এবং বিড ফ্লোর পুনরুদ্ধার করুন

মধ্যস্থতা নেটওয়ার্ক প্রথম পক্ষের (1P) প্রাসঙ্গিক বিজ্ঞাপন, মধ্যস্থতা শৃঙ্খল এবং তৃতীয় পক্ষের নেটওয়ার্কের বিড ফ্লোর (3P) পুনরুদ্ধারের জন্য দায়ী। এটি মধ্যস্থতা নেটওয়ার্ক দ্বারা সম্পাদিত প্রাসঙ্গিক বিজ্ঞাপন পুনরুদ্ধারের অনুরোধে ঘটতে পারে। মধ্যস্থতা শৃঙ্খল 3P নেটওয়ার্কের মাধ্যমে কীভাবে পুনরাবৃত্তি করা হবে তা নির্ধারণ করে এবং বিড ফ্লোরগুলি নিলাম প্রক্রিয়ায় adSelectionSignals হিসাবে প্রেরণ করা যেতে পারে।

মধ্যস্থতা শৃঙ্খলে নেটওয়ার্ক স্থাপন

একটি মধ্যস্থতা SDK 1P বিজ্ঞাপন বিডের লাইভ eCPM এর উপর ভিত্তি করে মধ্যস্থতা শৃঙ্খলে নিজেকে স্থাপন করতে পারে। Protected Audience API-তে, বিজ্ঞাপন বিডগুলি অস্বচ্ছ। একটি মধ্যস্থতা SDK-এর AdSelectionFromOutcomesConfig ব্যবহার করা উচিত যাতে একটি প্রদত্ত 1P বিজ্ঞাপনের বিডকে চেইনের পরবর্তী 3P নেটওয়ার্কের বিড ফ্লোরের সাথে তুলনা করা যায়। যদি 1P বিড বিড ফ্লোরের চেয়ে বেশি হয় তবে এর অর্থ হল মধ্যস্থতা SDK সেই 3P নেটওয়ার্কের সামনে স্থাপন করা হয়েছে।

বিজ্ঞাপন নির্বাচন চালান

একটি 1P বিজ্ঞাপন প্রার্থী পুনরুদ্ধার করতে, মধ্যস্থতা নেটওয়ার্ক রান বিজ্ঞাপন নির্বাচন বিভাগের ধাপগুলি অনুসরণ করে একটি অন-ডিভাইস নিলাম পরিচালনা করতে পারে। এটি একটি 1P বিজ্ঞাপন প্রার্থী, একটি বিড এবং একটি AdSelectionId তৈরি করে যা মধ্যস্থতা প্রক্রিয়ায় ব্যবহৃত হয়।

একটি AdSelectionFromOutcomesConfig তৈরি করুন

একটি AdSelectionFromOutcomesConfig মধ্যস্থতা নেটওয়ার্ককে AdSelectionIds (পূর্ববর্তী নিলামের ফলাফল), বিজ্ঞাপন নির্বাচন সংকেত এবং একাধিক প্রার্থীর কাছ থেকে একটি বিজ্ঞাপন নির্বাচন করে এমন জাভাস্ক্রিপ্ট আনার জন্য একটি URI এর তালিকা পাস করার অনুমতি দেয়। AdSelectionIds এর তালিকা, তাদের বিড এবং সংকেতগুলি জাভাস্ক্রিপ্টে পাঠানো হয় যা বিড ফ্লোরকে ছাড়িয়ে গেলে AdSelectionIds এর মধ্যে একটি ফেরত দিতে পারে, অথবা যদি মধ্যস্থতা শৃঙ্খলটি অব্যাহত থাকে তবে কোনও ফেরত দিতে পারে না।

মধ্যস্থতা নেটওয়ার্কগুলি পূর্ববর্তী বিভাগ থেকে 1P AdSelectionId ব্যবহার করে একটি AdSelectionFromOutcomesConfig তৈরি করে এবং 3P নেটওয়ার্কের জন্য বিড ফ্লোর বিবেচনা করা হয়। মধ্যস্থতা শৃঙ্খলের প্রতিটি ধাপের জন্য একটি নতুন AdSelectionFromOutcomesConfig তৈরি করা উচিত।

কোটলিন 

fun  runSelectOutcome(
    adSelectionClient : AdSelectionClient,
    outcome1p : AdSelectionOutcome,
    network3p : NetworkAdapter) : ListenableFuture<AdSelectionOutcome?> {
    val config = AdSelectionFromOutcomesConfig.Builder()
        .setSeller(seller)
        .setAdSelectionIds(listOf(outcome1p))
        .setSelectionSignals({"bid_floor": bid_floor})
        .setSelectionLogicUri(selectionLogicUri)
        .build()
    return adSelectionClient.selectAds(config)
}

জাভা 

public ListenableFuture<AdSelectionOutcome> runSelectOutcome(AdSelectionOutcome outcome1p,
                                              NetworkAdapter network3p) {
    AdSelectionFromOutcomesConfig config = new AdSelectionFromOutcomesConfig.Builder()
            .setSeller(seller)
            .setAdSelectionIds(Collection.singletonList(outcome1p))
            .setSelectionSignals({"bid_floor": bid_floor})
            .setSelectionLogicUri(selectionLogicUri)
            .build();

    return adSelectionClient.selectAds(config){}
}

ওয়াটারফল মেডিয়েশনের জন্য selectAds() পদ্ধতি ওভাররাইডের জন্য একটি AdSelectionFromOutcomesConfig ইনপুট প্রয়োজন, যেখানে আপনাকে নিম্নলিখিত প্রয়োজনীয় প্যারামিটারগুলি নির্দিষ্ট করতে হবে:

  • বিক্রেতা : বিজ্ঞাপন নির্বাচন শুরু করা বিক্রেতা বিজ্ঞাপন নেটওয়ার্কের জন্য শনাক্তকারী।
  • AdSelectionIds : একটি 1P বিজ্ঞাপনের জন্য পূর্ববর্তী selectAds() এর একটি সিঙ্গেলটন তালিকা।
  • বিজ্ঞাপন নির্বাচন সংকেত : একটি JSON অবজেক্ট, যা স্ট্রিং হিসেবে সিরিয়ালাইজ করা হয়েছে, যাতে ক্রেতা বিডিং লজিক দ্বারা ব্যবহারের জন্য সংকেত থাকে। এই ক্ষেত্রে, প্রদত্ত 3P নেটওয়ার্কের জন্য পুনরুদ্ধার করা বিড ফ্লোর অন্তর্ভুক্ত করুন।
  • সিলেকশন লজিক ইউআরআই : একটি বিজয়ী বিজ্ঞাপন নির্বাচনের জন্য মধ্যস্থতা নেটওয়ার্কের জাভাস্ক্রিপ্ট আনতে বিজ্ঞাপন নির্বাচনের সময় একটি HTTPS URL জিজ্ঞাসা করা হয়েছিল। এই জাভাস্ক্রিপ্টে প্রয়োজনীয় ফাংশন স্বাক্ষরগুলি দেখুন। যদি বিড বিড ফ্লোরের চেয়ে বেশি হয় তবে জাভাস্ক্রিপ্ট 3P বিজ্ঞাপনটি ফেরত দেবে, অথবা অন্যথায় null ফেরত দেবে। এটি মধ্যস্থতা SDK কে বিজয়ী খুঁজে পেলে মধ্যস্থতা শৃঙ্খলটি কেটে ফেলার অনুমতি দেয়।

AdSelectionOutcomesConfig তৈরি করার পর, চেইনের প্রথমে থাকা 3P নেটওয়ার্কের selectAds() পদ্ধতিটি কল করুন।

কোটলিন 

val adSelectionManager = context.getSystemService(AdSelectionManager::class.java)

// Initialize AdSelectionFromOutcomesConfig
AdSelectionFromOutcomesConfig adSelectionFromOutcomesConfig =
  AdSelectionFromOutcomesConfig.Builder()
    .setSeller(seller)
    .setAdSelectionIds(listof(outcome1p))
    .setSelectionSignals({"bid_floor": bid_floor})
    .setSelectionLogicUri(selectionLogicUri)
    .setAdSelectionIds(outcomeIds)
    .build()

// Run ad selection with AdSelectionConfig
adSelectionManager.selectAds(
    adSelectionFromOutcomesConfig,
    executor,
    outcomeReceiver)

জাভা 

AdSelectionManager adSelectionManager =
    context.getSystemService(AdSelectionManager.class);

// Initialize AdSelectionFromOutcomesConfig
AdSelectionFromOutcomesConfig adSelectionFromOutcomesConfig =
        new AdSelectionFromOutcomesConfig.Builder()
            .setSeller(seller)
            .setAdSelectionIds(Collection.singletonList(outcome1p))
            .setSelectionSignals({"bid_floor": bid_floor})
            .setSelectionLogicUri(selectionLogicUri)
            .setAdSelectionIds(outcomeIds)
            .build();

// Run ad selection with AdSelectionConfig
adSelectionManager.selectAds(
    adSelectionFromOutcomesConfig,
    executor,
    outcomeReceiver);

জলপ্রপাতের মধ্যস্থতা অর্কেস্ট্রেট করুন

মধ্যস্থতা প্রক্রিয়াটি পরিচালনার জন্য কার্যপদ্ধতির ক্রম নিম্নরূপ।

  1. 1P বিজ্ঞাপন নির্বাচন চালান।
  2. মধ্যস্থতা শৃঙ্খলে পুনরাবৃত্তি করুন। প্রতিটি 3P নেটওয়ার্কের জন্য, নিম্নলিখিতগুলি করুন:
    1. 1P outcomeId এবং 3P SDK এর বিড ফ্লোর সহ AdSelectionFromOutcomeConfig তৈরি করুন।
    2. আগের ধাপের কনফিগারেশন ব্যবহার করে selectAds() কল করুন।
    3. যদি ফলাফল খালি না থাকে, তাহলে বিজ্ঞাপনটি ফেরত দিন।
    4. বর্তমান SDK নেটওয়ার্ক অ্যাডাপ্টারের selectAds() পদ্ধতিতে কল করুন। যদি ফলাফল খালি না থাকে, তাহলে বিজ্ঞাপনটি ফেরত দিন।
  3. যদি চেইন থেকে কোনও বিজয়ী না পাওয়া যায়, তাহলে 1P বিজ্ঞাপনটি ফেরত দিন।

কোটলিন 

fun runWaterfallMediation(mediationChain : List<NetworkAdapter>)
  : Pair<AdSelectionOutcome, NetworkAdapter> {
    val outcome1p = runAdSelection()

    var outcome : AdSelectionOutcome
    for(network3p in mediationChain) {
      outcome = runSelectOutcome(outcome1p, network3p)
      if (outcome1p.hasOutcome() && outcome.hasOutcome()) {
          return Pair(outcome, this)
      }

      outcome = network3p.runAdSelection()
      if(outcome.hasOutcome()) {
          return Pair(outcome, network3p)
      }
    }
  return Pair(outcome1p, this)
}

জাভা 

class MediationNetwork {
    AdSelectionManager adSelectionManager;

    public MediationNetwork() {
        AdSelectionManager adSelectionManager =
            context.getSystemService(AdSelectionManager.class);
    }

    public void runAdSelection() {...}

    public void reportImpressions() {...}

    public Pair<AdSelectionOutcome, NetworkAdapter> runWaterfallMediation(
            List<NetworkAdapter> mediationChain) {
        AdSelectionOutcome outcome1p = runAdSelection();

        AdSelectionOutcome outcome;
        for(NetworkAdapter network3p: mediationChain) {
            if (outcome1p.hasOutcome() &&
              (outcome = runSelectOutcome(outcome1p, network3p)).hasOutcome()) {
                return new Pair<>(outcome, this);
            }

            if((outcome = network3p.runAdSelection()).hasOutcome()) {
                return new Pair<>(outcome, network3p);
            }
        }
        return new Pair<>(outcome1p, this);
    }

    /* Runs comparison by creating an AdSelectionFromOutcomesConfig */
    public AdSelectionOutcome runSelectOutcome(AdSelectionOutcome outcome1p,
                                              NetworkAdapter network3p) { ... }
}

বিজ্ঞাপনের ছাপ রিপোর্ট করুন

নিলাম কীভাবে পরিচালিত হয় তার উপর নির্ভর করে বিজ্ঞাপনের ছাপ রিপোর্ট করার জন্য দুটি প্রবাহ রয়েছে। আপনি যদি নিলাম পরিচালনাকারী একক SSP হন, তাহলে এই বিভাগটি অনুসরণ করুন। আপনি যদি জলপ্রপাত মধ্যস্থতা বাস্তবায়ন করতে যাচ্ছেন, তাহলে জলপ্রপাত মধ্যস্থতা ছাপ রিপোর্টিং বিভাগে পাওয়া পদক্ষেপগুলি অনুসরণ করুন।

একক এসএসপি ইম্প্রেশন রিপোর্টিং

বিজ্ঞাপন নির্বাচনের কর্মপ্রবাহ থেকে একটি বিজয়ী বিজ্ঞাপন নির্বাচিত হওয়ার পরে, আপনি AdSelectionManager.reportImpression() পদ্ধতি ব্যবহার করে অংশগ্রহণকারী বাই-সাইড এবং সেল-সাইড প্ল্যাটফর্মগুলিতে ইম্প্রেশনটি রিপোর্ট করতে পারেন। একটি বিজ্ঞাপন ইম্প্রেশন রিপোর্ট করতে:

  1. একটি AdSelectionManager অবজেক্ট আরম্ভ করুন।
  2. বিজ্ঞাপন নির্বাচন আইডি দিয়ে একটি ReportImpressionRequest অবজেক্ট তৈরি করুন।
  3. ReportImpressionRequest অবজেক্ট এবং প্রাসঙ্গিক Executor এবং OutcomeReceiver অবজেক্ট ব্যবহার করে অ্যাসিঙ্ক্রোনাস reportImpression() পদ্ধতিটি কল করুন।

জাভা 

AdSelectionManager adSelectionManager =
    context.getSystemService(AdSelectionManager.class);

// Initialize a ReportImpressionRequest
ReportImpressionRequest reportImpressionRequest =
        new ReportImpressionRequest.Builder()
                .setAdSelectionId(adSelectionId)
                .setAdSelectionConfig(adSelectionConfig)
                .build();

// Request to report the impression with the ReportImpressionRequest
adSelectionManager.reportImpression(
    reportImpressionRequest,
    executor,
    outcomeReceiver);

কোটলিন 

val adSelectionManager = context.getSystemService(AdSelectionManager::class.java)

// Initialize a ReportImpressionRequest
val adSelectionConfig: ReportImpressionRequest =
    ReportImpressionRequest.Builder()
        .setAdSelectionId(adSelectionId)
        .setAdSelectionConfig(adSelectionConfig)
        .build()

// Request to report the impression with the ReportImpressionRequest
adSelectionManager.reportImpression(
    reportImpressionRequest,
    executor,
    outcomeReceiver)

নিম্নলিখিত প্রয়োজনীয় প্যারামিটারগুলি দিয়ে ReportImpressionRequest শুরু করুন:

  • বিজ্ঞাপন নির্বাচন আইডি : শুধুমাত্র একজন ডিভাইস ব্যবহারকারীর জন্য অনন্য একটি আইডি যা একটি সফল বিজ্ঞাপন নির্বাচন সনাক্ত করে।
  • বিজ্ঞাপন নির্বাচন কনফিগারেশন : প্রদত্ত বিজ্ঞাপন নির্বাচন আইডি দ্বারা চিহ্নিত selectAds() কলে ব্যবহৃত একই কনফিগারেশন।

অ্যাসিঙ্ক্রোনাস reportImpression() পদ্ধতিটি API কলের ফলাফল সিগন্যাল করার জন্য OutcomeReceiver অবজেক্ট ব্যবহার করে।

  • onResult() কলব্যাক ইঙ্গিত করে যে ইম্প্রেশন রিপোর্টিং URL তৈরি করা হয়েছে কিনা এবং অনুরোধটি নির্ধারিত হয়েছে কিনা।
  • onError() কলব্যাক নিম্নলিখিত সম্ভাব্য শর্তগুলি নির্দেশ করে:
    • যদি কলটি একটি অবৈধ ইনপুট আর্গুমেন্ট দিয়ে শুরু করা হয়, তাহলে AdServicesException একটি IllegalArgumentException কারণ হিসেবে নির্দেশ করে।
    • অন্য সকল ত্রুটির জন্য একটি AdServicesException পাওয়া যায় যার কারণ হিসেবে একটি IllegalStateException থাকে।

জলপ্রপাত মধ্যস্থতা ছাপ রিপোর্টিং

একটি মধ্যস্থতা SDK-কে তাদের রিপোর্টিং ফ্লো ট্রিগার করার জন্য বিজয়ী SDK-এর উপর নজর রাখতে হবে। একটি মধ্যস্থতা শৃঙ্খলে অংশগ্রহণকারী SDK-গুলিকে মধ্যস্থতাকারীকে তাদের নিজস্ব রিপোর্টিং ফ্লো ট্রিগার করার জন্য একটি পদ্ধতি প্রদান করতে হবে। মধ্যস্থতা নিলামে অংশগ্রহণকারী একটি SDK তাদের নিজস্ব রিপোর্টিং বাস্তবায়নের জন্য উপরের পদক্ষেপগুলি অনুসরণ করতে পারে।

SSP গুলি মধ্যস্থতা প্রবাহে যোগদানের জন্য একটি প্রোটোটাইপ হিসাবে এই 3P SDK কোড উদাহরণটি ব্যবহার করতে পারে: 

Pair<AdSelectionOutcome, NetworkAdapter> winnerOutcomeAndNetwork =
         mediationSdk.orchestrateMediation(mediationChain);

if (winner.first.hasOutcome()) {
      winner.second.reportImpressions(winner.first.getAdSelectionId());

ইমপ্রেশন রিপোর্টিং এন্ডপয়েন্ট

রিপোর্ট ইম্প্রেশন API বিক্রয়-সাইড প্ল্যাটফর্ম এবং বিজয়ী বাই-সাইড প্ল্যাটফর্ম দ্বারা প্রদত্ত এন্ডপয়েন্টগুলিতে HTTPS GET অনুরোধগুলি ইস্যু করে:

বাই-সাইড প্ল্যাটফর্মের শেষ বিন্দু:

  • API কাস্টম অডিয়েন্সে নির্দিষ্ট করা বিডিং লজিক URL ব্যবহার করে ক্রেতার প্রদত্ত জাভাস্ক্রিপ্ট আনে, যাতে ইম্প্রেশন রিপোর্টিং URL ফেরত দেওয়ার জন্য লজিক অন্তর্ভুক্ত থাকে।
  • reportWin() জাভাস্ক্রিপ্ট ফাংশনটি ব্যবহার করুন, যা ক্রেতার ইম্প্রেশন রিপোর্টিং URL ফেরত দেবে বলে আশা করা হচ্ছে।

বিক্রয়-সাইড প্ল্যাটফর্মের শেষ বিন্দু:

  • বিক্রেতার ডিসিশন লজিক জাভাস্ক্রিপ্ট আনতে AdSelectionConfig অবজেক্টে উল্লেখিত ডিসিশন লজিক URL ব্যবহার করুন।
  • reportResult() জাভাস্ক্রিপ্ট ফাংশনটি ব্যবহার করুন, যা বিক্রেতার ইম্প্রেশন রিপোর্টিং URL ফেরত দেবে বলে আশা করা হচ্ছে।

বিডিং এবং নিলাম পরিষেবা রিপোর্টিং

বিডিং এবং নিলাম পরিষেবাগুলিতে সম্পাদিত একটি নিলামে সার্ভার-সাইড নিলাম থেকে এনক্রিপ্ট করা প্রতিক্রিয়ায় বিজ্ঞাপন ইন্টারঅ্যাকশন রিপোর্টিংয়ের জন্য তৈরি URL সহ সমস্ত প্রয়োজনীয় প্রতিবেদন তথ্য থাকবে। প্রতিক্রিয়াটি ডিক্রিপ্ট করা হলে, উপযুক্ত URLগুলি প্ল্যাটফর্মে নিবন্ধিত হয়, তাই বিজ্ঞাপন এবং ছাপ প্রতিবেদন একই পদক্ষেপ অনুসরণ করে।

সেরা প্রচেষ্টা ইমপ্রেশন রিপোর্টিং

reportImpression() পদ্ধতিটি রিপোর্টিংকে সর্বোত্তম প্রচেষ্টায় সম্পন্ন করার জন্য ডিজাইন করা হয়েছে।

বিজ্ঞাপন ইন্টারঅ্যাকশন রিপোর্ট করুন

প্রোটেক্টেড অডিয়েন্স একটি রেন্ডার করা বিজ্ঞাপনের জন্য আরও সুক্ষ্ম ইন্টারঅ্যাকশন রিপোর্ট করার জন্য সহায়তা প্রদান করে। এর মধ্যে দেখার সময়, ক্লিক, হোভার, অথবা সংগ্রহ করা যেতে পারে এমন অন্য কোনও দরকারী মেট্রিকের মতো ইন্টারঅ্যাকশন অন্তর্ভুক্ত থাকতে পারে। এই রিপোর্টগুলি পাওয়ার প্রক্রিয়াটির দুটি ধাপ প্রয়োজন। প্রথমত, ক্রেতা এবং বিক্রেতাদের তাদের রিপোর্টিং জাভাস্ক্রিপ্টে এই রিপোর্টগুলি পাওয়ার জন্য নিবন্ধন করতে হবে। তারপর, ক্লায়েন্টকে এই ইভেন্টগুলি রিপোর্ট করতে হবে।

ইন্টারঅ্যাকশন ইভেন্টগুলি গ্রহণের জন্য নিবন্ধন করা হচ্ছে

ইন্টারঅ্যাকশন ইভেন্টের জন্য নিবন্ধন করা হয় ক্রেতার reportWin() এবং বিক্রেতার reportResult() জাভাস্ক্রিপ্ট ফাংশনে প্ল্যাটফর্ম দ্বারা প্রদত্ত একটি জাভাস্ক্রিপ্ট ফাংশন ব্যবহার করে: registerAdBeacon । ইভেন্ট রিপোর্ট পেতে নিবন্ধন করতে, আপনার রিপোর্টিং জাভাস্ক্রিপ্ট থেকে প্ল্যাটফর্ম JavaScript ফাংশনে কল করুন। নিম্নলিখিত স্নিপেটটি একজন ক্রেতার reportWin() ব্যবহার করছে, তবে একই পদ্ধতি reportResult() এর ক্ষেত্রে প্রযোজ্য। 

reportWin(
  adSelectionSignals,
  perBuyerSignals,
  signalsForBuyer,
  contextualSignals,
  customAudienceSignals) {
    ...
    // Calculate reportingUri, clickUri, viewUri, and hoverUri

    registerAdBeacon({"click": clickUri, "view": viewUri, "hover": hoverUri});

    return reportingUri;
}

মিথস্ক্রিয়া ইভেন্ট রিপোর্ট করা

একটি ইম্প্রেশন রিপোর্ট করার পর, ক্লায়েন্টরা AdSelectionManager.reportInteraction() পদ্ধতি ব্যবহার করে পূর্বে নিবন্ধিত বিজয়ী বাই-সাইড এবং সেল-সাইড প্ল্যাটফর্মগুলিতে ইন্টারঅ্যাকশনগুলি রিপোর্ট করতে পারেন। একটি বিজ্ঞাপন ইভেন্ট রিপোর্ট করতে:

  1. একটি AdSelectionManager অবজেক্ট আরম্ভ করুন।
  2. বিজ্ঞাপন নির্বাচন আইডি, ইন্টারঅ্যাকশন কী, ইন্টারঅ্যাকশন ডেটা এবং রিপোর্টিং গন্তব্য ব্যবহার করে একটি ReportInteractionRequest অবজেক্ট তৈরি করুন।
  3. request অবজেক্ট এবং প্রাসঙ্গিক Executor এবং OutcomeReceiver অবজেক্টের সাথে অ্যাসিঙ্ক্রোনাস reportInteraction() পদ্ধতিটি কল করুন। 
AdSelectionManager adSelectionManager =
    context.getSystemService(AdSelectionManager.class);

// Initialize a ReportInteractionRequest
ReportInteractionRequest request =
  new ReportInteractionRequest.Builder()
    .setAdSelectionId(adSelectionId)
    .setInteractionKey("view")
    .setInteractionData("{ viewTimeInSeconds : 1 }") // Can be any string
    .setReportingDestinations(
      FLAG_REPORTING_DESTINATION_BUYER | FLAG_REPORTING_DESTINATION_SELLER
    )
    .build();

// Request to report the impression with the ReportImpressionRequest
adSelectionManager.reportInteraction(
  reportImpressionRequest,
  executor,
  outcomeReceiver);

নিম্নলিখিত প্রয়োজনীয় প্যারামিটারগুলি দিয়ে ReportInteractionRequest শুরু করুন:

  • বিজ্ঞাপন নির্বাচন আইডি : পূর্বে ফেরত দেওয়া AdSelectionOutcome থেকে পুনরুদ্ধার করা একটি বিজ্ঞাপন নির্বাচন আইডি।
  • ইন্টারঅ্যাকশন কী : ক্লায়েন্ট দ্বারা সংজ্ঞায়িত একটি স্ট্রিং কী যা রিপোর্ট করা হচ্ছে এমন ক্রিয়া বর্ণনা করে। এটি অবশ্যই রিপোর্টিং জাভাস্ক্রিপ্ট ফাংশনে বিক্রেতা বা ক্রেতা দ্বারা নিবন্ধিত কীটির সাথে মিলবে।
  • ইন্টারঅ্যাকশন ডেটা : ইভেন্ট রিপোর্টের সাথে অন্তর্ভুক্ত করার জন্য ডেটা সম্বলিত একটি স্ট্রিং, যা রিপোর্টিং সার্ভারে পোস্ট করা হবে।
  • গন্তব্যস্থল রিপোর্টিং : একটি বিট মাস্ক যা নির্দিষ্ট করে যে ইভেন্টগুলি ক্রেতা, বিক্রেতা, নাকি উভয়কেই রিপোর্ট করা উচিত। এই পতাকাগুলি প্ল্যাটফর্ম দ্বারা সরবরাহ করা হয় এবং বিটওয়াইজ অপারেশন ব্যবহার করে চূড়ান্ত গন্তব্যস্থল মাস্ক তৈরি করা যেতে পারে। একটি গন্তব্যস্থলে রিপোর্ট করার জন্য, আপনি সরাসরি প্ল্যাটফর্ম দ্বারা সরবরাহিত পতাকা ব্যবহার করতে পারেন। একাধিক গন্তব্যস্থলে রিপোর্ট করার জন্য, আপনি পতাকার মান একত্রিত করতে বিটওয়াইজ OR ( | ) ব্যবহার করতে পারেন।

অ্যাসিঙ্ক্রোনাস reportInteraction() পদ্ধতিটি API কলের ফলাফল সিগন্যাল করার জন্য OutcomeReceiver অবজেক্ট ব্যবহার করে।

  • onResult() কলব্যাক নির্দেশ করে যে রিপোর্ট ইন্টারঅ্যাকশন কলটি বৈধ।
  • onError() কলব্যাক নিম্নলিখিত সম্ভাব্য শর্তগুলি নির্দেশ করে:
    • যদি অ্যাপটি ব্যাকগ্রাউন্ডে চলাকালীন কল করা হয়, তাহলে ব্যর্থতার বিবরণ সহ একটি IllegalStateException ফেরত পাঠানো হবে।
    • যদি ক্লায়েন্টকে reportInteraction() কল করা থেকে বিরত রাখা হয়, তাহলে একটি LimitExceededException ফেরত পাঠানো হয়।
    • যদি প্যাকেজটি গোপনীয়তা সংরক্ষণকারী API গুলিকে কল করার জন্য নথিভুক্ত না করা হয়, তাহলে একটি SecurityException() ফেরত পাঠানো হয়।
    • যদি অ্যাপ রিপোর্টিং ইন্টারঅ্যাকশন selectAds() নামক অ্যাপ থেকে আলাদা হয়, তাহলে একটি IllegalStateException ফেরত পাঠানো হয়।
  • ব্যবহারকারী যদি প্রাইভেসি স্যান্ডবক্স API সক্রিয় করতে সম্মতি না দেন, তাহলে কলটি নীরবে ব্যর্থ হবে।

ইন্টারঅ্যাকশন রিপোর্টিং এন্ডপয়েন্ট

The report interaction API issues HTTPS POST requests to endpoints provided by the sell-side platform and the winning buy-side platform. Protected Audience will match the interaction keys with the URIs declared in reporting JavaScript and issue a POST request to each endpoint for each interaction being reported. The Content-Type of the request is plain text with the body being the Interaction Data.

Best effort Interaction reporting

The reportInteraction() is designed to offer a best-effort completion of reporting through HTTP POST.

Daily background update

When creating a custom audience, your app or SDK can initialize custom audience metadata. Additionally, the platform can update the following pieces of custom audience metadata with a daily background update process.

  • User bidding signals
  • Trusted bidding data
  • AdData list

This process queries against the Daily update URL defined in the custom audience and the URL may return a JSON response.

  • The JSON response may contain any of the supported metadata fields that needs to be updated.
  • Each JSON field is validated independently. The client ignores any malformed fields which results in no updates to that particular field in the response.
  • An empty HTTP response or an empty JSON object " {} " results in no metadata updates.
  • The response message size must be limited to 10 KB.
  • All URIs are required to use HTTPS.
  • trusted_bidding_uri must share the same ETLD+1 as the buyer.

Example: JSON response for background daily update 

{
    "user_bidding_signals" : { ... },  // Valid JSON object
    "trusted_bidding_data" : {
        "trusted_bidding_uri" : 'example-dsp1-key-value-service.com',
        "trusted_bidding_keys" : [ 'campaign123', 'campaign456', ... ]
    },
    'ads' : [
        {
            "render_uri" : 'www.example-dsp1.com/.../campaign123.html',
            'metadata' : { ... }  // Valid JSON object
        },
        {
            "render_uri" : 'www.example-dsp1.com/.../campaign456.html',
            'metadata' : { ... }  // Valid JSON object
        },
        ...
    ]
}

JavaScript for ad selection

The ad selection workflow orchestrates the execution of buyer-provided and seller-provided JavaScript.

Buyer-provided JavaScript is fetched from the Bidding logic URL specified in the custom audience. The returned JavaScript should include the following functions:

Seller-provided JavaScript is fetched from the decision logic URL specified in the AdSelectionConfig parameter for the ad selection API. The returned JavaScript should include the following functions:

generateBid() 

function generateBid(
  ad,
  auction_signals,
  per_buyer_signals,
  trusted_bidding_signals,
  contextual_signals,
  user_signals,
  custom_audience_bidding_signals) {
  return {'status': 0, 'ad': ad, 'bid': ad.metadata.result };
}

Input parameters:

  • ad : a JSON object with the format var ad = { 'render_url': url, 'metadata': json_metadata };
  • auction_signals, per_buyer_signals : JSON objects specified in the auction configuration object

  • custom_audience_bidding_signals : JSON object generated by the platform. The format for this JSON object is: 

    var custom_audience_signals = {
  "owner":"ca_owner",
  "buyer":"ca_buyer",
  "name":"ca_name",
  "activation_time":"ca_activation_time_epoch_ms",
  "expiration_time":"ca_expiration_time_epoch_ms",
  "user_bidding_signals":"ca_user_bidding_signals"
}

    where:

    • owner , buyer , and name are string taken from the properties with the same name of the Custom Audience participating to the ad selection
    • activation_time and expiration_time are the time of activation and expiration of the custom audience, expressed as seconds since the Unix epoch
    • ca_user_bidding_signals is a JSON string specified in the userBiddingSignals field of the CustomAudience at creation time
    • trusted_bidding_signals, contextual_signals , and user_signals are JSON objects. They are passed as empty objects and will be filled up in future releases. Their format is not enforced by the platform and is managed by the ad tech.

Result:

  • ad : is the ad the bid refers to. The script is allowed to return a copy of the ad it received with different metadata. The render_url property of the ad is expected to be unaltered.
  • bid : a float value representing the bid value for this ad
  • status : an integer value that can be:
    • 0 : for a successful execution
    • 1 : (or any non-zero value) in case any of the input signals is invalid. In case a non-zero value is returned by generate-bid the bidding process is invalidated for all the CA ads

scoreAd() 

function scoreAd(
  ad,
  bid,
  ad_selection_config,
  seller_signals,
  trusted_scoring_signals,
  contextual_signal,
  user_signal,
  custom_audience_signal) {
    return {'status': 0, 'score': score };
}

Input parameters:

  • ad : see the generateBid documentation
  • bid : the bid value for the ad

  • ad_selection_config : a JSON object representing the AdSelectionConfig parameter of the selectAds API. The format is: 

    var ad_selection_config = {
  'seller': 'seller',
  'decision_logic_url': 'url_of_decision_logic',
  'custom_audience_buyers': ['buyer1', 'buyer2'],
  'auction_signals': auction_signals,
  'per_buyer_signals': per_buyer_signals,
  'contextual_ads': [ad1, ad2]
}

  • seller_signals : JSON objects read from the sellerSignals AdSelectionConfig API parameter

  • trusted_scoring_signal : read from the adSelectionSignals field in the AdSelectionConfig API parameter

  • contextual_signals, user_signals : JSON objects. They are passed as empty objects and will be filled up in future releases. Their format is not enforced by the platform and is managed by the ad tech.

  • per_buyer_signals : JSON object read from the perBuyerSignal map in the AdSelectionConfig API parameter using as key the current Custom Audience buyer. Empty if the map doesn't contain any entry for the given buyer.

আউটপুট:

  • score : a float value representing the score value for this ad
  • status : an integer value that can be:
    • 0: for a successful execution
    • 1: in case the customAudienceSignals are invalid
    • 2: in case the AdSelectionConfig is invalid
    • 3: in case any of the other signals is invalid
    • Any non-zero value causes the failure of the process, the value determines the type of exception thrown

selectOutcome() 

function selectOutcome(
  outcomes,
  selection_signals) {
    return {'status': 0, 'result': null};
}

Input parameters:

  • outcomes : a JSON object {"id": id_string, "bid": bid_double}
  • selection_signals : JSON objects specified in the auction configuration object

আউটপুট:

  • status : 0 for success, non-zero for failure
  • result : one of the outcomes passed in or null

reportResult() 

function reportResult(ad_selection_config, render_url, bid, contextual_signals) {
   return {
      'status': status,
      'results': {'signals_for_buyer': signals_for_buyer, 'reporting_url': reporting_url }
   };
}

Input parameters:

  • ad_selection_config : see the documentation of scoreAds
  • render_url : the render URL of the winning ad
  • bid : the bid offered for the winning ad
  • contextual_signals : see the documentation of generateBid

আউটপুট:

  • status: 0 for success and non-zero for failure
  • results : a JSON objects containing:
    • signals_for_buyer : a JSON object that is passed to the reportWin function
    • reporting_url : a URL that is used by the platform to notify the impression to the buyer

reportWin() 

function reportWin(
   ad_selection_signals,
   per_buyer_signals,
   signals_for_buyer,
   contextual_signals,
   custom_audience_signals) {
   return {'status': 0, 'results': {'reporting_url': reporting_url } };
}

Input parameters:

  • ad_selection_signals, per_buyer_signals : see the documentation for scoreAd
  • signals_for_buyer : a JSON object returned by reportResult
  • contextual_signals, custom_audience_signals : see the documentation for generateBid

আউটপুট:

  • status: 0 for success and non-zero for failure
  • results : a JSON object containing:
    • reporting_url : a URL that is used by the platform to notify the impression to the seller

registerAdBeacon()

function registerAdBeacon(
  beacons
)

Input Parameters :

  • beacons : An object containing key-value pairs of interaction keys and reporting URIs. The format is: 

    let beacons = {
  'interaction_key': 'reporting_uri',
  'interaction_key': 'reporting_uri',
  ...
}
    • interaction_key : A string representing the event. This is used by the platform later when reporting event interactions to look up the reporting_uri that should be notified. This key needs to match between what the buyer or seller is registering, and what the seller is reporting.
    • reporting_uri : A URI to receive event reports. This should be specific to the event type being reported. It must accept a POST request to handle any data reported along with the event.

    উদাহরণস্বরূপ: 

      let beacons = {
    'click': 'https://reporting.example.com/click_event',
    'view': 'https://reporting.example.com/view_event'
  }

Ad Selection prebuilt URIs

Prebuilt URIs give ad techs the ability to appoint JavaScript functions for ad selection decision logic in the AdSelectionConfig and AdSelectionFromOutcomesConfig classes. Prebuilt URIs don't require network calls to download the corresponding JavaScript. Ad techs can use prebuilt URIs without having to set up an enrolled domain to host the JavaScript.

A prebuilt URI is constructed using the following format: 

ad-selection-prebuilt:<use-case>/<name>?<required-script-generation-parameters>

The Privacy Sandbox platform provides JavaScript using the information from this URI in the runtime.

An IllegalArgumentException is thrown if:

  • any of the required parameters are not present in the URI
  • there are unrecognized parameters in the URI

Supported prebuilt URI use cases and names

Use case 1: ad-selection

Prebuilt URIs under the ad-selection use case are supported in the selectAds(AdSelectionConfig) flow.

Prebuilt URI name: highest-bid-wins

This prebuilt URI provides a JavaScript that picks the ad with the highest bid after bidding. It also provides a basic reporting function to report the winner's render_uri and bid .

Required parameters

reportingUrl : The base reporting URL that is parameterized with the render_uri and the bid of the winning ad: 

<reportingUrl>?render_uri=<renderUriOfWinnigAd>&bid=<bidOfWinningAd>

ব্যবহার

If your base reporting URL is https://www.ssp.com/reporting then the prebuilt URI would be: 

`ad-selection-prebuilt://ad-selection/highest-bid-wins/?reportingUrl=https://www.ssp.com/reporting`

Use case 2: ad-selection-from-outcomes

Prebuilt URIs under the ad-selection-from-outcomes use case support the selectAds(AdSelectionFromOutcomesConfig) workflow.

Prebuilt URI name: waterfall-mediation-truncation

The waterfall-mediation-truncation prebuilt URI provides JavaScript that implements waterfall mediation truncation logic where the JavaScript returns a first-party ad if the bid is higher then or equal to the bid floor , and otherwise returns null .

Required parameters

bidFloor : The key of the bid floor value passed in the getSelectionSignals() that is compared against the mediation SDK's ad.

ব্যবহার

If your ad selection signals look like {"bid_floor": 10} then the resulting prebuilt URI would be: 

`ad-selection-prebuilt://ad-selection-from-outcomes/waterfall-mediation-truncation/?bidFloor=bid_floor`

পরীক্ষামূলক

To help you get started with the Protected Audience API, we've created sample apps in Kotlin and Java, which can be found on GitHub .

পূর্বশর্ত

The Protected Audience API requires some JavaScript during ad selection and impression reporting. There are two methods of providing this JavaScript in a testing environment:

  • Run a server with the required HTTPS endpoints that returns the JavaScript
  • Override remote fetching by providing the necessary code from a local source

Either approach requires setting up an HTTPS endpoint to handle impression reporting.

HTTPS endpoints

To test ad selection and impression reporting, you need to set up 7 HTTPS endpoints that your test device or emulator can access:

  1. Buyer endpoint that serves the bidding logic JavaScript.
  2. An endpoint that serves the bidding signals.
  3. Seller endpoint that serves the decision logic JavaScript.
  4. An endpoint that serves scoring signals.
  5. Winning buyer impression reporting endpoint.
  6. Seller impression reporting endpoint.
  7. An endpoint to serve the daily updates for a custom audience.

For convenience, the GitHub repository provides basic JavaScript code for testing purposes. It also includes OpenAPI service definitions which can be deployed to a supported mock or microservices platform. For more details, see the project README .

Override remote fetching of JavaScript

This feature is intended to be used for end-to-end testing. To override remote fetching, your app must run in debug mode with developer options enabled.

To enable debug mode for your application, add the following line to the application attribute in your AndroidManifest.xml: 

<application
  android:debuggable="true">

For an example of how to use these overrides, see the the Protected Audience API sample app on GitHub.

You need to add your own custom JavaScript to handle ad selection routines such as bidding, scoring decisions, and reporting. You can find basic JavaScript code examples that handle all required requests in the GitHub repo . The Protected Audience API sample application demonstrates how to read code from that file and prepare it for use as an override.

It is possible to override sell-side and buy-side JavaScript fetching independently, though you need an HTTPS endpoint to serve any JavaScript you aren't providing overrides for. See the README for information about how to set up a server that handles these cases.

It is only possible to override JavaScript fetching for custom audiences that are owned by your package.

Override sell-side JavaScript

To set up an override of sell-side JavaScript, do the following as demonstrated in the following code example:

  1. Initialize an AdSelectionManager object.
  2. Get a reference to TestAdSelectionManager from the AdSelectionManager object.
  3. Build an AdSelectionConfig object.
  4. Build an AddAdSelectionOverrideRequest with the AdSelectionConfig object and a String representing the JavaScript you intend to use as an override.
  5. Call the asynchronous overrideAdSelectionConfigRemoteInfo() method with the AddAdSelectionOverrideRequest object and relevant Executor and OutcomeReceiver objects.

কোটলিন 

val testAdSelectionManager: TestAdSelectionManager =
  context.getSystemService(AdSelectionManager::class.java).getTestAdSelectionManager()

// Initialize AdSelectionConfig =
val adSelectionConfig = new AdSelectionConfig.Builder()
    .setSeller(seller)
    .setDecisionLogicUrl(decisionLogicUrl)
    .setCustomAudienceBuyers(customAudienceBuyers)
    .setAdSelectionSignals(adSelectionSignals)
    .setSellerSignals(sellerSignals)
    .setPerBuyerSignals(perBuyerSignals)
    .build()

// Initialize AddAddSelectionOverrideRequest
val request = AddAdSelectionOverrideRequest.Builder()
    .setAdSelectionConfig(adSelectionConfig)
    .setDecisionLogicJs(decisionLogicJS)
    .build()

// Run the call to override the JavaScript for the given AdSelectionConfig
// Note that this only takes effect in apps marked as debuggable
testAdSelectionManager.overrideAdSelectionConfigRemoteInfo(
    request,
    executor,
    outComeReceiver)

জাভা 

TestAdSelectionManager testAdSelectionManager =
  context.getSystemService(AdSelectionManager.class).getTestAdSelectionManager();

// Initialize AdSelectionConfig =
AdSelectionConfig adSelectionConfig = new AdSelectionConfig.Builder()
    .setSeller(seller)
    .setDecisionLogicUrl(decisionLogicUrl)
    .setCustomAudienceBuyers(customAudienceBuyers)
    .setAdSelectionSignals(adSelectionSignals)
    .setSellerSignals(sellerSignals)
    .setPerBuyerSignals(perBuyerSignals)
    .build();

// Initialize AddAddSelectionOverrideRequest
AddAdSelectionOverrideRequest request = AddAdSelectionOverrideRequest.Builder()
    .setAdSelectionConfig(adSelectionConfig)
    .setDecisionLogicJs(decisionLogicJS)
    .build();

// Run the call to override the JavaScript for the given AdSelectionConfig
// Note that this only takes effect in apps marked as debuggable
testAdSelectionManager.overrideAdSelectionConfigRemoteInfo(
    request,
    executor,
    outComeReceiver);

See the Run ad selection section for more information about what each of the fields in the AdSelectionConfig represent. The key difference is that the decisionLogicUrl can be set to a placeholder value as it will be ignored.

In order to override the JavaScript used during ad selection, the decisionLogicJs must contain the proper seller-side function signatures . For an example of how to read a JavaScript file as a string, see the Protected Audience API sample app on GitHub.

The asynchronous overrideAdSelectionConfigRemoteInfo() method uses the OutcomeReceiver object to signal the result of the API call.

The onResult() callback signifies the override was applied successfully. Future calls to selectAds() will use whatever decision and reporting logic you have passed in as the override.

The onError() callback signifies two possible conditions:

  • If the override is attempted with invalid arguments, the AdServiceException indicates an IllegalArgumentException as the cause.
  • If the override is attempted with an app not running in debug mode with developer options enabled, the AdServiceException indicates IllegalStateException as the cause.

Reset sell-side overrides

This section assumes that you have overridden the sell-side JavaScript and that you have a reference to the TestAdSelectionManager and AdSelectionConfig used in the previous section.

In order to reset the overrides for all AdSelectionConfigs :

  1. Call the asynchronous resetAllAdSelectionConfigRemoteOverrides() method with the relevant OutcomeReceiver object.

কোটলিন 

// Resets overrides for all AdSelectionConfigs
testAadSelectionManager.resetAllAdSelectionConfigRemoteOverrides(
  outComeReceiver)

জাভা 

// Resets overrides for all AdSelectionConfigs
testAdSelectionManager.resetAllAdSelectionConfigRemoteOverrides(
    outComeReceiver);

After you reset sell-side overrides, calls to selectAds() use whatever decisionLogicUrl is stored in the AdSelectionConfig to attempt to fetch the required JavaScript.

If the call to resetAllAdSelectionConfigRemoteOverrides() fails, the OutComeReceiver.onError() callback provides an AdServiceException . If the removal of overrides is attempted with an app not running in debug mode with developer options enabled, AdServiceException indicates IllegalStateException as the cause.

Override buy-side JavaScript

  1. Follow the steps to join a custom audience
  2. Build an AddCustomAudienceOverrideRequest with the buyer and name of the custom audience you need to override, in addition to the bidding logic and data you want to use as an override.
  3. Call the asynchronous overrideCustomAudienceRemoteInfo() method with the AddCustomAudienceOverrideRequest object and relevant Executor and OutcomeReceiver objects.

কোটলিন 

val testCustomAudienceManager: TestCustomAudienceManager =
  context.getSystemService(CustomAudienceManager::class.java).getTestCustomAudienceManager()

// Join custom audience

// Build the AddCustomAudienceOverrideRequest
val request = AddCustomAudienceOverrideRequest.Builder()
    .setBuyer(buyer)
    .setName(name)
    .setBiddingLogicJs(biddingLogicJS)
    .setTrustedBiddingSignals(trustedBiddingSignals)
    .build()

// Run the call to override JavaScript for the given custom audience
testCustomAudienceManager.overrideCustomAudienceRemoteInfo(
    request,
    executor,
    outComeReceiver)

জাভা 

TestCustomAudienceManager testCustomAudienceManager =
  context.getSystemService(CustomAudienceManager.class).getTestCustomAudienceManager();

// Join custom audience

// Build the AddCustomAudienceOverrideRequest
AddCustomAudienceOverrideRequest request =
    AddCustomAudienceOverrideRequest.Builder()
        .setBuyer(buyer)
        .setName(name)
        .setBiddingLogicJs(biddingLogicJS)
        .setTrustedBiddingSignals(trustedBiddingSignals)
        .build();

// Run the call to override JavaScript for the given custom audience
testCustomAudienceManager.overrideCustomAudienceRemoteInfo(
    request,
    executor,
    outComeReceiver);

The values for buyer and name are the same ones used to create the custom audience. Learn more about these fields .

Additionally, you can specify two additional parameters:

  • biddingLogicJs : JavaScript that holds the buyer's logic that is used during ad selection. See the required function signatures in this JavaScript.
  • trustedBiddingSignals : Bidding signals to be used during ad selection. For testing purposes this can be an empty string.

The asynchronous overrideCustomAudienceRemoteInfo() method uses the OutcomeReceiver object to signal the result of the API call.

The onResult() callback signifies the override was applied successfully. Subsequent calls to selectAds() use whatever bidding and reporting logic you have passed in as the override.

The onError() callback signifies two possible conditions.

  • If the override is attempted with invalid arguments, the AdServiceException indicates an IllegalArgumentException as the cause.
  • If the override is attempted with an app not running in debug mode with developer options enabled, the AdServiceException indicates IllegalStateException as the cause.

Reset buy-side overrides

This section assumes that you have overridden the buy-side JavaScript and that you have a reference to the TestCustomAudienceManager used in the previous section.

To reset overrides for all custom audiences:

  1. Call the asynchronous resetAllCustomAudienceOverrides() method with relevant Executor and OutcomeReceiver objects.

কোটলিন 

// Resets overrides for all custom audiences
testCustomAudienceManager.resetCustomAudienceRemoteInfoOverride(
    executor,
    outComeReceiver)

জাভা 

// Resets overrides for all custom audiences
testCustomAudienceManager.resetCustomAudienceRemoteInfoOverride(
    executor,
    outComeReceiver)

After you reset buy-side overrides, subsequent calls to selectAds() use whatever biddingLogicUrl and trustedBiddingData is stored in the CustomAudience to attempt to fetch the required JavaScript.

If the call to resetCustomAudienceRemoteInfoOverride() fails, the OutComeReceiver.onError() callback provides an AdServiceException . If the removal of overrides is attempted with an app not running in debug mode with developer options enabled, the AdServiceException indicates IllegalStateException as the cause.

Set Up a Reporting Server

When you use remote fetching overrides, you'll still need to set up a server that your device or emulator can reach to respond to reporting events. An endpoint that returns 200 is sufficient for testing. The GitHub repository includes OpenAPI service definitions which can be deployed to a supported mock or microservices platform. For more details, see the project README .

When looking for the OpenAPI definitions, look for the reporting-server.json. This file contains an endpoint that returns 200, representing an HTTP response code. This endpoint is used during selectAds() and signals to the Protected Audience API that impression reporting completed successfully.

Functionality to test

  • Exercise joining or leaving and setting up a custom audience based on prior user actions.
  • Exercise the initiation of on-device ad selection through JavaScripts hosted remotely.
  • Observe how an app's association with custom audience settings may affect ad selection outcomes.
  • Exercise impression reporting after ad selection.

সীমাবদ্ধতা

The following table lists limitations for the Protected Audience API processing. The limits presented could be subject to change based on feedback. For in-progress capabilities, read the release notes .

উপাদান Limit Description Limit Value
Custom audience (CA) Maximum number of ads per CA ১০০
Maximum number of CAs per application ১০০০
Maximum number of apps that can create a CA ১০০০
Maximum delay in the activation time of a CA from its creation time 60 days
Maximum expiration time of a CA from its activation time 60 days
Maximum number of CAs on device ৪০০০
Maximum size of CA name 200 bytes
Maximum size of daily fetch URI 400 bytes
Maximum size of bidding logic URI 400 bytes
Maximum size of trusted bidding data 10 KB
Maximum size of user bidding signals 10 KB
Maximum call rate for leaveCustomAudience per buyer 1 per second
Maximum call rate for joinCustomAudience per buyer 1 per second
CA Background Fetch Connect timeout 5 seconds
HTTP read timeout 30 seconds
Maximum total download size 10 KB
Max duration of a fetch iteration ৫ মিনিট
Maximum number of CAs updated per job ১০০০
Ad Selection Maximum number of buyers টিবিডি
Maximum number of CAs per buyer টিবিডি
Maximum number of ads in an auction টিবিডি
Initial connection timeout 5 seconds
Connection read timeout 5 seconds
Maximum execution time of overall AdSelection 10 seconds
Maximum execution time of bidding per CA in AdSelection 5 second
Maximum execution time of scoring in AdSelection 5 second
Maximum execution time for per buyer in AdSelection টিবিডি
Maximum size of ad selection/seller/per buyer signals টিবিডি
Maximum size of seller/buyer scripts টিবিডি
Maximum call rate for selectAds 1 QPS
Impression reporting Minimum time before removing ad selection from persistence 24 hrs
Maximum number of storage ad selections টিবিডি
Maximum size of reporting output URL টিবিডি
Maximum time for impression reporting টিবিডি
Maximum number of retries for notification calls টিবিডি
Connection timeout 5 seconds
Maximum overall execution time for reportImpression 2 seconds
Maximum call rate for reportImpressions 1 QPS
Event reporting Maximum number of beacons per buyer per auction ১০

Maximum number of beacons per seller per auction

১০

Maximum size of event key

40 bytes

Maximum size of event data

64KB

বিজ্ঞাপন Maximum size of ad list 10 KB shared by all AdData in a single CA for contextual
URLs Maximum length of any URL string taken as input টিবিডি
Javascript Maximum execution time 1 second for bidding and scoring for impression reporting
Maximum memory used ১০ মেগাবাইট

Report bugs and issues

Your feedback is a crucial part of the Privacy Sandbox on Android! Let us know of any issues you find or ideas for improving Privacy Sandbox on Android.

{% অক্ষরে অক্ষরে %} {% এন্ডভারব্যাটিম %} {% অক্ষরে অক্ষরে %} {% এন্ডভারব্যাটিম %}