با IMA DAI SDK شروع کنید

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

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

سرویس کامل سرو پاد

سرویس پاد DAI

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

توجه: اپل فقط چارچوب هایی را برای پشتیبانی از HTTP Live Streaming (HLS) مانند AVKit، AVFoundation و WebKit ارائه می دهد. این چارچوب‌ها با قالب جریان DASH کار نمی‌کنند.

برای استفاده از IMA DAI، باید یک حساب Ad Manager 360 Advanced داشته باشید. اگر حساب Ad Manager دارید، برای جزئیات بیشتر با مدیر حساب خود تماس بگیرید. برای کسب اطلاعات در مورد ثبت نام در Ad Manager، از مرکز راهنمای Ad Manager دیدن کنید.

توجه: برای اطلاعات در مورد ادغام با سایر پلتفرم‌ها یا استفاده از کیت توسعه نرم‌افزارهای سمت سرویس گیرنده IMA، به کیت‌های توسعه نرم‌افزار تبلیغات رسانه‌ای تعاملی مراجعه کنید.

نمای کلی IMA DAI

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

• IMAAdDisplayContainer - یک شی کانتینری که در بالای عنصر پخش ویدیو قرار می گیرد و عناصر رابط کاربری تبلیغات را در خود جای می دهد.
• IMAAdsLoader – شی ای که جریان ها را درخواست می کند و رویدادهای ایجاد شده توسط اشیاء پاسخ درخواست جریان را مدیریت می کند. شما باید فقط یک بارکننده تبلیغات را نمونه برداری کنید، که می تواند در طول عمر برنامه مجددا استفاده شود.
• IMAStreamRequest – یک IMAPodVODStreamRequest یا یک IMAPodStreamRequest .
• IMAStreamManager – شیئی که جریانهای درج آگهی پویا و تعاملات با باطن DAI را مدیریت می کند. مدیر جریان همچنین پینگ‌های ردیابی را مدیریت می‌کند و جریان‌ها و رویدادهای تبلیغاتی را به ناشر ارسال می‌کند.

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

پیش نیازها

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

• Xcode 13 یا بالاتر
• CocoaPods (ترجیحا)، مدیریت بسته Swift، یا یک کپی دانلود شده از IMA DAI SDK برای iOS

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

پارامترهای پخش زنده
کد شبکه	کد شبکه برای حساب Ad Manager 360 شما. مثال: 51636543
کلید دارایی سفارشی	کلید دارایی سفارشی که رویداد سرویس Pod شما را در Ad Manager 360 شناسایی می‌کند. این کلید می‌تواند توسط دستکاری‌کننده مانیفست شما یا شریک سرویس Pod شخص ثالث ایجاد شود. مثال: google-sample
پارامترهای جریان VOD
کد شبکه	کد شبکه برای حساب Ad Manager 360 شما. مثال: 51636543

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

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

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

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

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

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

1. در همان پوشه فایل PodServingExample.xcodeproj خود، یک فایل متنی به نام Podfile ایجاد کنید و پیکربندی زیر را اضافه کنید:

   پادفایل
   source 'https://github.com/CocoaPods/Specs.git'
   
   platform :ios, '14'
   
   target 'PodServingExample' do
     pod 'GoogleAds-IMA-iOS-SDK'
   end
   Podfile

2. از دایرکتوری حاوی Podfile، اجرا کنید:

   pod install --repo-update

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

Interactive Media Ads SDK از Swift Package Manager با شروع نسخه 3.18.4 پشتیبانی می کند. برای وارد کردن بسته سوئیفت مراحل زیر را دنبال کنید.

توجه: اگر از یک پروژه مبتنی بر CocoaPods مهاجرت می کنید، pod deintegrate اجرا کنید تا CocoaPods را از پروژه Xcode خود حذف کنید. فایل .xcworkspace ایجاد شده توسط CocoaPods را می توان با خیال راحت حذف کرد. اگر برای اولین بار است که IMA DAI SDK را به پروژه ای اضافه می کنید، این مرحله می تواند نادیده گرفته شود.

1. در Xcode، بسته IMA DAI SDK Swift را با رفتن به 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 Package را که می خواهید استفاده کنید انتخاب کنید. برای پروژه‌های جدید، توصیه می‌کنیم از نسخه اصلی تا بعدی استفاده کنید.

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

SDK را به صورت دستی دانلود و نصب کنید

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

نمایش دستورالعمل ها

1. از صفحه دانلود iOS IMA ، آخرین نسخه IMA DAI SDK را دانلود و استخراج کنید.
2. BasicExample.xcodeproj را باز کنید.
3. در قسمت سمت چپ، روی نام پروژه کلیک کنید.
   
4. در قسمت مرکزی، روی Build Phases کلیک کنید.
   
5. بخش Link Binary With Libraries را گسترش دهید.
6. در پایین لیست کتابخانه ها، روی نماد مثبت [+] کلیک کنید.
7. روی Add Other کلیک کنید.
8. در فهرستی که SDK دانلود شده را استخراج کردید، GoogleInteractiveMediaAds.framework را انتخاب کنید و روی Open کلیک کنید.
9. در پایین لیست کتابخانه ها، دوباره روی نماد مثبت [+] کلیک کنید.
10. در ستون وضعیت ، بررسی کنید که GoogleInteractiveMediaAds.framework روی Required تنظیم شده باشد.
11. پرچم پیوند دهنده -ObjC را در تنظیمات ساخت خود قرار دهید. برای اطلاعات بیشتر، Apple QA1490 را ببینید.

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

