راه‌اندازی کیت توسعه نرم‌افزار آگهی‌های رسانه‌ای تعاملی

انتخاب پلاتفرم: HTML5 Android iOS tvOS

کیت‌های توسعه نرم‌افزار IMA ادغام آگهی‌های چندرسانه‌ای در وب‌سایت‌ها و برنامه‌هایتان را آسان می‌کنند. کیت‌های توسعه نرم‌افزار IMA می‌توانند از هر سرور آگهی مطابق با VAST درخواست آگهی کنند و بازپخش آگهی را در برنامه‌هایتان مدیریت کنند. با کیت‌های توسعه نرم‌افزار سمت کارخواه IMA، کنترل بازپخش ویدیو محتوا را حفظ می‌کنید، درحالی‌که کیت توسعه نرم‌افزار بازپخش آگهی را مدیریت می‌کند. آگهی‌ها در یک پخش‌کننده ویدیو جداگانه که در بالای پخش‌کننده ویدیو محتوای برنامه قرار دارد پخش می‌شوند.

این راهنما نشان می‌دهد که چگونه IMA SDK را در یک برنامه پخش‌کننده ویدیو ادغام کنید. برای مشاهده یا دنبال کردن یک نمونه ادغام تکمیل‌شده، BasicExample را از GitHub بارگیری کنید.

نمای کلی سمت کارخواه IMA

پیاده‌سازی IMA سمت کارخواه شامل چهار مؤلفه اصلی کیت توسعه نرم‌افزار است. این راهنما این مؤلفه‌ها را نشان می‌دهد:

  • IMAAdDisplayContainer: یک شیء محتوی که مشخص می‌کند IMA عناصر واسط کاربر آگهی را کجا پرداز می‌کند و رؤیت‌پذیری را کجا اندازه‌گیری می‌کند، ازجمله Active View و Open Measurement.
  • IMAAdsLoader: شیئی که آگهی‌ها را درخواست می‌کند و رویدادهای پاسخ‌های درخواست آگهی را مدیریت می‌کند. فقط باید یک بار بارکننده آگهی‌ها را نمونه‌سازی کنید که می‌تواند درطول عمر برنامه دوباره استفاده شود.
  • IMAAdsRequest: شیئی که درخواست آگهی را تعریف می‌کند. درخواست‌های آگهی نشانی وب را برای برچسب آگهی VAST و همچنین پارامترهای اضافی، مانند ابعاد آگهی، مشخص می‌کنند.
  • IMAAdsManager: شیئی که حاوی پاسخ به درخواست آگهی است، پخش آگهی را کنترل می‌کند، و به رویدادهای آگهی که ازسوی کیت توسعه نرم‌افزار راه‌اندازی می‌شوند گوش می‌دهد.

پیش‌نیازها

قبل‌از شروع، به موارد زیر نیاز دارید:

۱. ایجاد پروژه جدید Xcode

در Xcode، پروژه tvOS جدیدی بااستفاده از Objective-C یا Swift ایجاد کنید. از BasicExample به‌عنوان نام پروژه استفاده کنید.

۲. افزودن کیت توسعه نرم‌افزار IMA به پروژه Xcode

برای نصب کیت توسعه نرم‌افزار آگهی‌های رسانه‌ای تعاملی، روش ترجیحی را انتخاب کنید.

توصیه‌شده: نصب IMA SDK بااستفاده از Swift Package Manager

کیت توسعه نرم‌افزار آگهی‌های رسانه‌ای تعاملی از نسخه ۴.۸.۲ از مدیر بسته Swift پشتیبانی می‌کند. برای وارد کردن بسته Swift، این مراحل را دنبال کنید.

  1. در Xcode، بسته IMA SDK Swift را با پیمایش به 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 را که می‌خواهید استفاده کنید انتخاب کنید. برای پروژه‌های جدید، توصیه می‌کنیم از Up to Next Major Version استفاده کنید.

