البدء

تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

تُسهِّل أدوات تطوير البرامج لإعلانات الوسائط التفاعلية دمج إعلانات الوسائط المتعددة في مواقعك الإلكترونية وتطبيقاتك. ويمكن أن تطلب أدوات تطوير البرامج لإعلانات الوسائط التفاعلية إعلانات من أي خادم متوافق مع VAST وإدارة تشغيل الإعلانات في تطبيقاتك. باستخدام حزم تطوير البرامج (SDK) لإدراج إعلان ديناميكي لإعلانات الوسائط التفاعلية (IMA)، تقدم التطبيقات طلب بث للفيديو ومحتوى الإعلان، سواء كان ذلك من خلال الفيديو المباشر أو المحتوى المباشر. تعرض حزمة تطوير البرامج (SDK) بعد ذلك بث فيديو مجمّعًا، بحيث لا تحتاج إلى إدارة التبديل بين فيديو الإعلان والمحتوى في تطبيقك.

يوضح هذا الدليل كيفية دمج أداة تطوير البرامج (SDK) لإعلانات الوسائط التفاعلية (IMA) في تطبيق بسيط لمشغّل الفيديو. إذا كنت ترغب في عرض دمج نموذجي مكتمل أو المتابعة معه، يمكنك تنزيل BasicExample من GitHub.

نظرة عامة على DAI لإعلانات الوسائط التفاعلية

يتضمن تنفيذ إعلانات الوسائط التفاعلية (IMA) أربعة عناصر SDK رئيسية يتم توضيحها في هذا الدليل:

  • IMAAdDisplayContainer: كائن حاوية يظهر أعلى عنصر تشغيل الفيديو ويضم عناصر واجهة مستخدم الإعلان.
  • IMAAdsLoader: كائن يطلب البث ويعالج الأحداث التي شغّلتها كائنات استجابة طلب البث. يجب عليك إنشاء مثيل واحد لبرنامج تحميل إعلانات يمكن إعادة استخدامه طوال فترة عمل التطبيق.
  • IMAStreamRequest – إما IMAVODStreamRequest أو IMALiveStreamRequest: كائن يحدّد طلب البث. يمكن أن تكون طلبات البث إما لأحداث الفيديو حسب الطلب أو لأحداث البث المباشر. وتحدد الطلبات معرّف المحتوى، بالإضافة إلى مفتاح واجهة برمجة التطبيقات أو الرمز المميز للمصادقة ومعلمات أخرى.
  • IMAStreamManager: كائن يتعامل مع مجموعات بث إعلان ديناميكي وتفاعلات مع خلفية DAI. كما يتعامل مدير البث أيضًا مع أدوات فحص الاتصال ويعيد توجيه أحداث البث والإعلانات إلى الناشر.

المتطلبات الأساسية

قبل البدء، تحتاج إلى ما يلي:

1- إنشاء مشروع Xcode جديد

في Xcode، أنشئ مشروعًا جديدًا على نظام التشغيل iOS باستخدام الهدف C. استخدم BasicExample كاسم المشروع.

2. إضافة أداة تطوير البرامج (SDK) لإعلانات الوسائط التفاعلية (IMA) إلى مشروع Xcode

تثبيت حزمة تطوير البرامج (SDK) باستخدام CocoaPods (الخيار المفضّل)

CocoaPods هو مدير تبعي لمشاريع Xcode وهو الطريقة المُوصى بها لتثبيت أداة تطوير البرامج لإعلانات الوسائط التفاعلية. لمزيد من المعلومات حول تثبيت أو استخدام CocoaPods، يُرجى الاطّلاع على وثائق CocoaPods. بعد تثبيت CocoaPods، اتبع التعليمات التالية لتثبيت أداة تطوير البرامج (SDK) لإعلانات الوسائط التفاعلية (IMA):

  1. في نفس دليل ملف BasicExample.xcodeproj، أنشئ ملفًا نصيًا باسم Podfile، ثم أضف التهيئة التالية:

    source 'https://github.com/CocoaPods/Specs.git'
    platform :ios, '10'
    target "BasicExample" do
      pod 'GoogleAds-IMA-iOS-SDK', '~> 3.11.4'
    end
    
  2. من الدليل الذي يحتوي على Podfile، شغِّل pod install --repo-update

  3. تحقّق من نجاح عملية التثبيت من خلال فتح الملف BasicExample.xcworkspace والتأكّد من أنه يحتوي على مشروعَين: BasicExample وPods (التبعيات التي ثبّتها CocoaPods).

تنزيل SDK وتثبيته يدويًا

إذا لم تكن ترغب في استخدام CocoaPods، يمكنك تنزيل أداة تطوير البرامج (SDK) لإعلانات الوسائط التفاعلية (IMA) وإضافتها يدويًا إلى مشروعك.

3- إنشاء مشغل فيديو بسيط

أولاً، نفّذ مشغل فيديو أساسيًا. في البداية، لا يستخدم هذا المشغل أداة IMA IMA ولا يحتوي على أي طريقة لتشغيل التشغيل.

