تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

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

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

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

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

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

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

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

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

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

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

الإصدار 13 من Xcode أو إصدار أحدث
CocoaPods (الخيار المفضّل) أو Swift Package Manager أو نسخة تم تنزيلها من حزمة تطوير البرامج لإدراج إعلان ديناميكي لإعلانات الوسائط التفاعلية لنظام التشغيل tvOS

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

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

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

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

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

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

في الدليل نفسه الذي يتضمّن ملف BasicExample.xcodeproj، أنشِئ ملفًا نصيًا باسم Podfile وأضِف الإعدادات التالية:
```
source 'https://github.com/CocoaPods/Specs.git'
platform :tvos, '14'
target "BasicExample" do
  pod 'GoogleAds-IMA-tvOS-SDK', '~> 4.13.0'
end
```
من الدليل الذي يحتوي على Podfile، شغِّل:
```
pod install --repo-update`
```
تحقَّق من نجاح التثبيت من خلال فتح ملف BasicExample.xcworkspace والتأكّد من أنّه يحتوي على مشروعَين: BasicExample وPods (التبعيات التي تم تثبيتها من خلال CocoaPods).

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

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

في Xcode، ثبِّت حزمة GoogleInteractiveMediaAds Swift من خلال الانتقال إلى ملف > إضافة حِزم.
في الطلب الذي يظهر، ابحث عن مستودع GitHub الخاص بحزمة GoogleInteractiveMediaAds Swift Package:
```
https://github.com/googleads/swift-package-manager-google-interactive-media-ads-tvos
```
اختَر إصدار حزمة GoogleInteractiveMediaAds Swift التي تريد استخدامها. بالنسبة إلى المشاريع الجديدة، ننصحك باستخدام الإصدار التالي.

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

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

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

عرض التعليمات

من صفحة التنزيل، نزِّل أحدث إصدار من "حزمة تطوير البرامج لإدراج إعلان ديناميكي لإعلانات الوسائط التفاعلية" واستخرجه.
افتح BasicExample.xcodeproj.
في اللوحة اليمنى، انقر على اسم المشروع.
في اللوحة الوسطى، انقر على مراحل الإنشاء.
وسِّع القسم ربط النظام الثنائي مع المكتبات.
في أسفل قائمة المكتبات، انقر على رمز علامة الجمع [+].
انقر على إضافة غير ذلك.
في الدليل الذي استخرجت منه حزمة تطوير البرامج (SDK) التي تم تنزيلها، اختَر GoogleInteractiveMediaAds.framework وانقر على فتح.
في أسفل قائمة المكتبات، انقر على رمز الإضافة [+] مرة أخرى.
في عمود الحالة، تحقّق من ضبط GoogleInteractiveMediaAds.framework على Required.
يمكنك تضمين علامة رابط -ObjC في إعدادات الإصدار. للحصول على المزيد من المعلومات، يُرجى الاطّلاع على Apple QA1490.

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

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

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 وأضِف نماذج stubs لنقاط التفاعل الأساسية في 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.