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

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

اختيار حلّ DAI المطلوب

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

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

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

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

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

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

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

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

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

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

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

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

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

  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)

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

  1. في Xcode، ثبِّت حزمة Swift لواجهة برمجة التطبيقات لإدراج إعلان ديناميكي لإعلانات الوسائط التفاعلية من خلال الانتقال إلى ملف > إضافة حِزم.

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

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

  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.