لمناقشة منتجاتنا وتقديم ملاحظات بشأنها، انضمّ إلى قناة Discord الرسمية في "مدير إعلانات Google" على خادم منتدى Google للإعلان والقياس.

تستخدم Google تكنولوجيا الذكاء الاصطناعي لترجمة المحتوى إلى لغتك المفضّلة، وقد تتضمّن بعض الأخطاء.

الإعداد باستخدام "إدراج الإعلان الديناميكي" (DAI) مع الخدمة الكاملة

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

يتناول هذا الدليل كيفية دمج حزمة تطوير البرامج (SDK) لتقنية IMA DAI في تطبيق مشغّل فيديو. إذا أردت الاطّلاع على نموذج كامل لعملية الدمج أو اتّباعه، يمكنك تنزيل BasicExample من GitHub.

نظرة عامة على IMA DAI

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

‫IMAAdDisplayContainer: هو عنصر حاوية يقع فوق عنصر تشغيل الفيديو ويضم عناصر واجهة المستخدم الخاصة بالإعلان.
‫IMAAdsLoader: هو عنصر يطلب أحداثًا ويتعامل مع الأحداث التي يتم تشغيلها بواسطة عناصر استجابة طلب البث. يجب إنشاء مثيل واحد فقط من أداة تحميل الإعلانات، والذي يمكن إعادة استخدامه طوال مدة تشغيل التطبيق.
‫IMAStreamRequest: إما IMAVODStreamRequest أو IMALiveStreamRequest. عنصر يحدّد طلب بث يمكن أن تكون طلبات البث لفيديوهات عند الطلب أو أحداث بث مباشر. تحدّد طلبات البث المباشر مفتاح مادة عرض، بينما تحدّد طلبات الفيديو عند الطلب معرّف "نظام إدارة المحتوى" ومعرّف الفيديو. يمكن أن يتضمّن كلا نوعَي الطلبات اختياريًا مفتاح واجهة برمجة التطبيقات اللازم للوصول إلى أحداث بث معيّنة، ورمز شبكة "إدارة إعلانات Google" لكي تتعامل حزمة IMA SDK مع معرّفات الإعلانات على النحو المحدّد في إعدادات "إدارة إعلانات Google".
‫IMAStreamManager: هو عنصر يعالج أحداث البث والتفاعلات الخاصة بميزة "إدراج إعلان ديناميكي" مع الخلفية الخاصة بهذه الميزة. يتولّى مدير البث أيضًا تتبُّع إشعارات الاتصال وإعادة توجيه أحداث البث والإعلانات إلى الناشر.

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

قبل البدء، تحتاج إلى ما يلي:

الإصدار 13 من Xcode أو إصدار أحدث
طريقة تثبيت حزمة تطوير البرامج للإعلانات التفاعلية (IMA SDK):
- Swift Package Manager (الخيار المفضّل)
- نسخة قابلة للتنزيل من حزمة تطوير البرامج للإعلانات التفاعلية (IMA SDK) لنظام التشغيل iOS

ستحتاج أيضًا إلى المَعلمات لطلب البث من حزمة تطوير البرامج للإعلانات التفاعلية (IMA SDK). للاطّلاع على أمثلة على مَعلمات الطلب، يُرجى مراجعة نماذج أحداث البث.

مَعلمات البث المباشر
مفتاح مادة العرض	مفتاح مادة العرض الذي يحدّد البث المباشر في "مدير إعلانات Google" مثال: `c-rArva4ShKVIAkNfy6HUQ`
مَعلمات بث الفيديو عند الطلب
معرّف مصدر المحتوى	هو رقم تعريف مصدر المحتوى من "إدارة إعلانات Google". مثال: `2548831`
معرّف الفيديو	معرّف الفيديو من "إدارة إعلانات Google" مثال: `tears-of-steel`
المَعلمات الشائعة (للفيديوهات عند الطلب وأحداث البث المباشر)
رمز الشبكة	رمز شبكة "إدارة إعلانات Google" مثال: `21775744923`

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

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

إضافة حزمة تطوير البرامج (SDK) لتقنية IMA DAI إلى مشروع Xcode

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

الإجراء المقترَح: تثبيت حزمة تطوير البرامج (SDK) باستخدام Swift Package Manager

تتوافق حزمة تطوير البرامج لإعلانات الوسائط التفاعلية مع Swift Package Manager بدءًا من الإصدار 3.18.4. اتّبِع هذه الخطوات لاستيراد حزمة Swift.

