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

يوضِّح هذا الدليل كيفية طلب معلومات موافقة المستخدِم من خلال نموذج موافقة، ثم التحقُّق من موافقة المستخدِم عند طلب الإعلانات باستخدام حزمة تطوير البرامج (SDK) لمنصّة User Messaging (UMP) في أحد تطبيقات SwiftUI.

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

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

إليك مثال على كيفية التحقّق من الحالة من View في طريقة onAppear(perform:).

struct ContentView: View {
  @State private var hasViewAppeared = false

  var body: some View {
    VStack {
      ...
    }
    .onAppear {
      // Gather consent only the first time the view appears.
      guard !hasViewAppeared else { return }
      hasViewAppeared = true

      // 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) {
         (requestConsentError) in

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

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

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

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

إنشاء واجهة مستخدم UIViewControllerRepresentable

بما أنّ السمة loadAndPresentIfRequiredFromViewController:completionHandler: تتطلب كائن UIViewController، يجب إنشاء نوع يتوافق مع بروتوكول UIViewControllerRepresentable. وتتمثل مهمتها الأساسية في عرض مرجع UIViewController للوصول إلى البيانات في SwiftUI.

struct FormViewControllerRepresentable: UIViewControllerRepresentable {
  let viewController = UIViewController()

  func makeUIViewController(context: Context) -> some UIViewController {
    return viewController
  }

  func updateUIViewController(_ uiViewController: UIViewControllerType, context: Context) {}
}

من المفترض ألا يكون لنوع ViewControllerRepresentable أي دلالة على المحتوى المعروض على الشاشة، ولكن يجب إضافته إلى التسلسل الهرمي لطريقة العرض. يمكنك إضافته ضمن عنصر تعديل المشاهَدات background(alignment:content:) حتى لا يشغل مساحة كبيرة على الشاشة.

struct ContentView: View {
  @State private var hasViewAppeared = false
  private let formViewControllerRepresentable = FormViewControllerRepresentable()

  var body: some View {
    VStack {
      ...
    }
    .background {
      // Add the ViewControllerRepresentable to the background so it
      // doesn't influence the placement of other views in the view hierarchy.
      formViewControllerRepresentable
        .frame(width: .zero, height: .zero)
    }
    .onAppear {
      // Gather consent only the first time the view appears.
      guard !hasViewAppeared else { return }
      hasViewAppeared = true

      // 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) {
         (requestConsentError) in

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

        UMPConsentForm.loadAndPresentIfRequired(from:
            formViewControllerRepresentable.viewController) { loadAndPresentError in

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

          // Consent gathering completed.
        }
      }
    }
  }
}

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

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

  1. بعد الحصول على الموافقة في الجلسة الحالية
  2. بعد الاتصال بـ requestConsentInfoUpdateWithParameters:completionHandler:مباشرةً

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

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

struct ContentView: View {
  @State private var isMobileAdsStartCalled = false
  @State private var hasViewAppeared = false
  private let formViewControllerRepresentable = FormViewControllerRepresentable()

  var body: some View {
    VStack {
      ...
    }
    .background {
      // Add the ViewControllerRepresentable to the background so it
      // doesn't influence the placement of other views in the view hierarchy.
      formViewControllerRepresentable
        .frame(width: .zero, height: .zero)
    }
    .onAppear {
      // Gather consent only the first time the view appears.
      guard !hasViewAppeared else { return }
      hasViewAppeared = true

      // 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) {
         requestConsentError in

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

        UMPConsentForm.loadAndPresentIfRequired(from:
            formViewControllerRepresentable.viewController) { (loadAndPresentError) in

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

          // Consent gathering completed.
          if UMPConsentInformation.sharedInstance.canRequestAds {
            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() {
    guard !isMobileAdsStartCalled else { return }

    isMobileAdsStartCalled = true

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

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