ViewController.m

#import "ViewController.h"

#import <AVKit/AVKit.h>

@interface ViewController ()
@property(nonatomic) AVPlayerViewController *playerViewController;
@end

@implementation ViewController

- (void)viewDidLoad {
  [super viewDidLoad];
  self.view.backgroundColor = [UIColor blackColor];

  // Create a stream video player.
  AVPlayer *player = [[AVPlayer alloc] init];
  self.playerViewController = [[AVPlayerViewController alloc] init];
  self.playerViewController.player = player;

  // Attach the video player to the view hierarchy.
  [self addChildViewController:self.playerViewController];
  self.playerViewController.view.frame = self.view.bounds;
  [self.view addSubview:self.playerViewController.view];
  [self.playerViewController didMoveToParentViewController:self];
}

@end

4. استيراد حزمة SDK وإضافة التنويهات للتفاعل مع إعلانات الوسائط التفاعلية

بعد إضافة أداة تطوير البرامج لإعلانات الوسائط التفاعلية إلى مشروعك، استورد أداة SDK وأضف التنويهات للنقاط الأساسية للتفاعل مع إعلانات الوسائط التفاعلية.

ViewController.m

#import "ViewController.h"

#import <AVKit/AVKit.h>
#import <GoogleInteractiveMediaAds/GoogleInteractiveMediaAds.h>

@interface ViewController ()
@property(nonatomic) IMAAdsLoader *adsLoader;
@property(nonatomic) UIView *adContainerView;
@property(nonatomic) IMAStreamManager *streamManager;
@property(nonatomic) AVPlayerViewController *playerViewController;
@end

@implementation ViewController

- (void)viewDidLoad {
  [super viewDidLoad];
  self.view.backgroundColor = [UIColor blackColor];

  [self setupAdsLoader];

  // Create a stream video player.
  AVPlayer *player = [[AVPlayer alloc] init];
  self.playerViewController = [[AVPlayerViewController alloc] init];
  self.playerViewController.player = player;

  // Attach the video player to the view hierarchy.
  [self addChildViewController:self.playerViewController];
  self.playerViewController.view.frame = self.view.bounds;
  [self.view addSubview:self.playerViewController.view];
  [self.playerViewController didMoveToParentViewController:self];

  [self attachAdContainer];
}

- (void)viewDidAppear:(BOOL)animated {
  [super viewDidAppear:animated];
  [self requestStream];
}

- (void)setupAdsLoader {}

- (void)attachAdContainer {}

- (void)requestStream {}

@end

5- تنفيذ أداة IMAAdsLoader

بعد ذلك، عليك إنشاء مثيل للشكل IMAAdsLoader وإرفاق عرض حاوية الإعلان بالتسلسل الهرمي للملف الشخصي.

ViewController.m

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

- (void)attachAdContainer {
  self.adContainerView = [[UIView alloc] init];
  [self.view addSubview:self.adContainerView];
  self.adContainerView.frame = self.view.bounds;
}
...

6. تقديم طلب للبث

أنشِئ بعض الثوابت عند الاحتفاظ بمعلومات البث، ثم نفِّذ دالة طلب البث لإجراء الطلب.

ViewController.m

...
#import <GoogleInteractiveMediaAds/GoogleInteractiveMediaAds.h>

static NSString *const kAssetKey = @"sN_IYUG8STe1ZzhIIE_ksA";
static NSString *const kContentSourceID = @"2528370";
static NSString *const kVideoID = @"tears-of-steel";

@interface ViewController ()
...

- (void)requestStream {
  IMAAVPlayerVideoDisplay *videoDisplay =
      [[IMAAVPlayerVideoDisplay alloc] initWithAVPlayer:self.playerViewController.player];
  IMAAdDisplayContainer *adDisplayContainer =
      [[IMAAdDisplayContainer alloc] initWithAdContainer:self.adContainerView];
  IMALiveStreamRequest *request = [[IMALiveStreamRequest alloc] initWithAssetKey:kAssetKey
                                                              adDisplayContainer:adDisplayContainer
                                                                    videoDisplay:videoDisplay];
  // VOD request. Comment out the IMALiveStreamRequest above and uncomment this IMAVODStreamRequest
  // to switch from a livestream to a VOD stream.
  // IMAVODStreamRequest *request =
  //     [[IMAVODStreamRequest alloc] initWithContentSourceId:kContentSourceID
  //                                                  videoId:kVideoID
  //                                       adDisplayContainer:adDisplayContainer
  //                                             videoDisplay:videoDisplay];
  [self.adsLoader requestStreamWithRequest:request];
}
...

7- التعامل مع أحداث البث

IMAAdsLoader وIMAStreamManager حدثا إطفاء يُستخدمان لمعالجة معالجة أخطاء التهيئة والأخطاء والتغييرات في حالة البث. ويتم تنشيط هذه الأحداث عبر البروتوكولين IMAAdsLoaderDelegate وIMAStreamManagerDelegate. استمع إلى حدث تم تحميله للإعلانات وأعد البث. إذا أخفق تحميل أحد الإعلانات، فيمكنك تشغيل بث احتياطي بدلاً من ذلك.

