بدء استخدام حزمة تطوير البرامج لإدراج إعلان ديناميكي لإعلانات الوسائط التفاعلية

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

اختيار حلّ DAI الذي يهمّك

خدمة إدراج إعلان ديناميكي كاملة

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

نظرة عامة على ميزة "إدراج إعلان ديناميكي" في إعلانات الوسائط التفاعلية

يتضمّن تنفيذ IMA DAI أربعة مكوّنات رئيسية لحزمة SDK كما هو موضّح في هذا الدليل:

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

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

قبل البدء، يجب توفّر ما يلي:

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

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

إضافة حزمة تطوير البرامج لإعلانات الوسائط التفاعلية (IMA DAI SDK) إلى مشروع Xcode

استخدِم إحدى الطريقتَين التاليتَين لتثبيت حزمة تطوير البرامج لميزة DAI في إعلانات الوسائط التفاعلية.

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

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

  1. في الدليل نفسه الذي يتضمّن ملف BasicExample.xcodeproj، أنشِئ ملفًا نصيًا بعنوان Podfile وأضِف الإعدادات التالية:

    source 'https://github.com/CocoaPods/Specs.git'
platform :ios, '14'
target "BasicExample" do
  pod 'GoogleAds-IMA-iOS-SDK', '~> 3.23.0'
end

  2. من الدليل الذي يحتوي على Podfile، شغِّل:

    pod install --repo-update`

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

تثبيت حزمة SDK باستخدام Swift Package Manager

تتوافق حزمة تطوير البرامج لإعلانات الوسائط التفاعلية مع Swift Package Manager بدءًا من الإصدار 3.18.4. اتّبِع الخطوات التالية لاستيراد حزمة Swift.

  1. في Xcode، ثبِّت حزمة Swift الخاصة بحزمة تطوير البرامج (SDK) لميزة "الإعلانات الديناميكية أثناء عرض الفيديو" من IMA من خلال الانتقال إلى ملف > إضافة حِزم.

  2. في الطلب الذي يظهر، ابحث عن حزمة Swift لـ IMA DAI SDK في مستودع GitHub:

    https://github.com/googleads/swift-package-manager-google-interactive-media-ads-ios

  3. اختَر إصدار حزمة Swift لـ IMA DAI SDK التي تريد استخدامها. بالنسبة إلى المشاريع الجديدة، ننصحك باستخدام الإصدار التالي.

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

تنزيل حزمة تطوير البرامج (SDK) وتثبيتها يدويًا

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

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

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

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

استيراد حزمة تطوير البرامج (SDK) وإضافة نماذج تفاعل لإعلانات الوسائط التفاعلية

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

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

تنفيذ 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;
}

تقديم طلب بث

أنشئ بعض الثوابت لتخزين معلومات البث، ثم نفِّذ دالة طلب البث لتقديم الطلب.

ViewController.m

#import <GoogleInteractiveMediaAds/GoogleInteractiveMediaAds.h>

static NSString *const kAssetKey = @"sN_IYUG8STe1ZzhIIE_ksA";
static NSString *const kContentSourceID = @"2548831";
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];
}

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

تُطلق IMAAdsLoader وIMAStreamManager أحداثًا تُستخدَم لمعالجة عمليات الإعداد والأخطاء والتغييرات في حالة البث. يتم تنشيط هذه الأحداث من خلال بروتوكولَي IMAAdsLoaderDelegate وIMAStreamManagerDelegate. انتظِر حدث loading ads (تحميل الإعلانات) وابدأ البث. إذا تعذّر تحميل إعلان، يمكنك تشغيل بث احتياطي بدلاً منه.

ViewController.m

static NSString *const kAssetKey = @"sN_IYUG8STe1ZzhIIE_ksA";
static NSString *const kContentSourceID = @"2548831";
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

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

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

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) لعرض الإعلانات الديناميكية على الشبكة الإعلانية لإعلانات الوسائط التفاعلية. للاطّلاع على معلومات أكثر حول ميزات حزمة تطوير البرامج (SDK) المتقدّمة، يمكنك الاطّلاع على الأدلة الأخرى أو على عيّنات على GitHub.