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

پلاتفرم را انتخاب کنید: HTML5 Android iOS tvOS Cast Roku

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

راه‌حل DAI موردعلاقه‌تان را انتخاب کنید

«بازرسی پویای ARP» کامل

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

نمای کلی IMA DAI

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

  • IMAAdDisplayContainer – یک شیء ظرف که در بالای عنصر بازپخش ویدیو قرار می‌گیرد و عناصر میانای کاربر آگهی را در خود جای می‌دهد.
  • IMAAdsLoader – شیئی که جاری‌سازی‌ها را درخواست می‌کند و رویدادهای را که توسط اشیای پاسخ درخواست جاری‌سازی راه‌اندازی می‌شوند مدیریت می‌کند. فقط باید یک بارکننده آگهی‌ها را نمونه‌سازی کنید که می‌تواند درطول عمر برنامه دوباره استفاده شود.
  • IMAStreamRequest – IMAVODStreamRequest یا IMALiveStreamRequest. شیئی که درخواست جاری‌سازی را تعریف می‌کند. درخواست‌های جاری‌سازی می‌تواند برای ویدیو به‌درخواست یا جاری‌سازی زنده باشد. درخواست‌های جاری‌سازی زنده یک کلید دارایی را مشخص می‌کنند، درحالی‌که درخواست‌های VOD یک شناسه CMS و شناسه ویدیو را مشخص می‌کنند. هر دو نوع درخواست می‌توانند به‌صورت اختیاری شامل کلید API موردنیاز برای دسترسی به جاری‌سازی‌های مشخص‌شده و کد شبکه Google Ad Manager برای IMA SDK باشند تا شناسه‌های آگهی را همان‌طور که در تنظیمات Google Ad Manager مشخص شده است مدیریت کند.
  • ‫ IMAStreamManager – شیئی که جریان‌های درج آگهی پویا و تعاملات با زیرینه DAI را مدیریت می‌کند. مدیر جاری‌سازی همچنین پینگ‌های ردیابی را مدیریت می‌کند و رویدادهای جاری‌سازی و آگهی را به ناشر بازارسال می‌کند.

پیش‌نیازها

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

همچنین به پارامترهایی برای درخواست جاری‌سازی از کیت توسعه نرم‌افزار IMA نیاز دارید. برای نمونه‌هایی از پارامترهای درخواست، جاری‌سازی‌های نمونه را ببینید.

پارامترهای جاری‌سازی زنده
کلید دارایی کلید دارایی شناسایی جاری‌سازی زنده شما در Google Ad Manager.
مثال: c-rArva4ShKVIAkNfy6HUQ
پارامترهای جاری‌سازی VOD
شناسه منبع محتوا شناسه منبع محتوا از Google Ad Manager.
مثال: 2548831
شناسه ویدیو شناسه ویدیو از Google Ad Manager.
مثال: tears-of-steel
پارامترهای مشترک (ویدیو به‌درخواست و جاری‌سازی زنده)
کد شبکه کد شبکه Google Ad Manager شما.
مثال: 21775744923

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

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

افزودن IMA DAI SDK به پروژه Xcode

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

توصیه‌شده: «کیت توسعه نرم‌افزار» را بااستفاده از «مدیر بسته Swift» نصب کنید

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

  1. در Xcode، «بسته Swift کیت توسعه نرم‌افزار IMA DAI» را نصب کنید: به File > Add Packages (فایل > افزودن بسته‌ها) بروید.

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

    https://github.com/googleads/swift-package-manager-google-interactive-media-ads-ios
    
  3. نسخه بسته IMA DAI SDK Swift را که می‌خواهید استفاده کنید انتخاب کنید. برای پروژه‌های جدید، از تا نسخه اصلی بعدی استفاده کنید.

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

بارگیری و نصب دستی کیت توسعه نرم‌افزار (SDK)

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

ایجاد پخش‌کننده ویدیو

