शुरू करना

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

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

  • Android API लेवल 21 या इसके बाद का वर्शन (Android के लिए)

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

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

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

एसडीके टूल इंस्टॉल करना

  1. Firebase C++ SDK टूल इंस्टॉल करने के लिए, यह तरीका अपनाएं. UMP C++ SDK, Firebase C++ SDK में शामिल है.

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

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

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

namespace ump = ::firebase::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 इंस्टेंस को मिटाकर एसडीके को बंद किया जा सकता है:

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/ump/ump.h"

namespace ump = ::firebase::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/ump/ump.h"

namespace ump = ::firebase::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/ump/ump.h"

namespace gma = ::firebase::gma;
namespace ump = ::firebase::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 टूल की स्थिति रीसेट करने में मदद मिल सकती है. इससे, उपयोगकर्ता के लिए ऐप्लिकेशन को पहली बार इंस्टॉल करने का अनुभव सिम्युलेट किया जा सकता है. एसडीके, ऐसा करने के लिए Reset() तरीका उपलब्ध कराता है.

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