ViewController.m

...
static NSString *const kAssetKey = @"sN_IYUG8STe1ZzhIIE_ksA";
static NSString *const kContentSourceID = @"2528370";
static NSString *const kVideoID = @"tears-of-steel";
static NSString *const kBackupStreamURLString =
    @"https://storage.googleapis.com/interactive-media-ads/media/bbb.m3u8";

@interface ViewController () <IMAAdsLoaderDelegate, IMAStreamManagerDelegate>

...
  [self.adsLoader requestStreamWithRequest:request];
}

- (void)playBackupStream {
  NSURL *backupStreamURL = [NSURL URLWithString:kBackupStreamURLString];
  AVPlayerItem *backupStreamItem = [AVPlayerItem playerItemWithURL:backupStreamURL];
  [self.playerViewController.player replaceCurrentItemWithPlayerItem:backupStreamItem];
  [self.playerViewController.player play];
}


#pragma mark - IMAAdsLoaderDelegate

- (void)adsLoader:(IMAAdsLoader *)loader adsLoadedWithData:(IMAAdsLoadedData *)adsLoadedData {
  // Initialize and listen to stream manager's events.
  self.streamManager = adsLoadedData.streamManager;
  self.streamManager.delegate = self;
  [self.streamManager initializeWithAdsRenderingSettings:nil];
  NSLog(@"Stream created with: %@.", self.streamManager.streamId);
}

- (void)adsLoader:(IMAAdsLoader *)loader failedWithErrorData:(IMAAdLoadingErrorData *)adErrorData {
  // Fall back to playing the backup stream.
  NSLog(@"Error loading ads: %@", adErrorData.adError.message);
  [self playBackupStream];
}


#pragma mark - IMAStreamManagerDelegate

- (void)streamManager:(IMAStreamManager *)streamManager didReceiveAdEvent:(IMAAdEvent *)event {}

- (void)streamManager:(IMAStreamManager *)streamManager didReceiveAdError:(IMAAdError *)error {}

- (void)streamManager:(IMAStreamManager *)streamManager
  adDidProgressToTime:(NSTimeInterval)time
           adDuration:(NSTimeInterval)adDuration
           adPosition:(NSInteger)adPosition
             totalAds:(NSInteger)totalAds
      adBreakDuration:(NSTimeInterval)adBreakDuration {}

@end

8. التعامل مع التسجيل وأحداث الخطأ

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

ViewController.m

...
#pragma mark - IMAStreamManagerDelegate

- (void)streamManager:(IMAStreamManager *)streamManager didReceiveAdEvent:(IMAAdEvent *)event {
  NSLog(@"StreamManager event (%@).", event.typeString);
  switch (event.type) {
    case kIMAAdEvent_STARTED: {
      // Log extended data.
      NSString *extendedAdPodInfo = [[NSString alloc]
          initWithFormat:@"Showing ad %zd/%zd, bumper: %@, title: %@, description: %@, contentType:"
                         @"%@, pod index: %zd, time offset: %lf, max duration: %lf.",
                         event.ad.adPodInfo.adPosition, event.ad.adPodInfo.totalAds,
                         event.ad.adPodInfo.isBumper ? @"YES" : @"NO", event.ad.adTitle,
                         event.ad.adDescription, event.ad.contentType, event.ad.adPodInfo.podIndex,
                         event.ad.adPodInfo.timeOffset, event.ad.adPodInfo.maxDuration];

      NSLog(@"%@", extendedAdPodInfo);
      break;
    }
    case kIMAAdEvent_AD_BREAK_STARTED: {
      // Prevent user seek through when an ad starts and show the ad controls.
      self.adContainerView.hidden = NO;
      break;
    }
    case kIMAAdEvent_AD_BREAK_ENDED: {
      // Allow user seek through after an ad ends and hide the ad controls.
      self.adContainerView.hidden = YES;
      break;
    }
    default:
      break;
  }
}

- (void)streamManager:(IMAStreamManager *)streamManager didReceiveAdError:(IMAAdError *)error {
  // Fall back to playing the backup stream.
  NSLog(@"StreamManager error: %@", error.message);
  [self playBackupStream];
}

@end

أكملت هذه الخطوة. أنت الآن تطلب إعلانات وتعرضها باستخدام أداة تطوير البرامج (SDK) لإعلانات الوسائط التفاعلية (IMA). لمعرفة المزيد من المعلومات حول ميزات حزمة تطوير البرامج (SDK) الأكثر تقدمًا، اطّلع على الأدلة الأخرى أو على النماذج على GitHub.

الخطوات التالية

لزيادة أرباح الإعلانات إلى أقصى حد على منصة iOS، يمكنك طلب إذن تتبُّع التطبيقات والشفافية في التطبيقات لاستخدام معرّف المعلِنين (IDFA).