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

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

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

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

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

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

এই নির্দেশিকায় বর্ণনা করা হয়েছে কীভাবে অ্যান্ড্রয়েডে Protected Audience API ব্যবহার করে নিম্নলিখিত কাজগুলো করা যায়:

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

শুরু করার আগে

শুরু করার আগে, নিম্নলিখিত বিষয়গুলো সম্পন্ন করুন:

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

  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. ডিফল্টরূপে, অ্যাড সিলেকশন এপিআই একটি অকশন বা ইম্প্রেশন রিপোর্টিং স্ক্রিপ্টের জন্য বরাদ্দকৃত সর্বোচ্চ মেমরির পরিমাণের উপর সীমা আরোপ করে। এই মেমরি সীমাবদ্ধতা বৈশিষ্ট্যটির জন্য ওয়েবভিউ সংস্করণ 105.0.5195.58 বা তার উচ্চতর সংস্করণ প্রয়োজন। প্ল্যাটফর্মটি একটি সংস্করণ যাচাই করে এবং এটি পূরণ না হলে selectAds এবং reportImpression এপিআই-এর কলগুলো ব্যর্থ হয়। এটি সেট আপ করার জন্য দুটি বিকল্প রয়েছে:

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

      adb device_config put fledge_js_isolate_enforce_max_heap_size false

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

একটি কাস্টম অডিয়েন্সে যোগ দিন

একটি কাস্টম অডিয়েন্স হলো বিজ্ঞাপনদাতা অ্যাপের দ্বারা নির্ধারিত, একই উদ্দেশ্য বা আগ্রহসম্পন্ন ব্যবহারকারীদের একটি গোষ্ঠী। একটি অ্যাপ বা 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() কল করলে, একই owner, buyer , এবং name প্যারামিটারযুক্ত যেকোনো বিদ্যমান CustomAudience আপডেট হয়ে যায়। গোপনীয়তা রক্ষার স্বার্থে, এই API-এর ফলাফল 'তৈরি' এবং 'আপডেট'-এর মধ্যে কোনো পার্থক্য করে না।

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

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

  • অ্যাক্টিভেশন সময় : একটি কাস্টম অডিয়েন্স শুধুমাত্র তার অ্যাক্টিভেশন সময় শেষ হওয়ার পরেই বিজ্ঞাপন নির্বাচন এবং দৈনিক আপডেটে অংশগ্রহণ করতে পারে। উদাহরণস্বরূপ, কোনো অ্যাপের নিষ্ক্রিয় ব্যবহারকারীদের পুনরায় সক্রিয় করতে এটি কার্যকর হতে পারে।
  • মেয়াদ শেষ হওয়ার সময় : একটি ভবিষ্যৎ সময়, যার পরে কাস্টম অডিয়েন্স ডিভাইস থেকে মুছে ফেলা হবে।
  • ব্যবহারকারীর বিডিং সংকেত : এটি একটি JSON স্ট্রিং, যাতে ব্যবহারকারীর সংকেত (যেমন ব্যবহারকারীর পছন্দের লোকেল) থাকে। বিজ্ঞাপন বাছাই প্রক্রিয়ার সময় বিড তৈরি করার জন্য ক্রেতার বিডিং লজিক জাভাস্ক্রিপ্ট এই সংকেতগুলো ব্যবহার করে। এই ফরম্যাটটি অ্যাড টেক প্ল্যাটফর্মগুলোকে বিভিন্ন প্ল্যাটফর্মে কোড পুনঃব্যবহার করতে সাহায্য করে এবং জাভাস্ক্রিপ্ট ফাংশনে এর ব্যবহার সহজ করে তোলে।
  • বিশ্বস্ত বিডিং ডেটা : একটি HTTPS URL এবং স্ট্রিংগুলির একটি তালিকা যা বিজ্ঞাপন নির্বাচন প্রক্রিয়ার সময় একটি বিশ্বস্ত Key/Value পরিষেবা থেকে বিডিং সংকেত সংগ্রহ করে।
  • Ads : বিজ্ঞাপন নির্বাচনে অংশগ্রহণকারী বিজ্ঞাপনগুলোর সাথে সম্পর্কিত AdData অবজেক্টের একটি তালিকা। প্রতিটি AdData অবজেক্টে নিম্নলিখিত বিষয়গুলো থাকে:
    • রেন্ডার ইউআরএল : একটি HTTPS ইউআরএল যা চূড়ান্ত বিজ্ঞাপনটি রেন্ডার করার জন্য কোয়েরি করা হয়।
    • মেটাডেটা : একটি 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() মেথডটি এপিআই কলের ফলাফল জানানোর জন্য 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 টি শুরু করুন। এই ইনপুট ফিল্ডগুলো সম্পর্কে আরও জানতে, " একটি কাস্টম অডিয়েন্সে যোগদান করুন " পড়ুন।
  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 ইনপুট প্রয়োজন, যেখানে আপনাকে নিম্নলিখিত আবশ্যক প্যারামিটারগুলো অবশ্যই উল্লেখ করতে হবে:

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

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

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

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

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

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

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

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

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

