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

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

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

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

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

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

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

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

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

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

إنشاء مشروع 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 المدير بدءًا من الإصدار 3.18.4. اتّبِع التالية لاستيراد حزمة Swift.

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

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

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

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

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

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

إذا كنت لا تريد استخدام مدير حزم Swift أو 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.