הגדרת IMA SDK

בחירת פלטפורמה: HTML5 Android iOS tvOS

ערכות IMA SDK מאפשרות לשלב בקלות מודעות מולטימדיה באתרים ובאפליקציות. ‫IMA SDKs יכולים לשלוח בקשות למודעות מכל שרת מודעות שתואם ל-VAST ולנהל את ההפעלה של המודעות באפליקציות. עם IMA SDK בצד הלקוח, אתם שומרים על שליטה בהפעלת תוכן הווידאו, בזמן שה-SDK מטפל בהפעלת המודעה. המודעות מוצגות בנגן וידאו נפרד שממוקם מעל נגן הווידאו של התוכן באפליקציה.

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

סקירה כללית על IMA בצד הלקוח

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

  • IMAAdDisplayContainer: אובייקט מאגר שמציין איפה IMA מעבד רכיבי ממשק משתמש של מודעות ומודד את הניראות, כולל Active View ו-Open Measurement.
  • IMAAdsLoader: אובייקט שמבקש מודעות ומטפל באירועים מתגובות לבקשות מודעות. צריך ליצור רק מופע אחד של ads loader, שאפשר לעשות בו שימוש חוזר במהלך הפעילות של האפליקציה.
  • IMAAdsRequest: אובייקט שמגדיר בקשה להצגת מודעות. בבקשות להצגת מודעות מצוינת כתובת ה-URL של תג המודעה בפורמט VAST, וגם פרמטרים נוספים, כמו מידות המודעה.
  • IMAAdsManager: אובייקט שמכיל את התגובה לבקשת המודעות, שולט בהפעלת המודעות ומאזין לאירועי מודעות שמופעלים על ידי ה-SDK.

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

לפני שמתחילים, צריך:

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

ב-Xcode, יוצרים פרויקט iOS חדש באמצעות Objective-C או Swift. משתמשים ב-BasicExample כשם הפרויקט.

2. הוספת IMA SDK לפרויקט Xcode

כדי להתקין את IMA SDK, בוחרים את השיטה המועדפת.

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

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

  1. ב-Xcode, מתקינים את חבילת IMA SDK Swift על ידי מעבר אל File > Add Package Dependencies...‎ (קובץ > הוספת תלות בחבילה...).

  2. בהנחיה, מחפשים את מאגר IMA iOS SDK Swift Package GitHub: swift-package-manager-google-interactive-media-ads-ios.

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

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

התקנת ה-SDK באמצעות CocoaPods

‫CocoaPods הוא כלי לניהול תלות בפרויקטים של Xcode, והוא השיטה המומלצת להתקנת IMA SDK. מידע נוסף על התקנה או שימוש ב-CocoaPods זמין במסמכי העזרה של CocoaPods. אחרי שמתקינים את CocoaPods, פועלים לפי ההוראות הבאות כדי להתקין את IMA SDK:

  1. באותה תיקייה שבה נמצא הקובץ BasicExample.xcodeproj, יוצרים קובץ טקסט בשם Podfile ומוסיפים את ההגדרות הבאות:

    Objective-C

    platform :ios, '15'
    
    target "BasicExample" do
      pod 'GoogleAds-IMA-iOS-SDK', '~> 3.28.10'
    end
    
    

    Swift

    platform :ios, '15'
    
    target "BasicExample" do
      pod 'GoogleAds-IMA-iOS-SDK', '~> 3.28.10'
    end
    
    
  2. בספרייה שמכילה את קובץ Podfile, מריצים את הפקודה pod install --repo-update.

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

הורדה והתקנה של ה-SDK באופן ידני

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

3. יצירת נגן וידאו

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

Objective-C

מייבאים את יחסי התלות של הנגן:

#import "ViewController.h"

@import AVFoundation;

מגדירים את משתני הנגן:

@interface ViewController () <IMAAdsLoaderDelegate, IMAAdsManagerDelegate>

/// Content video player.
@property(nonatomic, strong) AVPlayer *contentPlayer;

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

/// UIView in which we will render our AVPlayer for content.
@property(nonatomic, weak) IBOutlet UIView *videoView;

הפעלת נגן הווידאו כשהתצוגה נטענת:

@implementation ViewController

// The content URL to play.
NSString *const kTestAppContentUrl_MP4 =
    @"https://storage.googleapis.com/gvabox/media/samples/stock.mp4";

// Ad tag
NSString *const kTestAppAdTagUrl = @"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=";

- (void)viewDidLoad {
  [super viewDidLoad];

  self.playButton.layer.zPosition = MAXFLOAT;

  [self setupAdsLoader];
  [self setUpContentPlayer];
}

