SDK टूल के रनटाइम में मीडिएशन की सुविधा

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

इस दस्तावेज़ में, SDK रनटाइम में मीडिएशन वर्कफ़्लो में हुए अहम बदलावों के बारे में बताया गया है. इसमें ये विषय शामिल हैं:

• पिछले मीडिएशन फ़्लो और मौजूदा SDK टूल के रनटाइम के मीडिएशन सपोर्ट के बीच अंतर
• SDK टूल के रनटाइम में मीडिएशन वर्कफ़्लो और ट्रांज़िशन के अलग-अलग चरणों के लिए कार्रवाइयां सेट अप करना
• उन स्थितियों को मैनेज करने का तरीका जहां सभी SDK टूल, रनटाइम पर माइग्रेट नहीं हुए हैं

SDK टूल के रनटाइम में, मीडिएटेड विज्ञापनों के लिए सहायता, AGP 8.5 और SDK टूल के रनटाइम की Jetpack लाइब्रेरी के इन वर्शन में उपलब्ध है:

Androidx लाइब्रेरी	वर्शन
androidx.privacysandbox.activity	1.0.0-alpha01
androidx.privacysandbox.sdkruntime	1.0.0-alpha13
androidx.privacysandbox.tools	1.0.0-alpha08
androidx.privacysandbox.ui	1.0.0-alpha09

शब्दावली

SDK रनटाइम में मीडिएशन को समझने के लिए, यहां दिए गए शब्द अहम हैं:

• रनटाइम के साथ काम करने वाला SDK टूल (RE SDK): यह SDK टूल, SDK टूल के रनटाइम एनवायरमेंट में काम करने के लिए बनाया गया है. साथ ही, यह इंटर-प्रोसेस कम्यूनिकेशन (आईपीसी) के ज़रिए ऐप्लिकेशन के साथ कम्यूनिकेट करता है.
• रनटाइम के बारे में जानकारी देने वाला SDK टूल (RA SDK): यह ऐसा SDK टूल है जिसमें रनटाइम की सुविधा नहीं होती. इसे ऐप्लिकेशन से स्टैटिक तौर पर लिंक किया जाता है. इसमें आपका मौजूदा SDK टूल कोड के साथ-साथ, रनटाइम की सुविधा वाले SDK टूल को कॉल करने के लिए नया कोड भी शामिल हो सकता है.
• इन-ऐप्लिकेशन SDK टूल: यह SDK टूल, ऐप्लिकेशन से स्टैटिक तौर पर लिंक होकर चलता है. साथ ही, यह SDK टूल के रनटाइम के बारे में नहीं जानता. यह कोई ऐसा विज्ञापन नेटवर्क हो सकता है जिसे SDK टूल के रनटाइम पर ट्रांज़िशन नहीं किया गया है या पब्लिशर का कस्टम अडैप्टर हो सकता है.
• मीडिएटर: विज्ञापन मीडिएशन SDK टूल, जो अन्य विज्ञापन नेटवर्क SDK टूल के साथ इंटरैक्ट करके, डिवाइस पर मीडिएशन सेवा उपलब्ध कराता है.
• Mediatee: विज्ञापन नेटवर्क SDK टूल, जिसे विज्ञापन दिखाने और उसे रेंडर करने के लिए मीडिएटर कॉल करता है.
• मीडिएशन अडैप्टर: ये ऐसे SDK टूल होते हैं जिनका इस्तेमाल, मीडिएटर SDK टूल करता है. इनकी मदद से, एपीआई इंटरफ़ेस का अनुवाद किया जाता है, ताकि मीडिएट किए जाने वाले अलग-अलग SDK टूल के साथ इंटरऑपरेट किया जा सके. आम तौर पर, ये टूल मीडिएटर उपलब्ध कराता है. ये रनटाइम के बारे में जानकारी रखने वाले या रनटाइम के बारे में जानकारी न रखने वाले हो सकते हैं.

