Android पर Topics API लागू करें

सेटअप

Topics API को लागू करने के लिए, आपको सबसे पहले अपना डेवलपमेंट एनवायरमेंट सेट अप करना होगा. इसके लिए, आपको ये चरण पूरे करने होंगे:

1. निजता बनाए रखने वाले एपीआई का सबसे नया वर्शन पाने के लिए, Android Privacy Sandbox SDK का नया वर्शन इस्तेमाल करें.

2. अपने मेनिफ़ेस्ट में यह जोड़ें:

   • अनुमति: अपने ऐप्लिकेशन को Topics API ऐक्सेस करने की अनुमति देने के लिए, 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" />
     

     मेनिफ़ेस्ट में शामिल किए गए Ad Services XML रिसॉर्स के बारे में बताएं. जैसे, res/xml/ad_services_config.xml. सभी एसडीके का ऐक्सेस देने के लिए, allowAllToAccess एट्रिब्यूट का इस्तेमाल करें. इसके अलावा, अलग-अलग एसडीके का ऐक्सेस देने के लिए, allowSdksToAccess एट्रिब्यूट का इस्तेमाल करें. विज्ञापन सेवाओं से जुड़ी अनुमतियों और एसडीके के ऐक्सेस कंट्रोल के बारे में ज़्यादा जानें.

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

3. अपने एसडीके में Topics API को कॉल करने के लिए, अपनी विज्ञापन टेक्नोलॉजी को Privacy Sandbox में रजिस्टर करें. स्थानीय तौर पर टेस्टिंग के लिए, इन कमांड का इस्तेमाल करके, विषयों के लिए ऑप्ट-इन करने की जांच को बंद किया जा सकता है:

   adb shell setprop debug.adservices.disable_topics_enrollment_check true
   

4. Topics API का ऐक्सेस चालू करें. Topics API डिफ़ॉल्ट रूप से बंद होता है. आपको इसे ADB कमांड का इस्तेमाल करके चालू करना होगा:

   adb shell device_config put adservices ppapi_app_signature_allow_list \"\*\"

   adb shell setprop debug.adservices.disable_topics_enrollment_check true

5. लागू करने की प्रोसेस शुरू करने के लिए, सैंपल ऐप्लिकेशन के Java या Kotlin वर्शन को फ़ोर्क करें. इससे आपको यह समझने में मदद मिलेगी कि किसी डिवाइस पर विषयों को कैसे वापस लाया जाता है.

विषयों के सेट का अनुरोध करना

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 Topics API से डेटा पाने के लिए ज़रूरी जानकारी देता है. इसमें एक फ़्लैग भी शामिल होता है, जिससे यह पता चलता है कि कॉलर, ऑब्ज़र्वर के तौर पर काम करेगा या नहीं. ऑब्ज़र्वर के तौर पर काम न करने पर, 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);

इस इनवोकेशन से, विषयों के ऑब्जेक्ट की सूची मिलेगी. इसमें आईडी वैल्यू शामिल होंगी. ये वैल्यू, ओपन सोर्स टैक्सोनॉमी में मौजूद उन विषयों से मेल खाती हैं जो उपयोगकर्ता के लिए काम के हैं. इसके अलावा, इससे काम की कोई गड़बड़ी भी मिल सकती है. विषय इस उदाहरण की तरह दिखेंगे:

/Internet & Telecom/Text & Instant Messaging

जवाब में शामिल किए जा सकने वाले विषयों की सूची के लिए, टैक्सोनॉमी देखें. यह टैक्सोनॉमी ओपन सोर्स है. इसमें बदलाव के सुझाव देने के लिए, इस पेज पर सबसे ऊपर मौजूद 'सुझाव/राय दें या शिकायत करें' बटन का इस्तेमाल करें.

टेस्ट करना

Topics API, ऐप्लिकेशन के इस्तेमाल के आधार पर काम के और नए विषय उपलब्ध कराता है. इस शुरुआती वर्शन में, एपीआई के काम करने के तरीके की झलक मिलती है. हम आने वाले समय में रिलीज़ होने वाले वर्शन में, विषयों की क्वालिटी को बेहतर बनाएंगे.

हमारा सुझाव है कि आप एक ऐसे टेस्टिंग एनवायरमेंट का इस्तेमाल करें जिसमें कई ऐप्लिकेशन हों. इससे आपको यह पता चलेगा कि विषयों को कैसे चुना जाता है. इसके लिए, आपको getTopics() को कॉल करना होगा. GitHub पर मौजूद SDK Runtime और निजता बनाए रखने वाले एपीआई के डेटा स्टोर में, Android Studio के अलग-अलग प्रोजेक्ट का एक सेट मौजूद है. इससे आपको शुरू करने में मदद मिलेगी. इसमें ऐसे सैंपल भी शामिल हैं जिनसे पता चलता है कि Topics API को कैसे शुरू किया जाए और उसे कैसे कॉल किया जाए.

