إضافة إعلانات الأصلية إلى تطبيق iOS

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

لنبدأ تنفيذ موضع الإعلان الأصلي التالي. سيلزمك إنشاء طرق العرض التالية في الإعلان الأصلي.

الخطوة الأولى: إنشاء طرق عرض الإعلان الأصلي في Storyboard

الخطوة الثانية: تحميل الإعلان الأصلي وعرضه

الخطوة الثالثة: كيفية الحصول على نسبة العرض إلى الارتفاع للمحتوى وتطبيق العرض والارتفاع الطبيعي

الخطوة الرابعة: التحقق من صحة تسجيل مرات الظهور والنقرات

الخطوة الخامسة: كيفية تصحيح الأخطاء في حالة عدم عرض الإعلان

الخطوة السادسة: تحميل إعلان بدون تخزين مؤقت تلقائي

الخطوة السابعة: اختبار تكامل الإعلانات

راجع المشاكل المعروفة في سجل التغييرات

الخطوة الأولى: إنشاء طرق عرض الإعلان الأصلي في Storyboard

1. بعد إنشاء مشروع جديد من دلائل بدء استخدام iOS، افتح Main.storyboard. أضف عنصر UIView إلى عنصر العرض الرئيسي وقم بتسميته ليكون adUIView.
   
   
   
2. وعلاوة على ذلك، أضف adIconImageView (FBMediaView), adTitleLabel (UILabel)، adCoverMediaView (FBMediaView)، adSocialContext (UILabel)، adCallToActionButton (UIButton)، adOptionsView (FBAdOptionsView)، adBodyLabel (UILabel)، sponsoredLabel (UILabel) ضمن adUIView كما هو موضح في الصورة أدناه.
   
   
   
3. قد تلاحظ ظهور سهم أحمر اللون بالقرب من عرض مشهد وحدة التحكم. دائمًا ما يشير ذلك إلى أن هناك قيودًا مفقودة في التخطيط الخاص بك.
   
   
   قد تحتاج إلى تحديد جميع كائنات العرض في المشهد الخاص بك والنقر على الأيقونة "إصلاح مشكلة التخطيط" لإضافة القيود المفقودة.
   
   
   
4. بعد الانتهاء من إنشاء جميع عناصر واجهة المستخدم اللازمة لعرض الإعلان الأصلي، ستحتاج إلى الإشارة إلى هذه العناصر في واجهة ViewController. أولاً، افتح ViewController.m (ViewController.swift إذا كنت تستخدم Swift)، ثم اسحب adUIView داخل الكائن ViewController. يمكنك تسميته adUIView. بعد ذلك، ستحتاج إلى تنفيذ الإجراء نفسه مع adIconImageView وadTitleLabel وadCoverMediaView وadSocialContext وadCallToActionButton وadOptionsView وadBodyLabel وsponsoredLabel.
   
   
   
5. قم بتطوير المشروع وتشغيله. من المفترض أن يظهر لك عبر الجهاز أو المحاكي محتوى فارغ على النحو التالي:
   

الخطوة التالية بعد إنشاء كل عناصر واجهة المستخدم لعرض الإعلانات الأصلية هي تحميل الإعلانات الأصلية وربط عناصر المحتوى بعناصر واجهة المستخدم.

الخطوة الثانية: تحميل الإعلان الأصلي وعرضه

1. في ملف مصدر View Controller، قم باستيراد مجموعة SDK، وأعلن أن ViewController يتوافق مع بروتوكول FBNativeAdDelegate، وأضف متغير المثيل FBNativeAd
   SwiftObjective-C

   import UIKit
   import FBAudienceNetwork
   
   class ViewController: UIViewController, FBNativeAdDelegate {
       
     private var nativeAd: FBNativeAd?
   }

   #import <UIKit/UIKit.h>
   @import FBAudienceNetwork;
   
   @interface ViewController () <FBNativeAdDelegate>
   
   @property (strong, nonatomic) FBNativeAd *nativeAd;
   
   @end


