تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

البدء

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

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

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

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

استيراد حزمة SDK

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

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

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

pod 'GoogleUserMessagingPlatform'

بعد ذلك، نفِّذ الأمر التالي:

pod install --repo-update

إذا كنت حديث العهد باستخدام CocoaPods، اطّلِع على مقالة استخدام CocoaPods لمعرفة تفاصيل حول كيفية إنشاء ملفات Podfiles واستخدامها.

أداة إدارة حِزم Swift

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

في Xcode، ثبِّت حزمة Swift الخاصة بحزمة تطوير البرامج (SDK) لمنصّة UMP من خلال الانتقال إلى ملف > إضافة حِزم....
في الطلب الذي يظهر، ابحث عن حزمة Swift لـ UMP SDK في مستودع GitHub:
```
https://github.com/googleads/swift-package-manager-google-user-messaging-platform.git
```
اختَر إصدار حزمة Swift الخاصة بحزمة تطوير البرامج (SDK) لمنصّة UMP الذي تريد استخدامه. بالنسبة إلى المشاريع الجديدة، ننصحك باستخدام الإصدار التالي.

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

أضِف رقم تعريف التطبيق.

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

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

جمع الموافقات

للحصول على الموافقة، أكمِل الخطوات التالية:

طلب أحدث معلومات موافقة المستخدم
حمِّل نموذج موافقة وقدِّمه، إذا لزم الأمر.

عليك طلب تعديل معلومات موافقة المستخدم عند كل بدء لتطبيقك باستخدام requestConsentInfoUpdateWithParameters:completionHandler:. يتحقّق هذا الطلب مما يلي:

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

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

بعد تلقّي أحدث حالة موافقة، اتصل بـ loadAndPresentIfRequiredFromViewController:completionHandler: لتحميل أي نماذج مطلوبة لجمع موافقة المستخدم. بعد التحميل، تظهر النماذج على الفور.

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

Swift


// Requesting an update to consent information should be called on every app launch.
UMPConsentInformation.sharedInstance.requestConsentInfoUpdate(with: parameters) {
  requestConsentError in
  guard requestConsentError == nil else {
    return consentGatheringComplete(requestConsentError)
  }

  UMPConsentForm.loadAndPresentIfRequired(from: consentFormPresentationviewController) {
    loadAndPresentError in

    // Consent has been gathered.
    consentGatheringComplete(loadAndPresentError)
  }
}ConsentManager.swift

Objective-C


// Requesting an update to consent information should be called on every app launch.
[UMPConsentInformation.sharedInstance
    requestConsentInfoUpdateWithParameters:parameters
                         completionHandler:^(NSError *_Nullable requestConsentError) {
                           if (requestConsentError) {
                             consentGatheringComplete(requestConsentError);
                           } else {
                             [UMPConsentForm
                                 loadAndPresentIfRequiredFromViewController:viewController
                                                          completionHandler:^(
                                                              NSError
                                                                  *_Nullable loadAndPresentError) {
                                                            // Consent has been gathered.
                                                            consentGatheringComplete(
                                                                loadAndPresentError);
                                                          }];
                           }
                         }];ConsentManager.m

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

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

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

بعد استدعاء requestConsentInfoUpdateWithParameters:completionHandler:، تحقّق من UMPConsentInformation.sharedInstance.privacyOptionsRequirementStatus لتحديد ما إذا كانت نقطة دخول خيارات الخصوصية مطلوبة لتطبيقك:

Swift


var isPrivacyOptionsRequired: Bool {
  return UMPConsentInformation.sharedInstance.privacyOptionsRequirementStatus == .required
}ConsentManager.swift

Objective-C


- (BOOL)areGDPRConsentMessagesRequired {
  return UMPConsentInformation.sharedInstance.privacyOptionsRequirementStatus ==
         UMPPrivacyOptionsRequirementStatusRequired;
}ConsentManager.m

إضافة عنصر مرئي إلى تطبيقك

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

Swift


self.privacySettingsButton.isEnabled = ConsentManager.shared.isPrivacyOptionsRequiredViewController.swift

Objective-C


// Set up the privacy options button to show the UMP privacy form.
// Check ConsentInformation.getPrivacyOptionsRequirementStatus
// to see the button should be shown or hidden.
strongSelf.privacySettingsButton.hidden =
    !ConsentManager.sharedInstance.areGDPRConsentMessagesRequired;ViewController.m

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

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

