SDK टूल के रनटाइम यूज़र इंटरफ़ेस (यूआई) प्रज़ेंटेशन के लिए एपीआई

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

SDK टूल के रनटाइम की मदद से, विज्ञापन दिखाने के लिए इस्तेमाल किए जाने वाले SDK टूल, सैंडबॉक्स वाले एनवायरमेंट में काम करते हैं. इससे, उन्हें पब्लिशर के व्यू हैरारकी को ऐक्सेस करने से रोका जा सकता है. विज्ञापन दिखाने के लिए, प्लैटफ़ॉर्म, विज्ञापन व्यू पाने के लिए SDK टूल को SandboxedSdkProvider.getView एपीआई दिखाता है. साथ ही, इसे SurfacePackage के तौर पर पैकेज करता है, ताकि इसे क्लाइंट ऐप्लिकेशन को आईपीसी (इंटर-प्रोसेस कम्यूनिकेशन) के ज़रिए भेजा जा सके. इसकी कई कमियां हैं, जिनके बारे में यहां बताया गया है. इसके बाद, इस दस्तावेज़ में एक ऐसी सुझाई गई Jetpack लाइब्रेरी दिखाई जाएगी जिसे इन चुनौतियों को हल करने के लिए बनाया जा रहा है.

प्लैटफ़ॉर्म एपीआई को बेहतर बनाने की वजह

फ़्रेमवर्क एपीआई को आसानी से इस्तेमाल करने के लिए डिज़ाइन किया गया है. साथ ही, यूज़र इंटरफ़ेस (यूआई) के प्रज़ेंटेशन के लिए, ऐप्लिकेशन और SDK टूल के बीच साइड चैनल बनाने का काम छोड़ दिया जाता है. यह साइड चैनल ये काम करता है:

1. इससे SDK टूल, विज्ञापन व्यू के लाइफ़टाइम के दौरान कई विज्ञापन व्यू मैनेज कर पाता है. साथ ही, यह भी समझ पाता है कि SDK टूल से विज्ञापन यूज़र इंटरफ़ेस (यूआई) बन जाने के बाद, उसमें क्या होता है.
2. व्यू बनाने और कॉन्टेंट को बांधने की प्रोसेस को अलग करता है. साइड चैनल का इस्तेमाल करने से, SDK टूल को ऐप्लिकेशन (कॉन्टेंट) के लिए विज्ञापन अनुरोध से जुड़ा ऑब्जेक्ट दिखाने की अनुमति मिलती है. जब भी ऐप्लिकेशन को सही लगे, तब इस ऑब्जेक्ट को विज्ञापन कंटेनर से जोड़ा जा सकता है.
3. यह प्लैटफ़ॉर्म के उन कॉन्स्ट्रक्ट को हटा देता है जिनका इस्तेमाल, सभी प्रोसेस में यूज़र इंटरफ़ेस (यूआई) दिखाने के लिए किया जाता है. (फ़िलहाल, प्लैटफ़ॉर्म SurfaceControlViewhost का इस्तेमाल करता है और उससे SurfacePackage जनरेट करता है.)
4. SDK टूल के रनटाइम में विज्ञापन SDK टूल चालू करता है, ताकि विज्ञापन कंटेनर के यूज़र इंटरफ़ेस (यूआई) में बदलाव होने पर, सूचनाएं अपने-आप मिल सकें. अगर कोई पब्लिशर विज्ञापन कंटेनर का लेआउट बदलता है, तो SDK टूल को इन बदलावों के बारे में तब तक नहीं पता चलता, जब तक पब्लिशर साफ़ तौर पर एपीआई को सूचना देने के लिए कॉल नहीं करता.
5. विज्ञापन यूज़र इंटरफ़ेस (यूआई) और विज्ञापन कंटेनर के साइज़ को सिंक करता है. ऐसा करने पर, उपयोगकर्ता को कोई झटका नहीं लगता.
6. पुराने सिस्टम के साथ काम करने की सुविधा को अपने-आप मैनेज करता है. SurfacePackage, एपीआई लेवल 30 से पहले उपलब्ध नहीं है. इसके अलावा, जिन डिवाइसों पर SDK टूल का रनटाइम नहीं है और SDK टूल, पब्लिशर के लिए प्रोसेस-लोकल है उन पर किसी विज्ञापन के लिए SurfacePackage बनाना बेकार है. ऐसा इसलिए, क्योंकि व्यू को सीधे SDK टूल से भी हासिल किया जा सकता है. साइड चैनल, SDK टूल और ऐप्लिकेशन डेवलपर कोड से इस जटिलता को हटा देता है.
7. इससे विज्ञापन यूज़र इंटरफ़ेस (यूआई), कॉम्पोज़ेबल के साथ आसानी से इंटिग्रेट हो जाता है. Jetpack Compose के ऐसे डेवलपर जो व्यू के साथ काम नहीं करते, वे भी SDK टूल के डेवलपर के जनरेट किए गए यूज़र इंटरफ़ेस (यूआई) को होस्ट कर सकते हैं.

