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

اختيار النظام الأساسي: HTML5 Android iOS tvOS

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

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

نظرة عامة على IMA من جهة العميل

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

  • IMAAdDisplayContainer: عنصر حاوٍ يحدّد المكان الذي تعرض فيه IMA عناصر واجهة مستخدم الإعلان وتقيس إمكانية العرض، بما في ذلك العرض النشط وOpen Measurement.
  • IMAAdsLoader: عنصر يطلب الإعلانات ويتعامل مع الأحداث من ردود طلبات الإعلانات. يجب إنشاء أداة تحميل إعلانات واحدة فقط، ويمكن إعادة استخدامها طوال مدة تشغيل التطبيق.
  • IMAAdsRequest: كائن يعرّف طلب إعلانات. تحدّد طلبات الإعلانات عنوان URL لعلامة إعلان VAST، بالإضافة إلى مَعلمات إضافية، مثل أبعاد الإعلان.
  • IMAAdsManager: كائن يحتوي على الردّ على طلب الإعلانات، ويتحكّم في تشغيل الإعلانات، ويستمع إلى أحداث الإعلانات التي يتم تشغيلها بواسطة حزمة SDK.

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

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

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

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

2. إضافة "حزمة تطوير البرامج للإعلانات التفاعلية" إلى مشروع Xcode

تثبيت "حزمة تطوير البرامج لإعلانات الوسائط التفاعلية" باستخدام Swift Package Manager

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

  1. في Xcode، ثبِّت حزمة IMA SDK Swift Package من خلال الانتقال إلى ملف > إضافة حِزم... (File > Add Packages...).

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

    https://github.com/googleads/swift-package-manager-google-interactive-media-ads-tvos
    
  3. اختَر إصدار حزمة IMA SDK Swift Package الذي تريد استخدامه. بالنسبة إلى المشاريع الجديدة، ننصحك باستخدام حتى الإصدار الرئيسي التالي.

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

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

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

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

    source 'https://github.com/CocoaPods/Specs.git'
    
    platform :tvos, '15'
    
    target "BasicExample" do
      pod 'GoogleAds-IMA-tvOS-SDK', '~> 4.16.0'
    end
    
    
  2. من الدليل الذي يحتوي على Podfile، نفِّذ الأمر pod install --repo-update

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

تنزيل حزمة تطوير البرامج لإعلانات الوسائط التفاعلية وتثبيتها يدويًا

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

3- استيراد "حزمة تطوير البرامج للإعلانات التفاعلية"

أضِف إطار عمل IMA باستخدام عبارة استيراد.

Objective-C

#import "ViewController.h"
#import <AVKit/AVKit.h>

@import GoogleInteractiveMediaAds;

Swift

import AVFoundation
import GoogleInteractiveMediaAds
import UIKit

4. إنشاء مشغّل فيديو ودمج حزمة تطوير البرامج لإعلانات الوسائط التفاعلية

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

Objective-C

NSString *const kContentURLString =
    @"https://storage.googleapis.com/interactive-media-ads/media/stock.mp4";
NSString *const kAdTagURLString =
    @"https://pubads.g.doubleclick.net/gampad/ads?"
    @"iu=/21775744923/external/vmap_ad_samples&sz=640x480&"
    @"cust_params=sample_ar%3Dpremidpostlongpod&ciu_szs=300x250&gdfp_req=1&ad_rule=1&"
    @"output=vmap&unviewed_position_start=1&env=vp&cmsid=496&vid=short_onecue&correlator=";

@interface ViewController () <IMAAdsLoaderDelegate, IMAAdsManagerDelegate>
@property(nonatomic) IMAAdsLoader *adsLoader;
@property(nonatomic) IMAAdDisplayContainer *adDisplayContainer;
@property(nonatomic) IMAAdsManager *adsManager;
@property(nonatomic) IMAAVPlayerContentPlayhead *contentPlayhead;
@property(nonatomic) AVPlayerViewController *contentPlayerViewController;
@property(nonatomic, getter=isAdBreakActive) BOOL adBreakActive;
@end

@implementation ViewController

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

- (void)viewDidAppear:(BOOL)animated {
  [super viewDidAppear:animated];
  [self requestAds];
}

// Add the content video player as a child view controller.
- (void)showContentPlayer {
  [self addChildViewController:self.contentPlayerViewController];
  self.contentPlayerViewController.view.frame = self.view.bounds;
  [self.view insertSubview:self.contentPlayerViewController.view atIndex:0];
  [self.contentPlayerViewController didMoveToParentViewController:self];
}

