शुरू करना

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

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

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

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

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

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

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

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

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

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

    • Android पर, आपको एनडीके से मिले 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 इंस्टेंस को मिटाकर, SDK टूल को बंद किया जा सकता है:

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

एसिंक्रोनस कार्रवाइयों को मॉनिटर करने के लिए, Future का इस्तेमाल करना

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

एसिंक्रोनस तरीके से काम करने वाले सभी यूएमपी 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, ऐप्लिकेशन के पिछले सेशन में मिली सहमति की स्थिति का इस्तेमाल करता है.

विज्ञापन दिखाने के लिए बार-बार अनुरोध करने से बचें

सहमति लेने और RequestConsentInfoUpdate() को कॉल करने के बाद, ConsentInfo::GetInstance()‑> CanRequestAds() की जांच करते समय पक्का करें कि आपका लॉजिक, विज्ञापन दिखाने के ऐसे अनुरोधों को रोकता हो जिनकी ज़रूरत नहीं है. ऐसा न होने पर, दोनों जांचों के नतीजे के तौर पर true मिल सकता है. उदाहरण के लिए, बूलियन वैरिएबल के साथ.

यहां दिए गए उदाहरण में, अपडेट लूप पोलिंग का इस्तेमाल किया गया है. हालांकि, एसिंक्रोनस कार्रवाइयों को मॉनिटर करने के लिए, 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();