תחילת העבודה עם IMA DAI SDK

ערכות ה-SDK של IMA מאפשרות לשלב בקלות מודעות מולטימדיה באתרים ובאפליקציות. ערכות ה-SDK של IMA יכולות לבקש מודעות מכל שרת מודעות שתואם ל-VAST ולנהל את ההפעלה של המודעות באפליקציות. באמצעות ערכות ה-SDK של IMA DAI, האפליקציות שולחות בקשה לשידור של מודעת וידאו ותוכן וידאו – VOD או תוכן בשידור חי. לאחר מכן, ה-SDK מחזיר שידור וידאו משולב, כך שלא תצטרכו לנהל את המעבר בין סרטון המודעה לסרטון התוכן באפליקציה.

בחירת פתרון ה-DAI הרצוי

שירות DAI מלא

המדריך הזה מראה איך לשלב את IMA DAI SDK באפליקציית נגן וידאו פשוטה. אם אתם רוצים לראות דוגמה לשילוב מלא או לפעול לפיה, תוכלו להוריד את BasicExample מ-GitHub.

סקירה כללית על הטמעת מודעות דינמיות (DAI) ב-IMA

הטמעת IMA DAI כוללת ארבעה רכיבים עיקריים של SDK, כפי שמתואר במדריך הזה:

  • IMAAdDisplayContainer – אובייקט קונטיינר שנמצא מעל אלמנט ההפעלה של הסרטון ומכיל את רכיבי ממשק המשתמש של המודעה.
  • IMAAdsLoader – אובייקט שמבקש שידורים ומטפל באירועים שמופעל על ידי אובייקטים של תגובות לבקשות של שידורים. צריך ליצור רק אובייקט אחד של Ads Loader, שאפשר לעשות בו שימוש חוזר לאורך כל חיי האפליקציה.
  • IMAStreamRequest – הערך יכול להיות IMAVODStreamRequest או IMALiveStreamRequest. אובייקט שמגדיר בקשת סטרימינג. בקשות להפעלת שידורים יכולות להיות לשידורים חיים או לשידורים לפי דרישה. הבקשות כוללות מזהה תוכן, מפתח API או אסימון אימות ופרמטרים אחרים.
  • IMAStreamManager – אובייקט שמטפל בזרמים של הטמעת מודעות דינמיות ובאינטראקציות עם הקצה העורפי של DAI. מנהל הסטרימינג מטפל גם בפניות מעקב (pings) ומעביר אירועי סטרימינג ומודעות לבעלי התוכן הדיגיטלי.

דרישות מוקדמות

לפני שמתחילים, צריך את הדברים הבאים:

צריך גם את הפרמטרים שמשמשים לשליחת בקשה לסטרימינג מ-IMA SDK. דוגמאות לפרמטרים של בקשות מפורטות במאמר מקורות נתונים לדוגמה.

פרמטרים של שידורים חיים
מפתח נכס מפתח הנכס שמזהה את השידור החי ב-Google Ad Manager.
דוגמה: c-rArva4ShKVIAkNfy6HUQ
פרמטרים של סטרימינג של VOD
מזהה של מקור התוכן מזהה מקור התוכן מ-Google Ad Manager.
דוגמה: 2548831
מזהה סרטון מזהה הסרטון מ-Google Ad Manager.
דוגמה: tears-of-steel

יצירת פרויקט חדש ב-Xcode

ב-Xcode, יוצרים פרויקט iOS חדש באמצעות 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 ומוסיפים את ההגדרות הבאות:

    Podfile 
    source 'https://github.com/CocoaPods/Specs.git'

platform :ios, '14'

target 'BasicExample' do
  pod 'GoogleAds-IMA-iOS-SDK', '~> 3.23.0'
