आरंभ करें

Google User Messaging Platform (UMP) SDK टूल, निजता और मैसेज सेवा के लिए एक टूल है. इससे आपको निजता के विकल्प मैनेज करने में मदद मिलती है. ज़्यादा जानकारी के लिए, निजता और मैसेज सेवा के बारे में जानकारी देखें.

ज़रूरी शर्तें

  • Android के लिए, एपीआई लेवल 21 या उसके बाद का वर्शन

मैसेज टाइप बनाना

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

ज़्यादा जानकारी के लिए, निजता और मैसेज सेवा के बारे में जानकारी देखें.

SDK टूल इंस्टॉल करना

  1. Google Mobile Ads (GMA) C++ SDK टूल को इंस्टॉल करने के लिए, यह तरीका अपनाएं. UMP C++ SDK टूल, GMA C++ SDK टूल में शामिल है.

  2. जारी रखने से पहले, पक्का करें कि आपने प्रोजेक्ट में अपने ऐप्लिकेशन का AdMob ऐप्लिकेशन आईडी कॉन्फ़िगर किया हो.

  3. अपने कोड में, ConsentInfo::GetInstance() को कॉल करके UMP SDK टूल को शुरू करें.

    • Android पर, आपको NDK से मिले JNIEnv और Activity को पास करना होगा. आपको ऐसा सिर्फ़ पहली बार GetInstance() को कॉल करते समय करना होगा.
    • इसके अलावा, अगर आपके ऐप्लिकेशन में पहले से ही Firebase C++ SDK टूल का इस्तेमाल किया जा रहा है, तो GetInstance() को पहली बार कॉल करते समय, firebase::App को पास किया जा सकता है.
    #include "firebase/gma/ump.h"

namespace ump = ::firebase::gma::ump;

// Initialize using a firebase::App
void InitializeUserMessagingPlatform(const firebase::App& app) {
  ump::ConsentInfo* consent_info = ump::ConsentInfo::GetInstance(app);
}

// Initialize without a firebase::App
#ifdef ANDROID
void InitializeUserMessagingPlatform(JNIEnv* jni_env, jobject activity) {
  ump::ConsentInfo* consent_info = ump::ConsentInfo::GetInstance(jni_env, activity);
}
#else  // non-Android
void InitializeUserMessagingPlatform() {
  ump::ConsentInfo* consent_info = ump::ConsentInfo::GetInstance();
}
#endif

ConsentInfo::GetInstance() को बाद में किए जाने वाले सभी कॉल, एक ही इंस्टेंस दिखाते हैं.

अगर आपको UMP SDK का इस्तेमाल नहीं करना है, तो ConsentInfo इंस्टेंस को मिटाकर, SDK टूल को बंद किया जा सकता है:

void ShutdownUserMessagingPlatform() {
  ump::ConsentInfo* consent_info = ump::ConsentInfo::GetInstance();
  delete consent_info;
}

असिंक्रोनस ऑपरेशन को मॉनिटर करने के लिए, Future का इस्तेमाल करना

firebase::Future की मदद से, एसिंक्रोनस तरीके से कॉल करने की प्रोसेस पूरी होने की स्थिति का पता लगाया जा सकता है.

एसिंक्रोनस तरीके से काम करने वाले सभी UMP C++ फ़ंक्शन और तरीकों के कॉल, एक Future दिखाते हैं. साथ ही, सबसे हाल ही के ऑपरेशन से Future पाने के लिए, "पिछला नतीजा" फ़ंक्शन भी देते हैं.

Future से नतीजा पाने के दो तरीके हैं:

  1. OnCompletion() को कॉल करें और अपने कॉलबैक फ़ंक्शन को पास करें. ऑपरेशन पूरा होने पर, इस फ़ंक्शन को कॉल किया जाता है.
  2. समय-समय पर Future के status() की जांच करें. जब स्टेटस kFutureStatusPending से kFutureStatusCompleted में बदल जाता है, तो इसका मतलब है कि कार्रवाई पूरी हो गई है.

असाइनमेंट पूरा होने के बाद, आपको ऑपरेशन की गड़बड़ी का कोड पाने के लिए, Future के error() की जांच करनी चाहिए. अगर गड़बड़ी का कोड 0 (kConsentRequestSuccess या kConsentFormSuccess) है, तो इसका मतलब है कि कार्रवाई पूरी हो गई है. अगर ऐसा नहीं है, तो गड़बड़ी का कोड और error_message() देखें और जानें कि क्या गड़बड़ी हुई है.

प्रोसेस पूरी होने पर कॉलबैक

