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

پلاتفرم را انتخاب کنید: 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 به‌عنوان نام پروژه استفاده کنید.

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

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

توصیه‌شده: نصب کیت توسعه نرم‌افزار آگهی‌های رسانه‌ای تعاملی بااستفاده از Swift Package Manager

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

  1. در Xcode، با رفتن به File > Add Packages...‎، بسته IMA SDK Swift را نصب کنید.

  2. در پیام‌واره‌ای که ظاهر می‌شود، IMA SDK Swift Package GitHub repository را جستجو کنید:

    https://github.com/googleads/swift-package-manager-google-interactive-media-ads-tvos
    
  3. نسخه «بسته IMA SDK Swift» را که می‌خواهید استفاده کنید انتخاب کنید. برای پروژه‌های جدید، توصیه می‌کنیم از Up to Next Major Version استفاده کنید.

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

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

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

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

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

آبجکتیو-سی

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

@import GoogleInteractiveMediaAds;

Swift

import AVFoundation
import GoogleInteractiveMediaAds
import UIKit

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

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

آبجکتیو-سی

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: نشان می‌دهد که آیا وقفه آگهی درحال پخش است تا از جستجو روی آگهی‌ها جلوگیری شود.

۵. ردیاب هد پخش محتوا و ناظر پایان جاری‌سازی را پیاده‌سازی کنید

برای پخش آگهی‌های میان‌ویدیویی، IMA SDK باید موقعیت فعلی محتوای ویدیویی شما را ردیابی کند. برای ارسال موقعیت فعلی به IMA، کلاسی ایجاد کنید که IMAContentPlayhead را پیاده‌سازی کند. اگر از AVPlayer استفاده می‌کنید، همان‌طور که این مثال نشان می‌دهد، «کیت توسعه نرم‌افزار آگهی‌های رسانه‌ای تعاملی» کلاس 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()
}

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

آبجکتیو-سی

- (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 SDK از کاربر جلوگیری می‌کند بخش‌های ازدست‌رفته محتوای ویدیویی هنگام نمایش آگهی‌ها.

آبجکتیو-سی

- (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، اجازه «شفاف‌سازی و ردیابی برنامه» را برای استفاده از IDFA درخواست کنید.