شروع به کار

پلاتفرم را انتخاب کنید: Android iOS

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

پیش‌نیازها

  • سطح ای‌پی‌آی Android نسخه ۲۱ یا بالاتر

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

بااستفاده از یکی از انواع پیام کاربر دردسترس در برگه حریم خصوصی و پیام‌رسانی حساب Ad Manager خود، پیام‌های کاربر ایجاد کنید. کیت توسعه نرم‌افزار UMP تلاش می‌کند پیام حریم خصوصی ایجادشده از «شناسه برنامه آگهی‌های رسانه‌ای تعاملی» را که در پروژه‌تان تنظیم شده است نمایش دهد.

برای جزئیات بیشتر، درباره حریم خصوصی و پیام‌رسانی را ببینید.

نصب با Gradle

وابستگی کیت توسعه نرم‌افزار پلاتفرم پیام‌رسانی کاربر Google را به فایل Gradle در سطح برنامه واحدتان اضافه کنید، معمولاً app/build.gradle:

dependencies {
  implementation("com.google.android.ump:user-messaging-platform:4.0.0")
}

پس‌از اعمال تغییرات در build.gradle برنامه‌تان، حتماً پروژه‌تان را با فایل‌های Gradle همگام‌سازی کنید.

افزودن شناسه برنامه

می‌توانید شناسه برنامه‌تان را در واسط کاربر Ad Manager پیدا کنید. شناسه را با تکه‌کد زیر به AndroidManifest.xml خود اضافه کنید:

<manifest>
  <application>
    <meta-data
        android:name="com.google.android.gms.ads.APPLICATION_ID"
        android:value="ca-app-pub-xxxxxxxxxxxxxxxx~yyyyyyyyyy"/>
  </application>
</manifest>

برای دریافت اطلاعات رضایت کاربر، موارد زیر را انجام دهید:

نمونه‌ای از ConsentInformation را اعلام کنید:

جاوا

private final ConsentInformation consentInformation;

Kotlin

private lateinit var consentInformation: ConsentInformation

مقداردهی اولیه نمونه ConsentInformation:

جاوا

consentInformation = UserMessagingPlatform.getConsentInformation(context);

Kotlin

consentInformation = UserMessagingPlatform.getConsentInformation(context)

باید بااستفاده از requestConsentInfoUpdate()، در هر بار راه‌اندازی برنامه، به‌روزرسانی اطلاعات رضایت کاربر را درخواست کنید. این درخواست موارد زیر را بررسی می‌کند:

  • آیا رضایت لازم است. برای مثال، برای اولین‌بار رضایت لازم است یا تصمیم رضایت قبلی منقضی شده است.
  • آیا نقطه ورودی گزینه‌های حریم خصوصی لازم است. برخی‌از پیام‌های حریم خصوصی برنامه‌ها را ملزم می‌کنند به کاربران اجازه دهند گزینه‌های حریم خصوصی‌شان را در هر زمانی تغییر دهند.

جاوا