2. في الأسلوب viewDidLoad، أضف سطور الرمز التالية لتحميل محتوى الإعلان الأصلي
   SwiftObjective-C

   override func viewDidLoad() {
     super.viewDidLoad()
       
     let nativeAd = FBNativeAd(placementID: "YOUR_PLACEMENT_ID")
     nativeAd.delegate = self
     nativeAd.loadAd()
   }

   - (void)viewDidLoad 
   {
     [super viewDidLoad];
   
     FBNativeAd *nativeAd = [[FBNativeAd alloc] initWithPlacementID:@"YOUR_PLACEMENT_ID"];
     nativeAd.delegate = self;
     [nativeAd loadAd];
   }
   
   

   المعرف الذي يظهر في YOUR_PLACEMENT_ID هو معرف مؤقت لأغراض الاختبار فقط.

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

   لمعرفة كيفية إنشاء معرف موضع مباشر، ارجع إلى إعداد شبكة الجمهور

3. الخطوة التالية هي عرض الإعلان عندما يكون المحتوى جاهزًا. ستحتاج إلى ViewController لتنفيذ أسلوب التفويض nativeAdDidLoad
   SwiftObjective-C

   func nativeAdDidLoad(_ nativeAd: FBNativeAd) {
       
     // 1. If there is an existing valid native ad, unregister the view
     if let previousNativeAd = self.nativeAd, previousNativeAd.isAdValid {
       previousNativeAd.unregisterView()
     }
       
     // 2. Retain a reference to the native ad object
     self.nativeAd = nativeAd
   
     // 3. Register what views will be tappable and what the delegate is to notify when a registered view is tapped
     // Here only the call-to-action button and the media view are tappable, and the delegate is the view controller
     nativeAd.registerView(
       forInteraction: adUIView,
       mediaView: adCoverMediaView,
       iconView: adIconImageView,
       viewController: self,
       clickableViews: [adCallToActionButton, adCoverMediaView]
     )
       
     // 4. Render the ad content onto the view
     adTitleLabel.text = nativeAd.advertiserName
     adBodyLabel.text = nativeAd.bodyText
     adSocialContextLabel.text = nativeAd.socialContext
     sponsoredLabel.text = nativeAd.sponsoredTranslation
     adCallToActionButton.setTitle(nativeAd.callToAction, for: .normal)
     adOptionsView.nativeAd = nativeAd
   }

   - (void)nativeAdDidLoad:(FBNativeAd *)nativeAd
   {
     // 1. If there is an existing valid native ad, unregister the view
     if (self.nativeAd && self.nativeAd.isAdValid) {
       [self.nativeAd unregisterView];
     }
   
     // 2. Retain a reference to the native ad object
     self.nativeAd = nativeAd;
   
     // 3. Register what views will be tappable and what the delegate is to notify when a registered view is tapped
     // Here only the call-to-action button and the media view are tappable, and the delegate is the view controller
     [self.nativeAd registerViewForInteraction:self.adUIView
                                     mediaView:self.adCoverMediaView
                                      iconView:self.adIconImageView
                                viewController:self
                                clickableViews:@[self.adCallToActionButton, self.adCoverMediaView]];
   
     // 4. Render the ad content onto the view
     self.adTitleLabel.text = self.nativeAd.advertiserName;
     self.adBodyLabel.text = self.nativeAd.bodyText;
     self.adSocialContextLabel.text = self.nativeAd.socialContext;
     self.sponsoredLabel.text = self.nativeAd.sponsoredTranslation;
     [self.adCallToActionButton setTitle:self.nativeAd.callToAction forState:UIControlStateNormal];
     self.adOptionsView.nativeAd = self.nativeAd; 
   }

التحكم في المساحة القابلة للنقر

لتقديم تجربة أفضل للمستخدم والحصول على نتائج أفضل، يجب عليك دائمًا مراعاة التحكم في المساحة القابلة للنقر عليها في إعلانك لتجنب النقرات غير المقصودة. يرجى الرجوع إلى صفحة سياسة مجموعة Audience Network SDK للتعرف على مزيد من التفاصيل حول تنفيذ المساحة البيضاء غير القابلة للنقر.




4. بعد اختيار الجهاز كهدف للإنشاء وتشغيل الرمز أعلاه، يجب أن يظهر لك إعلان كما يلي:
   
   
   
   

الخطوة الثالثة: كيفية الحصول على نسبة العرض إلى الارتفاع للمحتوى وتطبيق العرض والارتفاع الطبيعي

