بموجب سياسة موافقة المستخدم في الاتحاد الأوروبي التي تتّبعها Google، يجب الإفصاح عن معلومات معيّنة للمستخدمين في المنطقة الاقتصادية الأوروبية (EEA) والمملكة المتحدة والحصول على موافقتهم على استخدام ملفات تعريف الارتباط أو غير ذلك من البيانات المحفوظة على أجهزتهم المحلية حسب ما يقتضيه القانون، وعلى استخدام البيانات الشخصية (مثل AdID) لعرض الإعلانات. تعكس هذه السياسة شروط "التوجيه الأوروبي بشأن الخصوصية الإلكترونية" و"اللائحة العامة لحماية البيانات" (GDPR).
لدعم الناشرين في الوفاء بالتزاماتهم بموجب هذه السياسة، تقدّم Google حزمة تطوير البرامج (SDK) لمنصّة User Messaging Platform (UMP). تم تحديث حزمة تطوير البرامج لمنصة UMP لتتوافق مع أحدث معايير IAB. يمكن الآن التعامل مع كل هذه الإعدادات بسهولة في AdMob الخصوصية والمراسلة.
المتطلّبات الأساسية
- أكمِل دليل البدء.
- إذا كنت تعمل على استيفاء المتطلبات المتعلّقة باللائحة العامة لحماية البيانات، يُرجى قراءة تأثير متطلّبات مكتب IAB على رسائل طلب موافقة المستخدمين في الاتحاد الأوروبي
إنشاء نوع رسالة
يمكنك إنشاء رسائل المستخدمين باستخدام أحد أنواع رسائل المستخدمين المتوفرة ضمن علامة تبويب الخصوصية والمراسلة في حساب AdMob . تحاول حزمة تطوير البرامج لمنصة UMP عرض رسالة مستخدم تم إنشاؤها من AdMob معرّف التطبيق المحدّد في مشروعك. وفي حال عدم إعداد أي رسالة لتطبيقك، ستعرض حزمة تطوير البرامج (SDK) رسالة خطأ.
لمزيد من التفاصيل، يُرجى الاطّلاع على لمحة عن الخصوصية والمراسلة.
استيراد حزمة تطوير البرامج (SDK)
CocoaPods (الخيار المفضّل)
أسهل طريقة لاستيراد حزمة تطوير البرامج (SDK) إلى مشروع iOS هي استخدام CocoaPods. افتح ملف Podfile الخاص بمشروعك وأضف هذا السطر إلى هدف تطبيقك:
pod 'GoogleUserMessagingPlatform'
بعد ذلك، شغِّل الأمر التالي:
pod install --repo-update
إذا كنت مستخدمًا جديدًا لـ CocoaPods، يمكنك الاطّلاع على استخدام CocoaPods للحصول على تفاصيل حول كيفية إنشاء ملفات Podfiles واستخدامها.
مدير حزم Swift
تدعم حزمة تطوير البرامج لمنصّة UMP أيضًا أداة "إدارة حزم Swift". اتبع هذه الخطوات لاستيراد حزمة Swift.
في Xcode، ثبِّت حزمة UMP SDK Swift من خلال الانتقال إلى ملف > إضافة حِزم....
في المطالبة التي تظهر، ابحث عن مستودع UMP SDK Swift Package GitHub:
https://github.com/googleads/swift-package-manager-google-user-messaging-platform.git
اختَر إصدار حزمة 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>
طلب الحصول على معلومات الموافقة
يجب طلب تعديل لمعلومات موافقة المستخدم في كل مرة يتم فيها تشغيل التطبيق، وذلك باستخدام 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.
}];
}
تحميل نموذج موافقة وتقديمه إذا لزم الأمر
بعد تلقّي أحدث حالة للموافقة، يمكنك الاتصال
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:
. من المحتمل أن تكون قد حصلت على موافقة في الجلسة السابقة. ومن أفضل ممارسات وقت الاستجابة، عدم انتظار اكتمال معاودة الاتصال حتى تتمكن من البدء في تحميل الإعلانات في أقرب وقت ممكن بعد إطلاق تطبيقك.
إذا حدث خطأ أثناء عملية الحصول على الموافقات، يجب أن تحاول طلب الإعلانات. تستخدم حزمة تطوير البرامج لمنصّة 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){
...
}];
إعادة ضبط حالة الموافقة
أثناء اختبار تطبيقك باستخدام حزمة تطوير البرامج (SDK) لمنصّة UMP، قد يكون من المفيد إعادة ضبط
حالة حزمة تطوير البرامج (SDK) كي تتمكّن من محاكاة تجربة التثبيت الأولى للمستخدم.
وتوفّر حزمة تطوير البرامج (SDK) الطريقة reset
لإجراء ذلك.
Swift
UMPConsentInformation.sharedInstance.reset()
Objective-C
[UMPConsentInformation.sharedInstance reset];
أمثلة على GitHub
أمثلة على دمج حزمة تطوير البرامج لمنصّة UMP: Swift | Objective-C