सामान्य मीडिएशन फ़्लो

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

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

मीडिएशन फ़्लो को लागू करने के तरीकों में अंतर होने की वजह से, हम इन दो मुख्य फ़्लो पर फ़ोकस करते हैं:

• शुरुआत (इसमें विज्ञापन नेटवर्क और कम्यूनिकेशन की खोज भी शामिल है)
• विज्ञापन का यूज़र इंटरफ़ेस (यूआई) प्रज़ेंटेशन

डेटा लेयर में इवेंट बनाने की प्रोसेस

यहां स्टैंडर्ड शुरू करने, विज्ञापन नेटवर्क की खोज, और कम्यूनिकेशन फ़्लो के बारे में बताया गया है:

1. क्लाइंट ऐप्लिकेशन, मीडिएटर को शुरू करता है
2. मीडिएटर, काम के मीडिएट और अडैप्टर को ढूंढता है और उन्हें शुरू करता है
3. मीडिएटर, हर मीडिएट किए जाने वाले व्यक्ति के साथ बातचीत करने के लिए, अपने अडैप्टर का इस्तेमाल करता है
4. क्लाइंट ऐप्लिकेशन, मीडिएटर से विज्ञापन लोड करने का अनुरोध करता है
5. क्लाइंट ऐप्लिकेशन, मीडिएटर से यह विज्ञापन दिखाने का अनुरोध करता है

ध्यान दें: इस फ़्लो में यह माना गया है कि क्लाइंट ऐप्लिकेशन, मीडिएटर SDK टूल, मीडिएट किए जाने वाले ऐप्लिकेशन के SDK टूल, और मीडिएशन अडैप्टर पर निर्भर है. साथ ही, इसे इनके साथ बनाया गया है.

विज्ञापन का यूज़र इंटरफ़ेस (यूआई) प्रज़ेंटेशन

पिछले चरण में आखिरी अनुरोध करने के बाद, विज्ञापन को रेंडर करने का तरीका, विज्ञापन के टाइप पर निर्भर करता है:

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

SDK टूल के रनटाइम में मीडिएशन फ़्लो

SDK टूल के रनटाइम में मीडिएशन अलग-अलग तरीके से काम करता है. यह इस बात पर निर्भर करता है कि मीडिएट करने वाला ऐप्लिकेशन, रनटाइम के साथ काम करता है या नहीं. इस आधार पर, ये स्थितियां हो सकती हैं:

• मीडिएटर और मीडिएटेड, दोनों SDK टूल के रनटाइम में हैं: RE mediatee
• मीडिएटर, SDK टूल के रनटाइम में है और मीडिएट किया जाने वाला ऐप्लिकेशन, इन-ऐप्लिकेशन है: इन-ऐप्लिकेशन मीडिएट किया जाने वाला ऐप्लिकेशन

RE Mediatee

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

मीडिएशन अडैप्टर को उसी प्रोसेस में होना चाहिए जिससे वे इंटरफ़ेस कर रहे हैं. इसलिए, उन्हें भी SDK टूल के रनटाइम पर माइग्रेट करना होगा.

**पहली इमेज.** मीडिएटर और मीडिएटेड, दोनों RE SDK हैं.

डेटा लेयर में इवेंट बनाने की प्रोसेस

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

1. ऐप्लिकेशन (या RA SDK टूल), SdkSandboxManager#loadSdk का इस्तेमाल करके मीडिएटर SDK टूल को लोड और शुरू करता है.
2. शुरू होने के दौरान, मीडिएटर SDK टूल, SdkSandboxController#loadSdk का इस्तेमाल करके, SDK टूल के रनटाइम में ज़रूरी मीडिएटर्स को लोड और शुरू करता है.
3. RE SDK टूल, SdkSandboxController#getSandboxedSdks को कॉल करके, रनटाइम में लोड किए गए सभी SDK टूल का पता लगा सकता है.

