Topics API की डेवलपर गाइड

Android पर प्राइवसी सैंडबॉक्स से जुड़े दस्तावेज़ पढ़ते समय, डेवलपर के लिए झलक या बीटा वर्शन बटन का इस्तेमाल करें. इसके बाद, प्रोग्राम का वह वर्शन चुनें जिस पर आपको काम करना है. निर्देश अलग-अलग हो सकते हैं.

सुझाव/राय देना या शिकायत करना

Topics API, उपयोगकर्ताओं के ऐप्लिकेशन के इस्तेमाल के आधार पर, उनके डिवाइस पर सामान्य दिलचस्पियों के सिग्नल का पता लगाता है. विषय नाम के इन सिग्नल को विज्ञापन देने वालों के साथ शेयर किया जाता है, ताकि सभी ऐप्लिकेशन में उपयोगकर्ताओं को ट्रैक किए बिना, दिलचस्पी के हिसाब से विज्ञापन दिखाए जा सकें. डिज़ाइन प्रपोज़ल में Topics API के बारे में ज़्यादा जानें. अहम जानकारी: आपको प्रोग्राम का वह वर्शन चुनना है जिस पर काम किया जा रहा है, इसके लिए SDK एक्सटेंशन रिलीज़ या 'डेवलपर की झलक' बटन पर क्लिक करें. ऐसा करने के लिए निर्देश अलग-अलग हो सकते हैं.

सेटअप

निजता बनाए रखने वाले एपीआई का अप-टू-डेट वर्शन पाने के लिए, Android Privacy Sandbox SDK टूल का सबसे नया वर्शन इस्तेमाल करें. Topics API का इस्तेमाल करने के लिए, आपको अपने ऐप्लिकेशन के मेनिफ़ेस्ट में अनुमति शामिल करनी होगी और विज्ञापन सेवाओं का कॉन्फ़िगरेशन बनाना होगा:

<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 एक्सएमएल रिसॉर्स के बारे में बताएं, जैसे कि res/xml/ad_services_config.xml. सभी SDK टूल का ऐक्सेस देने के लिए, allowAllToAccess एट्रिब्यूट का इस्तेमाल करें या अलग-अलग SDK टूल का ऐक्सेस देने के लिए, allowSdksToAccess एट्रिब्यूट का इस्तेमाल करें. विज्ञापन सेवाओं की अनुमतियों और SDK टूल के ऐक्सेस कंट्रोल के बारे में ज़्यादा जानें.

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

इसके अलावा, आपको इन adb कमांड के साथ, Topics API (डिफ़ॉल्ट रूप से बंद) का ऐक्सेस चालू करना होगा.

adb shell device_config put adservices ppapi_app_signature_allow_list \"*\"

adb shell setprop debug.adservices.disable_topics_enrollment_check true

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

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

सेटअप तैयार हो जाने के बाद, GetTopicsResponse पाने के लिए getTopics() तरीके को कॉल किया जा सकता है:

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 प्रोजेक्ट का एक सेट शामिल होता है. इससे आपको अलग-अलग Android Studio प्रोजेक्ट की जानकारी मिलती है. इसमें ऐसे सैंपल शामिल होते हैं जो Topics API को शुरू करने और उसे कॉल करने का तरीका बताते हैं.

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

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

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

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

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

सीमाएं

Topics API के लिए अभी जिन सुविधाओं का इस्तेमाल किया जा रहा है उनकी सूची देखने के लिए, प्रॉडक्ट की जानकारी देखें.

बग और समस्याओं की रिपोर्ट करना

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