// Requesting an update to consent information should be called on every app launch.
consentInformation.requestConsentInfoUpdate(
    activity,
    params,
    () -> // Called when consent information is successfully updated.
    requestConsentError -> // Called when there's an error updating consent information.

Kotlin


// Requesting an update to consent information should be called on every app launch.
consentInformation.requestConsentInfoUpdate(
  activity,
  params,
  {
    // Called when consent information is successfully updated.
  },
  { requestConsentError -> // Called when there's an error updating consent information.



},
)

بار کردن و ارائه فرم پیام حریم خصوصی

پس‌از دریافت به‌روزترین وضعیت رضایت، loadAndShowConsentFormIfRequired() را فراخوانی کنید تا هر فرمی را که برای جمع‌آوری رضایت کاربر لازم است بار کند. پس‌از بار کردن، فرم‌ها بلافاصله ارائه می‌شوند.

جاوا


UserMessagingPlatform.loadAndShowConsentFormIfRequired(
    activity,
    formError -> {
      // Consent gathering process is complete.
    });

Kotlin


UserMessagingPlatform.loadAndShowConsentFormIfRequired(activity) { formError ->
  // Consent gathering is complete.
}

گزینه‌های حریم‌خصوصی

برخی‌از فرم‌های پیام حریم خصوصی از نقطه ورودی گزینه‌های حریم خصوصی ارائه‌شده توسط ناشر ارائه می‌شوند و به کاربران اجازه می‌دهند گزینه‌های حریم خصوصی خود را در هر زمان مدیریت کنند. برای کسب اطلاعات بیشتر درباره اینکه کاربران کدام پیام را در نقطه ورودی گزینه‌های حریم خصوصی می‌بینند، انواع پیام کاربر دردسترس را ببینید.

بررسی کنید که آیا نقطه ورودی گزینه‌های حریم خصوصی لازم است یا نه

پس‌از فراخوانی requestConsentInfoUpdate()، getPrivacyOptionsRequirementStatus() را بررسی کنید تا مشخص شود آیا نقطه ورودی گزینه‌های حریم خصوصی برای برنامه‌تان لازم است یا نه. اگر نقطه ورودی لازم است، عنصر میانای کاربر قابل‌مشاهده و تعاملی به برنامه‌تان اضافه کنید که فرم گزینه‌های حریم خصوصی را ارائه دهد. اگر نقطه ورود حریم خصوصی لازم نیست، عنصر میانای کاربر را طوری پیکربندی کنید که قابل‌مشاهده و تعامل نباشد.

جاوا


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

Kotlin


/** Helper variable to determine if the privacy options form is required. */
val isPrivacyOptionsRequired: Boolean
  get() =
    consentInformation.privacyOptionsRequirementStatus ==
      ConsentInformation.PrivacyOptionsRequirementStatus.REQUIRED

برای مشاهده فهرست کامل وضعیت‌های الزامات گزینه‌های حریم خصوصی، به ConsentInformation.PrivacyOptionsRequirementStatus مراجعه کنید.

ارائه فرم گزینه‌های حریم خصوصی

وقتی کاربر با عنصر شما تعامل برقرار می‌کند، فرم گزینه‌های حریم خصوصی را ارائه دهید:

جاوا


UserMessagingPlatform.showPrivacyOptionsForm(activity, onConsentFormDismissedListener);

Kotlin


UserMessagingPlatform.showPrivacyOptionsForm(activity, onConsentFormDismissedListener)

درخواست آگهی با رضایت کاربر

قبل‌از درخواست آگهی، از canRequestAds() استفاده کنید تا بررسی کنید که آیا رضایت کاربر را دریافت کرده‌اید یا نه:

جاوا

consentInformation.canRequestAds();

Kotlin

consentInformation.canRequestAds()

در زیر جاهایی که می‌توانید بررسی کنید آیا می‌توانید هنگام جمع‌آوری رضایت درخواست آگهی کنید یا نه فهرست شده است:

  • پس‌از اینکه کیت توسعه نرم‌افزار UMP در جلسه فعلی رضایت را جمع‌آوری کرد.
  • بلافاصله پس‌از تماس با requestConsentInfoUpdate(). کیت توسعه نرم‌افزار UMP ممکن است در جلسه قبلی برنامه رضایت را کسب کرده باشد.

اگر درطول فرایند جمع‌آوری رضایت خطایی رخ داد، بررسی کنید که آیا می‌توانید درخواست آگهی کنید. کیت توسعه نرم‌افزار UMP از وضعیت رضایت جلسه قبلی برنامه استفاده می‌کند.

جلوگیری از کار درخواست آگهی تکراری

وقتی canRequestAds() را پس‌از جمع‌آوری رضایت و پس‌از فراخوانی requestConsentInfoUpdate() بررسی می‌کنید، مطمئن شوید منطق شما از درخواست‌های آگهی زائد که ممکن است منجر به برگرداندن true توسط هر دو بررسی شود جلوگیری می‌کند. برای مثال، با متغیر بولی.

آزمایش

اگر می‌خواهید ادغام را در برنامه‌تان درحین توسعه آزمایش کنید، این مراحل را برای ثبت دستگاه آزمایشی‌تان به‌صورت برنامه‌نویسی‌شده دنبال کنید. حتماً قبل‌از انتشار برنامه‌تان، کدی را که این شناسه‌های دستگاه آزمایشی را تنظیم می‌کند بردارید.

  1. تماس با requestConsentInfoUpdate().

  2. خروجی گزارش را برای پیامی مشابه نمونه زیر بررسی کنید، که شناسه دستگاه شما و نحوه افزودن آن به‌عنوان دستگاه آزمایشی را نشان می‌دهد:

    Use new ConsentDebugSettings.Builder().addTestDeviceHashedId("33BE2250B43518CCDA7DE426D04EE231") to set this as a debug device.

  3. شناسه دستگاه آزمایشی‌تان را در بریده‌دان کپی کنید.

  4. کدتان را برای فراخوانی ConsentDebugSettings.Builder().addTestDeviceHashedId() و ارسال فهرست شناسه‌های دستگاه آزمایشی‌تان اصلاح کنید.

    جاوا

    ConsentDebugSettings debugSettings = new ConsentDebugSettings.Builder(this)
    .addTestDeviceHashedId("TEST-DEVICE-HASHED-ID")
    .build();

ConsentRequestParameters params = new ConsentRequestParameters
    .Builder()
    .setConsentDebugSettings(debugSettings)
    .build();

consentInformation = UserMessagingPlatform.getConsentInformation(this);
// Include the ConsentRequestParameters in your consent request.
consentInformation.requestConsentInfoUpdate(
    this,
    params,
    // ...
);

    Kotlin

    val debugSettings = ConsentDebugSettings.Builder(this)
    .addTestDeviceHashedId("TEST-DEVICE-HASHED-ID")
    .build()

val params = ConsentRequestParameters
    .Builder()
    .setConsentDebugSettings(debugSettings)
    .build()

consentInformation = UserMessagingPlatform.getConsentInformation(this)
// Include the ConsentRequestParameters in your consent request.
consentInformation.requestConsentInfoUpdate(
    this,
    params,
    // ...
)

اجبار به مکان جغرافیایی

کیت توسعه نرم‌افزار UMP راهی برای آزمایش رفتار برنامه‌تان ارائه می‌دهد، گویی دستگاه در مناطق مختلفی مانند منطقه اقتصادی اروپا (EEA)، پادشاهی متحد (UK)، و سوئیس قرار دارد. این کار بااستفاده از DebugGeography انجام می‌شود. توجه داشته باشید که تنظیمات اشکال‌زدایی فقط در دستگاه‌های آزمایشی کار می‌کند.

جاوا

ConsentDebugSettings debugSettings = new ConsentDebugSettings.Builder(this)
    .setDebugGeography(ConsentDebugSettings.DebugGeography.DEBUG_GEOGRAPHY_EEA)
    .addTestDeviceHashedId("TEST-DEVICE-HASHED-ID")
    .build();

ConsentRequestParameters params = new ConsentRequestParameters
    .Builder()
    .setConsentDebugSettings(debugSettings)
    .build();

consentInformation = UserMessagingPlatform.getConsentInformation(this);
// Include the ConsentRequestParameters in your consent request.
consentInformation.requestConsentInfoUpdate(
    this,
    params,
    ...
);

Kotlin

val debugSettings = ConsentDebugSettings.Builder(this)
    .setDebugGeography(ConsentDebugSettings.DebugGeography.DEBUG_GEOGRAPHY_EEA)
    .addTestDeviceHashedId("TEST-DEVICE-HASHED-ID")
    .build()

val params = ConsentRequestParameters
    .Builder()
    .setConsentDebugSettings(debugSettings)
    .build()

consentInformation = UserMessagingPlatform.getConsentInformation(this)
// Include the ConsentRequestParameters in your consent request.
consentInformation.requestConsentInfoUpdate(
    this,
    params,
    ...
)

هنگام آزمایش برنامه با کیت توسعه نرم‌افزار UMP، ممکن است بازنشانی کردن وضعیت کیت توسعه نرم‌افزار برایتان مفید باشد تا بتوانید تجربه اولین نصب کاربر را شبیه‌سازی کنید. کیت توسعه نرم‌افزار روش reset() را برای انجام این کار ارائه می‌دهد.

جاوا

consentInformation.reset();

Kotlin

consentInformation.reset()

نمونه‌ها در GitHub

نمونه کاملی از ادغام کیت توسعه نرم‌افزار «پلاتفرم پیام‌رسانی کاربر» را که در این صفحه پوشش داده شده است در UmpExample ببینید.

بعدی
درخواست رضایت از کاربران اتحادیه اروپا