#pragma mark Content Player Setup

- (void)setUpContentPlayer {
  // Load AVPlayer with path to our content.
  NSURL *contentURL = [NSURL URLWithString:kTestAppContentUrl_MP4];
  self.contentPlayer = [AVPlayer playerWithURL:contentURL];

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

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

  // Set up our content playhead and contentComplete callback.
  self.contentPlayhead = [[IMAAVPlayerContentPlayhead alloc] initWithAVPlayer:self.contentPlayer];
  [[NSNotificationCenter defaultCenter] addObserver:self
                                           selector:@selector(contentDidFinishPlaying:)
                                               name:AVPlayerItemDidPlayToEndTimeNotification
                                             object:self.contentPlayer.currentItem];
}

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

Swift

מייבאים את יחסי התלות של הנגן:

import AVFoundation

מגדירים את משתני הנגן:

class PlayerContainerViewController: UIViewController, IMAAdsLoaderDelegate, IMAAdsManagerDelegate {
  static let contentURL = URL(
    string: "https://storage.googleapis.com/gvabox/media/samples/stock.mp4")!

  private var contentPlayer = AVPlayer(url: PlayerContainerViewController.contentURL)

  private lazy var playerLayer: AVPlayerLayer = {
    AVPlayerLayer(player: contentPlayer)
  }()

הפעלת נגן הווידאו כשהתצוגה נטענת:

private lazy var videoView: UIView = {
  let videoView = UIView()
  videoView.translatesAutoresizingMaskIntoConstraints = false
  view.addSubview(videoView)

  NSLayoutConstraint.activate([
    videoView.bottomAnchor.constraint(
      equalTo: view.safeAreaLayoutGuide.bottomAnchor),
    videoView.topAnchor.constraint(equalTo: view.safeAreaLayoutGuide.topAnchor),
    videoView.trailingAnchor.constraint(equalTo: view.safeAreaLayoutGuide.trailingAnchor),
    videoView.leadingAnchor.constraint(equalTo: view.safeAreaLayoutGuide.leadingAnchor),
  ])
  return videoView
}()

// MARK: - View controller lifecycle methods

override func viewDidLoad() {
  super.viewDidLoad()

  videoView.layer.addSublayer(playerLayer)
  adsLoader.delegate = self

  NotificationCenter.default.addObserver(
    self,
    selector: #selector(contentDidFinishPlaying(_:)),
    name: .AVPlayerItemDidPlayToEndTime,
    object: contentPlayer.currentItem)
}

override func viewDidAppear(_ animated: Bool) {
  super.viewDidAppear(animated)
  playerLayer.frame = videoView.layer.bounds
}

override func viewWillTransition(
  to size: CGSize, with coordinator: UIViewControllerTransitionCoordinator
) {
  coordinator.animate { _ in
    // do nothing
  } completion: { _ in
    self.playerLayer.frame = self.videoView.layer.bounds
  }
}

// MARK: - Public methods

func playButtonPressed() {
  requestAds()
}

4. ייבוא של IMA SDK

כדי לייבא את IMA SDK:

Objective-C

  1. מייבאים את IMA SDK:

    @import GoogleInteractiveMediaAds;
    
  2. יוצרים משתנים עבור המחלקות IMAAdsLoader, IMAAVPlayerContentPlayhead ו-IMAAdsManager שמשמשות באפליקציה:

    // SDK
    /// Entry point for the SDK. Used to make ad requests.
    @property(nonatomic, strong) IMAAdsLoader *adsLoader;
    
    /// Playhead used by the SDK to track content video progress and insert mid-rolls.
    @property(nonatomic, strong) IMAAVPlayerContentPlayhead *contentPlayhead;
    
    /// Main point of interaction with the SDK. Created by the SDK as the result of an ad request.
    @property(nonatomic, strong) IMAAdsManager *adsManager;
    

Swift

  1. מייבאים את IMA SDK:

    import GoogleInteractiveMediaAds
    
    
  2. יוצרים משתנים עבור המחלקות IMAAdsLoader, IMAAVPlayerContentPlayhead ו-IMAAdsManager שמשמשות באפליקציה:

    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="
    
    private let adsLoader = IMAAdsLoader()
    private var adsManager: IMAAdsManager?
    