**दूसरी इमेज.** RE मीडिएटर को शुरू करने के लिए फ़्लो.

ध्यान दें: *Compat Runtime Manager और Controller क्लास का इस्तेमाल करके, पक्का करें कि रनटाइम के साथ काम करने वाला आपका SDK टूल, पुराने वर्शन के साथ काम करता हो.

विज्ञापन का यूज़र इंटरफ़ेस (यूआई) प्रज़ेंटेशन

इस सेक्शन में, किसी RE mediatee से बैनर और फ़ुल-स्क्रीन विज्ञापन लोड करने के बारे में बताया गया है.

RE Mediatee के बैनर विज्ञापन

ऐप्लिकेशन से बैनर विज्ञापन लोड करने का अनुरोध मिलने पर, रेंडरिंग पूरी करने का फ़्लो इस तरह से होता है:

1. मीडिएटर, इस विज्ञापन के लिए विज्ञापन देने वाले को चुनता है.
2. मध्यस्थ, मध्यस्थता में शामिल व्यक्ति से SandboxedUiAdapter पाने के बाद, मध्यस्थता की प्रक्रिया शुरू करता है.
3. मीडिएटर, UiAdapter को ऐप्लिकेशन पर भेजता है.

**तीसरी इमेज.** RE मीडिएटर से बैनर विज्ञापन रेंडर करने की प्रोसेस का फ़्लो.

SandboxedUiAdapter और SDK टूल के रनटाइम यूज़र इंटरफ़ेस (यूआई) लाइब्रेरी के इस्तेमाल के बारे में ज़्यादा जानें.

बैनर विज्ञापनों के लिए ओवरले

अगर मीडिएटर को विज्ञापन में कोई ओवरले जोड़ना है, तो उन्हें इस फ़्लो में बदलाव करना होगा:

1. मीडिएटर, ओवरले और SandboxedSdkView के साथ एक लेआउट बनाता है.
2. मीडिएटर, इस विज्ञापन के लिए विज्ञापन देने वाले को चुनता है.
3. मध्यस्थ, मध्यस्थता में शामिल व्यक्ति से SandboxedUiAdapter पाता है.
4. मीडिएटर, मीडिएट किए जाने वाले व्यक्ति के UiAdapter को SandboxedSdkView पर सेट करता है.
5. मीडिएटर, अपने-आप भरी गई जानकारी वाले व्यू को ऐप्लिकेशन के साथ शेयर करता है.

RE Mediatee से मिले बैनर विज्ञापन पर व्यू को ओवरले करने का फ़्लो.

RE Mediatee के फ़ुल स्क्रीन विज्ञापन

ऐप्लिकेशन से फ़ुल-स्क्रीन विज्ञापन लोड करने का अनुरोध मिलने पर, यह फ़्लो इन चरणों के हिसाब से काम करता है:

1. ऐप्लिकेशन (या RA SDK टूल), विज्ञापन लोड करने के अनुरोध के साथ मीडिएटर को SdkActivityLauncher भेजता है.
   1. क्लाइंट, प्रेडिकेट का इस्तेमाल करके गतिविधियों को बनाने पर पाबंदी लगा सकता है.
2. मीडिएटर, इस विज्ञापन के लिए विज्ञापन देने वाले को चुनता है.
3. मीडिएटर, ऐप्लिकेशन से SdkActivityLauncher को पास करके, मीडिएट करने वाले से विज्ञापन लोड करने का अनुरोध करता है.
4. मीडिएट करने वाला व्यक्ति, गतिविधि हैंडलर को रजिस्टर करता है और रजिस्टर की गई गतिविधि के लिए आइडेंटिफ़ायर टोकन पाता है.
5. मीडिएटर, इस टोकन का इस्तेमाल करके गतिविधि शुरू करने का अनुरोध करने के लिए, SdkActivityLauncher का इस्तेमाल करता है.
6. अगर क्लाइंट ऐप्लिकेशन का प्रीडिकेट इसकी अनुमति देता है, तो SDK टूल का रनटाइम, इस गतिविधि को खास प्रोसेस में शुरू करेगा.