यूज़र इंटरफ़ेस (यूआई) लाइब्रेरी

यूज़र इंटरफ़ेस (यूआई) लाइब्रेरी, ऊपर बताई गई जटिलताओं को हटा देती हैं. साथ ही, एक ऐसा साइड चैनल उपलब्ध कराती हैं जिसका इस्तेमाल पब्लिशर और SDK टूल, सभी प्रोसेस में यूज़र इंटरफ़ेस (यूआई) दिखाने के लिए कर सकते हैं. साथ ही, उपयोगकर्ता के डिवाइस और यूज़र इंटरफ़ेस (यूआई) के साथ इंटरैक्ट करने पर, इसे अपडेट रख सकते हैं.

यूज़र इंटरफ़ेस (यूआई) की तीन लाइब्रेरी हैं: कोर, क्लाइंट, और प्रोवाइडर. मुख्य लाइब्रेरी, क्लाइंट और प्रोवाइडर लाइब्रेरी के इस्तेमाल किए जाने वाले इंटरफ़ेस उपलब्ध कराती है. यूज़र इंटरफ़ेस (यूआई) की सेवा देने वाली कंपनी (आम तौर पर एसडीके), सेवा देने वाली लाइब्रेरी पर निर्भर करती है. वहीं, यूज़र इंटरफ़ेस का उपभोक्ता (आम तौर पर पब्लिशर), क्लाइंट लाइब्रेरी पर निर्भर करता है. क्लाइंट और प्रोवाइडर लाइब्रेरी, यूज़र इंटरफ़ेस सेशन बनाने और उसे मैनेज करने के लिए ज़रूरी साइड चैनल बनाती हैं.

एपीआई

SDK Runtime यूज़र इंटरफ़ेस (यूआई) के प्रज़ेंटेशन के लिए एपीआई इस तरह के हैं:

SandboxedUiAdapter: SDK टूल की मदद से बनाया गया, जो पब्लिशर के यूज़र इंटरफ़ेस (यूआई) में दिखाए जाने वाले कॉन्टेंट को पाने का तरीका उपलब्ध कराता है.

SandboxedSdkView: पब्लिशर की ओर से बनाया गया यह एक कंटेनर है, जिसमें SandboxedUiAdapter से मिला कॉन्टेंट होता है.

Session: SandboxedUiAdapter.openSession() के जवाब में, SDK टूल ने इसे बनाया है. एक यूज़र इंटरफ़ेस (यूआई) सेशन को दिखाता है. यह SDK टूल और पब्लिशर के बीच, कम्यूनिकेशन टनल का SDK टूल वाला हिस्सा होता है. साथ ही, इसे SandboxedSdkView में होने वाले बदलावों के बारे में सूचनाएं मिलती हैं. जैसे, विंडो को अलग करना, उसका साइज़ बदलना या कॉन्फ़िगरेशन में बदलाव करना.

SessionClient: क्लाइंट लाइब्रेरी से बनाया गया, यह SDK टूल और पब्लिशर के बीच कम्यूनिकेशन टनलिंग का पब्लिशर एंड बनाता है.

SandboxedSdkUiSessionStateChangedListener: पब्लिशर ने बनाया है. SandboxedSdkView से जुड़े यूज़र इंटरफ़ेस (यूआई) सेशन की स्थिति में होने वाले बदलावों के लिए, एक लिसनर.

इन एपीआई के बारे में ज़्यादा जानकारी के लिए, privacysandbox-ui का रेफ़रंस दस्तावेज़ पढ़ें.

कंट्रोल फ़्लो

यहां दिए गए डायग्राम में, अलग-अलग स्थितियों में क्लाइंट और प्रोवाइडर यूज़र इंटरफ़ेस (यूआई) लाइब्रेरी के बीच इंटरैक्शन को दिखाया गया है:

पिछले डायग्राम में दिखाया गया है कि पब्लिशर, प्रोग्राम के ज़रिए या अपने एक्सएमएल के ज़रिए SandboxedSdkView कैसे बना सकता है. साथ ही, SDK टूल से मिले SdkSandboxUiAdapter को SDK टूल के एपीआई के ज़रिए अटैच करने का तरीका भी बताया गया है. यूज़र इंटरफ़ेस (यूआई) की स्थिति में हुए सभी बदलावों को देखने के लिए, पब्लिशर को SdkSandboxUiAdapter को अटैच करने से पहले, SandboxedSdkView में SandboxedSdkUiSessionStateChangedListener जोड़ना चाहिए.

