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

پلاتفرم را انتخاب کنید: Android iOS Unity Flutter Android (Legacy)

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

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

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

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

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

CocoaPods (ترجیحی)

ساده‌ترین راه برای وارد کردن کیت توسعه نرم‌افزار به پروژه iOS استفاده از CocoaPods است. Podfile پروژه‌تان را باز کنید و این خط را به هدف برنامه‌تان اضافه کنید:

pod 'GoogleUserMessagingPlatform'

سپس، فرمان زیر را اجرا کنید:

pod install --repo-update

اگر CocoaPods برایتان جدید است، برای جزئیات مربوط به نحوه ایجاد و استفاده از Podfiles، به استفاده از CocoaPods مراجعه کنید.

Swift Package Manager

کیت توسعه نرم‌افزار «پلاتفرم پیام‌رسانی کاربر» از Swift Package Manager نیز پشتیبانی می‌کند. برای وارد کردن بسته Swift، این مراحل را دنبال کنید.

1. در Xcode، با رفتن به فایل > افزودن بسته‌ها...، «بسته Swift کیت توسعه نرم‌افزار UMP» را نصب کنید.

2. در پیام‌واره‌ای که ظاهر می‌شود، مخزن GitHub بسته Swift کیت توسعه نرم‌افزار UMP را جستجو کنید:

   https://github.com/googleads/swift-package-manager-google-user-messaging-platform.git
   

3. نسخه «بسته سوئیفت کیت توسعه نرم‌افزار پلاتفرم پیام‌رسانی کاربر» را که می‌خواهید استفاده کنید انتخاب کنید. برای پروژه‌های جدید، توصیه می‌کنیم از Up to Next Major Version استفاده کنید.

سپس Xcode وابستگی‌های بسته شما را حل می‌کند و آن‌ها را در پس‌زمینه بارگیری می‌کند. برای جزئیات بیشتر درباره نحوه افزودن وابستگی‌های بسته، مقاله Apple را ببینید.

بارگیری دستی

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

بارگیری کیت توسعه نرم‌افزار

سپس، چارچوب را به پروژه Xcode خود بکشید و مطمئن شوید که کپی کردن موارد درصورت نیاز را انتخاب کرده‌اید.

سپس می‌توانید چارچوب را بااستفاده از موارد زیر در هر فایلی که نیاز دارید اضافه کنید:

Swift

import UserMessagingPlatform

آبجکتیو-سی

#include <UserMessagingPlatform/UserMessagingPlatform.h>

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

می‌توانید شناسه برنامه‌تان را در رابط کاربری AdMob پیدا کنید. شناسه را با تکه‌کد زیر به Info.plist خود اضافه کنید:

<key>GADApplicationIdentifier</key>
<string>ca-app-pub-xxxxxxxxxxxxxxxx~yyyyyyyyyy</string>

دریافت اطلاعات رضایت کاربر

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

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

Swift

// Requesting an update to consent information should be called on every app launch.
ConsentInformation.shared.requestConsentInfoUpdate(with: parameters) {
  requestConsentError in
  // ...
}
GoogleMobileAdsConsentManager.swift

SwiftUI

// Requesting an update to consent information should be called on every app launch.
ConsentInformation.shared.requestConsentInfoUpdate(with: parameters) {
  requestConsentError in
  // ...
}
GoogleMobileAdsConsentManager.swift

آبجکتیو-سی

// Requesting an update to consent information should be called on every app launch.
[UMPConsentInformation.sharedInstance
    requestConsentInfoUpdateWithParameters:parameters
                         completionHandler:^(NSError *_Nullable requestConsentError) {
                           // ...
                         }];
GoogleMobileAdsConsentManager.m

هشدار: توصیه نمی‌کنیم وضعیت رضایت را به روش دیگری بررسی کنید، مثلاً ازطریق حافظه نهان در برنامه‌تان یا رشته رضایت ذخیره‌شده قبلی. این روش‌ها ممکن است داده‌های رضایت کاربر قدیمی را برگردانند.

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

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

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

Swift

try await ConsentForm.loadAndPresentIfRequired(from: viewController)
GoogleMobileAdsConsentManager.swift

SwiftUI

try await ConsentForm.loadAndPresentIfRequired(from: nil)
GoogleMobileAdsConsentManager.swift

آبجکتیو-سی

[UMPConsentForm
    loadAndPresentIfRequiredFromViewController:viewController
                             completionHandler:^(NSError *_Nullable loadAndPresentError) {
                                 // Consent gathering process is complete.
                                }];