**चौथी इमेज.** RE Mediatee से मीडिएट किए गए फ़ुल स्क्रीन विज्ञापन को लोड करने का तरीका बताने वाला फ़्लो डायग्राम.

ध्यान दें: गतिविधि के लाइफ़साइकल से जुड़े सभी इवेंट, मीडिएटर के लिए उपलब्ध होते हैं. इसके लिए, मीडिएटर को उस ActivityHolder का इस्तेमाल करना होता है जिसका इस्तेमाल उसने गतिविधि हैंडलर को रजिस्टर करते समय किया था.

SDK टूल के रनटाइम में, फ़ुल-स्क्रीन विज्ञापनों के लिए गतिविधि से जुड़ी सहायता के बारे में ज़्यादा जानें.

इन-ऐप्लिकेशन Mediatee

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

**पांचवीं इमेज.** मीडिएट, ऐप्लिकेशन से स्टैटिक तौर पर लिंक होता है. भले ही, उसे RE SDK टूल के बारे में पता हो.

डेटा लेयर में इवेंट बनाने की प्रोसेस

इस स्थिति में, मीडिएटर ऐप्लिकेशन से स्टैटिक तौर पर लिंक होते हैं और उन्हें अब तक SDK टूल के रनटाइम पर माइग्रेट नहीं किया गया है. इसलिए, मीडिएटर के रनटाइम की सुविधा वाले SDK टूल में उन्हें रजिस्टर करने की प्रोसेस होनी चाहिए.

इस रजिस्ट्रेशन को मीडिएटर के एपीआई का इस्तेमाल करके ऐक्सेस किया जा सकता है. हालांकि, इसे लागू करने की जानकारी, हर मीडिएटर के विवेक पर निर्भर करती है. हम इसे एपीआई कहेंगे MediationSandboxedSdk#registerInAppMediatee.

RE Mediator SDK टूल और इन-ऐप्लिकेशन Mediatee SDK टूल को शुरू करने, खोजने, और उनसे संपर्क करने के लिए, यह फ़्लो इन चरणों का पालन करेगा:

1. ऐप्लिकेशन, मीडिएटर के रनटाइम-अवेयर SDK टूल को लोड और शुरू करता है.
2. मीडिएटर का आरए SDK टूल:
   1. SdkSandboxManager#loadSdk का इस्तेमाल करके, मीडिएटर के RE SDK टूल को शुरू करता है.
   2. सभी इन-ऐप्लिकेशन मीडिएटर SDK टूल को शुरू करता है.
   3. यह MediationSandboxedSdk#registerInAppMediate के ज़रिए दिए गए एपीआई का इस्तेमाल करके, ऐप्लिकेशन में मौजूद ऐसे SDK टूल ढूंढता और रजिस्टर करता है जो मीडिएटर के तौर पर काम करते हैं.

मीडिएटर के RE SDK टूल में, इन-ऐप्लिकेशन मीडिएट किए जाने वाले सभी SDK टूल रजिस्टर होते हैं. साथ ही, SdkSandboxController#getSandboxedSdks का इस्तेमाल करके, SDK टूल के रनटाइम में लोड किए गए सभी SDK टूल का पता लगाया जा सकता है.

**छठी इमेज.** ध्यान दें कि हम सुझाए गए मीडिएटर के एपीआई का इस्तेमाल करके, इन-ऐप्लिकेशन मीडिएट किए जाने वाले उपयोगकर्ताओं के रेफ़रंस को रजिस्टर करते हैं.

विज्ञापन का यूज़र इंटरफ़ेस (यूआई) प्रज़ेंटेशन

इस सेक्शन में, इन-ऐप्लिकेशन मीडियाटी से बैनर और फ़ुल स्क्रीन विज्ञापन लोड करने के बारे में बताया गया है.

