आरंभ करें

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

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

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

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

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

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

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

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

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

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

    • Android पर, आपको एनडीके से मिले 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 टूल का दस्तावेज़ देखें.

सहमति लेने के लिए, नीचे दिया गया तरीका अपनाएं:

  1. उपयोगकर्ता की हाल ही की सहमति की जानकारी का अनुरोध.
  2. अगर ज़रूरी हो, तो सहमति फ़ॉर्म लोड करें और उसे लोगों को दिखाएं.

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

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

अगर ज़रूरी हो, तो निजता से जुड़ा मैसेज फ़ॉर्म लोड और दिखाएं

सहमति की अप-टू-डेट स्थिति मिलने के बाद, 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() का इस्तेमाल करके, उपयोगकर्ता से सहमति ली है या नहीं. सहमति लेते समय, इन दो जगहों पर जाकर देखें:

  • मौजूदा सेशन में सहमति मिलने के बाद.
  • RequestConsentInfoUpdate() को कॉल करने के तुरंत बाद. ऐसा हो सकता है कि सहमति पिछले सेशन में मिली हो. हमारा सुझाव है कि आप कॉलबैक के पूरा होने का इंतज़ार न करें. यह इंतज़ार करने का सबसे अच्छा तरीका है, ताकि आपके ऐप्लिकेशन के लॉन्च होने के बाद, विज्ञापन जल्द से जल्द लोड होने लगें.

अगर सहमति लेने की प्रोसेस के दौरान कोई गड़बड़ी होती है, तो भी आपको यह देखना चाहिए कि विज्ञापनों का अनुरोध किया जा सकता है या नहीं. 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();