في Xcode، ثبِّت حزمة Swift Package الخاصة بحزمة تطوير البرامج (SDK) لتقنية IMA DAI: انتقِل إلى File > Add Packages.
في الطلب الذي يظهر، ابحث عن مستودع GitHub لحزمة Swift Package الخاصة بـ IMA DAI SDK:
```
https://github.com/googleads/swift-package-manager-google-interactive-media-ads-ios
```
اختَر إصدار حزمة Swift Package من حزمة تطوير البرامج (SDK) لتقنية IMA DAI الذي تريد استخدامه. بالنسبة إلى المشاريع الجديدة، استخدِم Up to Next Major Version.

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

تنزيل حزمة SDK وتثبيتها يدويًا

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

عرض التعليمات

من صفحة تنزيل حزمة تطوير البرامج (SDK) لإعلانات الوسائط التفاعلية (IMA) لنظام التشغيل iOS، نزِّل أحدث إصدار من حزمة تطوير البرامج (SDK) لإدراج الإعلان الديناميكي (DAI) لإعلانات الوسائط التفاعلية (IMA) واستخرِجه.
افتح BasicExample.xcodeproj.
في اللوحة اليمنى، انقر على اسم المشروع.
في اللوحة الوسطى، انقر على مراحل الإنشاء (Build Phases).
وسِّع قسم ربط الملفات الثنائية بالمكتبات (Link Binary With Libraries).
في أسفل قائمة المكتبات، انقر على رمز الإضافة [+].
انقر على إضافة غير ذلك.
في الدليل الذي استخرجت منه حزمة تطوير البرامج (SDK) التي تم تنزيلها، اختَر GoogleInteractiveMediaAds.framework وانقر على فتح.
في أسفل قائمة المكتبات، انقر على رمز الإضافة [+] مرة أخرى.
في عمود الحالة، تأكَّد من أنّ GoogleInteractiveMediaAds.framework يعرض Required.
أدرِج علامة الرابط -ObjC في إعدادات الإصدار. لمزيد من المعلومات، يُرجى الاطّلاع على Apple QA1490.

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

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

Objective-C

#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

Swift

// Copyright 2024 Google LLC. All rights reserved.
//
//
// Licensed under the Apache License, Version 2.0 (the "License"); you may not use this
// file except in compliance with the License. You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software distributed under
// the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF
// ANY KIND, either express or implied. See the License for the specific language governing
// permissions and limitations under the License.

import AVFoundation
import UIKit

class ViewController: UIViewController {

  /// Content URL.
  static let backupStreamURLString =
    "http://devimages.apple.com/iphone/samples/bipbop/bipbopall.m3u8"

  /// Play button.
  @IBOutlet private weak var playButton: UIButton!

  @IBOutlet private weak var videoView: UIView!
  /// Video player.
  private var videoPlayer: AVPlayer?

  override func viewDidLoad() {
    super.viewDidLoad()

    playButton.layer.zPosition = CGFloat(MAXFLOAT)

    // Load AVPlayer with path to our content.
    // note: this unwrap is safe because the URL is a constant string.
    let contentURL = URL(string: ViewController.backupStreamURLString)!
    videoPlayer = AVPlayer(url: contentURL)

    // Create a player layer for the player.
    let playerLayer = AVPlayerLayer(player: videoPlayer)

    // Size, position, and display the AVPlayer.
    playerLayer.frame = videoView.layer.bounds
    videoView.layer.addSublayer(playerLayer)
  }

  @IBAction func onPlayButtonTouch(_ sender: Any) {
    videoPlayer?.play()
    playButton.isHidden = true
  }
}
ViewController.swift

إعداد أداة تحميل الإعلانات

استورِد حزمة تطوير البرامج للإعلانات التفاعلية (IMA SDK) إلى وحدة التحكّم في العرض واعتمد بروتوكولَي IMAAdsLoaderDelegate وIMAStreamManagerDelegate للتعامل مع أحداث أداة تحميل الإعلانات ومدير البث.

أضِف هذه السمات الخاصة لتخزين مكوّنات حزمة تطوير البرامج للإعلانات التفاعلية (IMA SDK) الرئيسية:

IMAAdsLoader
- يدير طلبات البث طوال فترة استخدام تطبيقك.
IMAAdDisplayContainer
- تتولّى هذه الفئة إدراج عناصر واجهة مستخدم الإعلانات وإدارتها.
IMAAVPlayerVideoDisplay - يتيح التواصل بين حزمة تطوير البرامج للإعلانات التفاعلية (IMA SDK) ومشغّل الوسائط ويتعامل مع البيانات الوصفية المحدّدة زمنيًا.
IMAStreamManager: تُدير تشغيل البث وتُطلق الأحداث ذات الصلة بالإعلانات.

يجب إعداد أداة تحميل الإعلانات وحاوية عرض الإعلانات وعرض الفيديو بعد تحميل العرض.

Objective-C

@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

Swift

import GoogleInteractiveMediaAds
// ...

class ViewController: UIViewController, IMAAdsLoaderDelegate, IMAStreamManagerDelegate {
  // ...

  /// The entry point for the IMA DAI SDK to make DAI stream requests.
  private var adsLoader: IMAAdsLoader?
  /// The container where the SDK renders each ad's user interface elements and companion slots.
  private var adDisplayContainer: IMAAdDisplayContainer?
  /// The reference of your video player for the IMA DAI SDK to monitor playback and handle timed
  /// metadata.
  private var imaVideoDisplay: IMAAVPlayerVideoDisplay!
  /// References the stream manager from the IMA DAI SDK after successfully loading the DAI stream.
  private var streamManager: IMAStreamManager?

  // ...

