البدء

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

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

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

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

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

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

CocoaPods (الخيار المفضّل)

أسهل طريقة لاستيراد حزمة SDK إلى مشروع 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 SDK Swift Package GitHub:

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

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

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

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

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

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

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

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

Swift

import UserMessagingPlatform

Objective-C

#include <UserMessagingPlatform/UserMessagingPlatform.h>

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

يمكنك العثور على رقم تعريف التطبيق في واجهة مستخدم AdMob. أضِف المعرّف إلى Info.plist باستخدام مقتطف الرمز التالي:

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

عليك طلب تعديل معلومات موافقة المستخدم عند كل عملية تشغيل للتطبيق، وذلك باستخدام requestConsentInfoUpdate(with:completionHandler:). يتحقّق هذا الطلب مما يلي:

  • ما إذا كانت الموافقة مطلوبة على سبيل المثال، يجب الحصول على الموافقة للمرة الأولى أو انتهت صلاحية قرار الموافقة السابق.
  • ما إذا كانت نقطة دخول خيارات الخصوصية مطلوبة تتطلّب بعض رسائل الخصوصية أن تسمح التطبيقات للمستخدمين بتعديل خيارات الخصوصية في أي وقت.

Swift


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

SwiftUI


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

Objective-C


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

تحميل نموذج رسالة الخصوصية وعرضه

بعد تلقّي أحدث حالة موافقة، استخدِم الدالة loadAndPresentIfRequired(from:) لتحميل أي نماذج مطلوبة لجمع موافقة المستخدم. بعد التحميل، تظهر النماذج على الفور.

Swift


try await ConsentForm.loadAndPresentIfRequired(from: viewController)
GoogleMobileAdsConsentManager.swift

SwiftUI


try await ConsentForm.loadAndPresentIfRequired(from: nil)
GoogleMobileAdsConsentManager.swift

Objective-C


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

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

يتم عرض بعض نماذج رسائل الخصوصية من نقطة دخول خيارات الخصوصية التي يعرضها الناشر، ما يتيح للمستخدمين إدارة خيارات الخصوصية في أي وقت. لمزيد من المعلومات حول نوع الرسالة التي تظهر للمستخدمين عند نقطة دخول خيارات الخصوصية، اطّلِع على أنواع رسائل المستخدِمين المتاحة.

التحقّق مما إذا كانت نقطة دخول خيارات الخصوصية مطلوبة

بعد طلب requestConsentInfoUpdate(with:completionHandler:)، تحقَّق من UMPConsentInformation.sharedInstance.privacyOptionsRequirementStatus لتحديد ما إذا كانت نقطة دخول لخيارات الخصوصية مطلوبة لتطبيقك. وإذا كانت نقطة الدخول مطلوبة، أضِف عنصرًا مرئيًا وقابلاً للتفاعل في واجهة المستخدم إلى تطبيقك يعرض نموذج خيارات الخصوصية. إذا لم تكن نقطة دخول الخصوصية مطلوبة، اضبط عنصر واجهة المستخدم على أن يكون غير مرئي وغير قابل للتفاعل.

Swift


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

Objective-C


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

للاطّلاع على القائمة الكاملة بحالات متطلبات خيارات الخصوصية، يُرجى الاطّلاع على UMPPrivacyOptionsRequirementStatus.

عرض نموذج خيارات الخصوصية

عندما يتفاعل المستخدم مع العنصر، اعرض نموذج خيارات الخصوصية:

Swift


try await ConsentForm.presentPrivacyOptionsForm(from: viewController)
GoogleMobileAdsConsentManager.swift

SwiftUI


try await ConsentForm.presentPrivacyOptionsForm(from: nil)
GoogleMobileAdsConsentManager.swift

Objective-C


[UMPConsentForm presentPrivacyOptionsFormFromViewController:viewController
                                          completionHandler:completionHandler];
GoogleMobileAdsConsentManager.m

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

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

Swift

ConsentInformation.shared.canRequestAds

Objective-C

UMPConsentInformation.sharedInstance.canRequestAds;

في ما يلي الأماكن التي يمكنك التحقّق منها لمعرفة ما إذا كان بإمكانك طلب عرض الإعلانات أثناء جمع الموافقة:

  • بعد أن تجمع حزمة تطوير البرامج (SDK) لمنصّة إدارة الموافقة الموافقة في الجلسة الحالية
  • مباشرةً بعد الاتصال بالرقم requestConsentInfoUpdate(with:completionHandler:) من المحتمل أنّ حزمة تطوير البرامج لمنصة UMP قد حصلت على الموافقة في جلسة التطبيق السابقة.

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

منع العمل المتكرّر في طلبات الإعلانات

أثناء التحقّق من UMPConsentInformation.sharedInstance.canRequestAds بعد جمع الموافقة وبعد طلب requestConsentInfoUpdate(with:completionHandler:)، تأكَّد من أنّ منطقك يمنع طلبات الإعلانات المكرّرة التي قد تؤدي إلى عرض true في كلتا الحالتين. على سبيل المثال، مع متغيّر منطقي.

الاختبار

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

  1. تواصل هاتفيًا مع " requestConsentInfoUpdate(with: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){
                          // ...
}];

فرض موقع جغرافي

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

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

Swift

ConsentInformation.shared.reset()

Objective-C

[UMPConsentInformation.sharedInstance reset];

أمثلة على GitHub

يمكنك الاطّلاع على مثال كامل لعملية دمج حزمة تطوير البرامج (SDK) الخاصة بمنصة UMP التي تم تناولها في هذه الصفحة في