پخش‌کننده ویدیویی را در کنترل‌کننده نمای اصلی‌تان پیاده‌سازی کنید؛ پخش‌کننده AV را در نمای UI بپیچید. کیت توسعه نرم‌افزار IMA از نمای میانای کاربر برای نمایش عناصر میانای کاربر آگهی استفاده می‌کند.

آبجکتیو-سی

#import "ViewController.h"

#import <AVKit/AVKit.h>

/// Content URL.
static NSString *const kBackupContentUrl =
    @"http://devimages.apple.com/iphone/samples/bipbop/bipbopall.m3u8";

@interface ViewController ()
/// Play button.
@property(nonatomic, weak) IBOutlet UIButton *playButton;

@property(nonatomic, weak) IBOutlet UIView *videoView;
/// Video player.
@property(nonatomic, strong) AVPlayer *videoPlayer;
@end

@implementation ViewController

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

  // Load AVPlayer with the path to your content.
  NSURL *contentURL = [NSURL URLWithString:kBackupContentUrl];
  self.videoPlayer = [AVPlayer playerWithURL:contentURL];

  // Create a player layer for the player.
  AVPlayerLayer *playerLayer = [AVPlayerLayer playerLayerWithPlayer:self.videoPlayer];

  // Size, position, and display the AVPlayer.
  playerLayer.frame = self.videoView.layer.bounds;
  [self.videoView.layer addSublayer:playerLayer];
}

- (IBAction)onPlayButtonTouch:(id)sender {
  [self.videoPlayer play];
  self.playButton.hidden = YES;
}

@end

Swift

// Copyright 2024 Google LLC. All rights reserved.
//
//
// Licensed under the Apache License, Version 2.0 (the "License"); you may not use this
// file except in compliance with the License. You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software distributed under
// the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF
// ANY KIND, either express or implied. See the License for the specific language governing
// permissions and limitations under the License.

import AVFoundation
import UIKit

class ViewController: UIViewController {

  /// Content URL.
  static let backupStreamURLString =
    "http://devimages.apple.com/iphone/samples/bipbop/bipbopall.m3u8"

  /// Play button.
  @IBOutlet private weak var playButton: UIButton!

  @IBOutlet private weak var videoView: UIView!
  /// Video player.
  private var videoPlayer: AVPlayer?

  override func viewDidLoad() {
    super.viewDidLoad()

    playButton.layer.zPosition = CGFloat(MAXFLOAT)

    // Load AVPlayer with path to our content.
    // note: this unwrap is safe because the URL is a constant string.
    let contentURL = URL(string: ViewController.backupStreamURLString)!
    videoPlayer = AVPlayer(url: contentURL)

    // Create a player layer for the player.
    let playerLayer = AVPlayerLayer(player: videoPlayer)

    // Size, position, and display the AVPlayer.
    playerLayer.frame = videoView.layer.bounds
    videoView.layer.addSublayer(playerLayer)
  }

  @IBAction func onPlayButtonTouch(_ sender: Any) {
    videoPlayer?.play()
    playButton.isHidden = true
  }
}

راه‌اندازی بارکننده آگهی

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

این دارایی‌های خصوصی را برای ذخیره کردن عناصر کلیدی «کیت توسعه نرم‌افزار IMA» اضافه کنید:

  • IMAAdsLoader
    • درخواست‌های جاری‌سازی را در طول عمر برنامه شما مدیریت می‌کند.
  • IMAAdDisplayContainer
    • عناصر میانای کاربر آگهی را درج و مدیریت می‌کند.
  • IMAAVPlayerVideoDisplay - بین «کیت توسعه نرم‌افزار IMA» و پخش‌کننده رسانه شما ارتباط برقرار می‌کند و فراداده زمان‌دار را مدیریت می‌کند.
  • IMAStreamManager - پخش جاری‌سازی را مدیریت می‌کند و رویدادهای مربوط به آگهی را راه‌اندازی می‌کند.

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

آبجکتیو-سی

