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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    pod install --repo-update`

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

تثبيت حزمة SDK باستخدام "مدير الحزم" في Swift

تتوافق "حزمة تطوير البرامج لإعلانات الوسائط التفاعلية" مع أداة Swift Package Manager بدءًا من الإصدار 4.8.2. اتبع هذه الخطوات لاستيراد حزمة Swift.

  1. في Xcode، ثبِّت حزمة IMA SDK Swift من خلال الانتقال إلى ملف > إضافة حِزم.

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

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

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

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

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

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

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

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

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) وإضافة الإشارات المرجعية للنقاط الأساسية لتفاعل إعلانات الوسائط التفاعلية.

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. استمع إلى حدث تم تحميله للإعلانات وابدأ عملية البث وإذا تعذّر تحميل الإعلان، يمكنك تشغيل بث احتياطي بدلاً من ذلك.

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، يمكنك الاطّلاع على الأدلة الأخرى أو النماذج على GitHub.