শ্রোতা ডেটা সংজ্ঞায়িত করুন

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

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

কাস্টম দর্শক

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

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

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

• দৈনিক আপডেট ইউআরএল : একটি HTTPS ইউআরএল যা কাস্টম অডিয়েন্সের ইউজার বিডিং সিগন্যাল, বিশ্বস্ত বিডিং ডেটা আপডেট করতে এবং বিজ্ঞাপনের জন্য ইউআরএল ও মেটাডেটা রেন্ডার করতে প্রতিদিন ব্যাকগ্রাউন্ডে কোয়েরি করা হয় ।
• বিডিং লজিক ইউআরএল : বিজ্ঞাপন নির্বাচনের সময় ক্রেতার জাভাস্ক্রিপ্ট বিডিং লজিক আনার জন্য ব্যবহৃত একটি HTTPS ইউআরএল। এই জাভাস্ক্রিপ্টে প্রয়োজনীয় ফাংশন সিগনেচারগুলো দেখুন।
• অ্যাড রেন্ডার আইডি : ক্রেতার অ্যাড টেক দ্বারা নির্ধারিত একটি যথেচ্ছ আইডি। এটি B&A-এর জন্য পেলোড তৈরির একটি অপটিমাইজেশন ।

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

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

একটি কাস্টম অডিয়েন্স আনুন এবং যোগদান করুন

fetchAndJoinCustomAudience API-টি ক্রেতাদেরকে তাদের পার্টনার MMP বা SSP-দের ডিভাইসে উপস্থিতিকে কাজে লাগিয়ে একটি কাস্টম অডিয়েন্সে যোগদানের দায়িত্ব অর্পণ করার সুযোগ দেয়।

এটি কার্যকর করার জন্য, ডিভাইস-ভিত্তিক কলার (সেটি MMP বা SSP SDK যাই হোক না কেন) নিম্নলিখিতের মতো একটি fetchAndJoinCustomAudienceRequest তৈরি করে:

/**
 * @param fetchUri The URL to retrieve the CA from.
 * (optional)@param name The name of the CA to join.
 * (optional)@param activationTime The time when the CA will activate.
 * (optional)@param expirationTime The time when the CA will expire,
    must be a time in the future otherwise this will fail
 * (optional)@param userBiddingSignals The user bidding signals used at auction.
*/

val request = FetchAndJoinCustomAudienceRequest.Builder(fetchUri)
    .setName(name)
    .setActivationTime(activationTime)
    .setExpirationTime(expirationTime)
    .setUserBiddingSignals(userBiddingSignals)
    .build()

/**
 * @param fetchUri The URL to retrieve the CA from.
 * (optional)@param name The name of the CA to join.
 * (optional)@param activationTime The time when the CA will activate.
 * (optional)@param expirationTime The time when the CA will expire,
    must be a time in the future otherwise this will fail
 * (optional)@param userBiddingSignals The user bidding signals used at auction.
*/

FetchAndJoinCustomAudienceRequest request =
 new FetchAndJoinCustomAudienceRequest.Builder(fetchUri)
  .setName(name) //Optional
  .setActivationTime(activationTime) //Optional
  .setExpirationTime(expirationTime) //Optional
  .setUserBiddingSignals(userBiddingSignals) //Optional
  .build();

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

fetchUri অবশ্যই ক্রেতা দ্বারা পরিচালিত একটি সার্ভার এন্ডপয়েন্টের দিকে নির্দেশ করতে হবে, যা এখানে প্রদর্শিত ফরম্যাটের সাথে মেলে এমন একটি কাস্টম অডিয়েন্স JSON অবজেক্ট ফেরত দেবে:

//Return a 200 response with data matching the format of the following in the body
{
  "daily_update_uri": "https://js.example.com/bidding/daily",
  "bidding_logic_uri": "https://js.example.com/bidding",
  "user_bidding_signals": {
    "valid": true,
    "arbitrary": "yes"
  },
  "trusted_bidding_data": {
    "trusted_bidding_uri": "https://js.example.com/bidding/trusted",
    "trusted_bidding_keys": [
      "key1",
      "key2"
    ]
  },
  "ads": [
    {
      "render_uri": "https://js.example.com/render/fetch_and_join_ad1",
      "metadata": {
        "valid": 1
      }
    },
    {
      "render_uri": "https://js.example.com/render/fetch_and_join_ad2",
      "metadata": {
        "valid": 2
      }
    }
  ]
}