इस डायग्राम में दिखाया गया है कि अगर पब्लिशर की गतिविधि, कॉन्फ़िगरेशन में हुए बदलावों को मैनेज करती है, तो क्लाइंट लाइब्रेरी, कॉन्फ़िगरेशन में हुए बदलाव को SDK को फ़ॉरवर्ड करती है, ताकि वे अपने यूज़र इंटरफ़ेस (यूआई) को उसी हिसाब से अपडेट कर सकें. उदाहरण के लिए, यह फ़्लो तब ट्रिगर हो सकता है, जब उपयोगकर्ता डिवाइस को घुमाए और पब्लिशर अपनी गतिविधि में कॉन्फ़िगरेशन में हुए बदलावों को मैनेज करने के लिए, android:configChanges=["orientation"] सेट करे.

इस डायग्राम में दिखाया गया है कि SDK, SessionClient पर मौजूद तरीकों का इस्तेमाल करके, विज्ञापन कंटेनर में बदलाव का अनुरोध कैसे कर सकता है. यह एपीआई तब ट्रिगर होता है, जब SDK टूल को विज्ञापन का साइज़ बदलना हो और पब्लिशर को नए डाइमेंशन के हिसाब से विज्ञापन कंटेनर का साइज़ बदलना हो. ऐसा उपयोगकर्ता के इंटरैक्शन के जवाब में हो सकता है, जैसे कि mraid.resize().

इस डायग्राम में दिखाया गया है कि SandboxedSdkView को विंडो से अलग करने पर, सेशन कैसे बंद होता है. SDK, SessionClient.onSessionError() को कॉल करके किसी भी समय सेशन को बंद कर सकता है. उदाहरण के लिए, जब उपयोगकर्ता का नेटवर्क कनेक्शन बंद हो जाता है.

Z ऑर्डर

क्लाइंट यूज़र इंटरफ़ेस (यूआई) लाइब्रेरी, SDK टूल के यूज़र इंटरफ़ेस (यूआई) को होस्ट करने के लिए, अंदरूनी तौर पर SurfaceView का इस्तेमाल करती है. SurfaceView, पब्लिशर की विंडो के ऊपर या नीचे अपना यूज़र इंटरफ़ेस दिखाने के लिए, Z ऑर्डर का इस्तेमाल कर सकता है. इसे SandboxedSdkView.orderProviderUiAboveClientUi() तरीके से कंट्रोल किया जाता है. यह तरीका, बोलियन setOnTop को स्वीकार करता है.

जब setOnTop true होता है, तो SandboxedSdkView पर मौजूद हर android.view.MotionEvent को SDK टूल पर भेजा जाता है. false होने पर, इन्हें पब्लिशर को भेजा जाता है. डिफ़ॉल्ट रूप से, मोशन इवेंट SDK टूल को भेजे जाते हैं.

आम तौर पर, पब्लिशर को विज्ञापन व्यू के डिफ़ॉल्ट Z-क्रम में बदलाव करने की ज़रूरत नहीं होती. हालांकि, किसी विज्ञापन को कवर करने वाले यूज़र इंटरफ़ेस (यूआई) को दिखाते समय, Z-क्रम को कुछ समय के लिए डिफ़ॉल्ट से बदला जाना चाहिए. इसके बाद, कवर करने वाले यूज़र इंटरफ़ेस एलिमेंट को खारिज करने पर, उसे वापस डिफ़ॉल्ट पर सेट कर दिया जाना चाहिए. हम क्लाइंट यूज़र इंटरफ़ेस (यूआई) लाइब्रेरी में इस प्रोसेस को ऑटोमेट करने के तरीके एक्सप्लोर कर रहे हैं.

स्क्रोल करना

जब विज्ञापन यूज़र इंटरफ़ेस (यूआई) को पब्लिशर विंडो के ऊपर Z-क्रम में रखा जाता है, तो विज्ञापन यूज़र इंटरफ़ेस (यूआई) से MotionEvents को SDK टूल पर भेजा जाता है. विज्ञापन यूज़र इंटरफ़ेस (यूआई) पर शुरू किए गए स्क्रोल और फ़्लिंग जेस्चर को खास प्राथमिकता दी जाती है:

1. वर्टिकल स्क्रोल और फ़्लिंग जेस्चर, पब्लिशर के कंटेनर को भेजे जाते हैं और उसे मैनेज किया जाता है. जब विज्ञापन यूज़र इंटरफ़ेस (यूआई) को पब्लिशर के उस कंटेनर में रखा जाता है जिसे वर्टिकल तौर पर स्क्रोल किया जा सकता है, तो इससे अच्छा यूज़र अनुभव मिलता है. इसके लिए, SDK टूल या पब्लिशर को कुछ और करने की ज़रूरत नहीं होती.
2. हॉरिज़ॉन्टल स्क्रोल और फ़्लिंग जेस्चर, SDK टूल को भेजे जाते हैं और उसे SDK टूल मैनेज करता है. जब विज्ञापन यूज़र इंटरफ़ेस (यूआई) को हॉरिज़ॉन्टल तौर पर स्क्रोल किया जा सकता है, तब इससे बेहतर यूज़र अनुभव मिलता है. जैसे, विज्ञापन कैरसेल.