विषयों की गिनती, एक इपॉक के खत्म होने पर की जाती है. डिफ़ॉल्ट रूप से, हर ईपॉक सात दिनों का होता है. हालांकि, नतीजे पाने के लिए इस इंटरवल में बदलाव किया जा सकता है. यह Android Debug Bridge शेल कमांड, इपॉक की अवधि को पांच मिनट तक कम कर देती है:

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

सैंपल ऐप्लिकेशन के अलावा, एक Colab भी है. इसका इस्तेमाल करके, विषयों के हिसाब से कॉन्टेंट को कैटगरी में बांटने वाले क्लासिफ़ायर के ख़िलाफ़, ऐप्लिकेशन की जानकारी के अलग-अलग कॉम्बिनेशन की जांच की जा सकती है. getTopics को कॉल करने पर, आपके ऐप्लिकेशन को किस तरह के नतीजे मिल सकते हैं, यह देखने के लिए इस Colab का इस्तेमाल करें.

एन्क्रिप्शन की जानकारी

डेटा को एन्क्रिप्ट (सुरक्षित) करने की सुविधा शुरू होने के बाद, GetTopics() को किए गए कॉल से अब EncryptedTopic ऑब्जेक्ट की सूची वाला जवाब जनरेट होगा. इन नतीजों को डिक्रिप्ट करने पर, आपको एक ऐसा ऑब्जेक्ट मिलेगा जिसका JSON फ़ॉर्मैट, पिछले Topic ऑब्जेक्ट के JSON फ़ॉर्मैट जैसा होगा.

Topics API, एचपीकेई (हाइब्रिड पब्लिक की एन्क्रिप्शन) को एक बार लागू करने की सुविधा देता है. हमारा मानना है कि रजिस्टर करने वाले कॉलर को, रजिस्टर करने के दौरान दिए गए सार्वजनिक एन्क्रिप्शन यूआरएल एंडपॉइंट पर 32-बिट की सार्वजनिक कुंजी होस्ट करनी होगी. इन कुंजियों को Base64 कोड में बदला जाना चाहिए.

EncryptedTopic ऑब्जेक्ट में तीन फ़ील्ड होते हैं. सार्वजनिक पासकोड के लिए, उससे जुड़े निजी पासकोड का इस्तेमाल करके, लौटाए गए विषयों की सूची पाई जा सकती है.

डेवलपमेंट के लिए, Topics API के एन्क्रिप्शन की जांच की जा सकती है. इसके लिए, आपको एनरोलमेंट की जांच करने की सुविधा बंद करनी होगी. इससे एपीआई, आपके जवाबों को एन्क्रिप्ट करने के लिए, टेस्ट की सार्वजनिक कुंजी का इस्तेमाल करेगा. एन्क्रिप्ट किए गए विषयों को डिक्रिप्ट करने के लिए, उनसे जुड़ी निजी कुंजी का इस्तेमाल किया जा सकता है.

सीमाएं

Topics API के लिए, अभी उपलब्ध सुविधाओं की सूची देखने के लिए, रिलीज़ नोट देखें.

गड़बड़ियों और समस्याओं की शिकायत करना

आपका सुझाव, राय या शिकायत, Android पर Privacy Sandbox का एक अहम हिस्सा है. अगर आपको कोई समस्या आती है या Android पर Privacy Sandbox को बेहतर बनाने के लिए आपके पास कोई सुझाव है, तो हमें बताएं.

आगे क्या करना होगा

कंट्रोल और पारदर्शिता

जानें कि उपयोगकर्ता और डेवलपर, Topics API को अपनी प्राथमिकताओं और ज़रूरतों के हिसाब से कैसे मैनेज और पसंद के मुताबिक बना सकते हैं.

Android पर Topics के बारे में खास जानकारी

जानें कि Topics, Android पर कैसे काम करता है. साथ ही, एपीआई फ़्लो के मुख्य चरणों के बारे में जानें.

इन्हें भी देखें

Android पर Topics API को बेहतर तरीके से समझने के लिए, हमारे संसाधन देखें.

• Topics के सैंपल ऐप्लिकेशन, साथ मिलकर बनाए जाने वाले वीडियो, और टॉपिक के बारे में जानकारी देने वाले वीडियो देखें.
• देखें कि उपयोगकर्ता और डेवलपर, एपीआई को कैसे कंट्रोल कर सकते हैं.
• सवाल पूछने, जुड़ाव बनाने, और सुझाव/राय देने के लिए, सहायता के लिए उपलब्ध संसाधन देखें.