यहां एक उदाहरण दिया गया है, जिसमें OnCompletion का इस्तेमाल करके, कार्रवाई पूरी होने पर कॉलबैक सेट करने का तरीका बताया गया है. यह कॉलबैक तब ट्रिगर होता है, जब असाइनमेंट के साथ-साथ दूसरी प्रोसेस भी चल रही हो.

void MyApplicationStart() {
  // [... other app initialization code ...]

  ump::ConsentInfo *consent_info = ump::ConsentInfo::GetInstance();

  // See the section below for more information about RequestConsentInfoUpdate.
  firebase::Future<void> result = consent_info->RequestConsentInfoUpdate(...);

  result.OnCompletion([](const firebase::Future<void>& req_result) {
    if (req_result.error() == ump::kConsentRequestSuccess) {
      // Operation succeeded. You can now call LoadAndShowConsentFormIfRequired().
    } else {
      // Operation failed. Check req_result.error_message() for more information.
    }
  });
}

अपडेट लूप पोलिंग

इस उदाहरण में, ऐप्लिकेशन लॉन्च होने पर असाइनिमेंट शुरू होने के बाद, गेम के अपडेट लूप फ़ंक्शन (जो हर फ़्रेम में एक बार चलता है) में, नतीजों की जांच कहीं और की जाती है.

ump::ConsentInfo *g_consent_info = nullptr;
bool g_waiting_for_request = false;

void MyApplicationStart() {
  // [... other app initialization code ...]

  g_consent_info = ump::ConsentInfo::GetInstance();
  // See the section below for more information about RequestConsentInfoUpdate.
  g_consent_info->RequestConsentInfoUpdate(...);
  g_waiting_for_request = true;
}

// Elsewhere, in the game's update loop, which runs once per frame:
void MyGameUpdateLoop() {
  // [... other game logic here ...]

  if (g_waiting_for_request) {
    // Check whether RequestConsentInfoUpdate() has finished.
    // Calling "LastResult" returns the Future for the most recent operation.
    firebase::Future<void> result =
      g_consent_info->RequestConsentInfoUpdateLastResult();

    if (result.status() == firebase::kFutureStatusComplete) {
      g_waiting_for_request = false;
      if (result.error() == ump::kConsentRequestSuccess) {
        // Operation succeeded. You can call LoadAndShowConsentFormIfRequired().
      } else {
        // Operation failed. Check result.error_message() for more information.
      }
    }
  }
}

firebase::Future के बारे में ज़्यादा जानकारी के लिए, Firebase C++ SDK टूल का दस्तावेज़ और GMA C++ SDK टूल का दस्तावेज़ देखें.

आपको RequestConsentInfoUpdate() का इस्तेमाल करके, ऐप्लिकेशन के हर लॉन्च पर उपयोगकर्ता की सहमति की जानकारी को अपडेट करने का अनुरोध करना चाहिए. इस अनुरोध से इन बातों की जांच की जाती है:

  • क्या सहमति लेना ज़रूरी है. उदाहरण के लिए, पहली बार सहमति लेना ज़रूरी है या सहमति के लिए पहले लिए गए फ़ैसले की समयसीमा खत्म हो गई है.
  • क्या निजता विकल्पों के एंट्री पॉइंट की ज़रूरत है. निजता से जुड़े कुछ मैसेज दिखाने के लिए, ऐप्लिकेशन को यह ज़रूरी है कि वे उपयोगकर्ताओं को निजता के विकल्पों में किसी भी समय बदलाव करने की अनुमति दें.
#include "firebase/gma/ump.h"

namespace ump = ::firebase::gma::ump;

void MyApplicationStart(ump::FormParent parent) {
  ump::ConsentInfo* consent_info = ump::ConsentInfo::GetInstance();

  // Create a ConsentRequestParameters struct..
  ump::ConsentRequestParameters params;
  // Set tag for under age of consent. False means users are NOT under age of consent.
  params.tag_for_under_age_of_consent = false;

  consent_info->RequestConsentInfoUpdate(params).OnCompletion(
    [*](const Future<void>& req_result) {
      if (req_result.error() != ump::kConsentRequestSuccess) {
        // req_result.error() is a kConsentRequestError enum.
        LogMessage("Error requesting consent update: %s", req_result.error_message());
      }
      // Consent information is successfully updated.
    });
}

निजता से जुड़ा मैसेज फ़ॉर्म लोड करना और दिखाना

सहमति का सबसे अप-टू-डेट स्टेटस मिलने के बाद, उपयोगकर्ता की सहमति इकट्ठा करने के लिए ज़रूरी फ़ॉर्म लोड करने के लिए, LoadAndShowConsentFormIfRequired() को कॉल करें. लोड होने के बाद, फ़ॉर्म तुरंत दिखने लगते हैं.