Swift


UMPConsentForm.presentPrivacyOptionsForm(
  from: viewController, completionHandler: completionHandler)ConsentManager.swift

Objective-C


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

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

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

بعد جمع الموافقة في الجلسة الحالية
بعد الاتصال بـ requestConsentInfoUpdateWithParameters:completionHandler: مباشرةً من المحتمل أنّه تم الحصول على الموافقة في الجلسة السابقة. من أفضل الممارسات المتعلّقة بالمُهلة عدم الانتظار حتى اكتمال عملية طلب إعادة الاتصال حتى تتمكّن من بدء تحميل الإعلانات في أقرب وقت ممكن بعد إطلاق تطبيقك.

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

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

Swift


ConsentManager.shared.gatherConsent(from: self) { [weak self] consentError in
  guard let self else { return }

  if let consentError {
    // Consent gathering failed. This sample loads ads using
    // consent obtained in the previous session.
    print("Error: \(consentError.localizedDescription)")
  }
  // ...
}ViewController.swift

Objective-C


  [ConsentManager.sharedInstance
      gatherConsentFromConsentPresentationViewController:self
                                consentGatheringComplete:^(NSError *_Nullable consentError) {
                                  if (consentError) {
                                    // Consent gathering failed.
                                    NSLog(@"Error: %@", consentError.localizedDescription);
                                  }

                                  __strong __typeof__(self) strongSelf = weakSelf;
                                  if (!strongSelf) {
                                    return;
                                  }

                                  // ...

                                  if (ConsentManager.sharedInstance.canRequestAds) {
                                    [strongSelf setupAdsLoader];
                                  }
                                }];

  // This sample attempts to load ads using consent obtained in the previous session.
  if (ConsentManager.sharedInstance.canRequestAds) {
    [self setupAdsLoader];
  }

  [self setUpContentPlayer];
}

- (IBAction)onPlayButtonTouch:(id)sender {
  [self requestAds];
  self.playButton.hidden = YES;
}

#pragma mark Content Player Setup

- (void)setUpContentPlayer {
  // Load AVPlayer with path to our content.
  NSURL *contentURL = [NSURL URLWithString:kTestAppContentUrl_MP4];
  self.contentPlayer = [AVPlayer playerWithURL:contentURL];

  // Create a player layer for the player.
  AVPlayerLayer *playerLayer = [AVPlayerLayer playerLayerWithPlayer:self.contentPlayer];

  // Size, position, and display the AVPlayer.
  playerLayer.frame = self.videoView.layer.bounds;
  [self.videoView.layer addSublayer:playerLayer];

  // Set up our content playhead and contentComplete callback.
  self.contentPlayhead = [[IMAAVPlayerContentPlayhead alloc] initWithAVPlayer:self.contentPlayer];
  [[NSNotificationCenter defaultCenter] addObserver:self
                                           selector:@selector(contentDidFinishPlaying:)
                                               name:AVPlayerItemDidPlayToEndTimeNotification
                                             object:self.contentPlayer.currentItem];
}

#pragma mark SDK Setup

- (void)setupAdsLoader {
  self.adsLoader = [[IMAAdsLoader alloc] initWithSettings:nil];
  self.adsLoader.delegate = self;
}

- (void)requestAds {
  // Create an ad display container for ad rendering.
  IMAAdDisplayContainer *adDisplayContainer =
      [[IMAAdDisplayContainer alloc] initWithAdContainer:self.videoView
                                          viewController:self
                                          companionSlots:nil];
  // Create an ad request with our ad tag, display container, and optional user context.
  IMAAdsRequest *request = [[IMAAdsRequest alloc] initWithAdTagUrl:kTestAppAdTagUrl
                                                adDisplayContainer:adDisplayContainer
                                                   contentPlayhead:self.contentPlayhead
                                                       userContext:nil];
  [self.adsLoader requestAdsWithRequest:request];
}

- (void)contentDidFinishPlaying:(NSNotification *)notification {
  // Make sure we don't call contentComplete as a result of an ad completing.
  if (notification.object == self.contentPlayer.currentItem) {
    [self.adsLoader contentComplete];
  }
}