এপিআই (API) পর্যায়ে এটি কীভাবে সমাধান করা হয় সে সম্পর্কে আরও তথ্য ‘Join CA Delegation’-এর ডিজাইন প্রস্তাবে পাওয়া যাবে।

পরীক্ষা

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

এই ফ্লো-এর একটি উদাহরণ দেখতে, গিটহাব-এর প্রাইভেসি স্যান্ডবক্স স্যাম্পলস রিপোজিটরিতে ফেচ কল যুক্ত করা হয়েছে।

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

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

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

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

// Minimal initialization of a CustomAudience object
val audience: CustomAudience = CustomAudience.Builder()
    .setBuyer(AdTechIdentifier.fromString("my.buyer.domain.name"))
    .setName("example-custom-audience-name")
    .setDailyUpdateUrl(Uri.parse("https://DAILY_UPDATE_URL"))
    .setBiddingLogicUrl(Uri.parse("https://BIDDING_LOGIC_URL"))
    .build()

// Initialize a custom audience request.
val joinCustomAudienceRequest: JoinCustomAudienceRequest =
  JoinCustomAudienceRequest.Builder().setCustomAudience(audience).build()

// Request to join a custom audience.
customAudienceManager.joinCustomAudience(joinCustomAudienceRequest,
    executor,
    outcomeReceiver)

CustomAudienceManager customAudienceManager =
  context.getSystemService(CustomAudienceManager.class);

// Minimal initialization of a CustomAudience object
CustomAudience audience = CustomAudience.Builder()
    .setBuyer(AdTechIdentifier.fromString("my.buyer.domain.name"))
    .setName("example-custom-audience-name")
    .setDailyUpdateUrl(Uri.parse("https://DAILY_UPDATE_URL"))
    .setBiddingLogicUrl(Uri.parse("https://BIDDING_LOGIC_URL"))
    .build();

// Initialize a custom audience request.
JoinCustomAudienceRequest joinCustomAudienceRequest =
    new JoinCustomAudienceRequest.Builder().setCustomAudience(audience).build();

// Request to join a custom audience.
customAudienceManager.joinCustomAudience(joinCustomAudienceRequest,
    executor,
    outcomeReceiver);

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

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

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

joinCustomAudience() এর ফলাফল কীভাবে পরিচালনা করতে হয় তার একটি উদাহরণ নিচে দেওয়া হলো:

var callback: OutcomeReceiver<Void, AdServicesException> =
    object : OutcomeReceiver<Void, AdServicesException> {
    override fun onResult(result: Void) {
        Log.i("CustomAudience", "Completed joinCustomAudience")
    }

    override fun onError(error: AdServicesException) {
        // Handle error
        Log.e("CustomAudience", "Error executing joinCustomAudience", error)
    }
};

OutcomeReceiver callback = new OutcomeReceiver<Void, AdServicesException>() {
    @Override
    public void onResult(@NonNull Void result) {
        Log.i("CustomAudience", "Completed joinCustomAudience");
    }

    @Override
    public void onError(@NonNull AdServicesException error) {
        // Handle error
        Log.e("CustomAudience", "Error executing joinCustomAudience", error);
    }
};

একটি কাস্টম দর্শক রেখে যান

যদি ব্যবহারকারী কোনো নির্দিষ্ট কাস্টম অডিয়েন্সের জন্য ব্যবসায়িক মানদণ্ড আর পূরণ না করেন, তাহলে একটি অ্যাপ বা SDK ডিভাইস থেকে কাস্টম অডিয়েন্সটি সরিয়ে ফেলার জন্য leaveCustomAudience() কল করতে পারে। এর অনন্য প্যারামিটারগুলির উপর ভিত্তি করে একটি CustomAudience সরিয়ে ফেলতে, নিম্নলিখিত পদক্ষেপগুলি অনুসরণ করুন:

1. CustomAudienceManager অবজেক্টটি প্রারম্ভিকীকরণ করুন।
2. কাস্টম অডিয়েন্সের 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() কলব্যাকটি কল করা হয়, এক্ষেত্রে সংশ্লিষ্ট কাস্টম অডিয়েন্স সফলভাবে সরানো হোক বা না হোক।