@import GoogleInteractiveMediaAds;

// ...

@interface ViewController () <IMAAdsLoaderDelegate, IMAStreamManagerDelegate>
/// The entry point for the IMA DAI SDK to make DAI stream requests.
@property(nonatomic, strong) IMAAdsLoader *adsLoader;
/// The container where the SDK renders each ad's user interface elements and companion slots.
@property(nonatomic, strong) IMAAdDisplayContainer *adDisplayContainer;
/// The reference of your video player for the IMA DAI SDK to monitor playback and handle timed
/// metadata.
@property(nonatomic, strong) IMAAVPlayerVideoDisplay *imaVideoDisplay;
/// References the stream manager from the IMA DAI SDK after successful stream loading.
@property(nonatomic, strong) IMAStreamManager *streamManager;

// ...

@end

@implementation ViewController

- (void)viewDidLoad {
  [super viewDidLoad];

  // ...

  self.adsLoader = [[IMAAdsLoader alloc] initWithSettings:nil];
  self.adsLoader.delegate = self;

  // Create an ad display container for rendering each ad's user interface elements and companion
  // slots.
  self.adDisplayContainer =
      [[IMAAdDisplayContainer alloc] initWithAdContainer:self.videoView
                                          viewController:self
                                          companionSlots:nil];

  // Create an IMAAVPlayerVideoDisplay to give the SDK access to your video player.
  self.imaVideoDisplay = [[IMAAVPlayerVideoDisplay alloc] initWithAVPlayer:self.videoPlayer];
}

Swift

import GoogleInteractiveMediaAds
// ...

class ViewController: UIViewController, IMAAdsLoaderDelegate, IMAStreamManagerDelegate {
  // ...

  /// The entry point for the IMA DAI SDK to make DAI stream requests.
  private var adsLoader: IMAAdsLoader?
  /// The container where the SDK renders each ad's user interface elements and companion slots.
  private var adDisplayContainer: IMAAdDisplayContainer?
  /// The reference of your video player for the IMA DAI SDK to monitor playback and handle timed
  /// metadata.
  private var imaVideoDisplay: IMAAVPlayerVideoDisplay!
  /// References the stream manager from the IMA DAI SDK after successfully loading the DAI stream.
  private var streamManager: IMAStreamManager?

  // ...