في المثال السابق، يظهر محتوى وسائط الإعلان في adCoverMediaView ونوع الكائن هو FBMediaView. خلال الخطوة السابقة، أوضحنا كيفية استخدام FBMediaView لتحميل محتوى وسائط من كائن FBNativeAd محدد. يتم استخدام طريقة العرض هذه كبديل لتحميل صورة الغلاف يدويًا. عند إنشاء FBMediaView، يمكن تحديد خيارات العرض والارتفاع من خلال تعيين قيود التخطيط التلقائي في storyboard أو يمكن تضمينها في الرمز. مع ذلك، يمكن ألا يتناسب عرض وارتفاع طريقة العرض مع صورة الغلاف الفعلية للإعلان التي يتم تحميلها لاحقًا. لحل هذه المشكلة، يوضح المثال التالي كيفية الحصول على نسبة العرض إلى الارتفاع للمحتوى وتطبيق العرض والارتفاع الطبيعيين:

1. يمكنك الإعلان بأن View Controller يعمل على تنفيذ بروتوكول FBMediaViewDelegate
   SwiftObjective-C

   class ViewController: UIViewController, FBNativeAdDelegate, FBMediaViewDelegate {
     ...
   }

   @interface ViewController : UIViewController <FBNativeAdDelegate, FBMediaViewDelegate>
   ...
   @end


2. عندما يتم تحميل الإعلان الأصلي، قم بتعيين تفويض الكائن FBMediaView ليكون وحدة التحكم في طريقة العرض
   SwiftObjective-C

   func nativeAdDidLoad(_ nativeAd: FBNativeAd) {
     adCoverMediaView.delegate = self
   }

   - (void)nativeAdDidLoad:(FBNativeAd *)nativeAd 
   {
     self.adCoverMediaView.delegate = self;
   }


3. تنفيذ الأسلوب mediaViewDidLoad في وحدة التحكم في طريقة العرض
   SwiftObjective-C

   func mediaViewDidLoad(_ mediaView: FBMediaView) {
     let currentAspect = mediaView.frame.size.width / mediaView.frame.size.height
     print(currentAspect)
     
     let actualAspect = mediaView.aspectRatio
     print(actualAspect)
   }

   - (void)mediaViewDidLoad:(FBMediaView *)mediaView
   {
     CGFloat currentAspect = mediaView.frame.size.width / mediaView.frame.size.height;
     NSLog(@"current aspect of media view: %f", currentAspect);
     
     CGFloat actualAspect = mediaView.aspectRatio;
     NSLog(@"actual aspect of media view: %f", actualAspect);
   }
   
   يعمل mediaView.aspectRatio على إرجاع CGFloat إيجابي، أو 0.0 إذا لم يتم تحميل أي إعلان حاليًا. وتتحول القيمة إلى قيمة صالحة بعد تحميل طريقة عرض الوسائط. هناك طرق مناسبة تساعد في تعيين عرض وارتفاع كائن FBMediaView وتراعي نسبة العرض إلى الارتفاع لمحتوى الوسائط التي تم تحميلها. يمكنك استدعاء applyNaturalWidth أو applyNaturalHeight لتحديث عرض أو ارتفاع الكائن FBMediaView لمراعاة نسبة العرض إلى الارتفاع لمحتوى الوسائط.

الخطوة الرابعة: التحقق من صحة تسجيل مرات الظهور والنقرات

اختياريًا، يمكن إضافة الوظائف التالية لمعالجة الحالات التي يكون فيها الإعلان الأصلي مغلقًا أو التي يقوم فيها المستخدم بالنقر عليه

func nativeAdDidClick(_ nativeAd: FBNativeAd) {
  print("Native ad was clicked.")
}

func nativeAdDidFinishHandlingClick(_ nativeAd: FBNativeAd) {
  print("Native ad did finish click handling.")
}

func nativeAdWillLogImpression(_ nativeAd: FBNativeAd) {
  print("Native ad impression is being captured.")
}

- (void)nativeAdDidClick:(FBNativeAd *)nativeAd
{
  NSLog(@"Native ad was clicked.");
}

- (void)nativeAdDidFinishHandlingClick:(FBNativeAd *)nativeAd
{
  NSLog(@"Native ad did finish click handling.");
}

- (void)nativeAdWillLogImpression:(FBNativeAd *)nativeAd
{
  NSLog(@"Native ad impression is being captured.");
}

الخطوة الخامسة: كيفية تصحيح الأخطاء في حالة عدم عرض الإعلان

