البدء

اختيار النظام الأساسي: Android iOS

حزمة تطوير البرامج لمنصة UMP هي أداة للخصوصية والمراسلة تساعدك في إدارة خيارات الخصوصية. لمزيد من المعلومات، يُرجى الاطّلاع على مقالة لمحة عن أداة "الخصوصية والمراسلة". يمكنك الاطّلاع على نموذج لتكامل حزمة تطوير البرامج لإعلانات الوسائط التفاعلية (IMA) مع حزمة تطوير البرامج لمنصة UMP في أحد تطبيقات UMP النموذجية، إما تطبيق UmpExample المستند إلى Objective-C أو Swift.

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

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

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

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

لا يتم تضمين حزمة تطوير البرامج لمنصة UMP كملحق لحزمة تطوير البرامج لإعلانات الوسائط التفاعلية، لذا عليك إضافتها بنفسك بشكلٍ صريح.

CocoaPods (مفضّل)

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

pod 'GoogleUserMessagingPlatform'

بعد ذلك، شغِّل الأمر أدناه:

pod install --repo-update

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

Swift Package Manager

تتوافق حزمة تطوير البرامج لمنصة UMP أيضًا مع Swift Package Manager. اتّبِع الخطوات التالية لاستيراد حزمة Swift:

  1. في Xcode، ثبِّت حزمة تطوير البرامج لمنصة UMP SDK Swift Package من خلال الانتقال إلى ملف > إضافة حِزم....

  2. في النافذة المنبثقة التي تظهر، ابحث عن مستودع حزمة تطوير البرامج لمنصة UMP Swift Package على GitHub:

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

  3. اختَر إصدار حزمة تطوير البرامج لمنصة UMP Swift Package الذي تريد استخدامه. بالنسبة إلى المشاريع الجديدة، ننصحك باستخدام الإصدار الرئيسي التالي أو إصدار أقدم.

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

إضافة رقم تعريف التطبيق

يمكنك العثور على رقم تعريف تطبيقك في الـ واجهة مستخدم إدارة الإعلانات. أضِف رقم التعريف إلى ملف 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
  // ...
}

Objective-C


// 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)

Objective-C


[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
}

Objective-C


- (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)

Objective-C


[UMPConsentForm presentPrivacyOptionsFormFromViewController:viewController
                                          completionHandler:completionHandler];

طلب الإعلانات بعد الحصول على موافقة المستخدم

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

Swift

ConsentInformation.shared.canRequestAds

Objective-C

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
      // ...
    })

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

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

توفر حزمة تطوير البرامج لمنصة UMP طريقة لاختبار سلوك تطبيقك كما لو كان الجهاز في مناطق مختلفة، مثل المنطقة الاقتصادية الأوروبية والمملكة المتحدة وسويسرا، وذلك باستخدام 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
      // ...
    })

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

Swift

ConsentInformation.shared.reset()

Objective-C

[UMPConsentInformation.sharedInstance reset];

أمثلة على GitHub

يمكنك الاطّلاع على مثال كامل حول تكامل حزمة تطوير البرامج لمنصة UMP التي ناقشناها في هذه الصفحة ضمن Swift UmpExample و Objective-C UmpExample.

التالي
طلب الموافقة من المستخدمين في الاتحاد الأوروبي