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

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 टूल अलग-अलग प्रोसेस पर यूज़र इंटरफ़ेस (यूआई) दिखा सकते हैं. साथ ही, जब उपयोगकर्ता डिवाइस और प्रोसेस के साथ इंटरैक्ट करता है, तब इस लाइब्रेरी को अपडेट रखा जाता है.

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

एपीआई

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

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

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

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

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

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

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

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

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

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

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

SDK टूल से यूज़र इंटरफ़ेस (यूआई) पाएं.

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

पब्लिशर की ओर से शुरू किए गए यूज़र इंटरफ़ेस (यूआई) में बदलाव.

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

SDK टूल से शुरू किए गए यूज़र इंटरफ़ेस (यूआई) में बदलाव.

इस डायग्राम में दिखाया गया है कि 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. वर्टिकल स्क्रोल और फ़्लिंग जेस्चर, पब्लिशर के कंटेनर को भेजे और मैनेज किए जाते हैं. इससे, पब्लिशर का UX अच्छा होता है. ऐसा तब होता है, जब पब्लिशर का वह कंटेनर जिस पर विज्ञापन का यूज़र इंटरफ़ेस (यूआई) रखा गया हो और उसे वर्टिकल तरीके से स्क्रोल किया जा सकता हो. इसके लिए, आपको SDK टूल या पब्लिशर को कुछ और करने की ज़रूरत नहीं है.
2. हॉरिज़ॉन्टल स्क्रोल और फ़्लिंग जेस्चर, SDK टूल को भेजे और मैनेज किए जाते हैं. जब विज्ञापन का यूज़र इंटरफ़ेस (यूआई) हॉरिज़ॉन्टल रूप से स्क्रोल किया जा सकता हो (जैसे कि विज्ञापन कैरसेल).

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

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

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

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

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

प्लैटफ़ॉर्म एपीआई का आने वाला समय

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

खुले सवाल

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