অ্যাপে প্রাসঙ্গিক বিজ্ঞাপন স্থাপন করতে, টার্গেট অ্যাপটিকে একটি 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();

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

কোটলিন 

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

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

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

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

আপনার নিলামে ফ্রিকোয়েন্সি ক্যাপিং ব্যবহার করতে হলে, আপনাকে প্রথমে 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 ব্যবহার করে।

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

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

  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);

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

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

  1. পূর্ব-নির্মিত ইউআরআই ব্যবহার করে প্রাসঙ্গিক বিজ্ঞাপনের জন্য বিজ্ঞাপন নির্বাচন চালানোর ধাপগুলো অনুসরণ করুন।

  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 মেডিয়েশন নেটওয়ার্ক দ্বারা একাধিক থার্ড পার্টি SDK (3P নেটওয়ার্ক) পরিচালনা করা প্রয়োজন। নিলামটি ডিভাইসে হোক বা বিডিং ও অকশন পরিষেবা (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-তে, অ্যাড বিডগুলি অস্বচ্ছ (opaque)। একটি মিডিয়েশন SDK-এর AdSelectionFromOutcomesConfig ব্যবহার করা উচিত, যাতে এটি একটি নির্দিষ্ট 1P অ্যাডের বিডকে চেইনের পরবর্তী 3P নেটওয়ার্কের বিড ফ্লোরের সাথে তুলনা করতে পারে। যদি 1P বিডটি বিড ফ্লোরের চেয়ে বেশি হয়, তাহলে এর অর্থ হলো মিডিয়েশন SDK-টি সেই 3P নেটওয়ার্কের সামনে স্থাপন করা হয়েছে।

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

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

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

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

মিডিয়েশন নেটওয়ার্কগুলো পূর্ববর্তী সেকশনের 1P AdSelectionId এবং বিবেচিত 3P নেটওয়ার্কের বিড ফ্লোর ব্যবহার করে একটি AdSelectionFromOutcomesConfig তৈরি করে। মিডিয়েশন চেইনের প্রতিটি ধাপের জন্য একটি নতুন 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 ইউআরএল যা বিজ্ঞাপন নির্বাচনের সময় বিজয়ী বিজ্ঞাপন বাছাই করার জন্য মিডিয়েশন নেটওয়ার্কের জাভাস্ক্রিপ্ট আনতে কোয়েরি করা হয়। এই জাভাস্ক্রিপ্টে প্রয়োজনীয় ফাংশন সিগনেচারগুলো দেখুন। যদি বিড, বিড ফ্লোরের চেয়ে বেশি হয়, তাহলে জাভাস্ক্রিপ্টটি 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. ১পি বিজ্ঞাপন নির্বাচন চালান।
  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() মেথডটি এপিআই কলের ফলাফল জানানোর জন্য OutcomeReceiver অবজেক্ট ব্যবহার করে।

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

জলপ্রপাত মধ্যস্থতা ছাপ প্রতিবেদন

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

এসএসপি-রা মিডিয়েশন ফ্লোতে কীভাবে যোগদান করতে হয় তার একটি প্রোটোটাইপ হিসেবে এই 3P SDK কোড উদাহরণটি ব্যবহার করতে পারেন: 

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

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

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

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

ক্রয়-পক্ষের প্ল্যাটফর্ম এন্ডপয়েন্ট:

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

বিক্রয়-পক্ষের প্ল্যাটফর্ম এন্ডপয়েন্ট:

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

বিডিং এবং নিলাম পরিষেবা প্রতিবেদন

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

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

` reportImpression() ` মেথডটি রিপোর্টিং-এর কাজটি সর্বোচ্চ প্রচেষ্টায় সম্পন্ন করার জন্য ডিজাইন করা হয়েছে।

বিজ্ঞাপনের প্রতিক্রিয়া রিপোর্ট করুন

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

ইন্টারেকশন ইভেন্টগুলি পেতে নিবন্ধন করুন

ইন্টার‍্যাকশন ইভেন্টের জন্য রেজিস্ট্রেশন ক্রেতার reportWin() এবং বিক্রেতার reportResult() জাভাস্ক্রিপ্ট ফাংশনে প্ল্যাটফর্ম দ্বারা প্রদত্ত একটি জাভাস্ক্রিপ্ট ফাংশন, registerAdBeacon , ব্যবহার করে সম্পন্ন হয়। একটি ইভেন্ট রিপোর্ট পাওয়ার জন্য রেজিস্টার করতে, আপনার রিপোর্টিং জাভাস্ক্রিপ্ট থেকে প্ল্যাটফর্মের জাভাস্ক্রিপ্ট ফাংশনটি কল করুন। নিম্নলিখিত কোড স্নিপেটটি ক্রেতার 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 থেকে সংগৃহীত একটি বিজ্ঞাপন নির্বাচন আইডি।
  • ইন্টারঅ্যাকশন কী : ক্লায়েন্ট দ্বারা সংজ্ঞায়িত একটি স্ট্রিং কী, যা রিপোর্ট করা অ্যাকশনটি বর্ণনা করে। এটি অবশ্যই সেই কী-এর সাথে মিলতে হবে যা বিক্রেতা বা ক্রেতা রিপোর্টিং জাভাস্ক্রিপ্ট ফাংশনগুলিতে রেজিস্টার করেছিলেন।
  • ইন্টারঅ্যাকশন ডেটা : একটি স্ট্রিং, যাতে ইভেন্ট রিপোর্টের সাথে অন্তর্ভুক্ত করার জন্য ডেটা থাকে, যা রিপোর্টিং সার্ভারগুলিতে POST করা হবে।
  • রিপোর্টিং গন্তব্য : একটি বিট মাস্ক যা নির্দিষ্ট করে যে ইভেন্টগুলি ক্রেতা, বিক্রেতা, নাকি উভয়ের কাছে রিপোর্ট করা হবে। এই ফ্ল্যাগগুলি প্ল্যাটফর্ম দ্বারা সরবরাহ করা হয় এবং বিটওয়াইজ অপারেশন ব্যবহার করে চূড়ান্ত গন্তব্য মাস্ক তৈরি করা যেতে পারে। একটি গন্তব্যে রিপোর্ট করার জন্য, আপনি সরাসরি প্ল্যাটফর্ম দ্বারা সরবরাহ করা ফ্ল্যাগটি ব্যবহার করতে পারেন। একাধিক গন্তব্যে রিপোর্ট করার জন্য, আপনি ফ্ল্যাগের মানগুলিকে একত্রিত করতে বিটওয়াইজ OR ( | ) ব্যবহার করতে পারেন।

অ্যাসিঙ্ক্রোনাস reportInteraction() মেথডটি এপিআই কলের ফলাফল জানানোর জন্য OutcomeReceiver অবজেক্ট ব্যবহার করে।

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

মিথস্ক্রিয়া রিপোর্টিং এন্ডপয়েন্ট

রিপোর্ট ইন্টারঅ্যাকশন এপিআই, সেল-সাইড প্ল্যাটফর্ম এবং বিজয়ী বাই-সাইড প্ল্যাটফর্ম দ্বারা প্রদত্ত এন্ডপয়েন্টগুলিতে HTTPS POST অনুরোধ পাঠায়। Protected Audience, রিপোর্টিং জাভাস্ক্রিপ্টে ঘোষিত URI-গুলির সাথে ইন্টারঅ্যাকশন কী-গুলি মিলিয়ে দেখবে এবং রিপোর্ট করা প্রতিটি ইন্টারঅ্যাকশনের জন্য প্রতিটি এন্ডপয়েন্টে একটি POST অনুরোধ পাঠাবে। অনুরোধটির Content-Type হলো প্লেইন টেক্সট এবং এর বডিতে থাকে ইন্টারঅ্যাকশন ডেটা।

সর্বোত্তম প্রচেষ্টা মিথস্ক্রিয়া প্রতিবেদন

` reportInteraction() ফাংশনটি HTTP POST-এর মাধ্যমে রিপোর্টিং সর্বোচ্চ প্রচেষ্টায় সম্পন্ন করার জন্য ডিজাইন করা হয়েছে।

দৈনিক পটভূমি আপডেট

কাস্টম অডিয়েন্স তৈরি করার সময়, আপনার অ্যাপ বা SDK কাস্টম অডিয়েন্স মেটাডেটা ইনিশিয়ালাইজ করতে পারে। এছাড়াও, প্ল্যাটফর্মটি একটি দৈনিক ব্যাকগ্রাউন্ড আপডেট প্রক্রিয়ার মাধ্যমে কাস্টম অডিয়েন্স মেটাডেটার নিম্নলিখিত অংশগুলো আপডেট করতে পারে।

  • 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 };
}

ইনপুট প্যারামিটারসমূহ:

  • 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.

ফলাফল:

  • 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 };
}

ইনপুট প্যারামিটারসমূহ:

  • 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};
}

ইনপুট প্যারামিটারসমূহ:

  • 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 }
   };
}

ইনপুট প্যারামিটারসমূহ:

  • 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 } };
}

ইনপুট প্যারামিটারসমূহ:

  • 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.

কার্যকারিতা পরীক্ষা করতে

  • 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 ৬০ দিন
Maximum expiration time of a CA from its activation time ৬০ দিন
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 ৫ সেকেন্ড
HTTP read timeout ৩০ সেকেন্ড
Maximum total download size 10 KB
Max duration of a fetch iteration ৫ মিনিট
Maximum number of CAs updated per job ১০০০
বিজ্ঞাপন নির্বাচন Maximum number of buyers TBD
Maximum number of CAs per buyer TBD
Maximum number of ads in an auction TBD
Initial connection timeout ৫ সেকেন্ড
Connection read timeout ৫ সেকেন্ড
Maximum execution time of overall AdSelection ১০ সেকেন্ড
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 TBD
Maximum size of ad selection/seller/per buyer signals TBD
Maximum size of seller/buyer scripts TBD
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 TBD
Maximum size of reporting output URL TBD
Maximum time for impression reporting TBD
Maximum number of retries for notification calls TBD
Connection timeout ৫ সেকেন্ড
Maximum overall execution time for reportImpression ২ সেকেন্ড
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 TBD
জাভাস্ক্রিপ্ট সর্বোচ্চ নির্বাহ সময় 1 second for bidding and scoring for impression reporting
Maximum memory used ১০ এমবি

বাগ এবং সমস্যা রিপোর্ট করুন

অ্যান্ড্রয়েডের প্রাইভেসি স্যান্ডবক্সের জন্য আপনার মতামত অত্যন্ত গুরুত্বপূর্ণ! আপনি কোনো সমস্যা খুঁজে পেলে অথবা অ্যান্ড্রয়েডের প্রাইভেসি স্যান্ডবক্স উন্নত করার জন্য কোনো ধারণা থাকলে আমাদের জানান।

{% হুবহু %} {% endverbatim %} {% হুবহু %} {% endverbatim %}