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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

استخدِم إحدى الطريقتَين التاليتَين لتثبيت حزمة تطوير البرامج (SDK) لميزة "عرض الإعلانات أثناء التشغيل" في إعلانات الوسائط التفاعلية.

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

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

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

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

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

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

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

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

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

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

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

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

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.