پس‌از اتمام، Xcode وابستگی‌های بسته شما را حل می‌کند و آن‌ها را در پس‌زمینه بارگیری می‌کند. برای جزئیات بیشتر درباره نحوه افزودن وابستگی‌های بسته، مقاله Apple را ببینید.

بارگیری و نصب دستی «کیت توسعه نرم‌افزار آگهی‌های رسانه‌ای تعاملی»

اگر نمی‌خواهید از «مدیر بسته Swift» استفاده کنید، IMA SDK را بارگیری و به‌صورت دستی به پروژه‌تان اضافه کنید.

۳. وارد کردن کیت توسعه نرم‌افزار IMA

چارچوب IMA را بااستفاده از بیانیه وارد کردن اضافه کنید.

آبجکتیو-سی

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

@import GoogleInteractiveMediaAds;

Swift

import AVFoundation
import GoogleInteractiveMediaAds
import UIKit

۴. ایجاد پخش‌کننده ویدیو و ادغام کیت توسعه نرم‌افزار آگهی‌های رسانه‌ای تعاملی

مثال زیر کیت توسعه نرم‌افزار IMA را مقداردهی اولیه می‌کند:

آبجکتیو-سی

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» استفاده می‌کند:

  • ‫adsLoader: درخواست‌ها و پاسخ‌های آگهی را مدیریت می‌کند. توصیه می‌کنیم برای چرخه حیات برنامه از یک نمونه واحد استفاده کنید.
  • adDisplayContainer: نمای موردنظر برای پرداز آگهی‌ها را مشخص می‌کند.
  • adsManager: بازپخش آگهی را مدیریت می‌کند و به رویدادهای آگهی گوش می‌دهد.
  • contentPlayhead: پیشرفت محتوا را برای راه‌اندازی وقفه‌های آگهی میان‌ویدیویی ردیابی می‌کند.
  • adBreakActive: نشان می‌دهد که آیا وقفه آگهی درحال پخش است تا از جستجو در آگهی‌ها جلوگیری شود.

۵. پیاده‌سازی ردیاب سرصفحه محتوا و ناظر پایان جاری‌سازی

برای پخش آگهی‌های میان‌ویدیویی، «کیت توسعه نرم‌افزار IMA» باید موقعیت فعلی محتوای ویدیویی شما را ردیابی کند. برای انتقال موقعیت فعلی به IMA، کلاسی ایجاد کنید که IMAContentPlayhead را پیاده‌سازی کند. اگر از AVPlayer استفاده می‌کنید، همان‌طور که این مثال نشان می‌دهد، IMA SDK کلاس IMAAVPlayerContentPlayhead را برای ارسال اطلاعات موقعیت فعلی برای شما ارائه می‌دهد. اگر از AVPlayer استفاده نمی‌کنید، IMAContentPlayhead را در کلاس خودتان پیاده‌سازی کنید.

آبجکتیو-سی

- (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()
}

شنونده‌ای را راه‌اندازی کنید تا وقتی محتوایتان تمام می‌شود، بااستفاده از AVPlayerItemDidPlayToEndTimeNotification، در IMAAdsLoader با contentComplete تماس بگیرد. «تماس گرفتن» contentComplete به «کیت توسعه نرم‌افزار IMA» اطلاع می‌دهد که محتوای شما چه زمانی پخش می‌شود تا آگهی‌های پس‌از پخش را نمایش دهد.

آبجکتیو-سی

- (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()
}

‫۶. بارکننده آگهی را مقداردهی اولیه کنید و درخواست آگهی بدهید

برای درخواست مجموعه آگهی، نمونه IMAAdsLoader ایجاد کنید. این بارکننده IMAAdsRequest شیء مرتبط با نشانی وب برچسب آگهی مشخص‌شده را پردازش می‌کند.

به‌عنوان روال مطلوب، فقط یک نمونه از IMAAdsLoader را برای کل دوره حیات برنامه‌تان حفظ کنید. برای درخواست‌های آگهی بیشتر، شیء IMAAdsRequest جدیدی ایجاد کنید، اما از همان IMAAdsLoader مجدداً استفاده کنید. برای اطلاعات بیشتر، پرسشگان کیت توسعه نرم‌افزار آگهی‌های رسانه‌ای تعاملی را ببینید.

