راه اندازی IMA SDK برای DAI، راه اندازی IMA SDK برای DAI، راه اندازی IMA SDK برای DAI، راه اندازی IMA SDK برای DAI

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

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

راهکار DAI مورد نظرتان را انتخاب کنید

سرویس کامل DAI

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

مرور کلی IMA DAI

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

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

پیش‌نیازها

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

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

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

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

برای نصب IMA DAI SDK از یکی از این سه روش استفاده کنید.

نصب SDK با استفاده از CocoaPods (ترجیحاً)

CocoaPods یک مدیر وابستگی برای پروژه‌های Xcode است و روش پیشنهادی برای نصب IMA DAI SDK می‌باشد. برای اطلاعات بیشتر در مورد نصب یا استفاده از CocoaPods، به مستندات CocoaPods مراجعه کنید. پس از نصب CocoaPods، از دستورالعمل‌های زیر برای نصب IMA DAI SDK استفاده کنید:

  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).

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

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

  1. در Xcode، با رفتن به مسیر File > Add Packages ، بسته‌ی سویفت GoogleInteractiveMediaAds را نصب کنید.

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

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

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

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

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

ساخت یک پخش کننده ویدیوی ساده

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

ViewController.m

#import "ViewController.h"

#import <AVKit/AVKit.h>

@interface ViewController ()
@property(nonatomic) AVPlayerViewController *playerViewController;
@end

@implementation ViewController

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

  // Create a stream video player.
  AVPlayer *player = [[AVPlayer alloc] init];
  self.playerViewController = [[AVPlayerViewController alloc] init];
  self.playerViewController.player = player;

  // Attach the video player to the view hierarchy.
  [self addChildViewController:self.playerViewController];
  self.playerViewController.view.frame = self.view.bounds;
  [self.view addSubview:self.playerViewController.view];
  [self.playerViewController didMoveToParentViewController:self];
}

@end

SDK را وارد کنید و stubهایی برای تعامل با IMA اضافه کنید

بعد از اینکه IMA DAI SDK را به پروژه خود اضافه کردید، SDK را وارد کنید و Stubهایی را برای نقاط اصلی تعامل IMA اضافه کنید.

ViewController.m

#import "ViewController.h"

#import <AVKit/AVKit.h>
#import <GoogleInteractiveMediaAds/GoogleInteractiveMediaAds.h>

@interface ViewController ()
@property(nonatomic) IMAAdsLoader *adsLoader;
@property(nonatomic) UIView *adContainerView;
@property(nonatomic) IMAStreamManager *streamManager;
@property(nonatomic) AVPlayerViewController *playerViewController;
@end

@implementation ViewController

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

  [self setupAdsLoader];

  // Create a stream video player.
  AVPlayer *player = [[AVPlayer alloc] init];
  self.playerViewController = [[AVPlayerViewController alloc] init];
  self.playerViewController.player = player;

  // Attach the video player to the view hierarchy.
  [self addChildViewController:self.playerViewController];
  self.playerViewController.view.frame = self.view.bounds;
  [self.view addSubview:self.playerViewController.view];
  [self.playerViewController didMoveToParentViewController:self];

  [self attachAdContainer];
}

- (void)viewDidAppear:(BOOL)animated {
  [super viewDidAppear:animated];
  [self requestStream];
}

- (void)setupAdsLoader {}

- (void)attachAdContainer {}

- (void)requestStream {}

@end

پیاده‌سازی IMAAdsLoader

در مرحله بعد، IMAAdsLoader را نمونه‌سازی کنید و نمای کانتینر تبلیغات را به سلسله مراتب نماها متصل کنید.

ViewController.m

- (void)setupAdsLoader {
  self.adsLoader = [[IMAAdsLoader alloc] init];
  self.adsLoader.delegate = self;
}

- (void)attachAdContainer {
  self.adContainerView = [[UIView alloc] init];
  [self.view addSubview:self.adContainerView];
  self.adContainerView.frame = self.view.bounds;
}

درخواست پخش جریانی بدهید

چند ثابت برای نگهداری اطلاعات جریان ایجاد کنید و سپس تابع درخواست جریان را برای ایجاد درخواست پیاده‌سازی کنید.

ViewController.m

#import <GoogleInteractiveMediaAds/GoogleInteractiveMediaAds.h>

static NSString *const kAssetKey = @"sN_IYUG8STe1ZzhIIE_ksA";
static NSString *const kContentSourceID = @"2548831";
static NSString *const kVideoID = @"tears-of-steel";
static NSString *const kNetworkCode = @"21775744923";

@interface ViewController ()
...