end

    Podfile

  2. בתיקייה שמכילה את Podfile, מריצים את הפקודה:

    pod install --repo-update`

  3. כדי לוודא שההתקנה בוצעה בהצלחה, פותחים את הקובץ BasicExample.xcworkspace ומוודאים שהוא מכיל שני פרויקטים: BasicExample ו-Pods (היחסי התלות שהותקנו על ידי CocoaPods).

התקנת ה-SDK באמצעות Swift Package Manager

‏Interactive Media Ads SDK תומך ב-Swift Package Manager החל מגרסה 3.18.4. כדי לייבא את חבילת Swift, פועלים לפי השלבים הבאים.

  1. ב-Xcode, מתקינים את חבילת Swift של IMA DAI SDK. לשם כך, עוברים אל File > Add Packages.

  2. בהודעה שמופיעה, מחפשים את המאגר של IMA DAI SDK Swift Package ב-GitHub:

    https://github.com/googleads/swift-package-manager-google-interactive-media-ads-ios

  3. בוחרים את הגרסה של חבילת Swift של IMA DAI SDK שבה רוצים להשתמש. בפרויקטים חדשים, מומלץ להשתמש באפשרות עד לגרסה הראשית הבאה.

בסיום, Xcode פותר את יחסי התלות בחבילות ומוריד אותן ברקע. למידע נוסף על הוספת יחסי תלות בין חבילות, אפשר לעיין במאמר של Apple.

הורדה והתקנה ידניות של ה-SDK

אם אתם לא רוצים להשתמש ב-Swift Package Manager או ב-CocoaPods, תוכלו להוריד את IMA DAI SDK ולהוסיף אותו לפרויקט באופן ידני.

יצירת נגן וידאו פשוט

הטמעת נגן וידאו ב-View Controller הראשי באמצעות נגן AV שמקובץ בתצוגת UI. מערכת 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 למנהל התצוגה ומשתמשים בפרוטוקולים 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

שליחת בקשה להעברת נתונים

כשמשתמש לוחץ על לחצן ההפעלה, שולחים בקשה חדשה לשידור. משתמשים בכיתה IMALiveStreamRequest לשידורים חיים. להעברות VOD, משתמשים במחלקה IMAVODStreamRequest.

בקשת הסטרימינג כוללת את הפרמטרים של הסטרימינג, וגם הפניה לקונטיינר של תצוגת המודעות ולתצוגת הווידאו.

ViewController.m 
- (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.
  IMAStreamRequest *request;
  // Switch this variable to NO to make a VOD request.
  BOOL useLiveStream = YES;
  if (useLiveStream) {
    // Live stream request. Replace the asset key with your value.
    request = [[IMALiveStreamRequest alloc] initWithAssetKey:@"c-rArva4ShKVIAkNfy6HUQ"
                                          adDisplayContainer:self.adDisplayContainer
                                                videoDisplay:self.imaVideoDisplay
                                                 userContext:nil];
  } else {
    // VOD request. Replace the content source ID and video ID with your values.
    request = [[IMAVODStreamRequest alloc] initWithContentSourceID:@"2548831"
                                                           videoID:@"tears-of-steel"
                                                adDisplayContainer:self.adDisplayContainer
                                                      videoDisplay:self.imaVideoDisplay
                                                       userContext:nil];
  }
  [self.adsLoader requestStreamWithRequest:request];
}
ViewController.m

הקשבה לאירועי טעינה של שידורים

הכיתה IMAAdsLoader קורא לשיטות IMAAdsLoaderDelegate אם האתחול של בקשת הסטרימינג הצליח או נכשל.

בשיטת הענקת הגישה adsLoadedWithData, מגדירים את IMAStreamManagerDelegate ומאתחלים את מנהל הסטרימינג. בזמן האינטליגנציה, מנהל הסטרימינג מתחיל את ההפעלה.

מתעדים את השגיאה ביומן של שיטת הענקת הגישה 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;
  [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];
}
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

מפעילים את האפליקציה. אם היא פועלת, אפשר לבקש ולנגן שידורים של Google DAI באמצעות IMA SDK. למידע נוסף על תכונות מתקדמות יותר של SDK, אפשר לעיין במדריכים נוספים שמפורטים בסרגל הצד הימני או בדוגמאות ב-GitHub.