  override func viewDidLoad() {
    super.viewDidLoad()

    // ...

    adsLoader = IMAAdsLoader(settings: nil)
    adsLoader?.delegate = self

    // Create an ad display container for rendering ad UI elements and the companion ad.
    adDisplayContainer = IMAAdDisplayContainer(
      adContainer: videoView,
      viewController: self,
      companionSlots: nil)

    // Create an IMAAVPlayerVideoDisplay to give the SDK access to your video player.
    imaVideoDisplay = IMAAVPlayerVideoDisplay(avPlayer: videoPlayer)
  }ViewController.swift

تقديم طلب بث

عندما يضغط المستخدم على زر التشغيل، أرسِل طلب بث جديد. استخدِم الفئة IMALiveStreamRequest لأحداث البث المباشر. بالنسبة إلى أحداث البث المباشر للفيديو عند الطلب، استخدِم الفئة IMAVODStreamRequest.

يتطلّب طلب البث مَعلمات البث، بالإضافة إلى مرجع إلى حاوية عرض الإعلانات وعرض الفيديو.

Objective-C

- (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.
  if (kStreamType == StreamTypeLive) {
    // Live stream request. Replace the asset key with your value.
    IMALiveStreamRequest *request =
        [[IMALiveStreamRequest alloc] initWithAssetKey:kLiveStreamAssetKey
                                           networkCode:kNetworkCode
                                    adDisplayContainer:self.adDisplayContainer
                                          videoDisplay:self.imaVideoDisplay
                                           userContext:nil];
    request.useHLSInterstitials = YES;
    [self.adsLoader requestStreamWithRequest:request];
  } else {
    // VOD request. Replace the content source ID and video ID with your values.
    IMAVODStreamRequest *request =
        [[IMAVODStreamRequest alloc] initWithContentSourceID:kVODContentSourceID
                                                     videoID:kVODVideoID
                                                 networkCode:kNetworkCode
                                          adDisplayContainer:self.adDisplayContainer
                                                videoDisplay:self.imaVideoDisplay
                                                 userContext:nil];
    [self.adsLoader requestStreamWithRequest:request];
  }
}ViewController.m

Swift

@IBAction func onPlayButtonTouch(_ sender: Any) {
  requestStream()
  playButton.isHidden = true
}

func requestStream() {
  // Create a stream request. Use one of "Livestream request" or "VOD request".
  if ViewController.requestType == StreamType.live {
    // Livestream request.
    let request = IMALiveStreamRequest(
      assetKey: ViewController.assetKey,
      networkCode: ViewController.networkCode,
      adDisplayContainer: adDisplayContainer!,
      videoDisplay: imaVideoDisplay,
      userContext: nil)
    request.useHLSInterstitials = true
    adsLoader?.requestStream(with: request)
  } else {
    // VOD stream request.
    let request = IMAVODStreamRequest(
      contentSourceID: ViewController.contentSourceID,
      videoID: ViewController.videoID,
      networkCode: ViewController.networkCode,
      adDisplayContainer: adDisplayContainer!,
      videoDisplay: imaVideoDisplay,
      userContext: nil)
    adsLoader?.requestStream(with: request)
  }
}ViewController.swift

الاستماع إلى أحداث تحميل البث

تستدعي الفئة IMAAdsLoader الطرق IMAAdsLoaderDelegate عند نجاح عملية الإعداد أو تعذُّر طلب البث.

في طريقة التفويض adsLoadedWithData، اضبط IMAStreamManagerDelegate. ابدأ تشغيل مدير البث. عند الإعداد، يبدأ مدير البث التشغيل.

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

Objective-C

- (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

Swift

func adsLoader(_ loader: IMAAdsLoader, adsLoadedWith adsLoadedData: IMAAdsLoadedData) {
  print("DAI stream loaded. Stream session ID: \(adsLoadedData.streamManager!.streamId!)")
  streamManager = adsLoadedData.streamManager!
  streamManager!.delegate = self
  streamManager!.initialize(with: nil)
}

func adsLoader(_ loader: IMAAdsLoader, failedWith adErrorData: IMAAdLoadingErrorData) {
  print("Error loading DAI stream. Error message: \(adErrorData.adError.message!)")
  // Play the backup stream.
  videoPlayer.play()
}ViewController.swift

الاستماع إلى أحداث الإعلانات

يستدعي IMAStreamManager طُرق IMAStreamManagerDelegate لتمرير أحداث البث والأخطاء إلى تطبيقك.

في هذا المثال، سجِّل أحداث الإعلانات الأساسية في وحدة التحكّم:

Objective-C

- (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

Swift

func streamManager(_ streamManager: IMAStreamManager, didReceive event: IMAAdEvent) {
  print("Ad event \(event.typeString).")
  switch event.type {
  case IMAAdEventType.STARTED:
    // Log extended data.
    if let ad = event.ad {
      let extendedAdPodInfo = String(
        format: "Showing ad %zd/%zd, bumper: %@, title: %@, "
          + "description: %@, contentType:%@, pod index: %zd, "
          + "time offset: %lf, max duration: %lf.",
        ad.adPodInfo.adPosition,
        ad.adPodInfo.totalAds,
        ad.adPodInfo.isBumper ? "YES" : "NO",
        ad.adTitle,
        ad.adDescription,
        ad.contentType,
        ad.adPodInfo.podIndex,
        ad.adPodInfo.timeOffset,
        ad.adPodInfo.maxDuration)

      print("\(extendedAdPodInfo)")
    }
    break
  case IMAAdEventType.AD_BREAK_STARTED:
    print("Ad break started.")
    break
  case IMAAdEventType.AD_BREAK_ENDED:
    print("Ad break ended.")
    break
  case IMAAdEventType.AD_PERIOD_STARTED:
    print("Ad period started.")
    break
  case IMAAdEventType.AD_PERIOD_ENDED:
    print("Ad period ended.")
    break
  default:
    break
  }
}

func streamManager(_ streamManager: IMAStreamManager, didReceive error: IMAAdError) {
  print("StreamManager error with type: \(error.type)")
  print("code: \(error.code)")
  print("message: \(error.message ?? "Unknown Error")")
}ViewController.swift

شغِّل تطبيقك. إذا نجحت العملية، اطلب بثّ "إدراج الإعلان الديناميكي" من Google وشغِّله باستخدام حزمة تطوير البرامج للإعلانات التفاعلية (IMA SDK). لمزيد من المعلومات حول ميزات حزمة تطوير البرامج (SDK) الأكثر تقدّمًا، يُرجى الاطّلاع على الأدلة الأخرى المدرَجة في الشريط الجانبي الأيمن أو النماذج على GitHub.

الإعداد باستخدام "إدراج الإعلان الديناميكي" (DAI) مع الخدمة الكاملة تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

نظرة عامة على IMA DAI

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

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

إضافة حزمة تطوير البرامج (SDK) لتقنية IMA DAI إلى مشروع Xcode

الإجراء المقترَح: تثبيت حزمة تطوير البرامج (SDK) باستخدام Swift Package Manager

تنزيل حزمة SDK وتثبيتها يدويًا

عرض التعليمات

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

Objective-C

Swift

إعداد أداة تحميل الإعلانات

Objective-C

Swift

تقديم طلب بث

Objective-C

Swift

الاستماع إلى أحداث تحميل البث

Objective-C

Swift

الاستماع إلى أحداث الإعلانات

Objective-C

Swift

الإعداد باستخدام "إدراج الإعلان الديناميكي" (DAI) مع الخدمة الكاملة