#pragma mark AdsLoader Delegates

- (void)adsLoader:(IMAAdsLoader *)loader adsLoadedWithData:(IMAAdsLoadedData *)adsLoadedData {
  // Grab the instance of the IMAAdsManager and set ourselves as the delegate.
  self.adsManager = adsLoadedData.adsManager;
  self.adsManager.delegate = self;
  // Create ads rendering settings to tell the SDK to use the in-app browser.
  IMAAdsRenderingSettings *adsRenderingSettings = [[IMAAdsRenderingSettings alloc] init];
  adsRenderingSettings.linkOpenerPresentingController = self;
  // Initialize the ads manager.
  [self.adsManager initializeWithAdsRenderingSettings:adsRenderingSettings];
}

- (void)adsLoader:(IMAAdsLoader *)loader failedWithErrorData:(IMAAdLoadingErrorData *)adErrorData {
  // Something went wrong loading ads. Log the error and play the content.
  NSLog(@"Error loading ads: %@", adErrorData.adError.message);
  [self.contentPlayer play];
}

#pragma mark AdsManager Delegates

- (void)adsManager:(IMAAdsManager *)adsManager didReceiveAdEvent:(IMAAdEvent *)event {
  // When the SDK notified us that ads have been loaded, play them.
  if (event.type == kIMAAdEvent_LOADED) {
    [adsManager start];
  }
}

- (void)adsManager:(IMAAdsManager *)adsManager didReceiveAdError:(IMAAdError *)error {
  // Something went wrong with the ads manager after ads were loaded. Log the error and play the
  // content.
  NSLog(@"AdsManager error: %@", error.message);
  [self.contentPlayer play];
}

- (void)adsManagerDidRequestContentPause:(IMAAdsManager *)adsManager {
  // The SDK is going to play ads, so pause the content.
  [self.contentPlayer pause];
}

- (void)adsManagerDidRequestContentResume:(IMAAdsManager *)adsManager {
  // The SDK is done playing ads (at least for now), so resume the content.
  [self.contentPlayer play];
}

@end
ViewController.m

يُعدّ الرمز البرمجي التالي أداة تطوير برامج (SDK) لميزة DAI في إعلانات الوسائط التفاعلية بعد جمع موافقة المستخدم:

Swift


private func requestAds() {
  // Create ad display container for ad rendering.
  let adDisplayContainer = IMAAdDisplayContainer(
    adContainer: videoView, viewController: self, companionSlots: nil)
  // Create an ad request with our ad tag, display container, and optional user context.
  let request = IMAAdsRequest(
    adTagUrl: ViewController.testAppAdTagURL,
    adDisplayContainer: adDisplayContainer,
    contentPlayhead: contentPlayhead,
    userContext: nil)

  adsLoader.requestAds(with: request)
}ViewController.swift

Objective-C


- (void)setupAdsLoader {
  self.adsLoader = [[IMAAdsLoader alloc] initWithSettings:nil];
  self.adsLoader.delegate = self;
}ViewController.m

الاختبار

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

تواصل هاتفيًا مع "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 طريقة لاختبار سلوك تطبيقك كما لو كان الجهاز يقع في مناطق مختلفة، مثل المنطقة الاقتصادية الأوروبية أو المملكة المتحدة، باستخدام UMPDebugGeography. يُرجى العِلم أنّ إعدادات تصحيح الأخطاء لا تعمل إلا على الأجهزة الاختبارية.

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

يمكنك الاطّلاع على مثال كامل لدمج حزمة تطوير البرامج (SDK) لمنصّة UMP الموضّح في هذه الصفحة في المثالَين التاليَين: Swift UmpExample و Objective-C UmpExample.

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

البدء

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

استيراد حزمة SDK

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

أداة إدارة حِزم Swift

أضِف رقم تعريف التطبيق.

جمع الموافقات

طلب الحصول على معلومات الموافقة

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

Swift

Objective-C

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

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

Swift

Objective-C

إضافة عنصر مرئي إلى تطبيقك

Swift

Objective-C

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

Swift

Objective-C

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

Swift

Objective-C

Swift

Objective-C

الاختبار

Swift

Objective-C

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

Swift

Objective-C

إعادة ضبط حالة الموافقة

Swift

Objective-C

أمثلة على GitHub