  override func viewDidLoad() {
    super.viewDidLoad()

    // ...

    adsLoader = IMAAdsLoader(settings: nil)
    adsLoader?.delegate = self

    // Create an ad display container for rendering ad UI elements and the companion ad.
    adDisplayContainer = IMAAdDisplayContainer(
      adContainer: videoView,
      viewController: self,
      companionSlots: nil)

    // Create an IMAAVPlayerVideoDisplay to give the SDK access to your video player.
    imaVideoDisplay = IMAAVPlayerVideoDisplay(avPlayer: videoPlayer)
  }

درخواست جاری‌سازی کنید

وقتی کاربر دکمه پخش را فشار می‌دهد، درخواست جاری‌سازی جدیدی ایجاد کنید. از کلاس IMALiveStreamRequest برای جاری‌سازی‌های زنده استفاده کنید. برای جاری‌سازی‌های VOD، از کلاس IMAVODStreamRequest استفاده کنید.

درخواست جاری‌سازی به پارامترهای جاری‌سازی شما و همچنین ارجاع به محفظه نمایش آگهی و نمایش ویدیو شما نیاز دارد.

آبجکتیو-سی

- (IBAction)onPlayButtonTouch:(id)sender {
  [self requestStream];
  self.playButton.hidden = YES;
}

- (void)requestStream {
  // Create a stream request. Use one of "Live stream request" or "VOD request", depending on your
  // type of stream.
  if (kStreamType == StreamTypeLive) {
    // Live stream request. Replace the asset key with your value.
    IMALiveStreamRequest *request =
        [[IMALiveStreamRequest alloc] initWithAssetKey:kLiveStreamAssetKey
                                           networkCode:kNetworkCode
                                    adDisplayContainer:self.adDisplayContainer
                                          videoDisplay:self.imaVideoDisplay
                                           userContext:nil];
    request.useHLSInterstitials = YES;
    [self.adsLoader requestStreamWithRequest:request];
  } else {
    // VOD request. Replace the content source ID and video ID with your values.
    IMAVODStreamRequest *request =
        [[IMAVODStreamRequest alloc] initWithContentSourceID:kVODContentSourceID
                                                     videoID:kVODVideoID
                                                 networkCode:kNetworkCode
                                          adDisplayContainer:self.adDisplayContainer
                                                videoDisplay:self.imaVideoDisplay
                                                 userContext:nil];
    [self.adsLoader requestStreamWithRequest:request];
  }
}

Swift

@IBAction func onPlayButtonTouch(_ sender: Any) {
  requestStream()
  playButton.isHidden = true
}

func requestStream() {
  // Create a stream request. Use one of "Livestream request" or "VOD request".
  if ViewController.requestType == StreamType.live {
    // Livestream request.
    let request = IMALiveStreamRequest(
      assetKey: ViewController.assetKey,
      networkCode: ViewController.networkCode,
      adDisplayContainer: adDisplayContainer!,
      videoDisplay: imaVideoDisplay,
      userContext: nil)
    request.useHLSInterstitials = true
    adsLoader?.requestStream(with: request)
  } else {
    // VOD stream request.
    let request = IMAVODStreamRequest(
      contentSourceID: ViewController.contentSourceID,
      videoID: ViewController.videoID,
      networkCode: ViewController.networkCode,
      adDisplayContainer: adDisplayContainer!,
      videoDisplay: imaVideoDisplay,
      userContext: nil)
    adsLoader?.requestStream(with: request)
  }
}

گوش دادن به رویدادهای بار کردن جاری‌سازی

کلاس IMAAdsLoader متدهای IMAAdsLoaderDelegate را درصورت موفقیت‌آمیز بودن راه‌اندازی یا ناموفق بودن درخواست جاری‌سازی فرا می‌خواند.

در روش نماینده adsLoadedWithData ، IMAStreamManagerDelegate را تنظیم کنید. مدیر جاری‌سازی را مقداردهی اولیه کنید. در هنگام مقداردهی اولیه، مدیر جاری‌سازی بازپخش را شروع می‌کند.

در روش نماینده failedWithErrorData ، خطا را ثبت کنید. درصورت تمایل، جاری‌سازی پشتیبان را پخش کنید. روال‌های مطلوب DAI را ببینید.

آبجکتیو-سی

- (void)adsLoader:(IMAAdsLoader *)loader adsLoadedWithData:(IMAAdsLoadedData *)adsLoadedData {
  NSLog(@"Stream created with: %@.", adsLoadedData.streamManager.streamId);
  self.streamManager = adsLoadedData.streamManager;
  self.streamManager.delegate = self;
  [self.streamManager initializeWithAdsRenderingSettings:nil];
}

- (void)adsLoader:(IMAAdsLoader *)loader failedWithErrorData:(IMAAdLoadingErrorData *)adErrorData {
  // Log the error and play the content.
  NSLog(@"AdsLoader error, code:%ld, message: %@", adErrorData.adError.code,
        adErrorData.adError.message);
  [self.videoPlayer play];
}

Swift

func adsLoader(_ loader: IMAAdsLoader, adsLoadedWith adsLoadedData: IMAAdsLoadedData) {
  print("DAI stream loaded. Stream session ID: \(adsLoadedData.streamManager!.streamId!)")
  streamManager = adsLoadedData.streamManager!
  streamManager!.delegate = self
  streamManager!.initialize(with: nil)
}

func adsLoader(_ loader: IMAAdsLoader, failedWith adErrorData: IMAAdLoadingErrorData) {
  print("Error loading DAI stream. Error message: \(adErrorData.adError.message!)")
  // Play the backup stream.
  videoPlayer.play()
}

گوش دادن به رویدادهای آگهی

IMAStreamManager روش‌های IMAStreamManagerDelegate را برای انتقال رویدادهای جاری‌سازی و خطاها به برنامه شما فرا می‌خواند.

برای این مثال، رویدادهای آگهی اصلی را در کنسول ثبت کنید:

آبجکتیو-سی

- (void)streamManager:(IMAStreamManager *)streamManager didReceiveAdEvent:(IMAAdEvent *)event {
  NSLog(@"Ad event (%@).", event.typeString);
  switch (event.type) {
    case kIMAAdEvent_STARTED: {
      // Log extended data.
      NSString *extendedAdPodInfo = [[NSString alloc]
          initWithFormat:@"Showing ad %ld/%ld, bumper: %@, title: %@, description: %@, contentType:"
                         @"%@, pod index: %ld, time offset: %lf, max duration: %lf.",
                         (long)event.ad.adPodInfo.adPosition, (long)event.ad.adPodInfo.totalAds,
                         event.ad.adPodInfo.isBumper ? @"YES" : @"NO", event.ad.adTitle,
                         event.ad.adDescription, event.ad.contentType,
                         (long)event.ad.adPodInfo.podIndex, event.ad.adPodInfo.timeOffset,
                         event.ad.adPodInfo.maxDuration];

      NSLog(@"%@", extendedAdPodInfo);
      break;
    }
    case kIMAAdEvent_AD_BREAK_STARTED: {
      NSLog(@"Ad break started");
      break;
    }
    case kIMAAdEvent_AD_BREAK_ENDED: {
      NSLog(@"Ad break ended");
      break;
    }
    case kIMAAdEvent_AD_PERIOD_STARTED: {
      NSLog(@"Ad period started");
      break;
    }
    case kIMAAdEvent_AD_PERIOD_ENDED: {
      NSLog(@"Ad period ended");
      break;
    }
    default:
      break;
  }
}

- (void)streamManager:(IMAStreamManager *)streamManager didReceiveAdError:(IMAAdError *)error {
  NSLog(@"StreamManager error with type: %ld\ncode: %ld\nmessage: %@", error.type, error.code,
        error.message);
  [self.videoPlayer play];
}

Swift

func streamManager(_ streamManager: IMAStreamManager, didReceive event: IMAAdEvent) {
  print("Ad event \(event.typeString).")
  switch event.type {
  case IMAAdEventType.STARTED:
    // Log extended data.
    if let ad = event.ad {
      let extendedAdPodInfo = String(
        format: "Showing ad %zd/%zd, bumper: %@, title: %@, "
          + "description: %@, contentType:%@, pod index: %zd, "
          + "time offset: %lf, max duration: %lf.",
        ad.adPodInfo.adPosition,
        ad.adPodInfo.totalAds,
        ad.adPodInfo.isBumper ? "YES" : "NO",
        ad.adTitle,
        ad.adDescription,
        ad.contentType,
        ad.adPodInfo.podIndex,
        ad.adPodInfo.timeOffset,
        ad.adPodInfo.maxDuration)

      print("\(extendedAdPodInfo)")
    }
    break
  case IMAAdEventType.AD_BREAK_STARTED:
    print("Ad break started.")
    break
  case IMAAdEventType.AD_BREAK_ENDED:
    print("Ad break ended.")
    break
  case IMAAdEventType.AD_PERIOD_STARTED:
    print("Ad period started.")
    break
  case IMAAdEventType.AD_PERIOD_ENDED:
    print("Ad period ended.")
    break
  default:
    break
  }
}

func streamManager(_ streamManager: IMAStreamManager, didReceive error: IMAAdError) {
  print("StreamManager error with type: \(error.type)")
  print("code: \(error.code)")
  print("message: \(error.message ?? "Unknown Error")")
}

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