شروع به کار

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

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

پیش‌نیازها

• سطح Android API 21 یا بالاتر

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

پیام‌های کاربر را با یکی از انواع پیام کاربر دردسترس در برگه حریم خصوصی و پیام‌رسانی حساب 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.
ConsentManager.java

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.
    });
ConsentManager.java

Kotlin

UserMessagingPlatform.loadAndShowConsentFormIfRequired(activity) { formError ->
  // Consent has been gathered.
}

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

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

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

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

جاوا

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

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);
ConsentManager.java

Kotlin

UserMessagingPlatform.showPrivacyOptionsForm(activity, onConsentFormDismissedListener)

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

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

جاوا

consentInformation.canRequestAds();

Kotlin

consentInformation.canRequestAds()

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

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

مهم: تا زمانی که با canRequestAds() تماس نگرفته‌اید، همیشه false را برمی‌گرداند requestConsentInfoUpdate()

اگر درطول فرایند جمع‌آوری موافقت خطایی رخ داد، بررسی کنید که آیا می‌توانید درخواست آگهی کنید. «کیت توسعه نرم‌افزار 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()

احتیاط: این روش فقط برای اهداف آزمایشی درنظر گرفته شده است. نباید reset() را در کد تولید فراخوانی کنید.

مثال‌ها در GitHub

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