- (void)requestStream {
  IMAAVPlayerVideoDisplay *videoDisplay =
      [[IMAAVPlayerVideoDisplay alloc] initWithAVPlayer:self.playerViewController.player];
  IMAAdDisplayContainer *adDisplayContainer =
      [[IMAAdDisplayContainer alloc] initWithAdContainer:self.adContainerView];
  IMALiveStreamRequest *request = [[IMALiveStreamRequest alloc] initWithAssetKey:kAssetKey
                                                                     networkCode:kNetworkCode
                                                              adDisplayContainer:adDisplayContainer
                                                                    videoDisplay:videoDisplay];
  // VOD request. Comment out the IMALiveStreamRequest above and uncomment this IMAVODStreamRequest
  // to switch from a livestream to a VOD stream.
  // IMAVODStreamRequest *request =
  //     [[IMAVODStreamRequest alloc] initWithContentSourceId:kContentSourceID
  //                                                  videoId:kVideoID
  //                                              networkCode:kNetworkCode
  //                                       adDisplayContainer:adDisplayContainer
  //                                             videoDisplay:videoDisplay];
  [self.adsLoader requestStreamWithRequest:request];
}

مدیریت رویدادهای جریان

IMAAdsLoader و IMAStreamManager رویدادهایی را اجرا می‌کنند که برای مدیریت مقداردهی اولیه، خطاها و تغییرات در وضعیت جریان استفاده می‌شوند. این رویدادها از طریق پروتکل‌های IMAAdsLoaderDelegate و IMAStreamManagerDelegate اجرا می‌شوند. به رویداد بارگذاری تبلیغات گوش دهید و جریان را مقداردهی اولیه کنید. اگر یک تبلیغ بارگذاری نشد، به جای آن یک جریان پشتیبان پخش کنید.

ViewController.m

static NSString *const kAssetKey = @"sN_IYUG8STe1ZzhIIE_ksA";
static NSString *const kContentSourceID = @"2548831";
static NSString *const kVideoID = @"tears-of-steel";
static NSString *const kNetworkCode = @"21775744923";
static NSString *const kBackupStreamURLString =
    @"https://storage.googleapis.com/interactive-media-ads/media/bbb.m3u8";

@interface ViewController () <IMAAdsLoaderDelegate, IMAStreamManagerDelegate>

...
  [self.adsLoader requestStreamWithRequest:request];
}

- (void)playBackupStream {
  NSURL *backupStreamURL = [NSURL URLWithString:kBackupStreamURLString];
  AVPlayerItem *backupStreamItem = [AVPlayerItem playerItemWithURL:backupStreamURL];
  [self.playerViewController.player replaceCurrentItemWithPlayerItem:backupStreamItem];
  [self.playerViewController.player play];
}

#pragma mark - IMAAdsLoaderDelegate

- (void)adsLoader:(IMAAdsLoader *)loader adsLoadedWithData:(IMAAdsLoadedData *)adsLoadedData {
  // Initialize and listen to stream manager's events.
  self.streamManager = adsLoadedData.streamManager;
  self.streamManager.delegate = self;
  [self.streamManager initializeWithAdsRenderingSettings:nil];
  NSLog(@"Stream created with: %@.", self.streamManager.streamId);
}

- (void)adsLoader:(IMAAdsLoader *)loader failedWithErrorData:(IMAAdLoadingErrorData *)adErrorData {
  // Fall back to playing the backup stream.
  NSLog(@"Error loading ads: %@", adErrorData.adError.message);
  [self playBackupStream];
}

#pragma mark - IMAStreamManagerDelegate

- (void)streamManager:(IMAStreamManager *)streamManager didReceiveAdEvent:(IMAAdEvent *)event {}

- (void)streamManager:(IMAStreamManager *)streamManager didReceiveAdError:(IMAAdError *)error {}

- (void)streamManager:(IMAStreamManager *)streamManager
  adDidProgressToTime:(NSTimeInterval)time
           adDuration:(NSTimeInterval)adDuration
           adPosition:(NSInteger)adPosition
             totalAds:(NSInteger)totalAds
      adBreakDuration:(NSTimeInterval)adBreakDuration {}

@end

مدیریت رویدادهای ثبت وقایع و خطاها

چندین رویداد وجود دارد که می‌توانند توسط نماینده مدیریت جریان مدیریت شوند، اما برای پیاده‌سازی‌های اولیه، مهم‌ترین کاربردها عبارتند از انجام ثبت وقایع، جلوگیری از اقدامات جستجو هنگام پخش تبلیغات و مدیریت خطاها.

ViewController.m

#pragma mark - IMAStreamManagerDelegate

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

      NSLog(@"%@", extendedAdPodInfo);
      break;
    }
    case kIMAAdEvent_AD_BREAK_STARTED: {
      // Prevent user seek through when an ad starts and show the ad controls.
      self.adContainerView.hidden = NO;
      break;
    }
    case kIMAAdEvent_AD_BREAK_ENDED: {
      // Allow user seek through after an ad ends and hide the ad controls.
      self.adContainerView.hidden = YES;
      break;
    }
    default:
      break;
  }
}

- (void)streamManager:(IMAStreamManager *)streamManager didReceiveAdError:(IMAAdError *)error {
  // Fall back to playing the backup stream.
  NSLog(@"StreamManager error: %@", error.message);
  [self playBackupStream];
}

@end

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