Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

البدء

حزمة تطوير البرامج لمنصة UMP هي أداة للخصوصية والمراسلة تساعدك في إدارة خيارات الخصوصية. لمزيد من المعلومات، يُرجى الاطّلاع على مقالة لمحة عن أداة "الخصوصية والمراسلة".

المتطلبات الأساسية

المستوى 21 من واجهة برمجة التطبيقات Android أو مستوى أحدث (لنظام Android)

إنشاء نوع رسالة

يمكنك إنشاء رسائل للمستخدمين باستخدام أحد أنواع رسائل المستخدمين المتاحة ضمن علامة التبويب الخصوصية والمراسلة في حسابك على AdMob. تحاول حزمة تطوير البرامج لمنصة UMP عرض رسالة خصوصية تم إنشاؤها من رقم تعريف تطبيق AdMob الذي تم ضبطه في مشروعك.

لمزيد من التفاصيل، يُرجى الاطّلاع على مقالة لمحة عن أداة "الخصوصية والمراسلة".

تثبيت حزمة تطوير البرامج (SDK)

اتّبِع الخطوات لتثبيت حزمة Firebase C++ SDK. يتم تضمين حزمة تطوير البرامج UMP C++ SDK في حزمة Firebase C++ SDK.
تأكَّد من ضبط رقم تعريف تطبيق AdMob في تطبيقك ضمن المشروع قبل المتابعة.

في الرمز البرمجي، ابدأ حزمة تطوير البرامج لمنصة UMP من خلال استدعاء ConsentInfo::GetInstance().

على Android، عليك تمرير JNIEnv وActivity اللذين يوفّرهما NDK. عليك إجراء ذلك للمرة الأولى فقط عند استدعاء GetInstance().
بدلاً من ذلك، إذا كنت تستخدم Firebase C++ SDK في تطبيقك، يمكنك تمرير firebase::App في المرة الأولى التي تستدعي فيها GetInstance().

#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، يمكنك إيقاف حزمة تطوير البرامج عن طريق حذف مثال ConsentInfo:

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

استخدام `Future` لمراقبة العمليات غير المتزامنة

A firebase::Future توفّر لك طريقة لتحديد حالة اكتمال استدعاءات الطريقة غير المتزامنة.

تعرض جميع دوال UMP C++ واستدعاءات الطريقة التي تعمل بشكل غير متزامن Future، وتوفّر أيضًا دالة "النتيجة الأخيرة" لاسترداد Future من أحدث عملية.

هناك طريقتان للحصول على نتيجة من Future:

استدعاء OnCompletion()، وتمرير دالة ردّ الاتصال الخاصة بك، والتي يتم استدعاؤها عند اكتمال العملية.
التحقّق بشكل دوري من 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.

الحصول على معلومات موافقة المستخدم

عليك طلب تعديل معلومات موافقة المستخدم في كل مرة يتم فيها تشغيل التطبيق ، وذلك باستخدام 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.
          }
        });
      }
    });
}

يُرجى الاطّلاع أعلاه على مثال للتحقّق من الاكتمال باستخدام التحقّق من حالة التعديل بشكل دوري بدلاً من دالة ردّ الاتصال عند الاكتمال.

إذا كنت بحاجة إلى تنفيذ أي إجراءات بعد أن يتّخذ المستخدم خيارًا أو يرفض النموذج، ضَع هذا المنطق في الرمز البرمجي الذي يعالج Future الذي تعرضه LoadAndShowConsentFormIfRequired().

خيارات الخصوصية

يتم عرض بعض نماذج رسائل الخصوصية من نقطة دخول خيارات الخصوصية التي يعرضها الناشر، ما يسمح للمستخدمين بإدارة خيارات الخصوصية في أي وقت. لمزيد من المعلومات عن نوع الرسالة التي تظهر للمستخدمين عند نقطة دخول خيارات الخصوصية ، يُرجى الاطّلاع على مقالة أنواع رسائل المستخدمين المتاحة.

طلب الإعلانات بموافقة المستخدم

قبل طلب الإعلانات، استخدِم ConsentInfo::GetInstance()‑> CanRequestAds() للتحقّق مما إذا كنت قد حصلت على موافقة من المستخدم:

في ما يلي الأماكن التي يمكنك التحقّق منها لمعرفة ما إذا كان بإمكانك طلب الإعلانات أثناء جمع الموافقة:

بعد أن تجمع حزمة تطوير البرامج لمنصّة UMP الموافقة في الجلسة الحالية
مباشرةً بعد استدعاء RequestConsentInfoUpdate(). من المحتمل أنّ حزمة تطوير البرامج لمنصة UMP قد حصلت على الموافقة في جلسة التطبيق السابقة.

في حال حدوث خطأ أثناء عملية جمع الموافقة، تحقَّق مما إذا كان بإمكانك طلب الإعلانات. تستخدِم حزمة تطوير البرامج لمنصّة UMP حالة الموافقة من جلسة التطبيق السابقة.

منع العمل غير الضروري لطلب عرض الإعلان

أثناء التحقّق من ConsentInfo::GetInstance()‑> CanRequestAds() بعد جمع الموافقة وبعد استدعاء RequestConsentInfoUpdate()، تأكَّد من أنّ المنطق يمنع طلبات الإعلانات غير الضرورية التي قد تؤدي إلى عرض 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;
      }
    }
  }
}

الاختبار

إذا أردت اختبار عملية التكامل في تطبيقك أثناء تطويره، اتّبِع الخطوات التالية لتسجيل جهاز الاختبار آليًا. احرص على إزالة الرمز الذي يضبط معرّفات الأجهزة الاختبارية هذه قبل طرح تطبيقك.

استدعِ RequestConsentInfoUpdate().

تحقَّق من ناتج السجلّ بحثًا عن رسالة مشابهة للمثال التالي، والتي تعرض رقم تعريف جهازك وكيفية إضافته كجهاز اختبار:

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]

انسخ رقم تعريف الجهاز الاختباري إلى الحافظة.

عدِّل الرمز البرمجي لضبط 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 طريقة لاختبار سلوك تطبيقك كما لو كان الجهاز في مناطق مختلفة، مثل المنطقة الاقتصادية الأوروبية والمملكة المتحدة وسويسرا، وذلك باستخدام 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، قد يكون من المفيد إعادة ضبط حالة حزمة تطوير البرامج حتى تتمكّن من محاكاة تجربة التثبيت الأولى للمستخدم. توفّر حزمة تطوير البرامج الطريقة Reset() لإجراء ذلك.

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