با استفاده از پخش کننده AV که در نمای رابط کاربری پیچیده شده است، یک پخش کننده ویدیو را در کنترلر نمای اصلی خود پیاده کنید. IMA SDK از نمای رابط کاربری برای نمایش عناصر رابط کاربری تبلیغات استفاده می کند.

ViewController.m

#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
ViewController.m

لودر تبلیغات را راه اندازی کنید

IMA SDK را در کنترل‌کننده view خود وارد کنید و پروتکل‌های IMAAdsLoaderDelegate و IMAStreamManagerDelegate را برای مدیریت رویدادهای بارکننده تبلیغات و مدیریت جریان استفاده کنید.

این ویژگی‌های خصوصی را برای ذخیره مؤلفه‌های کلیدی IMA SDK اضافه کنید:

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

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

ViewController.m

@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];
}
ViewController.m

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

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

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

نکته: پارامتر userContext به شما امکان می‌دهد داده‌های خاص درخواست را از درخواست جریان به روش‌های نمایندگی لودر تبلیغات مرتبط ارسال کنید. از زمینه کاربر برای تمایز بین چندین درخواست جریان همزمان استفاده کنید.

ViewController.m

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

- (void)requestStream {
  // Create a stream request.
  IMAStreamRequest *request;
  if (kStreamType == StreamTypeLive) {
    // Live stream request. Replace the network code and custom asset key with your values.
    request = [[IMAPodStreamRequest alloc] initWithNetworkCode:kNetworkCode
                                                customAssetKey:kCustomAssetKey
                                            adDisplayContainer:adDisplayContainer
                                                  videoDisplay:self.videoDisplay
                                         pictureInPictureProxy:nil
                                                   userContext:nil];
  } else {
    // VOD request. Replace the network code with your value.
    request = [[IMAPodVODStreamRequest alloc] initWithNetworkCode:@kNetworkCode
                                               adDisplayContainer:adDisplayContainer
                                                     videoDisplay:self.videoDisplay
                                            pictureInPictureProxy:nil
                                                      userContext:nil];
  }
  [self.adsLoader requestStreamWithRequest:request];
}
ViewController.m

به جریان رویدادهای بارگذاری گوش دهید

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

در روش نمایندگی adsLoadedWithData ، IMAStreamManagerDelegate خود را تنظیم کنید. شناسه جریان را به کنترل کننده VTP سفارشی خود منتقل کنید و URL مانیفست جریان را بازیابی کنید. برای پخش زنده، URL مانیفست را در نمایشگر ویدیوی خود بارگیری کنید و پخش را شروع کنید. برای جریان‌های VOD، URL مانیفست را به روش loadThirdPartyStream مدیر جریان ارسال کنید. این روش داده‌های رویداد آگهی را از Ad Manager 360 درخواست می‌کند، سپس URL مانیفست را بارگیری می‌کند و پخش را شروع می‌کند.

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

ViewController.m

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

  // Build the Pod serving Stream URL.
  NSString *streamID = adsLoadedData.streamManager.streamId;
  // Your custom VTP handler takes the stream ID and returns the stream manifest URL.
  NSString *urlString = gCustomVTPHandler(streamID);
  NSURL *streamUrl = [NSURL URLWithString:urlString];
  if (kStreamType == StreamTypeLive) {
    // Load live streams directly into the AVPlayer.
    [self.videoDisplay loadStream:streamUrl withSubtitles:@[]];
    [self.videoDisplay play];
  } else {
    // Load VOD streams using the `loadThirdPartyStream` method in IMA SDK's stream manager.
    // The stream manager loads the stream, requests metadata, and starts playback.
    [self.streamManager loadThirdPartyStream:streamUrl streamSubtitles:@[]];
  }
}

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

کنترلر VTP سفارشی خود را پیاده سازی کنید

کنترل کننده VTP سفارشی شناسه پخش جریان بیننده را به همراه هر اطلاعات دیگری که VTP شما برای بازگرداندن مانیفست جریانی حاوی محتوا و تبلیغات دوخته شده نیاز دارد، به شریک فنی ویدیوی شما (VTP) ارسال می کند. VTP شما دستورالعمل های خاصی را در مورد نحوه پیاده سازی کنترلر VTP سفارشی ارائه می دهد.

به عنوان مثال، یک VTP ممکن است شامل یک URL الگوی مانیفست حاوی ماکرو [[STREAMID]] باشد. در این مثال، handler شناسه جریان را به جای ماکرو وارد می‌کند و URL مانیفست حاصل را برمی‌گرداند.

ViewController.m

/// Custom VTP Handler.
///
/// Returns the stream manifest URL from the video technical partner or manifest manipulator.
static NSString *(^gCustomVTPHandler)(NSString *) = ^(NSString *streamID) {
  // Insert synchronous code here to retrieve a stream manifest URL from your video tech partner
  // or manifest manipulation server.
  // This example uses a hardcoded URL template, containing a placeholder for the stream
  // ID and replaces the placeholder with the stream ID.
  NSString *manifestUrl = @"YOUR_MANIFEST_URL_TEMPLATE";
  return [manifestUrl stringByReplacingOccurrencesOfString:@"[[STREAMID]]"
                                                withString:streamID];
};
ViewController.m

به رویدادهای تبلیغاتی گوش دهید

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

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

ViewController.m

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

دارایی های IMA DAI را پاکسازی کنید

برای توقف پخش جریانی، توقف همه ردیابی تبلیغات، و آزاد کردن همه دارایی های جریان بارگیری شده، با IMAStreamManager.destroy() تماس بگیرید.

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