تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

البدء

بموجب سياسة موافقة المستخدم في الاتحاد الأوروبي التي تتّبعها Google، يجب الإفصاح عن معلومات معيّنة للمستخدمين في المنطقة الاقتصادية الأوروبية (EEA) وفي المملكة المتحدة والحصول على موافقتهم على استخدام ملفات تعريف الارتباط أو غير ذلك من البيانات المحفوظة على أجهزتهم المحلية، حيثما يكون ذلك مطلوبًا بموجب القانون، وعلى استخدام البيانات الشخصية (مثل AdID) لعرض الإعلانات. تعكس هذه السياسة شروط "التوجيه الأوروبي بشأن الخصوصية الإلكترونية" و"اللائحة العامة لحماية البيانات" (GDPR).

لمساعدة الناشرين في الوفاء بالتزاماتهم بموجب هذه السياسة، تقدِّم Google حزمة تطوير البرامج (SDK) لمنصّة User Messaging Platform (UMP). تم تحديث حزمة تطوير البرامج (SDK) الخاصة بمنصة UMP لتتوافق مع أحدث معايير IAB. يمكن الآن التعامل مع كل هذه الإعدادات بسهولة في AdMob الخصوصية والمراسلة.

المتطلبات الأساسية

إكمال دليل البدء

للاطّلاع على المتطلبات المتعلقة باللائحة العامة لحماية البيانات، يُرجى الاطّلاع على تأثير متطلبات IAB في رسائل طلب موافقة المستخدمين في الاتحاد الأوروبي

إنشاء نوع رسالة

أنشئ رسائل للمستخدمين باستخدام أحد أنواع رسائل المستخدمين المتاحة ضمن علامة التبويب الخصوصية والمراسلة في AdMob . تحاول حزمة تطوير البرامج (SDK) لمنصة UMP عرض رسالة مستخدم تم إنشاؤها من مجموعة AdMob معرّف التطبيق في مشروعك. فإذا لم يتم تهيئة أي رسالة لتطبيقك، فستعرض حزمة SDK رسالة خطأ.

لمزيد من التفاصيل، يُرجى الاطّلاع على لمحة عن الخصوصية والمراسلة.

استيراد حزمة تطوير البرامج (SDK)

CocoaPods (مفضّل)

إنّ أسهل طريقة لاستيراد حزمة تطوير البرامج (SDK) إلى مشروع iOS هي استخدام CocoaPods. افتح Podfile لمشروعك وأضف هذا السطر إلى هدف تطبيقك:

pod 'GoogleUserMessagingPlatform'

ثم شغِّل الأمر التالي:

pod install --repo-update

إذا كنت مستخدمًا مبتدئًا لـ CocoaPods، يمكنك الاطّلاع على قسم استخدام CocoaPods للحصول على تفاصيل حول كيفية إنشاء ملفات Podfiles واستخدامها.

مدير حِزم Swift

تتوافق حزمة تطوير البرامج (SDK) لمنصة UMP أيضًا مع أداة Swift للحزمة. اتبع هذه الخطوات لاستيراد حزمة Swift.

في Xcode، ثبِّت حزمة Swift لمنصة UMP SDK من خلال الانتقال إلى File > Add Packages... (ملف > إضافة حِزم)...
في الطلب الذي يظهر، ابحث عن مستودع GitHub SDK Swift لمنصة UMP:
```
https://github.com/googleads/swift-package-manager-google-user-messaging-platform.git
```
اختَر إصدار حزمة Swift لحزمة تطوير البرامج (SDK) لمنصة UMP التي تريد استخدامها. بالنسبة إلى المشاريع الجديدة، ننصح باستخدام الإصدار الرئيسي التالي.

يقوم Xcode بعد ذلك بحل تبعيات الحزمة الخاصة بك وتنزيلها في الخلفية. لمزيد من التفاصيل حول كيفية إضافة تبعيات الحزمة، راجع مقالة Apple.

التنزيل اليدوي

