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

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

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

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

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 Runtime में मीडिएशन को समझने के लिए, इन शब्दों के बारे में जानना ज़रूरी है:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

RE Mediatee

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

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

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

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

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

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

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

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

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

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

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

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

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

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

RE Mediatee full-screen ads

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

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

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

ऐप्लिकेशन में विज्ञापन दिखाने वाली कंपनी

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

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

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

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

RE mediator SDK टूल और ऐप्लिकेशन में मौजूद mediatee SDK टूल को शुरू करने, खोजने, और उनसे कम्यूनिकेट करने के लिए, यह तरीका अपनाया जाएगा:

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

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

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

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

ऐप्लिकेशन में दिखने वाले मीडिएट किए गए बैनर विज्ञापन

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

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

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

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

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

उपयोग करना और सुझाव/राय देना या शिकायत करना

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