شروع کنید

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

پیش نیازها

  • Android API سطح 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 ارائه شده توسط 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() همگی همان نمونه را برمی گرداند.

اگر استفاده از 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() ، که تابع callback خودتان را ارسال می کند، که پس از اتمام عملیات فراخوانی می شود.
  2. به صورت دوره ای status() Future را بررسی کنید. وقتی وضعیت از kFutureStatusPending به kFutureStatusCompleted تغییر کرد، عملیات تکمیل شده است.

پس از اتمام عملیات ناهمزمان، باید error() Future را بررسی کنید تا کد خطای عملیات را بدست آورید. اگر کد خطا 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 مراجعه کنید.

شناسه برنامه را اضافه کنید

می‌توانید شناسه برنامه خود را در رابط کاربری AdMobپیدا کنید.شناسه را با قطعه کد زیر به:

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

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

namespace ump = ::firebase::gma::ump;

void MyApplicationStart() {
  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>& result) {
      if (result.error() != ump::kConsentRequestSuccess) {
        LogMessage("Error requesting consent update: %s", result.error_message());
      } else {
        // Consent status is now available.
      }
    });
}

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

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

پس از دریافت به‌روزترین وضعیت رضایت، باLoadAndShowConsentFormIfRequired() تماس بگیرید تا فرم‌های مورد نیاز برای دریافت رضایت کاربر بارگیری شود. پس از بارگذاری، فرم ها بلافاصله ارائه می شوند.

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.
          }
        });
      }
    });
}

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

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

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

برای پیاده سازی یک نقطه ورود گزینه های حریم خصوصی، مراحل زیر را انجام دهید:

  1. getPrivacyOptionsRequirementStatus()بررسی کنید.
  2. اگر به نقطه ورود گزینه های حریم خصوصی نیاز است، یک عنصر رابط کاربری قابل مشاهده و قابل تعامل به برنامه خود اضافه کنید.
  3. فرم گزینه های حریم خصوصی را با استفاده ازshowPrivacyOptionsForm()فعال کنید.

مثال کد زیر این مراحل را نشان می دهد:

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

قبل از درخواست تبلیغات در برنامه خود، بررسی کنید که آیا رضایت کاربر را با استفاده از 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. خروجی گزارش را برای پیامی شبیه به مثال زیر بررسی کنید، که شناسه دستگاه شما و نحوه افزودن آن را به عنوان یک دستگاه آزمایشی نشان می دهد:

    اندروید

    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 را به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 راهی برای آزمایش رفتار برنامه شما ارائه می‌کند که گویی دستگاه در منطقه اقتصادی اروپا یا بریتانیا با استفاده از ConsentRequestParameters.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();

نمونه هایی در GitHub

نمونه های ادغام