البدء

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

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

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

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

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

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

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

CocoaPods (مفضّل)

يتم تضمين حزمة تطوير البرامج (SDK) لمنصّة Google للتسويق كتبعية لحزمة SDK لإعلانات Google على الأجهزة الجوّالة التي تبدأ بالإصدار 7.64.0 من حزمة "SDK لإعلانات Google على الأجهزة الجوّالة".

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

pod 'Google-Mobile-Ads-SDK'

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

pod install --repo-update

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

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

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

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

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

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

Swift

import UserMessagingPlatform

Objective-C

#include <UserMessagingPlatform/UserMessagingPlatform.h>

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

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

Swift

override func viewDidLoad() {
  super.viewDidLoad()

  // Create a UMPRequestParameters object.
  let parameters = UMPRequestParameters()
  // Set tag for under age of consent. false means users are not under age
  // of consent.
  parameters.tagForUnderAgeOfConsent = false

  // Request an update for the consent information.
  UMPConsentInformation.sharedInstance.requestConsentInfoUpdate(with: parameters) {
    [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];

  // Create a UMPRequestParameters object.
  UMPRequestParameters *parameters = [[UMPRequestParameters alloc] init];
  // Set tag for under age of consent. NO means users are not under age
  // of consent.
  parameters.tagForUnderAgeOfConsent = NO;

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

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

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

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

Swift

override func viewDidLoad() {
  super.viewDidLoad()

  // Create a UMPRequestParameters object.
  let parameters = UMPRequestParameters()
  // Set tag for under age of consent. false means users are not under age
  // of consent.
  parameters.tagForUnderAgeOfConsent = false

  // Request an update for the consent information.
  UMPConsentInformation.sharedInstance.requestConsentInfoUpdate(with: parameters) {
    [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];

  // Create a UMPRequestParameters object.
  UMPRequestParameters *parameters = [[UMPRequestParameters alloc] init];
  // Set tag for under age of consent. NO means users are not under age
  // of consent.
  parameters.tagForUnderAgeOfConsent = NO;

  __weak __typeof__(self) weakSelf = self;
  // Request an update for the consent information.
  [UMPConsentInformation.sharedInstance
      requestConsentInfoUpdateWithParameters:parameters
          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. هناك مكانان للتحقق أثناء جمع الموافقات:

  1. بعد الحصول على الموافقة في الجلسة الحالية
  2. مباشرةً بعد الاتصال بـ 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()

    // Create a UMPRequestParameters object.
    let parameters = UMPRequestParameters()
    // Set tag for under age of consent. false means users are not under age
    // of consent.
    parameters.tagForUnderAgeOfConsent = false

    // Request an update for the consent information.
    UMPConsentInformation.sharedInstance.requestConsentInfoUpdate(with: parameters) {
      [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];

  // Create a UMPRequestParameters object.
  UMPRequestParameters *parameters = [[UMPRequestParameters alloc] init];
  // Set tag for under age of consent. NO means users are not under age
  // of consent.
  parameters.tagForUnderAgeOfConsent = NO;

  __weak __typeof__(self) weakSelf = self;
  // Request an update for the consent information.
  [UMPConsentInformation.sharedInstance
      requestConsentInfoUpdateWithParameters:parameters
          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 startGoogleMobileAdsSDKOnce];
                  }
                }];
          }];

  // 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 startGoogleMobileAdsSDKOnce];
  }
}

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

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

الاختبار

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

  1. يمكنك الاتصال بـ requestConsentInfoUpdateWithParameters:completionHandler:.
  2. تحقَّق من نتائج السجلّ بحثًا عن رسالة تشبه الرسالة أدناه، والتي تعرض رقم تعريف جهازك وكيفية إضافته كجهاز اختبار:

    <UMP SDK>To enable debug mode for this device, set: UMPDebugSettings.testDeviceIdentifiers = @[2077ef9a63d2b398840261c8221a0c9b]
    
  3. انسخ رقم تعريف جهاز الاختبار إلى الحافظة.

  4. يُرجى تعديل الرمز الخاص بك للاتصال 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){
                           ...
}];

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

Swift

UMPConsentInformation.sharedInstance.reset()

Objective-C

[UMPConsentInformation.sharedInstance reset];