इन-ऐप्लिकेशन मीडिएटर बैनर विज्ञापन

ऐप्लिकेशन से बैनर विज्ञापन लोड करने का अनुरोध मिलने पर, रेंडरिंग पूरी करने का फ़्लो इस तरह से होता है:

1. मीडिएटर का रनटाइम-अवेयर SDK टूल, ऐप्लिकेशन के अनुरोध को अपने रनटाइम-इनेबल किए गए SDK टूल को भेजता है.
2. मीडिएटर का RE SDK टूल, मीडिएशन के लिए सही उपयोगकर्ता चुनता है.
3. मीडिएटर का RE SDK टूल, मीडिएट किए जाने वाले ऐप्लिकेशन का रेफ़रंस लेता है और RA SDK टूल के ज़रिए विज्ञापन लोड करने का अनुरोध करता है.
4. आरए एसडीके टूल, इन-ऐप्लिकेशन मीडिएटर से व्यू पाता है.
5. RA SDK टूल, मिले व्यू के लिए एक SandboxedUiAdapter बनाता है.
6. RA SDK टूल, UiAdapter को RE SDK टूल को फ़ॉरवर्ड करता है.
7. RE SDK टूल, UiAdapter को ऐप्लिकेशन पर फ़ॉरवर्ड करता है.

चेतावनी: यह SandboxedUiAdapter, ऐप्लिकेशन की प्रोसेस से मिलता है. इसलिए, हमारा सुझाव है कि इस व्यू में ओवरले न जोड़ें. ऐसा करने से, इंतज़ार का समय, परफ़ॉर्मेंस, और व्यवहार से जुड़ी समस्याएं हो सकती हैं.

**सातवीं इमेज.** ध्यान दें कि मीडिएटर को V1 को इन-ऐप्लिकेशन मीडिएट किए गए वीडियो से हासिल करते समय, उस पर व्यू ओवरले नहीं करने चाहिए.

ऐप्लिकेशन में दिखने वाले, मीडिएटर के ज़रिए दिखाए जाने वाले फ़ुल-स्क्रीन विज्ञापन

ऐप्लिकेशन से फ़ुल-स्क्रीन विज्ञापन लोड करने का अनुरोध मिलने पर, यह फ़्लो इन चरणों के हिसाब से काम करता है:

1. ऐप्लिकेशन, विज्ञापन लोड करने के अनुरोध के साथ, मीडिएटर के RA SDK टूल को SdkActivityLauncher भेजता है.
   1. क्लाइंट, प्रेडिकेट का इस्तेमाल करके गतिविधियों को बनाने पर पाबंदी लगा सकता है.
2. मीडिएटर का RA SDK टूल, ऐप्लिकेशन के अनुरोध को अपने RE SDK टूल को फ़ॉरवर्ड करता है.
3. मीडिएटर का RE SDK टूल:
   1. उस व्यक्ति को चुनता है जिसे मध्यस्थता करनी है.
   2. इन-ऐप्लिकेशन मीडिएटर का रेफ़रंस वापस लाता है.
   3. RA SDK टूल की मदद से विज्ञापन लोड करने का अनुरोध.
4. RA SDK टूल, मीडिएटर से विज्ञापन लोड करने का अनुरोध करता है.
5. मीडिएटर, गतिविधि को सीधे शुरू करता है. ऐप्लिकेशन के प्रेडिकेट को लागू नहीं किया जाएगा.

**आठवीं इमेज.** इन-ऐप्लिकेशन मीडिएटर, प्रेडिकेट को अनदेखा कर देगा.

ध्यान दें: गतिविधि से जुड़े सभी इवेंट, मीडिएटर के लिए वैसे ही उपलब्ध हैं जैसे वे SDK टूल के रनटाइम से पहले थे.

दर्शकों से जुड़ना और सुझाव, राय या शिकायत शेयर करना

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