#include "firebase/gma/ump.h"

namespace ump = ::firebase::gma::ump;

void MyApplicationStart(ump::FormParent parent) {
  ump::ConsentInfo* consent_info = ump::ConsentInfo::GetInstance();

  // Create a ConsentRequestParameters struct..
  ump::ConsentRequestParameters params;
  // Set tag for under age of consent. False means users are NOT under age of consent.
  params.tag_for_under_age_of_consent = false;

  consent_info->RequestConsentInfoUpdate(params).OnCompletion(
    [*](const Future<void>& req_result) {
      if (req_result.error() != ump::kConsentRequestSuccess) {
        // req_result.error() is a kConsentRequestError enum.
        LogMessage("Error requesting consent update: %s", req_result.error_message());
      } else {
        consent_info->LoadAndShowConsentFormIfRequired(parent).OnCompletion(
        [*](const Future<void>& form_result) {
          if (form_result.error() != ump::kConsentFormSuccess) {
            // form_result.error() is a kConsentFormError enum.
            LogMessage("Error showing privacy message form: %s", form_result.error_message());
          } else {
            // Either the form was shown and completed by the user, or consent was not required.
          }
        });
      }
    });
}

'पूरा होने पर कॉलबैक' के बजाय, अपडेट लूप पोलिंग का इस्तेमाल करके, प्रोसेस पूरी होने की जांच करने का उदाहरण देखने के लिए, ऊपर देखें.

अगर उपयोगकर्ता ने कोई विकल्प चुना है या फ़ॉर्म को खारिज करने के बाद, आपको कोई कार्रवाई करनी है, तो उस लॉजिक को उस कोड में डालें जो LoadAndShowConsentFormIfRequired() से मिले Future को मैनेज करता है.

निजता के विकल्प

निजता से जुड़े कुछ मैसेज फ़ॉर्म, पब्लिशर के रेंडर किए गए निजता विकल्पों के एंट्री पॉइंट से दिखाए जाते हैं. इससे उपयोगकर्ता, निजता के विकल्पों को कभी भी मैनेज कर सकते हैं. इस बारे में ज़्यादा जानने के लिए कि निजता के विकल्पों के एंट्री पॉइंट पर, आपके उपयोगकर्ताओं को कौनसा मैसेज दिखता है, उपयोगकर्ताओं के लिए उपलब्ध मैसेज टाइप देखें.

उपयोगकर्ता की सहमति के साथ विज्ञापन दिखाने का अनुरोध करना

विज्ञापनों का अनुरोध करने से पहले, ConsentInfo::GetInstance()‑> CanRequestAds() का इस्तेमाल करके देखें कि आपने उपयोगकर्ता से सहमति ली है या नहीं:

यहां कुछ जगहों के बारे में बताया गया है जहां यह देखा जा सकता है कि सहमति लेते समय, विज्ञापन दिखाने का अनुरोध किया जा सकता है या नहीं:

  • UMP SDK टूल, मौजूदा सेशन में सहमति लेने के बाद.
  • RequestConsentInfoUpdate() को कॉल करने के तुरंत बाद. हो सकता है कि UMP SDK टूल ने, ऐप्लिकेशन के पिछले सेशन में सहमति ली हो.
को कॉल नहीं किया है

अगर सहमति लेने की प्रोसेस के दौरान कोई गड़बड़ी होती है, तो देखें कि आपके पास विज्ञापनों का अनुरोध करने का विकल्प है या नहीं. UMP SDK टूल, ऐप्लिकेशन के पिछले सेशन की सहमति की स्थिति का इस्तेमाल करता है.

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

#include "firebase/future.h"
#include "firebase/gma/gma.h"
#include "firebase/gma/ump.h"

namespace gma = ::firebase::gma;
namespace ump = ::firebase::gma::ump;
using firebase::Future;

ump::ConsentInfo* g_consent_info = nullptr;
// State variable for tracking the UMP consent flow.
enum { kStart, kRequest, kLoadAndShow, kInitGma, kFinished, kErrorState } g_state = kStart;
bool g_ads_allowed = false;

void MyApplicationStart() {
  g_consent_info = ump::ConsentInfo::GetInstance(...);

  // Create a ConsentRequestParameters struct..
  ump::ConsentRequestParameters params;
  // Set tag for under age of consent. False means users are NOT under age of consent.
  params.tag_for_under_age_of_consent = false;

  g_consent_info->RequestConsentInfoUpdate(params);
  // CanRequestAds() can return a cached value from a previous run immediately.
  g_ads_allowed = g_consent_info->CanRequestAds();
  g_state = kRequest;
}

