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

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

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

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

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

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

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

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

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

قبل البدء، يجب توفّر ما يلي:

ستحتاج أيضًا إلى المَعلمات المستخدَمة لطلب البث من حزمة تطوير البرامج لإعلانات الوسائط التفاعلية. للحصول على أمثلة على مَعلمات الطلب، يُرجى الاطّلاع على عيّنات أحداث البث.

مَعلمات البث المباشر
مفتاح مادة العرض مفتاح مادة العرض الذي يحدّد بثك المباشر في "مدير إعلانات Google"
مثال: c-rArva4ShKVIAkNfy6HUQ
مَعلمات بث الفيديوهات عند الطلب
معرّف مصدر المحتوى رقم تعريف مصدر المحتوى من "مدير إعلانات Google".
مثال: 2548831
معرّف الفيديو رقم تعريف الفيديو من "مدير إعلانات Google"
مثال: tears-of-steel

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

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

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

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

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

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

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

    Podfile 
    source 'https://github.com/CocoaPods/Specs.git'

platform :ios, '14'

target 'BasicExample' do
  pod 'GoogleAds-IMA-iOS-SDK', '~> 3.23.0'
end

    Podfile

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

    pod install --repo-update`

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

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

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

  1. في Xcode، ثبِّت حزمة Swift الخاصة بحزمة تطوير البرامج (SDK) لميزة "الإعلانات الديناميكية أثناء عرض الفيديو" من IMA من خلال الانتقال إلى ملف > إضافة حِزم.

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

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

  3. اختَر إصدار حزمة Swift لـ IMA DAI SDK التي تريد استخدامها. بالنسبة إلى المشاريع الجديدة، ننصحك باستخدام الإصدار التالي.

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

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

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

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

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

ViewController.m 
#import "ViewController.h"

#import <AVKit/AVKit.h>

/// Content URL.
static NSString *const kBackupContentUrl =
    @"http://devimages.apple.com/iphone/samples/bipbop/bipbopall.m3u8";

@interface ViewController ()
/// Play button.
@property(nonatomic, weak) IBOutlet UIButton *playButton;

@property(nonatomic, weak) IBOutlet UIView *videoView;
/// Video player.
@property(nonatomic, strong) AVPlayer *videoPlayer;
@end

@implementation ViewController

- (void)viewDidLoad {
  [super viewDidLoad];
  self.view.backgroundColor = [UIColor blackColor];

  // Load AVPlayer with the path to your content.
  NSURL *contentURL = [NSURL URLWithString:kBackupContentUrl];
  self.videoPlayer = [AVPlayer playerWithURL:contentURL];

  // Create a player layer for the player.
  AVPlayerLayer *playerLayer = [AVPlayerLayer playerLayerWithPlayer:self.videoPlayer];

  // Size, position, and display the AVPlayer.
  playerLayer.frame = self.videoView.layer.bounds;
  [self.videoView.layer addSublayer:playerLayer];
}

- (IBAction)onPlayButtonTouch:(id)sender {
  [self.videoPlayer play];
  self.playButton.hidden = YES;
}

@end

ViewController.m

بدء تحميل الإعلانات

استورِد حزمة تطوير البرامج (SDK) لـ IMA في أداة التحكّم في العرض واستخدِم بروتوكولَي IMAAdsLoaderDelegate و IMAStreamManagerDelegate لمعالجة أحداث أداة تحميل الإعلانات ومدير البث.

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

  • ‫IMAAdsLoader: تدير طلبات البث طوال مدة تطبيقك.
  • ‫IMAAdDisplayContainer: تُستخدَم لإدارة إدراج عناصر واجهة مستخدِم الإعلان وإدارتها.
  • ‫IMAAVPlayerVideoDisplay: تُستخدم للتواصل بين حزمة تطوير البرامج لإعلانات الوسائط التفاعلية ومشغل الوسائط، كما تعالج metadata المبرمَجة.
  • ‫IMAStreamManager: تدير تشغيل البث وتنشئ الأحداث ذات الصلة بالإعلانات.

ابدأ أداة تحميل الإعلانات وحاوية عرض الإعلانات وعرض الفيديو بعد تحميل المشهد.

ViewController.m 
@import GoogleInteractiveMediaAds;

// ...

@interface ViewController () <IMAAdsLoaderDelegate, IMAStreamManagerDelegate>
/// The entry point for the IMA DAI SDK to make DAI stream requests.
@property(nonatomic, strong) IMAAdsLoader *adsLoader;
/// The container where the SDK renders each ad's user interface elements and companion slots.
@property(nonatomic, strong) IMAAdDisplayContainer *adDisplayContainer;
/// The reference of your video player for the IMA DAI SDK to monitor playback and handle timed
/// metadata.
@property(nonatomic, strong) IMAAVPlayerVideoDisplay *imaVideoDisplay;
/// References the stream manager from the IMA DAI SDK after successful stream loading.
@property(nonatomic, strong) IMAStreamManager *streamManager;

// ...

@end

@implementation ViewController

- (void)viewDidLoad {
  [super viewDidLoad];

  // ...

  self.adsLoader = [[IMAAdsLoader alloc] initWithSettings:nil];
  self.adsLoader.delegate = self;

  // Create an ad display container for rendering each ad's user interface elements and companion
  // slots.
  self.adDisplayContainer =
      [[IMAAdDisplayContainer alloc] initWithAdContainer:self.videoView
                                          viewController:self
                                          companionSlots:nil];

  // Create an IMAAVPlayerVideoDisplay to give the SDK access to your video player.
  self.imaVideoDisplay = [[IMAAVPlayerVideoDisplay alloc] initWithAVPlayer:self.videoPlayer];
}
ViewController.m

تقديم طلب بث

عندما يضغط المستخدم على زر التشغيل، يمكنك تقديم طلب بث جديد. استخدِم فئة IMALiveStreamRequest البث المباشر. بالنسبة إلى أحداث البث المباشر عند الطلب، استخدِم فئة IMAVODStreamRequest.

يتطلّب طلب البث مَعلمات البث، بالإضافة إلى إشارة إلى حاوية عرض الإعلان وعرض الفيديو.

ViewController.m 
- (IBAction)onPlayButtonTouch:(id)sender {
  [self requestStream];
  self.playButton.hidden = YES;
}

- (void)requestStream {
  // Create a stream request. Use one of "Live stream request" or "VOD request", depending on your
  // type of stream.
  IMAStreamRequest *request;
  // Switch this variable to NO to make a VOD request.
  BOOL useLiveStream = YES;
  if (useLiveStream) {
    // Live stream request. Replace the asset key with your value.
    request = [[IMALiveStreamRequest alloc] initWithAssetKey:@"c-rArva4ShKVIAkNfy6HUQ"
                                          adDisplayContainer:self.adDisplayContainer
                                                videoDisplay:self.imaVideoDisplay
                                                 userContext:nil];
  } else {
    // VOD request. Replace the content source ID and video ID with your values.
    request = [[IMAVODStreamRequest alloc] initWithContentSourceID:@"2548831"
                                                           videoID:@"tears-of-steel"
                                                adDisplayContainer:self.adDisplayContainer
                                                      videoDisplay:self.imaVideoDisplay
                                                       userContext:nil];
  }
  [self.adsLoader requestStreamWithRequest:request];
}
ViewController.m

الاستماع إلى أحداث تحميل البث

تستدعي فئة IMAAdsLoader الاستدعاءات IMAAdsLoaderDelegate في حال نجاح عملية الإعداد أو تعذُّر طلب البث.

في طريقة التفويض adsLoadedWithData ، اضبط IMAStreamManagerDelegate وأعِد تشغيل مدير البث. عند بدء التشغيل، يبدأ مدير البث تشغيل المحتوى.

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

ViewController.m 
- (void)adsLoader:(IMAAdsLoader *)loader adsLoadedWithData:(IMAAdsLoadedData *)adsLoadedData {
  NSLog(@"Stream created with: %@.", adsLoadedData.streamManager.streamId);
  self.streamManager = adsLoadedData.streamManager;
  self.streamManager.delegate = self;
  [self.streamManager initializeWithAdsRenderingSettings:nil];
}

- (void)adsLoader:(IMAAdsLoader *)loader failedWithErrorData:(IMAAdLoadingErrorData *)adErrorData {
  // Log the error and play the content.
  NSLog(@"AdsLoader error, code:%ld, message: %@", adErrorData.adError.code,
        adErrorData.adError.message);
  [self.videoPlayer play];
}
ViewController.m

الاستماع إلى أحداث الإعلانات

يُطلِق IMAStreamManager طُرق IMAStreamManagerDelegate لتمرير أحداث البث والأخطاء إلى تطبيقك.

في هذا المثال، سجِّل أحداث الإعلانات الأساسية في وحدة التحكّم:

ViewController.m 
- (void)streamManager:(IMAStreamManager *)streamManager didReceiveAdEvent:(IMAAdEvent *)event {
  NSLog(@"Ad event (%@).", event.typeString);
  switch (event.type) {
    case kIMAAdEvent_STARTED: {
      // Log extended data.
      NSString *extendedAdPodInfo = [[NSString alloc]
          initWithFormat:@"Showing ad %ld/%ld, bumper: %@, title: %@, description: %@, contentType:"
                         @"%@, pod index: %ld, time offset: %lf, max duration: %lf.",
                         (long)event.ad.adPodInfo.adPosition, (long)event.ad.adPodInfo.totalAds,
                         event.ad.adPodInfo.isBumper ? @"YES" : @"NO", event.ad.adTitle,
                         event.ad.adDescription, event.ad.contentType,
                         (long)event.ad.adPodInfo.podIndex, event.ad.adPodInfo.timeOffset,
                         event.ad.adPodInfo.maxDuration];

      NSLog(@"%@", extendedAdPodInfo);
      break;
    }
    case kIMAAdEvent_AD_BREAK_STARTED: {
      NSLog(@"Ad break started");
      break;
    }
    case kIMAAdEvent_AD_BREAK_ENDED: {
      NSLog(@"Ad break ended");
      break;
    }
    case kIMAAdEvent_AD_PERIOD_STARTED: {
      NSLog(@"Ad period started");
      break;
    }
    case kIMAAdEvent_AD_PERIOD_ENDED: {
      NSLog(@"Ad period ended");
      break;
    }
    default:
      break;
  }
}

- (void)streamManager:(IMAStreamManager *)streamManager didReceiveAdError:(IMAAdError *)error {
  NSLog(@"StreamManager error with type: %ld\ncode: %ld\nmessage: %@", error.type, error.code,
        error.message);
  [self.videoPlayer play];
}
ViewController.m

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