GoogleMobileAdsConsentManager.m

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

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

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

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

Swift

var isPrivacyOptionsRequired: Bool {
  return ConsentInformation.shared.privacyOptionsRequirementStatus == .required
}
GoogleMobileAdsConsentManager.swift

آبجکتیو-سی

- (BOOL)isPrivacyOptionsRequired {
  return UMPConsentInformation.sharedInstance.privacyOptionsRequirementStatus ==
         UMPPrivacyOptionsRequirementStatusRequired;
}
GoogleMobileAdsConsentManager.m

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

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

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

Swift

try await ConsentForm.presentPrivacyOptionsForm(from: viewController)
GoogleMobileAdsConsentManager.swift

SwiftUI

try await ConsentForm.presentPrivacyOptionsForm(from: nil)
GoogleMobileAdsConsentManager.swift

آبجکتیو-سی

[UMPConsentForm presentPrivacyOptionsFormFromViewController:viewController
                                          completionHandler:completionHandler];
GoogleMobileAdsConsentManager.m

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

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

Swift

ConsentInformation.shared.canRequestAds

آبجکتیو-سی

UMPConsentInformation.sharedInstance.canRequestAds;

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

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

مهم: UMPConsentInformation.sharedInstance.canRequestAds همیشه false را برمی‌گرداند تا زمانی که requestConsentInfoUpdate(with:completionHandler:) را فراخوانی کنید

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

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

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

آزمایش

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

توجه: شبیه‌سازها نیازی به اضافه شدن به فهرست شناسه دستگاه شما ندارند زیرا به‌طور پیش‌فرض دستگاه‌های آزمایشی هستند.

1. تماس با requestConsentInfoUpdate(with:completionHandler:).

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

   <UMP SDK>To enable debug mode for this device, set: UMPDebugSettings.testDeviceIdentifiers = @[2077ef9a63d2b398840261c8221a0c9b]
   

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

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

   Swift

   let parameters = RequestParameters()
   let debugSettings = DebugSettings()
   
   debugSettings.testDeviceIdentifiers = ["TEST-DEVICE-HASHED-ID"]
   parameters.debugSettings = debugSettings
   
   // Include the UMPRequestParameters in your consent request.
   ConsentInformation.shared.requestConsentInfoUpdate(
       with: parameters,
       completionHandler: { error in
         // ...
       })
   

   آبجکتیو-سی

   UMPRequestParameters *parameters = [[UMPRequestParameters alloc] init];
   UMPDebugSettings *debugSettings = [[UMPDebugSettings alloc] init];
   
   debugSettings.testDeviceIdentifiers = @[ @"TEST-DEVICE-HASHED-ID" ];
   parameters.debugSettings = debugSettings;
   
   // Include the UMPRequestParameters in your consent request.
   [UMPConsentInformation.sharedInstance
       requestConsentInfoUpdateWithParameters:parameters
                           completionHandler:^(NSError *_Nullable error){
                             // ...
   }];
   

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

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

Swift

let parameters = RequestParameters()
let debugSettings = DebugSettings()

debugSettings.testDeviceIdentifiers = ["TEST-DEVICE-HASHED-ID"]
debugSettings.geography = .EEA
parameters.debugSettings = debugSettings

// Include the UMPRequestParameters in your consent request.
ConsentInformation.shared.requestConsentInfoUpdate(
    with: parameters,
    completionHandler: { error in
      // ...
    })

آبجکتیو-سی

UMPRequestParameters *parameters = [[UMPRequestParameters alloc] init];
UMPDebugSettings *debugSettings = [[UMPDebugSettings alloc] init];

debugSettings.testDeviceIdentifiers = @[ @"TEST-DEVICE-HASHED-ID" ];
debugSettings.geography = UMPDebugGeographyEEA;
parameters.debugSettings = debugSettings;

// Include the UMPRequestParameters in your consent request.
[UMPConsentInformation.sharedInstance
    requestConsentInfoUpdateWithParameters:parameters
                         completionHandler:^(NSError *_Nullable error){
                           // ...
}];

بازنشانی حالت رضایت

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

Swift

ConsentInformation.shared.reset()

آبجکتیو-سی

[UMPConsentInformation.sharedInstance reset];

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

نمونه‌ها در GitHub

نمونه کامل ادغام کیت توسعه نرم‌افزار UMP را که در این صفحه پوشش داده شده است در اینجا ببینید

• Swift BannerExample
• SwiftUIDemo
• Objective-C BannerExample