البدء

حزمة تطوير البرامج لمنصّة User Messaging Platform (UMP) من Google هي أداة للخصوصية والمراسلة في إدارة خيارات الخصوصية لمزيد من المعلومات، يُرجى مراجعة حول الخصوصية و المراسلة

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

  • المستوى 21 من واجهة برمجة تطبيقات Android أو المستويات الأعلى (لنظام التشغيل Android)

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

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

لمزيد من التفاصيل، يُرجى مراجعة لمحة عن الخصوصية والمراسلة

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

  1. اتبع الخطوات لتثبيت إعلانات Google للأجهزة الجوّالة (GMA) C++ SDK. UMP C++ يتم تضمين حزمة SDK في حزمة تطوير البرامج (SDK) لإعلانات Google على الأجهزة الجوّالة (GMA C++).

  2. تأكَّد من ضبط تطبيق AdMob لتطبيقك. رقم التعريف في المشروع قبل المتابعة.

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

    • على نظام التشغيل Android، يجب اجتياز الاختبار في JNIEnv وActivity المقدَّمَين من خلال NDK. عليك إجراء ذلك فقط في المرة الأولى التي تتصل فيها بـ GetInstance().
    • أما إذا كنت تستخدم الإصدار C++ من Firebase حاليًا SDK في تطبيقك، يمكنك تمرير في firebase::App في أول مرة تتصل فيها بـ GetInstance().
    #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() المثيل نفسه.

إذا انتهيت من استخدام حزمة تطوير البرامج (SDK) لمنصّة UMP، يمكنك إيقاف حزمة SDK من خلال حذف مثال واحد (ConsentInfo):

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

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

حاسمة firebase::Future طريقة لتحديد حالة الإكمال للطريقة غير المتزامنة الاتصالات.

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

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

  1. يمكنك الاتصال على الرقم OnCompletion()، تمرير دالة الاستدعاء الخاصة بك، وهو ما يسمى عند إجراء العملية تكتمل.
  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، يُرجى الاطّلاع على حزمة تطوير البرامج (SDK) بلغة C++ من Firebase المستندات ومستندات حزمة تطوير البرامج (SDK) لإعلانات Google على الأجهزة الجوّالة (GMA C++).

إضافة معرّف التطبيق

يمكنك العثور على رقم تعريف طلبك في واجهة مستخدم 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 حالة الموافقة من الحزمة السابقة جلسة المراجعة.

يستخدم المثال الكامل التالي الاستطلاع المتكرر، ولكن يمكنك أيضًا استخدام 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. يمكنك التحقّق من مخرجات السجلّ لرسالة مشابهة للمثال التالي، وهي تعرض رقم تعريف جهازك وكيفية إضافته كجهاز اختبار:

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

فرض موقع جغرافي

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

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

أمثلة على GitHub