شروع به کار

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

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

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

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

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

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

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

CocoaPods (ترجیحی)

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

pod 'GoogleUserMessagingPlatform'

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

pod install --repo-update

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

Swift Package Manager

«کیت توسعه نرم‌افزار پلاتفرم پیام‌رسانی کاربر» از «مدیر بسته Swift» نیز پشتیبانی می‌کند. برای وارد کردن بسته 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 را ببینید.

شناسه برنامه را اضافه کنید

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

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

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

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

Swift


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

آبجکتیو-سی


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

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

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

Swift


try await ConsentForm.loadAndPresentIfRequired(from: viewController)

آبجکتیو-سی


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

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

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

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

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

Swift


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

آبجکتیو-سی


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

- (void)gatherConsentFromConsentPresentationViewController:(UIViewController *)viewController
                                  consentGatheringComplete:
                                      (void (^)(NSError *_Nullable))consentGatheringComplete {
  UMPRequestParameters *parameters = [[UMPRequestParameters alloc] init];
  // Set tag for under age of consent. Use NO constant to indicate that the user is not under age.
  parameters.tagForUnderAgeOfConsent = NO;

  UMPDebugSettings *debugSettings = [[UMPDebugSettings alloc] init];
  // Uncomment the following line to simulate a consent request from users in the
  // European Economic Area (EEA) for testing purposes.
  // debugSettings.geography = UMPDebugGeographyEEA;
  parameters.debugSettings = debugSettings;

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

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

- (void)presentPrivacyOptionsFormFromViewController:(UIViewController *)viewController
                                  completionHandler:
                                      (void (^)(NSError *_Nullable))completionHandler {
  [UMPConsentForm presentPrivacyOptionsFormFromViewController:viewController
                                            completionHandler:completionHandler];
}

@end

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

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

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

Swift


ConsentForm.presentPrivacyOptionsForm(
  from: viewController, completionHandler: completionHandler)

آبجکتیو-سی


[UMPConsentForm presentPrivacyOptionsFormFromViewController:viewController
                                          completionHandler:completionHandler];

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

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

Swift

ConsentInformation.shared.canRequestAds

آبجکتیو-سی

UMPConsentInformation.sharedInstance.canRequestAds;

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

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

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

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

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

آزمایش

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

  1. تماس با requestConsentInfoUpdateWithParameters: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)، و سوئیس بااستفاده از UMPDebugGeography قرار دارد. توجه داشته باشید که تنظیمات اشکال‌زدایی فقط در دستگاه‌های آزمایشی کار می‌کند.

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];

نمونه‌ها در GitHub

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

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