والطريقة الأخرى لاستيراد حزمة SDK هي إجراء ذلك يدويًا.

تنزيل حزمة تطوير البرامج (SDK)

بعد ذلك، اسحب إطار العمل إلى مشروع Xcode، مع التأكّد من اختيار نسخ العناصر إذا لزم الأمر.

يمكنك بعد ذلك تضمين إطار العمل في أي ملف تحتاجه باستخدام:

Swift

import UserMessagingPlatform

Objective-C

#include <UserMessagingPlatform/UserMessagingPlatform.h>

عليك طلب تعديل معلومات موافقة المستخدم عند كل عملية إطلاق للتطبيق باستخدام requestConsentInfoUpdateWithParameters:completionHandler:. يحدِّد هذا الإجراء ما إذا كان المستخدم بحاجة إلى تقديم موافقته إذا لم يسبق له تقديم موافقته أو إذا انتهت صلاحيتها.

في ما يلي مثال على كيفية التحقّق من الحالة من UIViewController في طريقة viewDidLoad().

Swift

override func viewDidLoad() {
  super.viewDidLoad()

  // Request an update for the consent information.
  UMPConsentInformation.sharedInstance.requestConsentInfoUpdate(with: nil) {
    [weak self] requestConsentError in
    guard let self else { return }

    if let consentError = requestConsentError {
      // Consent gathering failed.
      return print("Error: \(consentError.localizedDescription)")
    }

    // TODO: Load and present the consent form.
  }
}

Objective-C

- (void)viewDidLoad {
  [super viewDidLoad];

  // Request an update for the consent information.
  [UMPConsentInformation.sharedInstance
      requestConsentInfoUpdateWithParameters:nil
          completionHandler:^(NSError *_Nullable requestConsentError) {
            if (requestConsentError) {
              // Consent gathering failed.
              NSLog(@"Error: %@", requestConsentError.localizedDescription);
              return;
            }

            // TODO: Load and present the consent form.
          }];
}

تحميل نموذج موافقة وتقديمه إذا لزم الأمر

ملاحظة مُهمّة: واجهات برمجة التطبيقات التالية متوافقة مع الإصدار 2.1.0 أو الإصدارات الأحدث من حزمة تطوير البرامج (SDK) الخاصة بمنصة UMP.

بعد حصولك على أحدث حالة للموافقة، تواصَل مع loadAndPresentIfRequiredFromViewController:completionHandler: الصف UMPConsentForm لتحميل نموذج موافقة. إذا كانت حالة الموافقة مطلوبة، تُحمِّل حزمة تطوير البرامج (SDK) نموذجًا وتعرضه على الفور من view controllerالتي تم توفيرها. يتم استدعاء completion handler بعد إغلاق النموذج. في حال لم تكن الموافقة مطلوبة، يتم طلب completion handler على الفور.

Swift

override func viewDidLoad() {
  super.viewDidLoad()

  // Request an update for the consent information.
  UMPConsentInformation.sharedInstance.requestConsentInfoUpdate(with: nil) {
    [weak self] requestConsentError in
    guard let self else { return }

    if let consentError = requestConsentError {
      // Consent gathering failed.
      return print("Error: \(consentError.localizedDescription)")
    }

    UMPConsentForm.loadAndPresentIfRequired(from: self) {
      [weak self] loadAndPresentError in
      guard let self else { return }

      if let consentError = loadAndPresentError {
        // Consent gathering failed.
        return print("Error: \(consentError.localizedDescription)")
      }

      // Consent has been gathered.
    }
  }
}

Objective-C

- (void)viewDidLoad {
  [super viewDidLoad];

  __weak __typeof__(self) weakSelf = self;
  // Request an update for the consent information.
  [UMPConsentInformation.sharedInstance
      requestConsentInfoUpdateWithParameters:nil
          completionHandler:^(NSError *_Nullable requestConsentError) {
            if (requestConsentError) {
              // Consent gathering failed.
              NSLog(@"Error: %@", requestConsentError.localizedDescription);
              return;
            }

            __strong __typeof__(self) strongSelf = weakSelf;
            if (!strongSelf) {
              return;
            }

            [UMPConsentForm loadAndPresentIfRequiredFromViewController:strongSelf
                completionHandler:^(NSError *loadAndPresentError) {
                  if (loadAndPresentError) {
                    // Consent gathering failed.
                    NSLog(@"Error: %@", loadAndPresentError.localizedDescription);
                    return;
                  }

                  // Consent has been gathered.
                }];
          }];
}

