অ্যান্ড্রয়েডে টপিক এপিআই প্রয়োগ করুন

সেটআপ

টপিকস এপিআই প্রয়োগ করতে, আপনাকে প্রথমে আপনার ডেভেলপমেন্ট এনভায়রনমেন্ট সেট আপ করতে হবে। এর জন্য নিম্নলিখিত সেটআপ ধাপগুলো অনুসরণ করুন:

  1. গোপনীয়তা-সংরক্ষক API-গুলোর সবচেয়ে হালনাগাদ সংস্করণ পেতে সর্বশেষ Android Privacy Sandbox SDK ব্যবহার করুন।

  2. আপনার ম্যানিফেস্টে নিম্নলিখিতগুলি যোগ করুন:

    • অনুমতি: আপনার অ্যাপকে টপিকস এপিআই অ্যাক্সেস করার অনুমতি দিতে ACCESS_ADSERVICES_TOPICS পারমিশনটি অন্তর্ভুক্ত করুন:

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

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

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

      ম্যানিফেস্টে উল্লেখিত অ্যাড সার্ভিসেস এক্সএমএল রিসোর্সটি নির্দিষ্ট করুন, যেমন res/xml/ad_services_config.xml । ​​সমস্ত SDK-কে অ্যাক্সেস দেওয়ার জন্য allowAllToAccess অ্যাট্রিবিউটটি, অথবা স্বতন্ত্র SDK-কে অ্যাক্সেস দেওয়ার জন্য allowSdksToAccess অ্যাট্রিবিউটটি ব্যবহার করুন। অ্যাড সার্ভিসেস পারমিশন এবং SDK অ্যাক্সেস কন্ট্রোল সম্পর্কে আরও জানুন।

      <ad-services-config>
    <topics allowAllToAccess="true"/>
</ad-services-config>

  3. আপনার SDK-তে টপিকস এপিআই (Topics API) কল করার জন্য প্রাইভেসি স্যান্ডবক্সে আপনার অ্যাড টেক (ad tech) নথিভুক্ত করুন । স্থানীয়ভাবে পরীক্ষার জন্য, আপনি নিম্নলিখিত কমান্ডগুলির সাহায্যে টপিকস নথিভুক্তিকরণ যাচাইকরণ নিষ্ক্রিয় করতে পারেন:

    adb shell setprop debug.adservices.disable_topics_enrollment_check true

  4. টপিকস এপিআই-তে অ্যাক্সেস সক্ষম করুন । ডিফল্টরূপে, টপিকস এপিআই নিষ্ক্রিয় থাকে। আপনাকে এডিবি কমান্ড ব্যবহার করে এটি সক্রিয় করতে হবে:

    adb shell device_config put adservices ppapi_app_signature_allow_list \"\*\"
    adb shell setprop debug.adservices.disable_topics_enrollment_check true

  5. ডিভাইসে কীভাবে টপিক পুনরুদ্ধার করতে হয়, তা ভালোভাবে বোঝার জন্য আমাদের স্যাম্পল অ্যাপটির জাভা বা কোটলিন সংস্করণ ফোর্ক করে আপনার ইমপ্লিমেন্টেশন শুরু করুন।

বিষয়সমূহের একটি সেট অনুরোধ করুন

Topics API-এর প্রধান কার্যকারিতা TopicsManager অবজেক্টের ভেতরের getTopics() মেথডে নিহিত, যেমনটি এই উদাহরণে দেখানো হয়েছে:

কোটলিন 

fun getTopics(
        getTopicsRequest: GetTopicsRequest,
        executor: Executor,
        callback: OutcomeReceiver<GetTopicsResponse, Exception>
    ) { }

জাভা 

public void getTopics (@NonNull GetTopicsRequest getTopicsRequest,
    @NonNull Executor executor,
    @NonNull OutcomeReceiver<GetTopicsResponse, Exception> callback)

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

কোটলিন 

private fun topicGetter() {
    val mContext = baseContext
    val mTopicsManager = mContext.getSystemService(TopicsManager::class.java)
    val mExecutor: Executor = Executors.newCachedThreadPool()
    val shouldRecordObservation = false
    val mTopicsRequestBuilder: GetTopicsRequest.Builder = GetTopicsRequest.Builder()
    mTopicsRequestBuilder.setAdsSdkName(baseContext.packageName)
    mTopicsRequestBuilder.setShouldRecordObservation(shouldRecordObservation)
    mTopicsManager.getTopics(mTopicsRequestBuilder.build(), mExecutor,
        mCallback as OutcomeReceiver<GetTopicsResponse, Exception>)
}
private var mCallback: OutcomeReceiver<GetTopicsResponse, java.lang.Exception> =
object : OutcomeReceiver<GetTopicsResponse, java.lang.Exception> {
    override fun onResult(result: GetTopicsResponse) {
        // handle successful result
        val topicsResult = result.topics
        for (i in topicsResult.indices) {
            Log.i("Topic", topicsResult[i].getTopicId().toString())
        }
        if (topicsResult.size == 0) {
            Log.i("Topic", "Returned Empty")
        }
    }
    override fun onError(error: java.lang.Exception) {
        // handle error
        Log.i("Topic", "Error, did not return successfully")
    }
}

জাভা 

