إعداد حزمة تطوير البرامج (SDK) الخاصة بمنصة UMP

اختيار النظام الأساسي: Android جديد Android iOS Unity Flutter

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

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

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

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

عليك طلب تحديث معلومات موافقة المستخدم في كل مرة يتم فيها تشغيل التطبيق، وذلك باستخدام Update(). يتحقّق هذا الطلب مما يلي:

  • ما إذا كانت الموافقة مطلوبة: على سبيل المثال، يجب الحصول على الموافقة عند التشغيل للمرة الأولى أو إذا انتهت صلاحية قرار الموافقة السابق.
  • ما إذا كانت نقطة دخول خيارات الخصوصية مطلوبة: تتطلّب بعض رسائل الخصوصية أن تسمح التطبيقات للمستخدمين بتعديل خيارات الخصوصية في أي وقت.
void Start()
{
    // Create a ConsentRequestParameters object.
    ConsentRequestParameters requestParameters = new ConsentRequestParameters();

    // Request an update of the user's consent information.
    ConsentInformation.Update(requestParameters, OnConsentInfoUpdated);
}
UMPSnippets.cs

تحميل نموذج رسالة الخصوصية وعرضه

بعد تلقّي أحدث حالة موافقة، استدعِ LoadAndShowConsentFormIfRequired() لتحميل أي نماذج مطلوبة لجمع موافقة المستخدم. بعد التحميل، يتم عرض النماذج على الفور.

ConsentForm.LoadAndShowConsentFormIfRequired((FormError formError) =>
{
    if (formError != null)
    {
        // Consent gathering failed.
        Debug.LogError("Error loading/showing consent form: " + formError.Message);
    }

    // ...
});
UMPSnippets.cs

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

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

التحقّق مما إذا كانت نقطة دخول خيارات الخصوصية مطلوبة

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

void UpdatePrivacyButton()
{
    if (_privacyButton != null)
    {
        // Enable the button only if a privacy options entry point is required.
        _privacyButton.interactable =
            ConsentInformation.PrivacyOptionsRequirementStatus == PrivacyOptionsRequirementStatus.Required;
    }
}
UMPSnippets.cs

للاطّلاع على القائمة الكاملة لحالات متطلبات خيارات الخصوصية، يُرجى الرجوع إلى ConsentInformation.PrivacyOptionsRequirementStatus.

عرض نموذج خيارات الخصوصية

عندما يتفاعل المستخدم مع العنصر، اعرض نموذج خيارات الخصوصية:

public void ShowPrivacyOptionsForm()
{
    ConsentForm.ShowPrivacyOptionsForm((FormError showError) =>
    {
        if (showError != null)
        {
            Debug.LogError("Error showing privacy options form: " + showError.Message);
        }
    });
}
UMPSnippets.cs

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

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

ConsentInformation.CanRequestAds()

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

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

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

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

أثناء التحقّق من CanRequestAds() بعد جمع الموافقة وبعد استدعاء Update()، تأكَّد من أنّ المنطق يمنع طلبات الإعلانات غير الضرورية التي قد تؤدي إلى عرض true في كلتا عمليتَي التحقّق. على سبيل المثال، باستخدام متغيّر منطقي.

الاختبار

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

  1. استدعِ Update().

  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. عدِّل الرمز البرمجي لاستدعاء DebugGeography.TestDeviceHashedIds وتوفير قائمة بأرقام تعريف أجهزتك الاختبارية.

    void Start()
{
    var debugSettings = new ConsentDebugSettings
    {
        TestDeviceHashedIds =
        new List<string>
        {
            "TEST-DEVICE-HASHED-ID"
        }
    };

    // Create a ConsentRequestParameters object.
    ConsentRequestParameters request = new ConsentRequestParameters
    {
        ConsentDebugSettings = debugSettings,
    };

    // Check the current consent information status.
    ConsentInformation.Update(request, OnConsentInfoUpdated);
}

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

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

void Start()
{
    var debugSettings = new ConsentDebugSettings
    {
        // Geography appears as in EEA for debug devices.
        DebugGeography = DebugGeography.EEA,
        TestDeviceHashedIds = new List<string>
        {
            "TEST-DEVICE-HASHED-ID"
        }
    };

    // Create a ConsentRequestParameters object.
    ConsentRequestParameters request = new ConsentRequestParameters
    {
        ConsentDebugSettings = debugSettings,
    };

    // Check the current consent information status.
    ConsentInformation.Update(request, OnConsentInfoUpdated);
}

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

ConsentInformation.Reset();

أمثلة على GitHub

يمكنك الاطّلاع على مثال كامل حول تكامل حزمة تطوير البرامج لمنصة UMP التي ناقشناها في هذه الصفحة ضمن HelloWorld.