إذا كنت بحاجة إلى تنفيذ أي إجراءات بعد أن يختار المستخدم النموذج أو يرفضه، حدِّد المنطق في completion handler النموذج.

طلب إدراج الإعلانات

قبل طلب الإعلانات في تطبيقك، تحقّق مما إذا حصلت على موافقة من المستخدِم الذي يستخدم UMPConsentInformation.sharedInstance.canRequestAds. هناك مكانان يمكن التحقق منهما أثناء جمع الموافقات:

بعد الحصول على الموافقة في الجلسة الحالية
مباشرة بعد الاتصال بـ requestConsentInfoUpdateWithParameters:completionHandler:. من المحتمَل أنّه تم الحصول على موافقة في الجلسة السابقة. من بين أفضل الممارسات التي يجب اتّباعها لوقت الاستجابة، عدم انتظار اكتمال معاودة الاتصال حتى تتمكن من البدء في تحميل الإعلانات في أقرب وقت ممكن بعد إطلاق التطبيق.

وفي حال حدوث خطأ أثناء عملية الحصول على الموافقات، عليك مع ذلك محاولة طلب الإعلانات. تستخدم حزمة تطوير البرامج (SDK) لمنصة UMP حالة الموافقة من الجلسة السابقة.

Swift

class ViewController: UIViewController {

  // Use a boolean to initialize the Google Mobile Ads SDK and load ads once.
  private var isMobileAdsStartCalled = false

  override func viewDidLoad() {
    super.viewDidLoad()

    // Request an update for the consent information.
    UMPConsentInformation.sharedInstance.requestConsentInfoUpdate(with: nil) {
      [weak self] requestConsentError in
      guard let self else { return }

      if let consentError = requestConsentError {
        // Consent gathering failed.
        return print("Error: \(consentError.localizedDescription)")
      }

      UMPConsentForm.loadAndPresentIfRequired(from: self) {
        [weak self] loadAndPresentError in
        guard let self else { return }

        if let consentError = loadAndPresentError {
          // Consent gathering failed.
          return print("Error: \(consentError.localizedDescription)")
        }

        // Consent has been gathered.
        if UMPConsentInformation.sharedInstance.canRequestAds {
          self.startGoogleMobileAdsSDK()
        }
      }
    }
    
    // Check if you can initialize the Google Mobile Ads SDK in parallel
    // while checking for new consent information. Consent obtained in
    // the previous session can be used to request ads.
    if UMPConsentInformation.sharedInstance.canRequestAds {
      startGoogleMobileAdsSDK()
    }
  }
  
  private func startGoogleMobileAdsSDK() {
    DispatchQueue.main.async {
      guard !self.isMobileAdsStartCalled else { return }

      self.isMobileAdsStartCalled = true

      // Initialize the Google Mobile Ads SDK.
      GADMobileAds.sharedInstance().start()

      // TODO: Request an ad.
      // GADInterstitialAd.load(...)
    }
  }
}

Objective-C

@implementation ViewController

