إعداد حزمة تطوير البرامج (SDK) لإعلانات الوسائط التفاعلية

اختيار النظام الأساسي: HTML5 Android iOS tvOS

تسهّل حِزم تطوير البرامج (SDK) لإعلانات الوسائط التفاعلية دمج إعلانات الوسائط المتعددة في مواقعك الإلكترونية وتطبيقاتك. يمكن لحِزم تطوير البرامج لإعلانات الوسائط التفاعلية طلب الإعلانات من أي خادم إعلانات متوافق مع VAST وإدارة تشغيل الإعلانات في تطبيقاتك. باستخدام حِزم تطوير البرامج لإعلانات الوسائط التفاعلية من جهة العميل، يمكنك التحكّم في تشغيل فيديوهات المحتوى، بينما تتولّى حزمة تطوير البرامج تشغيل الإعلانات. يتم تشغيل الإعلانات في مشغّل فيديو منفصل يظهر فوق مشغّل فيديو المحتوى في التطبيق.

يوضّح هذا الدليل كيفية دمج "حزمة تطوير البرامج لإعلانات الوسائط التفاعلية" في تطبيق مشغّل فيديو. لعرض نموذج تكامل مكتمل أو اتّباعه، نزِّل BasicExample من GitHub.

نظرة عامة على IMA من جهة العميل

يتضمّن تنفيذ "حزمة تطوير البرامج للإعلانات التفاعلية" من جهة العميل أربعة مكوّنات رئيسية من الحزمة، ويوضّح هذا الدليل كيفية استخدامها:

  • IMAAdDisplayContainer: عنصر حاوٍ يحدّد المكان الذي تعرض فيه IMA عناصر واجهة مستخدم الإعلان وتقيس إمكانية العرض، بما في ذلك العرض النشط وOpen Measurement.
  • ‫ IMAAdsLoader: عنصر يطلب الإعلانات ويتعامل مع الأحداث من ردود طلبات الإعلانات. يجب إنشاء أداة تحميل إعلانات واحدة فقط، ويمكن إعادة استخدامها طوال مدة تشغيل التطبيق.
  • ‫ IMAAdsRequest: كائن يعرّف طلب إعلانات. تحدّد طلبات الإعلانات عنوان URL الخاص بعلامة إعلان VAST، بالإضافة إلى مَعلمات إضافية، مثل أبعاد الإعلان.
  • ‫ IMAAdsManager: كائن يحتوي على الردّ على طلب الإعلانات، ويتحكّم في تشغيل الإعلانات، ويستمع إلى أحداث الإعلانات التي يتم تشغيلها بواسطة حزمة SDK.

المتطلبات الأساسية

قبل البدء، يجب أن يتوفّر لديك ما يلي:

1. إنشاء مشروع Xcode جديد

في Xcode، أنشئ مشروعًا جديدًا لنظام التشغيل iOS باستخدام Objective-C أو Swift. استخدِم BasicExample كاسم للمشروع.

2. إضافة حزمة تطوير البرامج لإعلانات الوسائط التفاعلية إلى مشروع Xcode

لتثبيت "حزمة تطوير البرامج لإعلانات الوسائط التفاعلية"، اختَر طريقة مفضّلة.

يُنصح بتثبيت حزمة تطوير البرامج (SDK) باستخدام Swift Package Manager

تتيح حزمة تطوير البرامج لإعلانات الوسائط التفاعلية Swift Package Manager بدءًا من الإصدار 3.18.4. لاستيراد حزمة Swift، أكمِل الخطوات التالية:

  1. في Xcode، ثبِّت حزمة IMA SDK Swift Package من خلال الانتقال إلى ملف > إضافة موارد الاعتمادية للحزمة... (File > Add Package Dependencies...).

  2. في الطلب، ابحث عن مستودع حزمة تطوير البرامج لنظام التشغيل iOS من "إعلانات الوسائط التفاعلية" على GitHub: swift-package-manager-google-interactive-media-ads-ios.

  3. اختَر إصدار حزمة IMA SDK Swift Package الذي تريد استخدامه. بالنسبة إلى المشاريع الجديدة، ننصحك باستخدام حتى الإصدار الرئيسي التالي.

بعد الانتهاء، يحلّ Xcode التبعيات المرتبطة بحِزمك وينزّلها في الخلفية. لمزيد من التفاصيل حول كيفية إضافة حِزم معتمدة، يُرجى الاطّلاع على مقالة Apple.

تثبيت حزمة SDK باستخدام CocoaPods

‫CocoaPods هو نظام لإدارة التبعيات في مشاريع Xcode، وهو الطريقة المقترَحة لتثبيت "حزمة تطوير البرامج للإعلانات التفاعلية". لمزيد من المعلومات حول تثبيت CocoaPods أو استخدامه، يُرجى الاطّلاع على مستندات CocoaPods. بعد تثبيت CocoaPods، اتّبِع التعليمات التالية لتثبيت حزمة تطوير البرامج لإعلانات الوسائط التفاعلية:

  1. في الدليل نفسه الذي يحتوي على ملف BasicExample.xcodeproj، أنشئ ملفًا نصيًا باسم Podfile وأضِف الإعداد التالي:

    Objective-C

    platform :ios, '15'

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

    Podfile

    Swift

    platform :ios, '15'

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

    Podfile

  2. من الدليل الذي يحتوي على ملف Podfile، شغِّل pod install --repo-update.

  3. تأكَّد من نجاح عملية التثبيت من خلال فتح الملف BasicExample.xcworkspace والتأكّد من أنّه يتضمّن مشروعَين: BasicExample وPods (وهي التبعيات التي ثبّتها CocoaPods).

