इस पेज का अनुवाद Cloud Translation API से किया गया है.

Android पर Topics API लागू करें
संग्रह की मदद से व्यवस्थित रहें अपनी प्राथमिकताओं के आधार पर, कॉन्टेंट को सेव करें और कैटगरी में बांटें.

ध्यान दें: अगर बीटा प्रोग्राम के वर्शन का इस्तेमाल किया जा रहा है, तो Privacy Sandbox के निजता बनाए रखने वाले एपीआई के साथ इंटिग्रेशन को आसान बनाने के लिए, ads-adservices Jetpack लाइब्रेरी 1.0.0-beta01 या उसके बाद के वर्शन का इस्तेमाल किया जा सकता है. साथ ही, अपने कोड को प्लैटफ़ॉर्म और SDK एक्सटेंशन की जटिलताओं से अलग रखा जा सकता है. Jetpack लाइब्रेरी, Privacy Sandbox के Topics, Protected Audience, और Attribution Reporting के साथ इंटिग्रेशन की सुविधा चालू करती है.

सेटअप

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

निजता बनाए रखने वाले एपीआई का सबसे अप-टू-डेट वर्शन पाने के लिए, Android Privacy Sandbox SDK का इस्तेमाल करें.
अपने मेनिफ़ेस्ट में ये चीज़ें जोड़ें:
- अनुमति: अपने ऐप्लिकेशन को Topics API को ऐक्सेस करने की अनुमति देने के लिए, ACCESS_ADSERVICES_TOPICS अनुमति शामिल करें:
```
<uses-permission android:name="android.permission.ACCESS_ADSERVICES_TOPICS" />
```
- Ad Services कॉन्फ़िगरेशन: अपने मेनिफ़ेस्ट के <application> एलिमेंट में, Ad Services कॉन्फ़िगरेशन फ़ाइल का रेफ़रंस दें.
```
<property android:name="android.adservices.AD_SERVICES_CONFIG"
android:resource="@xml/ad_services_config" />
```
  मेनिफ़ेस्ट में रेफ़र किए गए Ad Services एक्सएमएल रिसॉर्स की जानकारी दें, जैसे कि res/xml/ad_services_config.xml. सभी SDK टूल का ऐक्सेस देने के लिए, allowAllToAccess एट्रिब्यूट का इस्तेमाल करें. इसके अलावा, किसी एक SDK टूल का ऐक्सेस देने के लिए, allowSdksToAccess एट्रिब्यूट का इस्तेमाल करें. Ad Services की अनुमतियों और SDK टूल के ऐक्सेस कंट्रोल के बारे में ज़्यादा जानें.
```
<ad-services-config>
    <topics allowAllToAccess="true"/>
</ad-services-config>
```
अपने SDK टूल में Topics API को कॉल करने के लिए, Privacy Sandbox में अपनी विज्ञापन टेक्नोलॉजी को रजिस्टर करें. स्थानीय तौर पर टेस्ट करने के लिए, Topics में रजिस्टर करने की जांच की सुविधा को इन निर्देशों की मदद से बंद किया जा सकता है:
```
adb shell setprop debug.adservices.disable_topics_enrollment_check true
```
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
```
किसी डिवाइस पर विषयों को वापस पाने का तरीका जानने के लिए, सैंपल ऐप्लिकेशन के Java या Kotlin वर्शन को फ़ॉर्क करके, इसे लागू करना शुरू करें.

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

Topics API की मुख्य सुविधा, TopicsManager ऑब्जेक्ट के अंदर मौजूद getTopics() तरीके में होती है, जैसा कि इस उदाहरण में दिखाया गया है:

Kotlin

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

Java

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

इस तरीके का इस्तेमाल करने के लिए, TopicsManager ऑब्जेक्ट और विषयों का डेटा पाने के लिए ज़रूरी पैरामीटर को शुरू करें. Topics API का डेटा पाने के लिए, GetTopicsRequest ज़रूरी जानकारी भेजता है. इसमें एक फ़्लैग भी शामिल होता है, जिससे यह पता चलता है कि कॉल करने वाला व्यक्ति ऑब्ज़र्वर के तौर पर काम करेगा या नहीं. जब ऑब्ज़र्वर के तौर पर काम नहीं किया जा रहा है, तो getTopics कॉल पिछले एपच से कोई विषय दिखाता है. हालांकि, इससे अगले एपच के विषयों के डेटा पर कोई असर नहीं पड़ेगा. OutcomeReceiver कॉलबैक, नतीजे को असिंक्रोनस तरीके से हैंडल करता है. उदाहरण के लिए:

Kotlin

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")
    }
}

Java

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 पाने के लिए कॉल किया जा सकता है:

Kotlin

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

Java

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

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

/Internet & Telecom/Text & Instant Messaging

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

टेस्ट करना

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

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

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

adb shell device_config put adservices topics_epoch_job_period_ms 300000

topics_epoch_job_period_ms वैल्यू की पुष्टि get से की जा सकती है:

adb shell device_config get adservices topics_epoch_job_period_ms

मैन्युअल तरीके से, इकोसिस्टम के शुरू होने का समय कैलकुलेट करने की प्रोसेस को ट्रिगर करने के लिए, यह कमांड चलाएं:

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

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

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

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

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

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

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

सीमाएं

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

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

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

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

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

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

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

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

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

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

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