शुरू करना

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

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

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

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

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

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

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

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

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

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

    • 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 इंस्टेंस को मिटाकर, SDK को बंद किया जा सकता है:

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

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

A 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, पिछले ऐप्लिकेशन सेशन से सहमति की स्थिति का इस्तेमाल करता है.

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

सहमति इकट्ठा करने के बाद और 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 की स्थिति रीसेट करना मददगार साबित हो सकता है. इससे, उपयोगकर्ता के पहले इंस्टॉलेशन के अनुभव को सिम्युलेट किया जा सकता है. इसके लिए, SDK में Reset() तरीका उपलब्ध है.

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