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

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

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

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

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

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

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

CocoaPods (ترجیحی)

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

pod 'GoogleUserMessagingPlatform'

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

pod install --repo-update

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

مدیر بسته Swift

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

1. در Xcode، «بسته Swift کیت توسعه نرم‌افزار UMP» را با پیمایش به File (فایل) > Add Packages… (افزودن بسته‌ها…) نصب کنید.

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

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

3. نسخه بسته Swift کیت توسعه نرم‌افزار UMP موردنظرتان را برای استفاده انتخاب کنید. برای پروژه‌های جدید، توصیه می‌کنیم از تا نسخه اصلی بعدی استفاده کنید.

سپس 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