راه‌اندازی IMA SDK

پلتفرم مورد نظر را انتخاب کنید: HTML5 اندروید iOS tvOS

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

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

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

پیاده‌سازی IMA سمت کلاینت شامل چهار جزء اصلی SDK است که در این راهنما نشان داده شده‌اند:

  • IMAAdDisplayContainer : یک شیء کانتینر که مشخص می‌کند IMA عناصر رابط کاربری تبلیغاتی را کجا رندر می‌کند و قابلیت مشاهده، از جمله نمای فعال و اندازه‌گیری باز را اندازه‌گیری می‌کند.
  • IMAAdsLoader : شیء‌ای که تبلیغات را درخواست می‌کند و رویدادهای پاسخ به درخواست تبلیغات را مدیریت می‌کند. شما فقط باید یک بارگذار تبلیغات را نمونه‌سازی کنید که می‌تواند در طول عمر برنامه بارها مورد استفاده قرار گیرد.
  • IMAAdsRequest : شیء‌ای که یک درخواست تبلیغات را تعریف می‌کند. درخواست‌های تبلیغات، URL مربوط به تگ تبلیغ VAST و همچنین پارامترهای اضافی مانند ابعاد تبلیغ را مشخص می‌کنند.
  • IMAAdsManager : شیء‌ای که شامل پاسخ به درخواست تبلیغات است، پخش تبلیغات را کنترل می‌کند و به رویدادهای تبلیغاتی که توسط SDK ایجاد می‌شوند، گوش می‌دهد.

پیش‌نیازها

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

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

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

۲. اضافه کردن IMA SDK به پروژه Xcode

نصب IMA SDK با استفاده از Swift Package Manager

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

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

  2. در اعلانی که ظاهر می‌شود، مخزن گیت‌هاب IMA SDK Swift Package را جستجو کنید:

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

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

نصب IMA SDK با استفاده از CocoaPods

برای نصب IMA SDK، از 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).

دانلود و نصب دستی IMA SDK

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

۳. ایمپورت کردن IMA SDK

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

هدف-سی

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

@import GoogleInteractiveMediaAds;

سویفت

import AVFoundation
import GoogleInteractiveMediaAds
import UIKit

۴. یک پخش‌کننده ویدیو ایجاد کنید و IMA SDK را ادغام کنید

مثال زیر IMA SDK را مقداردهی اولیه می‌کند:

هدف-سی

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];
}

سویفت

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 باید موقعیت فعلی محتوای ویدیوی شما را ردیابی کند. برای انجام این کار، کلاسی ایجاد کنید که IMAContentPlayhead را پیاده‌سازی کند. اگر از AVPlayer استفاده می‌کنید، همانطور که در این مثال نشان داده شده است، 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];
}

سویفت

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 انجام می‌شود.

هدف-سی

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

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

سویفت

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

۶. بارگذاری تبلیغات را راه‌اندازی اولیه کنید و درخواست تبلیغات ارسال کنید

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

به عنوان یک روش بهتر، فقط یک نمونه از IMAAdsLoader را برای کل چرخه حیات برنامه خود نگه دارید. برای ایجاد درخواست‌های تبلیغاتی بیشتر، یک شیء IMAAdsRequest جدید ایجاد کنید، اما از همان IMAAdsLoader دوباره استفاده کنید. برای اطلاعات بیشتر، به سوالات متداول IMA SDK مراجعه کنید.

هدف-سی

- (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];
}

سویفت

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 را به آن ارسال می‌کند. سپس می‌توانید مدیر تبلیغات را مقداردهی اولیه کنید که تبلیغات منفرد را بارگذاری می‌کند، همانطور که توسط پاسخ به URL تگ تبلیغ تعریف شده است.

علاوه بر این، حتماً هرگونه خطایی را که ممکن است در طول فرآیند بارگیری رخ دهد، مدیریت کنید. اگر تبلیغات بارگیری نشدند، مطمئن شوید که پخش رسانه بدون تبلیغات ادامه می‌یابد تا در تجربه کاربر اختلال ایجاد نشود.

هدف-سی

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

سویفت

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

۸. یک نماینده برای مدیریت تبلیغات تعیین کنید

در نهایت، برای مدیریت رویدادها و تغییرات وضعیت، مدیر تبلیغات به یک نماینده (delegate) مخصوص به خود نیاز دارد. IMAAdManagerDelegate متدهایی برای مدیریت رویدادها و خطاهای تبلیغات و همچنین متدهایی برای شروع پخش و مکث محتوای ویدیوی شما دارد.

شروع پخش

رویدادهای زیادی وجود دارند که می‌توان از متد didReceiveAdEvent برای مدیریت آنها استفاده کرد. برای این مثال ساده، به رویداد LOADED گوش دهید تا به مدیر تبلیغات بگویید پخش محتوا و تبلیغات را شروع کند. IMA SDK رویداد 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;
  }
}

سویفت

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];
}

سویفت

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 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];
}

سویفت

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 SDK درخواست و نمایش تبلیغات می‌دهید. برای کسب اطلاعات بیشتر در مورد ویژگی‌های اضافی SDK، به راهنماهای دیگر یا نمونه‌های موجود در GitHub مراجعه کنید.

مراحل بعدی

برای به حداکثر رساندن درآمد حاصل از تبلیغات در پلتفرم tvOS، برای استفاده از IDFA از بخش شفافیت و ردیابی برنامه (App Transparency and Tracking) درخواست مجوز کنید .