फ़ुल-स्क्रीन विज्ञापनों के लिए गतिविधि से जुड़ी सहायता

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

SDK टूल के रनटाइम एनवायरमेंट में लोड किए गए SDK टूल, अपने मेनिफ़ेस्ट में सीधे तौर पर <activity> टैग तय नहीं कर सकते या अपनी गतिविधियां शुरू नहीं कर सकते. इसके बजाय, एक नई इंटेंट ऐक्शन, START_SANDBOXED_ACTIVITY को पेश किया गया है.

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

इसके बाद, SDK टूल इस गतिविधि का इस्तेमाल करके, फ़ुल स्क्रीन विज्ञापन अनुभव को लागू और मैनेज कर सकता है.

प्लैटफ़ॉर्म से मिलने वाली गतिविधि एक स्टैंडर्ड android.app.Activity होती है, जिसे क्लाइंट ऐप्लिकेशन के टास्क के हिस्से के तौर पर लॉन्च किया जाता है.

SDK टूल के रनटाइम पर गतिविधि बनाना

गतिविधियां बनाने के लिए, आपके पास दो मुख्य तरीके हैं: बेहतर बनाए गए Jetpack गतिविधि लाइब्रेरी का इस्तेमाल करना या सीधे तौर पर Platform API के साथ इंटरैक्ट करना.

हमारा सुझाव है कि आप गतिविधि लाइब्रेरी का इस्तेमाल करें. इनकी मदद से, गतिविधि बनाने की प्रोसेस आसान हो जाती है.

गतिविधि लाइब्रेरी

गतिविधि लाइब्रेरी से कई फ़ायदे मिलते हैं:

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

तीन ऐक्टिविटी लाइब्रेरी हैं: कोर, क्लाइंट, और प्रोवाइडर.

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

इन लाइब्रेरी में ये एपीआई शामिल हैं:

  • SdkActivityLauncher: गतिविधि लॉन्चर की मदद से, SDK टूल, क्लाइंट ऐप्लिकेशन से गतिविधियां लॉन्च कर सकते हैं. क्लाइंट ऐप्लिकेशन को एक लॉन्चर बनाना चाहिए और उसे गतिविधियां शुरू करने वाले SDK टूल के एपीआई को पैरामीटर के तौर पर पास करना चाहिए.
  • <T : Activity & LifecycleOwner> T.createSdkActivityLauncher(() -> Boolean ): यह एक एक्सटेंशन फ़ंक्शन है. क्लाइंट ऐप्लिकेशन, लॉन्चर बनाने के लिए अपनी गतिविधियों से इसे कॉल कर सकता है.
  • SdkActivityLauncher.launchSdkActivity(IBinder): ऐप्लिकेशन में गतिविधियां शुरू करने का अनुरोध करने के लिए, SDK टूल इस तरीके का इस्तेमाल करता है.

गतिविधि लाइब्रेरी की मदद से गतिविधियां शुरू करने का तरीका यहां बताया गया है:

  1. SDK टूल, गतिविधियां शुरू करने वाले किसी भी एपीआई में SdkActivityLauncher टाइप का पैरामीटर जोड़ता है.
  2. क्लाइंट ऐप्लिकेशन, अपनी किसी गतिविधि पर createSdkActivityLauncher को कॉल करता है, ताकि एक लॉन्चर बनाया जा सके. इस लॉन्चर को एपीआई कॉल पर SDK टूल को पास किया जा सकता है.
  3. SDK टूल, SdkSandboxControllerCompat.registerSdkSandboxActivityHandler(SdkSandboxActivityHandlerCompat) को कॉल करता है और आइडेंटिफ़ायर टोकन को वापस लाता है.
  4. गतिविधि लॉन्च करने के लिए, SDK launchSdkActivity को कॉल करता है.

नीचे दिया गया डायग्राम, गतिविधि लाइब्रेरी इस्तेमाल करने के मामले में फ़्लो दिखाता है.

गतिविधि लाइब्रेरी का क्रम डायग्राम
गतिविधि लाइब्रेरी का इस्तेमाल करके गतिविधि शुरू करने के फ़्लो को दिखाने वाला सिलसिलेवार डायग्राम.