    private lazy var contentPlayhead: IMAAVPlayerContentPlayhead = {
      IMAAVPlayerContentPlayhead(avPlayer: contentPlayer)
    }()
    

5. הטמעה של מעקב אחר מיקום ההפעלה של התוכן ושל כלי מעקב אחר סיום הסטרימינג

כדי להציג מודעות באמצע הסרטון (mid-roll), ערכת IMA SDK צריכה לעקוב אחרי המיקום הנוכחי של תוכן הווידאו. כדי לעשות זאת, יוצרים מחלקה שמטמיעה את IMAContentPlayhead. אם אתם משתמשים ב-AVPlayer, כמו שמוצג בדוגמה הזו, ה-SDK מספק את המחלקה IMAAVPlayerContentPlayhead שמבצעת את הפעולה הזו בשבילכם. אם אתם לא משתמשים ב-AVPlayer, אתם צריכים להטמיע את IMAContentPlayhead בכיתה משלכם.

צריך גם להודיע ל-SDK מתי התוכן סיים את ההפעלה כדי שיוכל להציג מודעות אחרי הפעלת התוכן. כדי לעשות את זה, מפעילים את השיטה contentComplete ב-IMAAdsLoader באמצעות AVPlayerItemDidPlayToEndTimeNotification.

Objective-C

יוצרים את מופע IMAAVPlayerContentPlayhead בהגדרת הנגן:

// Set up our content playhead and contentComplete callback.
self.contentPlayhead = [[IMAAVPlayerContentPlayhead alloc] initWithAVPlayer:self.contentPlayer];
[[NSNotificationCenter defaultCenter] addObserver:self
                                         selector:@selector(contentDidFinishPlaying:)
                                             name:AVPlayerItemDidPlayToEndTimeNotification
                                           object:self.contentPlayer.currentItem];

יוצרים את השיטה contentDidFinishPlaying() כדי להתקשר אל IMAAdsLoader.contentComplete() כשהתוכן מסיים את ההפעלה:

- (void)contentDidFinishPlaying:(NSNotification *)notification {
  // Make sure we don't call contentComplete as a result of an ad completing.
  if (notification.object == self.contentPlayer.currentItem) {
    [self.adsLoader contentComplete];
  }
}

Swift

יוצרים את האובייקט content ended observer בהגדרת הנגן:

NotificationCenter.default.addObserver(
  self,
  selector: #selector(contentDidFinishPlaying(_:)),
  name: .AVPlayerItemDidPlayToEndTime,
  object: contentPlayer.currentItem)

יוצרים את השיטה contentDidFinishPlaying() כדי להתקשר אל IMAAdsLoader.contentComplete() כשהתוכן מסיים את ההפעלה:

@objc func contentDidFinishPlaying(_ notification: Notification) {
  // Make sure we don't call contentComplete as a result of an ad completing.
  if notification.object as? AVPlayerItem == contentPlayer.currentItem {
    adsLoader.contentComplete()
  }
}

6. מאתחלים את הכלי לטעינת מודעות ושולחים בקשה להצגת מודעות

כדי לבקש קבוצה של מודעות, צריך ליצור מופע של IMAAdsLoader. הטוען הזה מעבד אובייקטים של IMAAdsRequest שמשויכים לכתובת URL ספציפית של תג פרסום.

מומלץ לשמור רק מופע אחד של IMAAdsLoader לאורך כל מחזור החיים של האפליקציה. כדי לשלוח בקשות נוספות להצגת מודעות, צריך ליצור אובייקט IMAAdsRequest חדש, אבל להשתמש מחדש באותו IMAAdsLoader. מידע נוסף זמין בשאלות הנפוצות בנושא IMA SDK.

Objective-C

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

- (void)requestAds {
  // Create an ad display container for ad rendering.
  IMAAdDisplayContainer *adDisplayContainer =
      [[IMAAdDisplayContainer alloc] initWithAdContainer:self.videoView
                                          viewController:self
                                          companionSlots:nil];
  // Create an ad request with our ad tag, display container, and optional user context.
  IMAAdsRequest *request = [[IMAAdsRequest alloc] initWithAdTagUrl:kTestAppAdTagUrl
                                                adDisplayContainer:adDisplayContainer
                                                   contentPlayhead:self.contentPlayhead
                                                       userContext:nil];
  [self.adsLoader requestAdsWithRequest:request];
}

Swift

private func requestAds() {
  // Create ad display container for ad rendering.
  let adDisplayContainer = IMAAdDisplayContainer(
    adContainer: videoView, viewController: self, companionSlots: nil)
  // Create an ad request with our ad tag, display container, and optional user context.
  let request = IMAAdsRequest(
    adTagUrl: PlayerContainerViewController.adTagURLString,
    adDisplayContainer: adDisplayContainer,
    contentPlayhead: contentPlayhead,
    userContext: nil)

  adsLoader.requestAds(with: request)
}

7. הגדרת נציג לטעינת מודעות

באירוע טעינה מוצלח, האובייקט IMAAdsLoader קורא לשיטה adsLoadedWithData של הנציג שהוקצה לו, ומעביר לו מופע של IMAAdsManager. לאחר מכן תוכלו להפעיל את כלי ניהול המודעות, שיטען את המודעות הבודדות, כפי שהוגדר בתגובה לכתובת ה-URL של תג המודעה.

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

Objective-C

- (void)adsLoader:(IMAAdsLoader *)loader adsLoadedWithData:(IMAAdsLoadedData *)adsLoadedData {
  // Grab the instance of the IMAAdsManager and set ourselves as the delegate.
  self.adsManager = adsLoadedData.adsManager;
  self.adsManager.delegate = self;
  // Create ads rendering settings to tell the SDK to use the in-app browser.
  IMAAdsRenderingSettings *adsRenderingSettings = [[IMAAdsRenderingSettings alloc] init];
  adsRenderingSettings.linkOpenerPresentingController = self;
  // Initialize the ads manager.
  [self.adsManager initializeWithAdsRenderingSettings:adsRenderingSettings];
}

- (void)adsLoader:(IMAAdsLoader *)loader failedWithErrorData:(IMAAdLoadingErrorData *)adErrorData {
  // Something went wrong loading ads. Log the error and play the content.
  NSLog(@"Error loading ads: %@", adErrorData.adError.message);
  [self.contentPlayer play];
}

Swift

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

