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

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

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

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

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

  • ما إذا كانت الموافقة مطلوبة: على سبيل المثال، يجب الحصول على الموافقة عند التشغيل للمرة الأولى أو إذا انتهت صلاحية قرار الموافقة السابق.
  • ما إذا كانت نقطة دخول خيارات الخصوصية مطلوبة: تتطلّب بعض رسائل الخصوصية أن تسمح التطبيقات للمستخدمين بتعديل خيارات الخصوصية في أي وقت.
/**
 * Requests consent information update on app launch.
 */
export function requestConsent(onComplete?: () => void) {
  requestConsentInfoUpdate({}, (error) => {
    if (error) {
      console.warn('Consent info update error:', error.message);
    } else {
      console.log('Consent info update complete.');
    }

    // Load and show consent form if required.
    loadAndPresentConsentForm(onComplete);
  });
}

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

بعد تلقّي أحدث حالة موافقة، يمكنك استدعاء loadAndShowConsentFormIfRequired() لتحميل أي نماذج مطلوبة لجمع موافقة المستخدم. بعد التحميل، تظهر النماذج على الفور.

/**
 * Loads and presents the privacy message form if required to collect user consent.
 */
export function loadAndPresentConsentForm(onComplete?: () => void) {
  loadAndShowConsentFormIfRequired((formError) => {
    if (formError) {
      console.warn('Consent form error:', formError.message);
    } else {
      console.log('Consent gathering complete.');
    }

    // Execute logic that depends on consent state (for example, initialize the SDK).
    onComplete?.();
  });
}

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

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

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

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

/**
 * Helper to determine if the privacy options entry point is required.
 */
export function isPrivacyOptionsRequired(): boolean {
  return (
    getPrivacyOptionsRequirementStatus() ===
    PrivacyOptionsRequirementStatus.REQUIRED
  );
}

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

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

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

/**
 * Renders a privacy options button if required by user consent policy.
 */
export function PrivacyOptionsButton({
  onDismissed,
}: {
  onDismissed?: (error?: FormError) => void;
}) {
  const isRequired =
    getPrivacyOptionsRequirementStatus() ===
    PrivacyOptionsRequirementStatus.REQUIRED;

  if (!isRequired) {
    return null;
  }

  const handleShowPrivacyOptions = () => {
    showPrivacyOptionsForm((error) => {
      if (error) {
        console.error('Failed to show privacy options form:', error.message);
      } else {
        console.log('Privacy options form dismissed.');
      }

      // Execute custom logic after form is dismissed.
      onDismissed?.(error);
    });
  };

  return <Button title="Privacy Settings" onPress={handleShowPrivacyOptions} />;
}

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

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

/**
 * Checks whether user consent allows requesting ads and initializes the SDK.
 */
let isMobileAdsInitialized = false;

export function initializeMobileAdsSdkIfConsentGiven() {
  if (canRequestAds()) {
    if (!isMobileAdsInitialized) {
      isMobileAdsInitialized = true;
      initialize({}, (status) => {
        console.log('Google Mobile Ads SDK initialized:', status);
      });
    }
  }
}

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

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

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

منع تكرار طلبات عرض الإعلانات

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

الاختبار

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

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

    /**
 * Registers a test device for testing consent flows.
 */
export function configureTestDevice() {
  requestConsentInfoUpdate(
    {
      consentDebugSettings: {
        debugGeography: DebugGeography.DISABLED,
        testDeviceIdentifiers: ["TEST_DEVICE_HASHED_ID"],
      },
    },
    (error) => {
      if (!error) {
        console.log('Test device registered.');
      }
    },
  );
}

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

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

/**
 * Configures debug settings to force EEA geography on a test device.
 */
export function configureDebugGeography() {
  requestConsentInfoUpdate(
    {
      consentDebugSettings: {
        debugGeography: DebugGeography.EEA,
        testDeviceIdentifiers: ["TEST_DEVICE_HASHED_ID"],
      },
    },
    (error) => {
      if (!error) {
        console.log('Consent debug test configuration loaded.');
      }
    },
  );
}

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

/**
 * Resets consent state for testing purposes.
 */
export function resetConsentState() {
  reset();
}