- (void)viewDidLoad {
  [super viewDidLoad];

  __weak __typeof__(self) weakSelf = self;
  // Request an update for the consent information.
  [UMPConsentInformation.sharedInstance
      requestConsentInfoUpdateWithParameters:nil
          completionHandler:^(NSError *_Nullable requestConsentError) {
            if (requestConsentError) {
              // Consent gathering failed.
              NSLog(@"Error: %@", requestConsentError.localizedDescription);
              return;
            }
            __strong __typeof__(self) strongSelf = weakSelf;
            if (!strongSelf) {
              return;
            }

            [UMPConsentForm loadAndPresentIfRequiredFromViewController:strongSelf
                completionHandler:^(NSError *loadAndPresentError) {
                  if (loadAndPresentError) {
                    // Consent gathering failed.
                    NSLog(@"Error: %@", loadAndPresentError.localizedDescription);
                    return;
                  }

                  // Consent has been gathered.
                  __strong __typeof__(self) strongSelf = weakSelf;
                  if (!strongSelf) {
                    return;
                  }

                  if (UMPConsentInformation.sharedInstance.canRequestAds) {
                    [strongSelf startGoogleMobileAdsSDK];
                  }
                }];
          }];

  // Check if you can initialize the Google Mobile Ads SDK in parallel
  // while checking for new consent information. Consent obtained in
  // the previous session can be used to request ads.
  if (UMPConsentInformation.sharedInstance.canRequestAds) {
    [self startGoogleMobileAdsSDK];
  }
}

- (void)startGoogleMobileAdsSDK {
  static dispatch_once_t onceToken;
  dispatch_once(&onceToken, ^{
    // Initialize the Google Mobile Ads SDK.
    [GADMobileAds.sharedInstance startWithCompletionHandler:nil];

    // TODO: Request an ad.
    // [GADInterstitialAd loadWithAdUnitID...];
  });
}

خيارات الخصوصية

تتطلّب بعض نماذج الموافقة من المستخدم تعديل موافقته في أي وقت. التزم بالخطوات التالية لعرض زر خيارات الخصوصية إذا لزم الأمر.

ولإجراء ذلك:

نفِّذ عنصر واجهة مستخدم، مثل زر في صفحة إعدادات تطبيقك، يمكن أن يؤدي إلى ظهور نموذج خيارات الخصوصية.
بعد loadAndPresentIfRequiredFromViewController:completionHandler: الاكتمال، ضَع علامة في المربّع privacyOptionsRequirementStatus لتحديد ما إذا كان سيتم عرض عنصر واجهة المستخدم الذي يمكنه عرض نموذج خيارات الخصوصية.
عندما يتفاعل مستخدم مع عنصر في واجهة المستخدم، يمكنك استدعاء presentPrivacyOptionsFormFromViewController:completionHandler: لعرض النموذج حتى يتمكّن المستخدم من تعديل خيارات الخصوصية في أي وقت.

يوضّح المثال التالي كيفية تقديم نموذج خيارات الخصوصية من UIBarButtonItem.

Swift

@IBOutlet weak var privacySettingsButton: UIBarButtonItem!

var isPrivacyOptionsRequired: Bool {
  return UMPConsentInformation.sharedInstance.privacyOptionsRequirementStatus == .required
}

override func viewDidLoad() {
  // ...

  // Request an update for the consent information.
  UMPConsentInformation.sharedInstance.requestConsentInfoUpdate(with: parameters) {
    // ...

    UMPConsentForm.loadAndPresentIfRequired(from: self) {
      //...

      // Consent has been gathered.

      // Show the button if privacy options are required.
      self.privacySettingsButton.isEnabled = isPrivacyOptionsRequired
    }
  }
  // ...
}

// Present the privacy options form when a user interacts with the
// privacy settings button.
@IBAction func privacySettingsTapped(_ sender: UIBarButtonItem) {
  UMPConsentForm.presentPrivacyOptionsForm(from: self) {
    [weak self] formError in
    guard let self, let formError else { return }

    // Handle the error.
  }
}

Objective-C

@interface ViewController ()
@property(weak, nonatomic) IBOutlet UIBarButtonItem *privacySettingsButton;
@end

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

- (void)viewDidLoad {
  // ...

  __weak __typeof__(self) weakSelf = self;
  // Request an update for the consent information.
  [UMPConsentInformation.sharedInstance
      requestConsentInfoUpdateWithParameters:parameters
          completionHandler:^(NSError *_Nullable requestConsentError) {
            // ...

            [UMPConsentForm loadAndPresentIfRequiredFromViewController:strongSelf
                completionHandler:^(NSError *loadAndPresentError) {
                  // ...

                  // Consent has been gathered.

                  // Show the button if privacy options are required.
                  strongSelf.privacySettingsButton.enabled = isPrivacyOptionsRequired;
                }];
          }];
}