  // Create ads rendering settings and tell the SDK to use the in-app browser.
  let adsRenderingSettings = IMAAdsRenderingSettings()
  adsRenderingSettings.linkOpenerPresentingController = self

  // Initialize the ads manager.
  adsManager?.initialize(with: adsRenderingSettings)
}

func adsLoader(_ loader: IMAAdsLoader, failedWith adErrorData: IMAAdLoadingErrorData) {
  if let message = adErrorData.adError.message {
    print("Error loading ads: \(message)")
  }
  contentPlayer.play()
}

8. הגדרת הרשאת גישה לחשבון ניהול המודעות

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

להפעלה

כדי להתחיל בהפעלה של תוכן ומודעות, צריך להגדיר את המערכת לזיהוי של האירוע LOADED. פרטים נוספים זמינים במאמר didReceiveAdEvent.

Objective-C

- (void)adsManager:(IMAAdsManager *)adsManager didReceiveAdEvent:(IMAAdEvent *)event {
  // When the SDK notified us that ads have been loaded, play them.
  if (event.type == kIMAAdEvent_LOADED) {
    [adsManager start];
  }
}

Swift

func adsManager(_ adsManager: IMAAdsManager, didReceive event: IMAAdEvent) {
  // When the SDK notifies us the ads have been loaded, play them.
  if event.type == IMAAdEventType.LOADED {
    adsManager.start()
  }
}

טיפול בשגיאות

כדאי להוסיף גם handler לשגיאות שקשורות למודעות. אם מתרחשת שגיאה, כמו בשלב הקודם, צריך להמשיך בהפעלת התוכן.

Objective-C

- (void)adsManager:(IMAAdsManager *)adsManager didReceiveAdError:(IMAAdError *)error {
  // Something went wrong with the ads manager after ads were loaded. Log the error and play the
  // content.
  NSLog(@"AdsManager error: %@", error.message);
  [self.contentPlayer play];
}

Swift

func adsManager(_ adsManager: IMAAdsManager, didReceive error: IMAAdError) {
  // Something went wrong with the ads manager after ads were loaded.
  // Log the error and play the content.
  if let message = error.message {
    print("AdsManager error: \(message)")
  }
  contentPlayer.play()
}

האזנה לאירועי הפעלה והשהיה

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

Objective-C

- (void)adsManagerDidRequestContentPause:(IMAAdsManager *)adsManager {
  // The SDK is going to play ads, so pause the content.
  [self.contentPlayer pause];
}

- (void)adsManagerDidRequestContentResume:(IMAAdsManager *)adsManager {
  // The SDK is done playing ads (at least for now), so resume the content.
  [self.contentPlayer play];
}

Swift

func adsManagerDidRequestContentPause(_ adsManager: IMAAdsManager) {
  // The SDK is going to play ads, so pause the content.
  contentPlayer.pause()
}

func adsManagerDidRequestContentResume(_ adsManager: IMAAdsManager) {
  // The SDK is done playing ads (at least for now), so resume the content.
  contentPlayer.play()
}

זהו! מעכשיו אתם שולחים בקשות להצגת מודעות ומציגים אותן באמצעות IMA SDK. כדי לקבל מידע על תכונות נוספות של ה-SDK, אפשר לעיין במדריכים האחרים או בדוגמאות ב-GitHub.

השלבים הבאים

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