إضافة الوظيفة التالية وتنفيذها في وحدة التحكم في طريقة العرض لمعالجة حالات فشل تحميل الإعلان

func nativeAd(_ nativeAd: FBNativeAd, didFailWithError error: Error) {
  print("Native ad failed to load with error: \(error.localizedDescription)")
}

- (void)nativeAd:(FBNativeAd *)nativeAd didFailWithError:(NSError *)error
{
  NSLog(@"Native ad failed to load with error: %@", error);
}

الخطوة السادسة: تحميل إعلان بدون تخزين مؤقت تلقائي

1. نوصي بشدة بالاحتفاظ بالتخزين المؤقت للوسائط قيد التشغيل افتراضيًا في كل الحالات. مع ذلك، نسمح لك بتجاوز الإعداد الافتراضي. يُرجى توخي الحذر إذا قررت تخطي تخزين الوسائط المؤقت الافتراضي
   SwiftObjective-C

   let nativeAd = FBNativeAd(placementID: "YOUR_PLACEMENT_ID")
   nativeAd.delegate = self
   nativeAd.loadAd(withMediaCachePolicy: .none)

   FBNativeAd *nativeAd = [[FBNativeAd alloc] initWithPlacementID:@"YOUR_PLACEMENT_ID"];
   nativeAd.delegate = self;
   [nativeAd loadAdWithMediaCachePolicy:FBNativeAdsCachePolicyNone];


2. أولاً، ستحتاج إلى تنزيل كل الوسائط يدويًا للإعلان الأصلي
   SwiftObjective-C

   func nativeAdDidLoad(_ nativeAd: FBNativeAd) {
     
     ...
     
     self.adCoverMediaView.delegate = self
     nativeAd.downloadMedia()
     self.nativeAd = nativeAd
     
     ...
   }

   - (void)nativeAdDidLoad:(FBNativeAd *)nativeAd
   {
     ...
   
     self.adCoverMediaView.delegate = self;
     [nativeAd downloadMedia];
     self.nativeAd = nativeAd;
   
     ...
   }


3. بعد ذلك، يجب ألا يتم استدعاء registerViewForInteraction وعرض الإعلان بعد استدعاء mediaViewDidLoad. يجب تحميل كل الوسائط وعرضها للحصول على مرة ظهور إعلان مؤهلة
   SwiftObjective-C

   func mediaViewDidLoad(_ mediaView: FBMediaView) {
     guard let nativeAd = nativeAd else {
       return
     }
     
     // 1. Register what views will be tappable and what the delegate is to notify when a registered view is tapped
     // Here only the call-to-action button and the media view are tappable, and the delegate is the view controller
     nativeAd.registerView(
       forInteraction: adUIView,
       mediaView: mediaView,
       iconView: adIconImageView,
       viewController: self,
       clickableViews: [adCallToActionButton, mediaView]
     )
       
     // 2. Render the ad content onto the view
     adTitleLabel.text = nativeAd.advertiserName
     adBodyLabel.text = nativeAd.bodyText
     adSocialContextLabel.text = nativeAd.socialContext
     sponsoredLabel.text = nativeAd.sponsoredTranslation
     adCallToActionButton.setTitle(nativeAd.callToAction, for: .normal)
     adOptionsView.nativeAd = nativeAd
   }

   - (void)mediaViewDidLoad:(FBMediaView *)mediaView 
   {
     if (!self.nativeAd) {
       return;
     }
   
     // 1. Register what views will be tappable and what the delegate is to notify when a registered view is tapped
     // Here only the call-to-action button and the media view are tappable, and the delegate is the view controller
     [self.nativeAd registerViewForInteraction:self.adUIView
                                     mediaView:mediaView
                                      iconView:self.adIconImageView
                             viewController:self
                            clickableViews:@[self.adCallToActionButton, mediaView]];
   
     // 2. Render the ad content onto the view
     self.adTitleLabel.text = self.nativeAd.advertiserName;
     self.adBodyLabel.text = self.nativeAd.bodyText;
     self.adSocialContextLabel.text = self.nativeAd.socialContext;
     self.sponsoredLabel.text = self.nativeAd.sponsoredTranslation;
     [self.adCallToActionButton setTitle:self.nativeAd.callToAction forState:UIControlStateNormal];
     self.adOptionsView.nativeAd = self.nativeAd; 
   }