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

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

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

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

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

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

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

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

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

আনুন এবং একটি কাস্টম শ্রোতা যোগদান করুন

fetchAndJoinCustomAudience API ক্রেতাদের তাদের অংশীদার MMPs বা SSP-এর অন-ডিভাইস উপস্থিতি ব্যবহার করে কাস্টম দর্শকদের সাথে যোগদানের প্রতিনিধিত্ব করতে দেয়।

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

কোটলিন 

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

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

জাভা 

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

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

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

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

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

এপিআই সাইডে কীভাবে এটি সমাধান হয় সে সম্পর্কে আরও তথ্য CA প্রতিনিধিত্বে যোগদানের জন্য ডিজাইন প্রস্তাবে পাওয়া যাবে।

টেস্টিং

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

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

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

একটি কাস্টম শ্রোতা তৈরি করতে এবং যোগদান করার জন্য আপনার কাছে ইতিমধ্যেই প্রয়োজনীয় সমস্ত তথ্য থাকলে, আপনি সরাসরি একটি অ্যাসিঙ্ক্রোনাস প্রোটেক্টেড অডিয়েন্স 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 নির্দেশ করে।
    • অন্যান্য সমস্ত ত্রুটি কারণ হিসাবে একটি IllegalStateException সহ একটি AdServicesException পায়।

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