آبجکتیو-سی

- (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)
}

‫۷. راه‌اندازی نماینده بارکننده آگهی

در رویداد بار موفق، IMAAdsLoader متد adsLoadedWithData نماینده اختصاص‌یافته خود را فرا می‌خواند و نمونه‌ای از IMAAdsManager را به آن منتقل می‌کند. پس‌از داشتن نمونه IMAAdsManager، مدیر آگهی‌ها را مقداردهی اولیه کنید، که آگهی‌های تکی را براساس پاسخ نشانی وب برچسب آگهی بار می‌کند.

برای رویدادهای بار کردن ناموفق، یک نماینده IMAAdsLoader برای رسیدگی به خطاهایی که درطول فرایند بار کردن رخ می‌دهد تنظیم کنید. اگر آگهی‌ها بارگیری نمی‌شوند، مطمئن شوید که بازپخش رسانه بدون آگهی ادامه می‌یابد تا کاربران بتوانند محتوای رسانه را مشاهده کنند.

آبجکتیو-سی

#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()
}

‫۸. راه‌اندازی نماینده مدیر آگهی‌ها

در آخر، برای مدیریت رویدادها و تغییرات وضعیت، مدیر آگهی‌ها به نماینده‌ای از خودش نیاز دارد. IMAAdManagerDelegate روش‌هایی برای مدیریت رویدادهای آگهی و خطاها، و همچنین روش‌هایی برای راه‌اندازی پخش و توقف در محتوای ویدیویی شما دارد.

درحال شروع بازپخش

روش didReceiveAdEvent همه رویدادهای IMAAdEvent را مدیریت می‌کند. برای این مثال ساده، به رویداد LOADED گوش دهید تا به مدیر آگهی‌ها بگوید پخش محتوا و آگهی‌ها را شروع کند. وقتی کاربر پس‌از تک‌ضرب زدن روی نماد، کادر گفتگوی جایگزین نماد را می‌بندد، «کیت توسعه نرم‌افزار آگهی‌های رسانه‌ای تعاملی» رویداد ICON_FALLBACK_IMAGE_CLOSED را راه‌اندازی می‌کند. پس‌از این کنش، بازپخش آگهی ازسر گرفته می‌شود.

آبجکتیو-سی

#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
  }
}

مدیریت خطاها

یک کنترل‌کننده برای خطاهای آگهی نیز اضافه کنید. اگر خطایی رخ داد، مانند مرحله قبلی، بازپخش محتوا را ازسر بگیرید.

آبجکتیو-سی

- (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()
}

راه‌اندازی رویدادهای پخش و توقف موقت

دو روش نماینده آخر که پیاده‌سازی می‌کنید، رویدادهای پخش و توقف موقت را در محتوای ویدیویی زیرین زمانی که «کیت توسعه نرم‌افزار IMA» آن‌ها را درخواست می‌کند، راه‌اندازی می‌کنند. راه‌اندازی توقف و پخش زمانی که «کیت توسعه نرم‌افزار IMA» آن‌ها را درخواست می‌کند، از ازدست رفتن بخش‌هایی از محتوای ویدیو هنگام نمایش آگهی‌ها جلوگیری می‌کند.

آبجکتیو-سی

- (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()
}

فقط همین! اکنون با «کیت توسعه نرم‌افزار IMA» آگهی درخواست و نمایش می‌دهید. برای آشنایی با ویژگی‌های اضافی «کیت توسعه نرم‌افزار»، راهنماهای دیگر یا نمونه‌های GitHub را ببینید.

مراحل بعدی

برای به حداکثر رساندن درآمد آگهی در پلاتفرم tvOS، برای استفاده از «شناسه تبلیغ‌کنندگان»، اجازه «شفاف‌سازی ردیابی برنامه» را درخواست کنید.