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

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

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

কাস্টম শ্রোতা

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

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

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

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

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

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

পরীক্ষামূলক

ক্লায়েন্ট কোডের ভেতরে Fetch কলটি বাস্তবায়ন করার পর এবং DSP পাশে Custom Audience Data ফেরত দেওয়ার জন্য একটি এন্ডপয়েন্ট সেট আপ করার পর, আপনি Custom Audience-এ যোগদানের প্রতিনিধিত্ব পরীক্ষা করতে পারেন। আপনার অ্যাপটি চালানোর আগে, আপনাকে Testing setup পৃষ্ঠায় কমান্ডগুলি চালাতে হবে। এই কমান্ডগুলি চালানোর পরে, আপনি Fetch API ব্যবহার করে সফলভাবে কল করা শুরু করতে সক্ষম হবেন।

এই প্রবাহের একটি উদাহরণ দেখতে, GitHub-এর Privacy Sandbox Samples সংগ্রহস্থলে ফেচ কল যোগ করা হয়েছে।

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

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

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() পদ্ধতিটি API কলের ফলাফল সিগন্যাল করার জন্য OutcomeReceiver অবজেক্ট ব্যবহার করে।

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

joinCustomAudience() এর ফলাফল পরিচালনা করার একটি উদাহরণ এখানে দেওয়া হল:

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

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

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

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

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

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

1. CustomAudienceManager অবজেক্টটি আরম্ভ করুন।
2. কাস্টম অডিয়েন্সের buyer এবং name দিয়ে LeaveCustomAudienceRequest শুরু করুন। এই ইনপুট ফিল্ডগুলি সম্পর্কে আরও জানতে, " সরাসরি কাস্টম অডিয়েন্সে যোগদান করুন " পড়ুন।
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() কলব্যাক কল করা হয়, মিলিত কাস্টম অডিয়েন্স সফলভাবে সরানো হোক বা না হোক।