लागू करने के बारे में जानकारी देने वाली गाइड

SDK टूल को ये काम करने चाहिए:

• SandboxedUiAdapter: यह वैल्यू, पब्लिशर को SDK टूल के तय किए गए एपीआई के जवाब में दी जाती है. जैसे, loadAd. SDK टूल के सर्वर से विज्ञापन का अनुरोध करने और उस अनुरोध के लिए विज्ञापन व्यू तैयार करने के लिए, openSession() तरीके का इस्तेमाल किया जाना चाहिए.
• Session**: यह वैल्यू, SandboxedUiAdapter.openSession कॉल के जवाब में दिखती है. यह क्लाइंट लाइब्रेरी को विज्ञापन यूज़र इंटरफ़ेस (यूआई) पाने और इस एपीआई में हुए बदलावों के बारे में SDK टूल को सूचना देने का तरीका उपलब्ध कराता है. सभी Session तरीके यहां लागू किए जाने चाहिए.

पब्लिशर को ये काम करने चाहिए:

1. एक्सएमएल या प्रोग्राम के ज़रिए SandboxedSdkView बनाएं.
2. यूज़र इंटरफ़ेस (यूआई) में हुए बदलावों को देखने के लिए, SandboxedSdkView के साथ SandboxedSdkUiSessionStateChangedListener अटैच करें.
3. SandboxedSdkView में, दिया गया SDK टूल SandboxedUiAdapter अटैच करें.
4. हमेशा की तरह, विंडो में SandboxedSdkView जोड़ें और SDK टूल की मदद से, क्लाइंट लाइब्रेरी को यूज़र इंटरफ़ेस (यूआई) सेशन बनाने और उसे मैनेज करने दें.
5. SandboxedSdkUiSessionChangedListener की रिपोर्ट की गई स्थिति में होने वाले बदलावों पर, सही समय पर कार्रवाई करें. उदाहरण के लिए, अगर SDK टूल अचानक से सेशन को बंद कर देता है, तो पब्लिशर SandboxedSdkView को स्टैटिक इमेज से बदल सकता है या उसे अपनी व्यू हैरारकी से हटा सकता है.
6. अगर कोई ऐसा ट्रांज़िशन किया जा रहा है जिससे विज्ञापन यूज़र इंटरफ़ेस (यूआई) छिप सकता है, जैसे कि ड्रॉप-डाउन मेन्यू, तो विज्ञापन यूज़र इंटरफ़ेस को पब्लिशर की विंडो के नीचे रखने के लिए, orderProviderUiAboveClientUi को कुछ समय के लिए 'गलत' पर सेट करें. ड्रॉप-डाउन मेन्यू बंद करने के बाद, orderProviderUiAboveClientUi से true को कॉल करें.

प्लैटफ़ॉर्म एपीआई का भविष्य

यूज़र इंटरफ़ेस (यूआई) लाइब्रेरी के बीटा वर्शन के रिलीज़ होने के बाद, हम यूज़र इंटरफ़ेस के प्रज़ेंटेशन से जुड़े SDK टूल के रनटाइम प्लैटफ़ॉर्म एपीआई को बंद कर देंगे. जैसे, SdkSandboxManager.requestSurfacePackage() और SandbxedSdkProvider.getView().

सवाल पूछे जा सकते हैं

1. क्या विज्ञापन यूज़र इंटरफ़ेस (यूआई) के ऐसे और भी सामान्य इस्तेमाल के उदाहरण हैं जिन्हें यूआई लाइब्रेरी को अपने-आप मैनेज करना चाहिए?
2. विज्ञापन का यूज़र इंटरफ़ेस (यूआई) दिखाने के लिए, कौनसे यूआई फ़्रेमवर्क का इस्तेमाल किया जाता है. क्या आपको इन फ़्रेमवर्क के साथ यूआई लाइब्रेरी को इंटिग्रेट करने में समस्याएं आ सकती हैं?
3. क्या स्क्रोल किए जा सकने वाले पब्लिशर कंटेनर में, स्क्रोल किए जा सकने वाले विज्ञापन यूज़र इंटरफ़ेस (यूआई) का इस्तेमाल करना आपके लिए आम है? इस मामले में, विज्ञापन यूज़र इंटरफ़ेस (यूआई) और कंटेनर के लिए स्क्रोल की दिशा क्या है? जब उपयोगकर्ता, विज्ञापन यूज़र इंटरफ़ेस (यूआई) पर स्क्रोल करना शुरू करता है, तो आपको क्या करना चाहिए?