حزمة تطوير البرامج لمنصّة User Messaging Platform (UMP) من Google هي أداة للخصوصية والمراسلة في إدارة خيارات الخصوصية لمزيد من المعلومات، يُرجى مراجعة حول الخصوصية و المراسلة يمكنك الاطّلاع على عملية تنفيذ إعلانات الوسائط التفاعلية باستخدام حزمة تطوير البرامج (SDK) لمنصة UMP في الهدف-ج أو Swift نماذج تطبيقات UMP.
إنشاء نوع رسالة
يمكنك إنشاء رسائل المستخدمين باستخدام إحدى أنواع رسائل المستخدمين المتاحة بموجب الخصوصية "المراسلة" في مدير إعلانات Google الحساب. تحاول حزمة تطوير البرامج لمنصّة UMP عرض رسالة خصوصية تم إنشاؤها من Interactive Media Ads معرّف التطبيق التي تم تعيينها في مشروعك.
لمزيد من التفاصيل، يُرجى مراجعة لمحة عن الخصوصية والمراسلة
استيراد حزمة تطوير البرامج (SDK)
لا يتم تضمين حزمة تطوير البرامج لمنصة UMP كملحق لحزمة تطوير البرامج لإعلانات الوسائط التفاعلية، لذا يجب عليك أضفها بنفسك بشكل صريح.
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 GitHub المستودع:
https://github.com/googleads/swift-package-manager-google-user-messaging-platform.git
اختَر إصدار حزمة UMP SDK Swift الذي تريد استخدامه. بالنسبة إلى الألعاب الجديدة ننصحك باستخدام الإصدار الرئيسي التالي.
يقوم Xcode بعد ذلك بحل تبعيات الحزمة الخاصة بك وتنزيلها في الخلفية. لمزيد من المعلومات حول كيفية إضافة تبعيات الحزمة، راجع Apple المقالة.
إضافة معرّف التطبيق
يمكنك العثور على رقم تعريف طلبك في
واجهة مستخدم "مدير إعلانات Google".
إضافة رقم التعريف إلى
Info.plist
باستخدام مقتطف الرمز التالي:
<key>UMPApplicationIdentifier</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 privacy message 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 privacy message form.
}];
}
تحميل نموذج رسالة الخصوصية وتقديمه إذا لزم الأمر
بعد تلقّي أحدث حالة الموافقة، اتصل
loadAndPresentIfRequiredFromViewController:completionHandler:
لتحميل أي نماذج مطلوبة
جمع موافقات المستخدمين بعد التحميل، تظهر النماذج على الفور.
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.privacyOptionsRequirementStatus
. - إذا كانت نقطة إدخال خيارات الخصوصية ، أضف عنصر واجهة مستخدم مرئيًا وتفاعليًا إلى تطبيقك.
- تشغيل نموذج خيارات الخصوصية باستخدام
presentPrivacyOptionsFormFromViewController:completionHandler:
يوضح مثال الرمز التالي هذه الخطوات:
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.
}
}];
}
طلب إدراج الإعلانات
قبل طلب الإعلانات في تطبيقك، يُرجى التحقّق مما إذا كنت قد حصلت على الموافقة.
من المستخدم باستخدام UMPConsentInformation.sharedInstance.canRequestAds
. هناك خياران
الأماكن التي يجب التحقّق منها أثناء جمع الموافقات:
- بعد الحصول على الموافقة في الجلسة الحالية
- فور اتصالك بـ
requestConsentInfoUpdateWithParameters:completionHandler:
. من المحتمل أن تكون قد حصلت على موافقة في الجلسة السابقة. كوقت استجابة أحد أفضل الممارسات، نوصي بعدم انتظار اكتمال معاودة الاتصال حتى تتمكن ابدأ في تحميل الإعلانات في أقرب وقت ممكن بعد إطلاق تطبيقك.
إذا حدث خطأ أثناء عملية الحصول على الموافقات، يجب عليك محاولة طلب إعلانات. تستخدم حزمة تطوير البرامج لمنصة UMP حالة الموافقة من الحزمة السابقة جلسة المراجعة.
Swift
class ViewController: UIViewController {
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.startImaSdk()
}
}
}
// Check if you can initialize the IMA 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 {
startImaSdk()
}
}
private func startImaSdk() {
// Create an IMAAdsLoader instance.
adsLoader = IMAAdsLoader(settings: nil)
// TODO: Create an IMAAdDisplayContainer and IMAAdsRequest, then make
// a request for ads.
}
}
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 startImaSdk];
}
}];
}];
// Check if you can initialize the Google IMA 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 startImaSdk];
}
}
- (void)startImaSdk {
static dispatch_once_t onceToken;
dispatch_once(&onceToken, ^{
// Create an IMAAdsLoader instance.
self.adsLoader = [[IMAAdsLoader alloc] init];
// TODO: Create an IMAAdDisplayContainer and IMAAdsRequest, then make
// a request for ads.
});
}
الاختبار
إذا أردت اختبار التكامل في تطبيقك أثناء تطويره، اتّبِع الخطوات التالية: هذه الخطوات لتسجيل جهاز الاختبار برمجيًا. تأكد من إزالة الذي يضبط أرقام تعريف الأجهزة الاختبارية هذه قبل إصدار تطبيقك.
- اتصل على
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){
...
}];
إعادة ضبط حالة الموافقة
أثناء اختبار تطبيقك باستخدام حزمة تطوير البرامج لمنصة UMP، قد يكون من المفيد إعادة ضبط
لحالة حزمة SDK لكي تتمكّن من محاكاة أول عملية تثبيت للمستخدم.
وتوفّر حزمة تطوير البرامج (SDK) الطريقة reset
لإجراء ذلك.
Swift
UMPConsentInformation.sharedInstance.reset()
Objective-C
[UMPConsentInformation.sharedInstance reset];