// Present the privacy options form when a user interacts with your
// privacy settings button.
- (IBAction)privacySettingsTapped:(UIBarButtonItem *)sender {
  [UMPConsentForm presentPrivacyOptionsFormFromViewController:self
                                completionHandler:^(NSError *_Nullable formError) {
                                  if (formError) {
                                    // Handle the error.
                                  }
                                }];
}

الاختبار

إذا كنت تريد اختبار عملية الدمج في تطبيقك أثناء تطويره، اتّبِع الخطوات التالية لتسجيل جهازك الاختباري آليًا. احرص على إزالة الرمز الذي يحدّد أرقام تعريف الأجهزة الاختبارية هذه قبل إصدار تطبيقك

الاتصال requestConsentInfoUpdateWithParameters:completionHandler:
تحقق من مخرجات السجلّ الخاصة برسالة مشابهة للمثال التالي والتي تُظهر رقم تعريف جهازك وكيفية إضافته كجهاز اختبار:
```
<UMP SDK>To enable debug mode for this device, set: UMPDebugSettings.testDeviceIdentifiers = @[2077ef9a63d2b398840261c8221a0c9b]
```
انسخ رقم تعريف جهاز الاختبار إلى الحافظة.

يُرجى تعديل الرمز الخاص بك الاتصال UMPDebugSettings().testDeviceIdentifiers وإرسال قائمة بأرقام تعريف الأجهزة الاختبارية.

Swift

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

Objective-C

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){
                          ...
}];

فرض منطقة جغرافية

توفّر حزمة تطوير البرامج (SDK) لمنصة UMP طريقة لاختبار سلوك تطبيقك كما لو كان الجهاز مقيمًا في المنطقة الاقتصادية الأوروبية أو المملكة المتحدة باستخدام the debugGeography property of type UMPDebugGeography on UMPDebugSettings. تجدر الإشارة إلى أنّ إعدادات تصحيح الأخطاء لا تعمل إلا على الأجهزة الاختبارية.

Swift

let parameters = UMPRequestParameters()
let debugSettings = UMPDebugSettings()
debugSettings.testDeviceIdentifiers = ["TEST-DEVICE-HASHED-ID"]
debugSettings.geography = .EEA
parameters.debugSettings = debugSettings
// Include the UMPRequestParameters in your consent request.
UMPConsentInformation.sharedInstance.requestConsentInfoUpdate(
    with: parameters,
    completionHandler: { error in
      ...
    })

Objective-C

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، قد يكون من المفيد إعادة ضبط حالة حزمة تطوير البرامج (SDK) كي تتمكّن من محاكاة تجربة التثبيت الأولى للمستخدم. توفر حزمة SDK الطريقة reset لإجراء ذلك.

Swift

UMPConsentInformation.sharedInstance.reset()

Objective-C

[UMPConsentInformation.sharedInstance reset];

أمثلة على GitHub

أمثلة على دمج حزمة تطوير البرامج (SDK) لمنصة UMP: Swift | Objective-C

البدء

المتطلبات الأساسية

إنشاء نوع رسالة

استيراد حزمة تطوير البرامج (SDK)

CocoaPods (مفضّل)

مدير حِزم Swift

التنزيل اليدوي

Swift

Objective-C

طلب الحصول على معلومات الموافقة

Swift

Objective-C

تحميل نموذج موافقة وتقديمه إذا لزم الأمر

Swift

Objective-C

طلب إدراج الإعلانات

Swift

Objective-C

خيارات الخصوصية

Swift

Objective-C

الاختبار

Swift

Objective-C

فرض منطقة جغرافية

Swift

Objective-C

إعادة ضبط حالة الموافقة

Swift

Objective-C

أمثلة على GitHub