تنزيل حزمة تطوير البرامج (SDK) وتثبيتها يدويًا

إذا كنت لا تريد استخدام Swift Package Manager، يمكنك تنزيل حزمة تطوير البرامج (SDK) الخاصة بـ IMA وإضافتها يدويًا إلى مشروعك.

3- إنشاء مشغّل فيديو

أولاً، عليك تنفيذ مشغّل فيديو. في البداية، لا يستخدم مشغّل الفيديو هذا حزمة تطوير البرامج (SDK) من IMA ولا يتضمّن أي طريقة لتشغيل الفيديو.

Objective-C

استورِد تبعيات المشغّل:

#import "ViewController.h"

@import AVFoundation;
ViewController.m

اضبط متغيّرات المشغّل:

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

ابدأ مشغّل الفيديو عند تحميل طريقة العرض:

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

Swift

استورِد تبعيات المشغّل:

import AVFoundation
PlayerContainerViewController.swift

اضبط متغيّرات المشغّل:

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)
  }()
PlayerContainerViewController.swift

ابدأ مشغّل الفيديو عند تحميل طريقة العرض:

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()
}
PlayerContainerViewController.swift

4. استيراد "حزمة تطوير البرامج للإعلانات التفاعلية"

لاستيراد "حزمة تطوير البرامج لإعلانات الوسائط التفاعلية"، اتّبِع الخطوات التالية:

Objective-C

  1. استورِد "حزمة تطوير البرامج لإعلانات الوسائط التفاعلية" (IMA SDK):

    @import GoogleInteractiveMediaAds;
    ViewController.m

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

Swift

  1. استورِد "حزمة تطوير البرامج لإعلانات الوسائط التفاعلية" (IMA SDK):

    import GoogleInteractiveMediaAds

    PlayerContainerViewController.swift

  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)
}()
    PlayerContainerViewController.swift

5- تنفيذ أداة تتبُّع رأس التشغيل للمحتوى ومراقب نهاية البث

لعرض "الإعلانات أثناء عرض الفيديو"، يجب أن تتتبّع حزمة تطوير البرامج للإعلانات التفاعلية الموضع الحالي لمحتوى الفيديو. لإجراء ذلك، أنشئ فئة تنفّذ 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];
ViewController.m

أنشئ طريقة 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];
  }
}
ViewController.m

Swift

أنشئ أداة مراقبة انتهاء المحتوى في إعدادات المشغّل:

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

أنشئ طريقة 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()
  }
}
PlayerContainerViewController.swift

6. تهيئة أداة تحميل الإعلانات وإرسال طلب إعلانات

لطلب مجموعة من الإعلانات، عليك إنشاء مثيل IMAAdsLoader. يعالج أداة التحميل هذه عناصر IMAAdsRequest المرتبطة بعنوان URL محدّد لعلامة إعلانية.

كأفضل ممارسة، احتفِظ بنسخة واحدة فقط من IMAAdsLoader طوال دورة حياة تطبيقك. لتقديم طلبات إعلانات إضافية، أنشِئ عنصر IMAAdsRequest جديدًا، ولكن أعِد استخدام IMAAdsLoader نفسه. لمزيد من المعلومات، يُرجى الاطّلاع على الأسئلة الشائعة حول حزمة تطوير البرامج (SDK) من IMA.

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

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)
}
PlayerContainerViewController.swift

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

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()
}
PlayerContainerViewController.swift

8. إعداد مفوّض في "مدير إعلانات Google"

أخيرًا، لإدارة الأحداث وتغييرات الحالة، يحتاج مدير الإعلانات إلى عنصر نائب خاص به. تحتوي 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];
  }
}
ViewController.m

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()
  }
}
PlayerContainerViewController.swift

معالجة الأخطاء

أضِف معالجًا لأخطاء الإعلانات أيضًا. في حال حدوث خطأ، كما في الخطوة السابقة، استأنِف تشغيل المحتوى.

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

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()
}
PlayerContainerViewController.swift

الاستماع إلى أحداث التشغيل والإيقاف المؤقت

يؤدي آخر طريقتَين تفويضيتَين عليك تنفيذهما إلى تشغيل أحداث التشغيل والإيقاف المؤقت في محتوى الفيديو الأساسي عندما تطلبهما حزمة 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];
}
ViewController.m

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()
}
PlayerContainerViewController.swift

هذا كل شيء! أنت الآن تطلب الإعلانات وتعرضها باستخدام حزمة تطوير البرامج للإعلانات التفاعلية. للاطّلاع على مزيد من المعلومات حول ميزات حزمة تطوير البرامج (SDK) الإضافية، يُرجى الرجوع إلى الأدلة الأخرى أو الأمثلة على GitHub.

الخطوات التالية

لزيادة إيرادات الإعلانات إلى أقصى حدّ على نظام التشغيل iOS، عليك طلب إذن "شفافية تتبُّع التطبيقات" لاستخدام معرّف المعلِنين (IDFA).