// This function runs once per frame.
void MyGameUpdateLoop() {
  // [... other game logic here ...]

  if (g_state == kRequest) {
    Future<void> req_result = g_consent_info->RequestConsentInfoUpdateLastResult();

    if (req_result.status() == firebase::kFutureStatusComplete) {
      g_ads_allowed = g_consent_info->CanRequestAds();
      if (req_result.error() == ump::kConsentRequestSuccess) {
        // You must provide the FormParent (Android Activity or iOS UIViewController).
        ump::FormParent parent = GetMyFormParent();
        g_consent_info->LoadAndShowConsentFormIfRequired(parent);
        g_state = kLoadAndShow;
      } else {
        LogMessage("Error requesting consent status: %s", req_result.error_message());
        g_state = kErrorState;
      }
    }
  }
  if (g_state == kLoadAndShow) {
    Future<void> form_result = g_consent_info->LoadAndShowConsentFormIfRequiredLastResult();

    if (form_result.status() == firebase::kFutureStatusComplete) {
      g_ads_allowed = g_consent_info->CanRequestAds();
      if (form_result.error() == ump::kConsentRequestSuccess) {
        if (g_ads_allowed) {
          // Initialize GMA. This is another asynchronous operation.
          firebase::gma::Initialize();
          g_state = kInitGma;
        } else {
          g_state = kFinished;
        }
        // Optional: shut down the UMP SDK to save memory.
        delete g_consent_info;
        g_consent_info = nullptr;
      } else {
        LogMessage("Error displaying privacy message form: %s", form_result.error_message());
        g_state = kErrorState;
      }
    }
  }
  if (g_state == kInitGma && g_ads_allowed) {
    Future<gma::AdapterInitializationStatus> gma_future = gma::InitializeLastResult();

    if (gma_future.status() == firebase::kFutureStatusComplete) {
      if (gma_future.error() == gma::kAdErrorCodeNone) {
        g_state = kFinished;
        // TODO: Request an ad.
      } else {
        LogMessage("Error initializing GMA: %s", gma_future.error_message());
        g_state = kErrorState;
      }
    }
  }
}

टेस्ट करना

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

  1. RequestConsentInfoUpdate() पर कॉल करें.

  2. लॉग आउट में, नीचे दिए गए उदाहरण से मिलते-जुलते मैसेज देखें. इसमें आपका डिवाइस आईडी और उसे टेस्ट डिवाइस के तौर पर जोड़ने का तरीका दिखता है:

    Android

    Use new ConsentDebugSettings.Builder().addTestDeviceHashedId("33BE2250B43518CCDA7DE426D04EE231")
to set this as a debug device.

    iOS

    <UMP SDK>To enable debug mode for this device,
set: UMPDebugSettings.testDeviceIdentifiers = @[2077ef9a63d2b398840261c8221a0c9b]

  3. अपने टेस्ट डिवाइस का आईडी, क्लिपबोर्ड पर कॉपी करें.

  4. अपने कोड में बदलाव करके, ConsentRequestParameters.debug_settings.debug_device_ids को अपने टेस्ट डिवाइस आईडी की सूची में सेट करें.

    void MyApplicationStart() {
  ump::ConsentInfo consent_info = ump::ConsentInfo::GetInstance(...);

  ump::ConsentRequestParameters params;
  params.tag_for_under_age_of_consent = false;
  params.debug_settings.debug_device_ids = {"TEST-DEVICE-HASHED-ID"};

  consent_info->RequestConsentInfoUpdate(params);
}

किसी देश या इलाके के लिए ज़रूरी शर्तें तय करना

UMP SDK टूल की मदद से, अपने ऐप्लिकेशन के व्यवहार की जांच की जा सकती है. ऐसा करने के लिए, debug_settings.debug_geography का इस्तेमाल करके यह माना जाता है कि डिवाइस ईईए या यूके जैसे अलग-अलग इलाकों में है. ध्यान दें कि डीबग सेटिंग सिर्फ़ टेस्ट डिवाइसों पर काम करती हैं.

void MyApplicationStart() {
  ump::ConsentInfo consent_info = ump::ConsentInfo::GetInstance(...);

  ump::ConsentRequestParameters params;
  params.tag_for_under_age_of_consent = false;
  params.debug_settings.debug_device_ids = {"TEST-DEVICE-HASHED-ID"};
  // Geography appears as EEA for debug devices.
  params.debug_settings.debug_geography = ump::kConsentDebugGeographyEEA

  consent_info->RequestConsentInfoUpdate(params);
}

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

  ConsentInfo::GetInstance()->Reset();