public void TopicGetter() {
    @NonNull Context mContext = getBaseContext();
    TopicsManager mTopicsManager = mContext.getSystemService(TopicsManager.class);
    Executor mExecutor = Executors.newCachedThreadPool();
    boolean shouldRecordObservation = false;
    GetTopicsRequest.Builder mTopicsRequestBuilder = new GetTopicsRequest.Builder();
    mTopicsRequestBuilder.setAdsSdkName(getBaseContext().getPackageName());
    mTopicsRequestBuilder.setShouldRecordObservation(shouldRecordObservation);
    mTopicsManager.getTopics(mTopicsRequestBuilder.build(), mExecutor, mCallback);
}
OutcomeReceiver mCallback = new OutcomeReceiver<GetTopicsResponse, Exception>() {
    @Override
    public void onResult(@NonNull GetTopicsResponse result) {
        //Handle Successful Result
        List<Topic> topicsResult = result.getTopics();
        for (int i = 0; i < topicsResult.size(); i++) {
            Log.i("Topic", topicsResult.get(i).getTopicId().toString());
        }
        if (topicsResult.size() == 0) {
            Log.i("Topic", "Returned Empty");
        }
    }
    @Override
    public void onError(@NonNull Exception error) {
        // Handle error
        Log.i("Topic", "Experienced an error, and did not return successfully");
    }
};

আপনার সেটআপ প্রস্তুত হয়ে গেলে, আপনি getTopics() মেথড থেকে ফলাফল হিসেবে একটি GetTopicsResponse পাওয়ার জন্য কল করতে পারেন:

কোটলিন 

mTopicsManager.getTopics(mTopicsRequestBuilder.build(), mExecutor,
        mCallback as OutcomeReceiver<GetTopicsResponse, java.lang.Exception>)

জাভা 

mTopicsManager.getTopics(mTopicsRequestBuilder.build(), mExecutor, mCallback);

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

/Internet & Telecom/Text & Instant Messaging

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

পরীক্ষা

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

সম্পূর্ণ অভিজ্ঞতা লাভের জন্য, আমরা একাধিক অ্যাপ সহ একটি টেস্টিং এনভায়রনমেন্ট ব্যবহারের পরামর্শ দিই, যেখানে টপিকগুলো কীভাবে নির্বাচিত হয় তা দেখার জন্য আপনি getTopics() কল করতে পারেন। GitHub-এ থাকা SDK Runtime and Privacy Preserving APIs Repository-তে আপনাকে কাজ শুরু করতে সাহায্য করার জন্য বেশ কিছু স্বতন্ত্র Android Studio প্রজেক্ট রয়েছে, যার মধ্যে Topics API কীভাবে ইনিশিয়ালাইজ এবং কল করতে হয় তা প্রদর্শনকারী স্যাম্পলও অন্তর্ভুক্ত।

টপিক গণনা একটি ইপকের শেষে সম্পন্ন হয়। ডিফল্টরূপে, প্রতিটি ইপক ৭ দিন দীর্ঘ হয়, কিন্তু আপনি ফলাফল পাওয়ার জন্য এই ব্যবধানটি পরিবর্তন করতে পারেন। এই অ্যান্ড্রয়েড ডিবাগ ব্রিজ শেল কমান্ডটি ইপকের দৈর্ঘ্য কমিয়ে ৫ মিনিট করে দেয়: 

adb shell device_config put adservices topics_epoch_job_period_ms 300000

আপনি get ব্যবহার করে topics_epoch_job_period_ms মানটি নিশ্চিত করতে পারেন: 

adb shell device_config get adservices topics_epoch_job_period_ms

ম্যানুয়ালি ইপক গণনা শুরু করতে, নিম্নলিখিত কমান্ডটি চালান: 

adb shell cmd jobscheduler run -f com.google.android.adservices.api 2

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

এনক্রিপশনের বিবরণ

এনক্রিপশন চালু হওয়ার ফলে, এখন থেকে GetTopics() কল করলে EncryptedTopic অবজেক্টের একটি তালিকা সহ প্রতিক্রিয়া তৈরি হবে। এই ফলাফলগুলি ডিক্রিপ্ট করলে পূর্ববর্তী Topic অবজেক্টের মতো একই JSON ফরম্যাটের একটি অবজেক্ট পাওয়া যাবে।

টপিকস এপিআই (Topics API) এইচপিকেই (HPKE - হাইব্রিড পাবলিক কী এনক্রিপশন)-এর ওয়ান-শট বাস্তবায়ন সমর্থন করে। আমরা আশা করি যে, নথিভুক্ত কলার (enrolled caller) নথিভুক্তির সময় প্রদত্ত পাবলিক এনক্রিপশন ইউআরএল এন্ডপয়েন্টে (public encryption URL endpoint) একটি ৩২-বিট পাবলিক কী হোস্ট করবে। এই কীগুলো বেস৬৪ (Base64) এনকোড করা থাকবে বলে আশা করা হয়।

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

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

সীমাবদ্ধতা

টপিকস এপিআই-এর নির্মাণাধীন সক্ষমতাগুলোর তালিকার জন্য রিলিজ নোট দেখুন।

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

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

পরবর্তী পদক্ষেপ

ব্যবহারকারী এবং বিকাশকারীরা কীভাবে ব্যবহারকারীর পছন্দ এবং প্রয়োজন অনুসারে বিষয় API-কে পরিচালনা এবং কাস্টমাইজ করতে পারে তা জানুন।
Android এ বিষয়গুলি কীভাবে কাজ করে তা জানুন এবং API প্রবাহের মূল ধাপগুলি সম্পর্কে জানুন।

এছাড়াও দেখুন

অ্যান্ড্রয়েডে টপিক এপিআই আরও ভালভাবে বুঝতে আমাদের সংস্থানগুলি দেখুন।