راه‌اندازی کیت توسعه نرم‌افزار UMP

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

ایجاد نوع پیام

پیام‌های کاربر را با یکی از انواع پیام‌های کاربر دردسترس در برگه حریم خصوصی و پیام‌رسانی حساب 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 روشی برای آزمایش رفتار برنامه‌تان ارائه می‌دهد، گویی دستگاه در مناطق مختلفی مانند منطقه اقتصادی اروپا (EEA)، پادشاهی متحد (UK)، و سوئیس قرار دارد، بااستفاده از 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();
}