// Remove and detach the content video player.
- (void)hideContentPlayer {
  // The whole controller needs to be detached so that it doesn't capture resume events from the
  // remote and play content underneath the ad.
  [self.contentPlayerViewController willMoveToParentViewController:nil];
  [self.contentPlayerViewController.view removeFromSuperview];
  [self.contentPlayerViewController removeFromParentViewController];
}

Swift

class ViewController: UIViewController, IMAAdsLoaderDelegate, IMAAdsManagerDelegate {
  static let contentURLString =
    "https://devstreaming-cdn.apple.com/videos/streaming/examples/"
    + "img_bipbop_adv_example_fmp4/master.m3u8"
  static let adTagURLString =
    "https://pubads.g.doubleclick.net/gampad/ads?iu=/21775744923/external/single_ad_samples&"
    + "sz=640x480&cust_params=sample_ct%3Dlinear&ciu_szs=300x250%2C728x90&gdfp_req=1&output=vast&"
    + "unviewed_position_start=1&env=vp&correlator="

  var adsLoader: IMAAdsLoader!
  var adDisplayContainer: IMAAdDisplayContainer!
  var adsManager: IMAAdsManager!
  var contentPlayhead: IMAAVPlayerContentPlayhead?
  var playerViewController: AVPlayerViewController!
  var adBreakActive = false

  deinit {
    NotificationCenter.default.removeObserver(self)
  }

  override func viewDidLoad() {
    super.viewDidLoad()
    self.view.backgroundColor = UIColor.black
    setUpContentPlayer()
    setUpAdsLoader()
  }

  override func viewDidAppear(_ animated: Bool) {
    super.viewDidAppear(animated)
    requestAds()
  }

في هذا المثال، تعمل السمة viewDidLoad() على تهيئة السمة IMAAdsLoader، وتطلب السمة viewDidAppear() عرض الإعلانات بعد أن يصبح العرض مرئيًا. تتيح الطريقتان المساعدتان showContentPlayer() وhideContentPlayer() تبديل مستوى ظهور المحتوى أثناء تشغيل الإعلان.

يستخدم هذا المثال المتغيّر الثابت adTagURLString لتحديد علامة إعلان VAST لطلب الإعلان، والمكوّنات التالية لإدارة حزمة IMA SDK:

