راه‌اندازی 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، یک روش ترجیحی را انتخاب کنید.

توصیه می‌شود: 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

    Podfile

  2. از دایرکتوری که شامل Podfile است، pod install --repo-update را اجرا کنید.

  3. با باز کردن فایل BasicExample.xcworkspace و تأیید اینکه شامل دو پروژه است، تأیید کنید که نصب موفقیت‌آمیز بوده است: BasicExample و Pods (وابستگی‌های نصب شده توسط CocoaPods).

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

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

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

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

هدف-سی 

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

@import GoogleInteractiveMediaAds;
ViewController.m

سویفت 

import AVFoundation
import GoogleInteractiveMediaAds
import UIKit

ViewController.swift

۴. یک پخش‌کننده ویدیو ایجاد کنید و 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];
}
ViewController.m

سویفت 

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()
  }
ViewController.swift

در این مثال، viewDidLoad() مقداردهی اولیه IMAAdsLoader را انجام می‌دهد و viewDidAppear() پس از نمایش نما، تبلیغات را درخواست می‌کند. متدهای کمکی showContentPlayer() و hideContentPlayer() قابلیت نمایش محتوا را در حین پخش تبلیغات تغییر می‌دهند.

این مثال از متغیر ثابت adTagURLString برای تعریف تگ تبلیغ VAST برای درخواست تبلیغ و از اجزای زیر برای مدیریت IMA SDK استفاده می‌کند:

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

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

برای پخش تبلیغات میان‌پرده، IMA SDK باید موقعیت فعلی محتوای ویدیوی شما را ردیابی کند. برای ارسال موقعیت فعلی به 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];
}
ViewController.m

سویفت 

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()
}
ViewController.swift

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

هدف-سی 

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

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

سویفت 

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

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

برای درخواست مجموعه‌ای از تبلیغات، یک نمونه 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];
}
ViewController.m

سویفت 

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)
}
ViewController.swift

۷. یک نماینده بارگذاری تبلیغات تنظیم کنید

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

برای رویدادهای بارگذاری ناموفق، یک نماینده 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];
}
ViewController.m

سویفت 

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()
}
ViewController.swift

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

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

شروع پخش

متد didReceiveAdEvent تمام رویدادهای IMAAdEvent را مدیریت می‌کند. برای این مثال ساده، منتظر رویداد 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;
  }
}
ViewController.m

سویفت 

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
  }
}
ViewController.swift

مدیریت خطاها

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

هدف-سی 

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

سویفت 

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()
}
ViewController.swift

فعال کردن رویدادهای پخش و مکث

دو متد آخر delegate، رویدادهای پخش و مکث را روی محتوای ویدیویی اصلی، زمانی که IMA SDK درخواست می‌کند، پیاده‌سازی می‌کنند. فعال کردن مکث و پخش زمانی که 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];
}
ViewController.m

سویفت 

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()
}
ViewController.swift

همین! شما اکنون با IMA SDK درخواست و نمایش تبلیغات می‌دهید. برای کسب اطلاعات بیشتر در مورد ویژگی‌های اضافی SDK، به راهنماهای دیگر یا نمونه‌های موجود در GitHub مراجعه کنید.

مراحل بعدی

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