प्लैटफ़ॉर्म एपीआई

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

  • SdkSandboxActivityHandler: ऐक्टिविटी बनाने पर, SDK टूल को सूचना देने के लिए ऐक्टिविटी हैंडलर का इस्तेमाल किया जाता है. साथ ही, SDK टूल इसे रजिस्टर करता है.
  • गतिविधि हैंडलर के रजिस्ट्रेशन में मदद करने के लिए, SDK टूल SdkSandboxController में दिए गए इन तरीकों का इस्तेमाल कर सकता है:
    • .registerSdkSandboxActivityHandler(SdkSandboxActivityHandler): SdkSandboxActivityHandler का एक इंस्टेंस रजिस्टर करता है, जो IBinder आइडेंटिफ़ायर दिखाता है.
    • .unregisterSdkSandboxActivityHandler(SdkSandboxActivityHandler): SdkSandboxActivityHandler के रजिस्टर किए गए किसी इंस्टेंस को उसके आइडेंटिफ़ायर का इस्तेमाल करके, रजिस्टर किए जाने की स्थिति से हटाता है.
  • SdkSandboxManager.startSdkSandboxActivity(Activity, IBinder): क्लाइंट ऐप्लिकेशन से शुरू किया जाने वाला यह तरीका, SDK टूल के लिए गतिविधियों को बनाने की प्रोसेस को ट्रिगर करता है. क्लाइंट ऐप्लिकेशन को पैरामीटर के तौर पर, अपनी चुनी गई शुरुआती गतिविधि और SDK के गतिविधि हैंडलर आइडेंटिफ़ायर को पास करना होगा.

Platform API का इस्तेमाल करके कोई गतिविधि शुरू करने के लिए, SDK को यह तरीका अपनाना होगा:

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

प्लैटफ़ॉर्म एपीआई का इस्तेमाल करने पर, एसडीके टूल को SdkSandboxActivityHandler का आइडेंटिफ़ायर, अपने एपीआई के ज़रिए सही समय पर क्लाइंट ऐप्लिकेशन के साथ शेयर करना होता है. साथ ही, क्लाइंट ऐप्लिकेशन को इसका इस्तेमाल करने का तरीका बताना होता है.

नीचे दिए गए फ़्लो डायग्राम में, उदाहरण के तौर पर दिए गए SDK टूल में एक तरीका launchActivity(AppCallback) है, जिसमें कॉलबैक की ज़रूरत होती है. इसे SDK टूल के एपीआई के हिस्से के तौर पर तय किया गया है. SDK टूल, इस कॉलबैक का इस्तेमाल क्लाइंट ऐप्लिकेशन के साथ गतिविधि हैंडलर (SdkSandboxActivityHandler) का आइडेंटिफ़ायर शेयर करने के लिए करता है.

Platform APIs का सीक्वेंस डायग्राम
प्लेटफ़ॉर्म एपीआई का इस्तेमाल करके गतिविधि शुरू करने के फ़्लो को दिखाने वाला क्रम डायग्राम.

विज्ञापन दिखने से जुड़े आंकड़े

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

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

इसके उलट, प्लैटफ़ॉर्म की ओर से दी गई गतिविधि, SDK टूल के रनटाइम प्रोसेस में नेटिव तौर पर चलती है. इससे साइड चैनलों की ज़रूरत नहीं पड़ती और SDK टूल, स्टैंडर्ड Android Activity और View एपीआई का इस्तेमाल कर पाते हैं.

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

जीवनचक्र

SdkSandboxActivityHandlerCompat.onActivityCreated(ActivityHolder) के ज़रिए SDK टूल को भेजा गया ActivityHolder, LifecycleOwner को लागू करता है. साथ ही, इसका इस्तेमाल Lifecycle.Event के बारे में जानने के लिए किया जा सकता है.

पिछले पेज पर जाने का नेविगेशन

यह तरीका ActivityHolder.getOnBackPressedDispatcher() OnBackPressedDispatcher को दिखाता है. इसका इस्तेमाल, बैक नेविगेशन को मैनेज करने के लिए, OnBackPressedCallback के इंस्टेंस रजिस्टर करने के लिए किया जा सकता है.