  • adsLoader: يتعامل مع طلبات الإعلانات وردودها. ننصح باستخدام مثيل واحد لدورة حياة التطبيق.
  • adDisplayContainer: تحدّد هذه السمة طريقة عرض الإعلانات.
  • adsManager: تدير عملية تشغيل الإعلانات وتستمع إلى أحداث الإعلانات.
  • contentPlayhead: يتتبّع تقدّم المحتوى لعرض فواصل إعلانية أثناء التشغيل.
  • adBreakActive: تشير إلى ما إذا كان يتم تشغيل فاصل إعلاني لمنع التقديم السريع للإعلانات.

5- تنفيذ أداة تتبُّع رأس التشغيل للمحتوى ومراقب نهاية البث

لعرض الإعلانات أثناء عرض الفيديو، يجب أن تتتبّع "حزمة تطوير البرامج للإعلانات التفاعلية" الموضع الحالي لمحتوى الفيديو. لإجراء ذلك، أنشئ فئة تنفّذ IMAContentPlayhead. إذا كنت تستخدم AVPlayer، كما هو موضّح في هذا المثال، توفّر حزمة تطوير البرامج (SDK) الفئة IMAAVPlayerContentPlayhead التي تنفّذ ذلك نيابةً عنك. إذا كنت لا تستخدم AVPlayer، عليك تنفيذ IMAContentPlayhead في فئة خاصة بك.

Objective-C

- (void)setupContentPlayer {
  // Create a content video player. Create a playhead to track content progress so the SDK knows
  // when to play ads in a VMAP playlist.
  NSURL *contentURL = [NSURL URLWithString:kContentURLString];
  AVPlayer *player = [AVPlayer playerWithURL:contentURL];
  self.contentPlayerViewController = [[AVPlayerViewController alloc] init];
  self.contentPlayerViewController.player = player;
  self.contentPlayerViewController.view.frame = self.view.bounds;
  self.contentPlayhead =
      [[IMAAVPlayerContentPlayhead alloc] initWithAVPlayer:self.contentPlayerViewController.player];

  // Track end of content.
  AVPlayerItem *contentPlayerItem = self.contentPlayerViewController.player.currentItem;
  [[NSNotificationCenter defaultCenter] addObserver:self
                                           selector:@selector(contentDidFinishPlaying:)
                                               name:AVPlayerItemDidPlayToEndTimeNotification
                                             object:contentPlayerItem];

  // Attach content video player to view hierarchy.
  [self showContentPlayer];
}

Swift

func setUpContentPlayer() {
  // Load AVPlayer with path to our content.
  let contentURL = URL(string: ViewController.contentURLString)!
  let player = AVPlayer(url: contentURL)
  playerViewController = AVPlayerViewController()
  playerViewController.player = player

  // Set up our content playhead and contentComplete callback.
  contentPlayhead = IMAAVPlayerContentPlayhead(avPlayer: player)
  NotificationCenter.default.addObserver(
    self,
    selector: #selector(ViewController.contentDidFinishPlaying(_:)),
    name: NSNotification.Name.AVPlayerItemDidPlayToEndTime,
    object: player.currentItem)

  showContentPlayer()
}

عليك أيضًا إعلام حزمة SDK عند انتهاء تشغيل المحتوى كي تتمكّن من عرض إعلانات ما بعد التشغيل. يتم ذلك من خلال استدعاء contentComplete على IMAAdsLoader باستخدام AVPlayerItemDidPlayToEndTimeNotification.

Objective-C

- (void)contentDidFinishPlaying:(NSNotification *)notification {
  // Notify the SDK that the postrolls should be played.
  [self.adsLoader contentComplete];
}

- (void)dealloc {
  [[NSNotificationCenter defaultCenter] removeObserver:self];
}

Swift

@objc func contentDidFinishPlaying(_ notification: Notification) {
  adsLoader.contentComplete()
}

6. تهيئة أداة تحميل الإعلانات وإرسال طلب إعلانات

لطلب مجموعة من الإعلانات، عليك إنشاء مثيل IMAAdsLoader. يمكن استخدام أداة التحميل هذه لمعالجة عناصر IMAAdsRequest المرتبطة بعنوان URL محدّد لعلامة إعلان.

كأفضل ممارسة، احتفِظ بنسخة واحدة فقط من IMAAdsLoader طوال دورة حياة تطبيقك. لتقديم طلبات إعلانية إضافية، أنشِئ عنصر IMAAdsRequest جديدًا، ولكن أعِد استخدام IMAAdsLoader نفسه. لمزيد من المعلومات، يُرجى الاطّلاع على الأسئلة الشائعة حول حزمة تطوير البرامج (SDK) من IMA.

Objective-C

- (void)setupAdsLoader {
  self.adsLoader = [[IMAAdsLoader alloc] init];
  self.adsLoader.delegate = self;
}

- (void)requestAds {
  // Pass the main view as the container for ad display.
  self.adDisplayContainer = [[IMAAdDisplayContainer alloc] initWithAdContainer:self.view
                                                                viewController:self];
  IMAAdsRequest *request = [[IMAAdsRequest alloc] initWithAdTagUrl:kAdTagURLString
                                                adDisplayContainer:self.adDisplayContainer
                                                   contentPlayhead:self.contentPlayhead
                                                       userContext:nil];
  [self.adsLoader requestAdsWithRequest:request];
}

Swift

func setUpAdsLoader() {
  adsLoader = IMAAdsLoader(settings: nil)
  adsLoader.delegate = self
}

func requestAds() {
  // Create ad display container for ad rendering.
  adDisplayContainer = IMAAdDisplayContainer(adContainer: self.view, viewController: self)
  // Create an ad request with our ad tag, display container, and optional user context.
  let request = IMAAdsRequest(
    adTagUrl: ViewController.adTagURLString,
    adDisplayContainer: adDisplayContainer,
    contentPlayhead: contentPlayhead,
    userContext: nil)

  adsLoader.requestAds(with: request)
}

7. إعداد مفوّض أداة تحميل الإعلانات

عند وقوع حدث تحميل ناجح، تستدعي IMAAdsLoader الطريقة adsLoadedWithData الخاصة بالمفوّض المعيّن، وتمرّر إليها مثيلاً من IMAAdsManager. يمكنك بعد ذلك بدء تشغيل "مدير الإعلانات" الذي يحمّل الإعلانات الفردية على النحو المحدّد في الردّ على عنوان URL لعلامة الإعلان.

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

Objective-C

#pragma mark - IMAAdsLoaderDelegate

- (void)adsLoader:(IMAAdsLoader *)loader adsLoadedWithData:(IMAAdsLoadedData *)adsLoadedData {
  // Initialize and listen to the ads manager loaded for this request.
  self.adsManager = adsLoadedData.adsManager;
  self.adsManager.delegate = self;
  [self.adsManager initializeWithAdsRenderingSettings:nil];
}

- (void)adsLoader:(IMAAdsLoader *)loader failedWithErrorData:(IMAAdLoadingErrorData *)adErrorData {
  // Fall back to playing content.
  NSLog(@"Error loading ads: %@", adErrorData.adError.message);
  [self.contentPlayerViewController.player play];
}

Swift

func adsLoader(_ loader: IMAAdsLoader, adsLoadedWith adsLoadedData: IMAAdsLoadedData) {
  // Grab the instance of the IMAAdsManager and set ourselves as the delegate.
  adsManager = adsLoadedData.adsManager
  adsManager.delegate = self
  adsManager.initialize(with: nil)
}

func adsLoader(_ loader: IMAAdsLoader, failedWith adErrorData: IMAAdLoadingErrorData) {
  print("Error loading ads: \(adErrorData.adError.message ?? "No error message available.")")
  showContentPlayer()
  playerViewController.player?.play()
}

8. إعداد مفوّض في "مدير إعلانات Google"

أخيرًا، لإدارة الأحداث وتغييرات الحالة، يحتاج مدير الإعلانات إلى عنصر نائب خاص به. يحتوي IMAAdManagerDelegate على طرق للتعامل مع أحداث الإعلانات والأخطاء، بالإضافة إلى طرق لتشغيل محتوى الفيديو وإيقافه مؤقتًا.

بدء التشغيل

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

Objective-C

#pragma mark - IMAAdsManagerDelegate

- (void)adsManager:(IMAAdsManager *)adsManager didReceiveAdEvent:(IMAAdEvent *)event {
  switch (event.type) {
    case kIMAAdEvent_LOADED: {
      // Play each ad once it has loaded.
      [adsManager start];
      break;
    }
    case kIMAAdEvent_ICON_FALLBACK_IMAGE_CLOSED: {
      // Resume ad after user has closed dialog.
      [adsManager resume];
      break;
    }
    default:
      break;
  }
}

Swift

func adsManager(_ adsManager: IMAAdsManager, didReceive event: IMAAdEvent) {
  switch event.type {
  case IMAAdEventType.LOADED:
    // Play each ad once it has been loaded.
    adsManager.start()
  case IMAAdEventType.ICON_FALLBACK_IMAGE_CLOSED:
    // Resume playback after the user has closed the dialog.
    adsManager.resume()
  default:
    break
  }
}

معالجة الأخطاء

أضِف معالجًا لأخطاء الإعلانات أيضًا. في حال حدوث خطأ، كما في الخطوة السابقة، استأنِف تشغيل المحتوى.

Objective-C

- (void)adsManager:(IMAAdsManager *)adsManager didReceiveAdError:(IMAAdError *)error {
  // Fall back to playing content.
  NSLog(@"AdsManager error: %@", error.message);
  [self showContentPlayer];
  [self.contentPlayerViewController.player play];
}

Swift

func adsManager(_ adsManager: IMAAdsManager, didReceive error: IMAAdError) {
  // Fall back to playing content
  print("AdsManager error: \(error.message ?? "No error message available.")")
  showContentPlayer()
  playerViewController.player?.play()
}

تفعيل أحداث التشغيل والإيقاف المؤقت

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

Objective-C

- (void)adsManagerDidRequestContentPause:(IMAAdsManager *)adsManager {
  // Pause the content for the SDK to play ads.
  [self.contentPlayerViewController.player pause];
  [self hideContentPlayer];
  // Trigger an update to send focus to the ad display container.
  self.adBreakActive = YES;
  [self setNeedsFocusUpdate];
}

- (void)adsManagerDidRequestContentResume:(IMAAdsManager *)adsManager {
  // Resume the content since the SDK is done playing ads (at least for now).
  [self showContentPlayer];
  [self.contentPlayerViewController.player play];
  // Trigger an update to send focus to the content player.
  self.adBreakActive = NO;
  [self setNeedsFocusUpdate];
}

Swift

func adsManagerDidRequestContentPause(_ adsManager: IMAAdsManager) {
  // Pause the content for the SDK to play ads.
  playerViewController.player?.pause()
  hideContentPlayer()
  // Trigger an update to send focus to the ad display container.
  adBreakActive = true
  setNeedsFocusUpdate()
}

func adsManagerDidRequestContentResume(_ adsManager: IMAAdsManager) {
  // Resume the content since the SDK is done playing ads (at least for now).
  showContentPlayer()
  playerViewController.player?.play()
  // Trigger an update to send focus to the content player.
  adBreakActive = false
  setNeedsFocusUpdate()
}

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

الخطوات التالية

لزيادة إيرادات الإعلانات إلى أقصى حدّ على منصة tvOS، عليك طلب إذن "شفافية تتبُّع التطبيقات" لاستخدام معرّف المعلِنين (IDFA).