شروع کنید

Google User Messaging Platform (UMP) SDK ابزاری برای حفظ حریم خصوصی و پیام‌رسانی است که به شما در مدیریت انتخاب‌های حریم خصوصی کمک می‌کند. برای اطلاعات بیشتر، درباره حریم خصوصی و پیام‌رسانی را ببینید.

پیش نیازها

• Android API سطح 21 یا بالاتر (برای اندروید)

یک نوع پیام ایجاد کنید

پیام‌های کاربر را با یکی از انواع پیام‌های کاربر موجود در برگه حریم خصوصی و پیام‌رسانی حساب AdMob خود ایجاد کنید. UMP SDK سعی می‌کند پیام حریم خصوصی ایجاد شده از AdMob Application ID را در پروژه شما نمایش دهد.

برای جزئیات بیشتر، درباره حریم خصوصی و پیام‌رسانی را ببینید.

SDK را نصب کنید

1. مراحل نصب Google Mobile Ads (GMA) C++ SDK را دنبال کنید. UMP C++ SDK در GMA C++ SDK گنجانده شده است.

2. قبل از ادامه، مطمئن شوید که شناسه برنامه AdMob برنامه خود را در پروژه پیکربندی کرده اید.

3. در کد خود، UMP SDK را با فراخوانی ConsentInfo::GetInstance() مقداردهی اولیه کنید.

   • در Android، باید JNIEnv و Activity ارائه شده توسط NDK را پاس کنید. فقط باید اولین باری که 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() همگی همان نمونه را برمی گرداند.

توجه: متدهای GetInstance() یک پارامتر خروجی firebase::InitResult اختیاری دارند که اگر SDK با موفقیت راه اندازی شد، firebase::kInitResultSuccess یا اگر وابستگی های مورد نیاز در برنامه شما وجود نداشته باشد firebase::kInitResultFailedMissingDependency برمی گرداند. در صورت بروز این خطا، مطمئن شوید که تمام مراحل نصب پلتفرم خود را دنبال کرده اید.

اگر استفاده از UMP SDK را تمام کرده‌اید، می‌توانید با حذف نمونه ConsentInfo ، SDK را خاموش کنید:

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

توجه: لازم نیست قبل از راه‌اندازی SDK پلتفرم پیام‌رسانی کاربر، کیت توسعه نرم‌افزار Google Mobile Ads C++ را مقداردهی اولیه کنید.

از Future برای نظارت بر عملیات ناهمزمان استفاده کنید

firebase::Future راهی برای تعیین وضعیت تکمیل فراخوانی متدهای ناهمزمان در اختیار شما قرار می دهد.

همه توابع UMP C++ و فراخوانی‌های متد که به صورت ناهمزمان عمل می‌کنند، Future برمی‌گردانند، و همچنین یک تابع "آخرین نتیجه" را برای بازیابی Future از آخرین عملیات ارائه می‌دهند.

دو راه برای به دست آوردن نتیجه از Future وجود دارد:

1. فراخوانی OnCompletion() ، که تابع callback خودتان را ارسال می کند، که پس از اتمام عملیات فراخوانی می شود.
2. به صورت دوره ای status() Future را بررسی کنید. وقتی وضعیت از kFutureStatusPending به kFutureStatusCompleted تغییر کرد، عملیات تکمیل شده است.

پس از اتمام عملیات ناهمزمان، باید error() Future را بررسی کنید تا کد خطای عملیات را بدست آورید. اگر کد خطا 0 باشد ( kConsentRequestSuccess یا kConsentFormSuccess )، عملیات با موفقیت انجام شد. در غیر این صورت، کد خطا و error_message() را بررسی کنید تا مشخص شود چه مشکلی رخ داده است.

توجه: کد خطای بازگردانده شده توسط RequestConsentInfoUpdate() از enum ConsentRequestError استفاده می کند. تمام عملیات های دیگر از ConsentFormError استفاده می کنند.

تکمیل تماس پاسخ

در اینجا مثالی از نحوه استفاده از 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 مراجعه کنید.

توجه: در UMP C++ SDK، همه عملیات ناهمزمان firebase::Future<void> .

جلب رضایت

برای جلب رضایت، مراحل زیر را انجام دهید:

1. درخواست برای آخرین اطلاعات رضایت کاربر.
2. در صورت نیاز فرم رضایت نامه را بارگیری و ارائه دهید.

درخواست اطلاعات رضایت

باید در هر راه اندازی برنامه با استفاده از RequestConsentInfoUpdate() درخواست به روز رسانی اطلاعات رضایت کاربر را بدهید. این درخواست موارد زیر را بررسی می کند:

• آیا رضایت لازم است . به عنوان مثال، برای بار اول رضایت لازم است، یا تصمیم قبلی رضایت منقضی شده است.
• آیا یک نقطه ورود گزینه های حریم خصوصی مورد نیاز است یا خیر . برخی از پیام‌های حریم خصوصی به برنامه‌ها نیاز دارند که به کاربران اجازه دهند گزینه‌های حریم خصوصی خود را در هر زمان تغییر دهند.

هشدار: اگر رضایت منقضی شده باشد، استفاده از روش‌های دیگر برای بررسی وضعیت رضایت، مانند حافظه پنهان در برنامه یا رشته رضایت قبلی ذخیره شده، می‌تواند منجر به خطای TCF 3.3 شود.

در صورت نیاز فرم پیام حریم خصوصی را بارگیری و ارائه دهید

پس از دریافت به‌روزترین وضعیت رضایت، با 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.
          }
        });
      }
    });
}

برای مثالی از بررسی تکمیل با استفاده از نظرسنجی حلقه به روز رسانی به جای پاسخ به تماس تکمیل، به بالا مراجعه کنید.

توجه: بسته به پلتفرم، FormParent یا یک مرجع JNI jobject به یک Android Activity است، یا یک اشاره‌گر به یک iOS UIViewController است که به یک نوع FormParent ارسال می‌شود.

اگر بعد از انتخاب کاربر یا رد کردن فرم، نیاز به انجام هر کاری دارید، آن منطق را در کدی قرار دهید که Future که توسط LoadAndShowConsentFormIfRequired() بازگردانده شده است قرار دهید.

گزینه های حفظ حریم خصوصی

برخی از فرم‌های پیام حریم خصوصی از نقطه ورود گزینه‌های حریم خصوصی ارائه‌شده توسط ناشر ارائه می‌شوند و به کاربران اجازه می‌دهند گزینه‌های حریم خصوصی خود را در هر زمان مدیریت کنند. برای اطلاعات بیشتر در مورد پیامی که کاربران شما در نقطه ورودی گزینه‌های حریم خصوصی می‌بینند، به انواع پیام‌های کاربر موجود مراجعه کنید.

درخواست تبلیغات

قبل از درخواست تبلیغات در برنامه خود، بررسی کنید که آیا رضایت کاربر را با استفاده از ConsentInfo::GetInstance()‑> CanRequestAds() دریافت کرده اید. هنگام جمع آوری رضایت دو مکان برای بررسی وجود دارد:

• پس از کسب رضایت در جلسه جاری.
• بلافاصله پس از اینکه RequestConsentInfoUpdate() فراخوانی کردید. امکان دارد در جلسه قبل رضایت گرفته شده باشد. به‌عنوان بهترین روش تأخیر، توصیه می‌کنیم منتظر تکمیل تماس نمانید تا بتوانید در اسرع وقت پس از راه‌اندازی برنامه، بارگیری تبلیغات را شروع کنید.

توجه: ConsentInfo::GetInstance()‑> CanRequestAds() همیشه false برمی گرداند تا زمانی که 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. خروجی گزارش را برای پیامی شبیه به مثال زیر بررسی کنید، که شناسه دستگاه شما و نحوه افزودن آن را به عنوان یک دستگاه آزمایشی نشان می دهد:

   اندروید

   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 ، روشی را برای آزمایش رفتار برنامه شما ارائه می‌کند که گویی دستگاه در مناطق مختلفی مانند EEA یا بریتانیا قرار دارد. توجه داشته باشید که تنظیمات اشکال زدایی فقط در دستگاه های آزمایشی کار می کند.

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();

احتیاط: این روش فقط برای اهداف آزمایشی استفاده می شود. شما نباید Reset() در کد تولید فراخوانی کنید.