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

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

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. विज्ञापन यूज़र इंटरफ़ेस (यूआई) को इससे Composables के साथ आसानी से इंटिग्रेट किया जा सकता है. Jetpack Compose जो डेवलपर व्यू के साथ काम नहीं करते वे भी जनरेट किए गए यूज़र इंटरफ़ेस (यूआई) को होस्ट कर सकते हैं जो अब भी व्यू के साथ काम करता है.

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

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

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

एपीआई

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

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

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

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

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

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

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

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

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

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

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

एसडीके से यूज़र इंटरफ़ेस (यूआई) पाएं.

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

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

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

SDK टूल की वजह से यूज़र इंटरफ़ेस में हुआ बदलाव.

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

यूज़र इंटरफ़ेस (यूआई) सेशन को बंद करना.

Z क्रम

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

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

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

स्क्रोल करना

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

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

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

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

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

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

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

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

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

खुले सवाल

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