البدء

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

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

نظرة عامة على عرض الإعلانات الديناميكية على شبكة البحث

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

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

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

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

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

في Xcode، أنشئ مشروعًا جديدًا على iOS باستخدام Purpose-C. استخدِم أساسي مثال كاسم للمشروع.

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

تثبيت حزمة تطوير البرامج (SDK) باستخدام CocoaPods (الخيار المفضّل)

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

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

    source 'https://github.com/CocoaPods/Specs.git'
platform :ios, '10'
target "BasicExample" do
  pod 'GoogleAds-IMA-iOS-SDK', '~> 3.11.4'
end

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

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

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

إذا كنت لا تريد استخدام CocoaPods، يمكنك تنزيل حزمة تطوير البرامج لإعلانات الوسائط التفاعلية وإضافتها يدويًا إلى مشروعك.

3. إنشاء مشغّل فيديو بسيط

أولاً، عليك استخدام مشغّل فيديو أساسي. في البداية، لا يستخدم هذا المشغّل حزمة تطوير البرامج لإعلانات الوسائط التفاعلية ولا يحتوي على أي طريقة لبدء التشغيل.

ViewController.m

#import "ViewController.h"

#import <AVKit/AVKit.h>

@interface ViewController ()
@property(nonatomic) AVPlayerViewController *playerViewController;
@end

@implementation ViewController

- (void)viewDidLoad {
  [super viewDidLoad];
  self.view.backgroundColor = [UIColor blackColor];

  // Create a stream video player.
  AVPlayer *player = [[AVPlayer alloc] init];
  self.playerViewController = [[AVPlayerViewController alloc] init];
  self.playerViewController.player = player;

  // Attach the video player to the view hierarchy.
  [self addChildViewController:self.playerViewController];
  self.playerViewController.view.frame = self.view.bounds;
  [self.view addSubview:self.playerViewController.view];
  [self.playerViewController didMoveToParentViewController:self];
}

@end

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

بعد إضافة حزمة تطوير البرامج لإعلانات الوسائط التفاعلية إلى مشروعك، استورِد حزمة تطوير البرامج وأضِف الرموز البديلة للنقاط الأساسية للتفاعل مع إعلانات الوسائط التفاعلية.

ViewController.m

#import "ViewController.h"

#import <AVKit/AVKit.h>
#import <GoogleInteractiveMediaAds/GoogleInteractiveMediaAds.h>

@interface ViewController ()
@property(nonatomic) IMAAdsLoader *adsLoader;
@property(nonatomic) UIView *adContainerView;
@property(nonatomic) IMAStreamManager *streamManager;
@property(nonatomic) AVPlayerViewController *playerViewController;
@end

@implementation ViewController

- (void)viewDidLoad {
  [super viewDidLoad];
  self.view.backgroundColor = [UIColor blackColor];

  [self setupAdsLoader];

  // Create a stream video player.
  AVPlayer *player = [[AVPlayer alloc] init];
  self.playerViewController = [[AVPlayerViewController alloc] init];
  self.playerViewController.player = player;

  // Attach the video player to the view hierarchy.
  [self addChildViewController:self.playerViewController];
  self.playerViewController.view.frame = self.view.bounds;
  [self.view addSubview:self.playerViewController.view];
  [self.playerViewController didMoveToParentViewController:self];

  [self attachAdContainer];
}

- (void)viewDidAppear:(BOOL)animated {
  [super viewDidAppear:animated];
  [self requestStream];
}

- (void)setupAdsLoader {}

- (void)attachAdContainer {}

- (void)requestStream {}

@end

5. تنفيذ أداة IMAAdsLoader

بعد ذلك، أنشِئ مثيلًا لـ IMAAdsLoader وأرفِق عرض حاوية الإعلان في التسلسل الهرمي للملف الشخصي.

ViewController.m

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

- (void)attachAdContainer {
  self.adContainerView = [[UIView alloc] init];
  [self.view addSubview:self.adContainerView];
  self.adContainerView.frame = self.view.bounds;
}
...

6- تقديم طلب بث

أنشِئ بعض الثوابت لتجميد معلومات مصدر البيانات، ثم نفِّذ وظيفة طلب مصدر البيانات لإجراء الطلب.

ViewController.m

...
#import <GoogleInteractiveMediaAds/GoogleInteractiveMediaAds.h>

static NSString *const kAssetKey = @"sN_IYUG8STe1ZzhIIE_ksA";
static NSString *const kContentSourceID = @"2528370";
static NSString *const kVideoID = @"tears-of-steel";

@interface ViewController ()
...

- (void)requestStream {
  IMAAVPlayerVideoDisplay *videoDisplay =
      [[IMAAVPlayerVideoDisplay alloc] initWithAVPlayer:self.playerViewController.player];
  IMAAdDisplayContainer *adDisplayContainer =
      [[IMAAdDisplayContainer alloc] initWithAdContainer:self.adContainerView];
  IMALiveStreamRequest *request = [[IMALiveStreamRequest alloc] initWithAssetKey:kAssetKey
                                                              adDisplayContainer:adDisplayContainer
                                                                    videoDisplay:videoDisplay];
  // VOD request. Comment out the IMALiveStreamRequest above and uncomment this IMAVODStreamRequest
  // to switch from a livestream to a VOD stream.
  // IMAVODStreamRequest *request =
  //     [[IMAVODStreamRequest alloc] initWithContentSourceId:kContentSourceID
  //                                                  videoId:kVideoID
  //                                       adDisplayContainer:adDisplayContainer
  //                                             videoDisplay:videoDisplay];
  [self.adsLoader requestStreamWithRequest:request];
}
...

7- التعامل مع أحداث البث

يتم استخدام حدثَي تنشيط IMAAdsLoader وIMAStreamManager المستخدمَين لمعالجة عملية الإعداد والأخطاء والتغييرات في حالة البث. يتم تنشيط هذه الأحداث عبر البروتوكولين IMAAdsLoaderDelegate وIMAStreamManagerDelegate. عليك الاستماع إلى حدث تم تحميل الإعلانات وإعداده. في حال تعذّر تحميل الإعلان، يمكنك تشغيل مصدر بيانات احتياطي بدلاً من ذلك.

ViewController.m

...
static NSString *const kAssetKey = @"sN_IYUG8STe1ZzhIIE_ksA";
static NSString *const kContentSourceID = @"2528370";
static NSString *const kVideoID = @"tears-of-steel";
static NSString *const kBackupStreamURLString =
    @"https://storage.googleapis.com/interactive-media-ads/media/bbb.m3u8";

@interface ViewController () <IMAAdsLoaderDelegate, IMAStreamManagerDelegate>

...
  [self.adsLoader requestStreamWithRequest:request];
}

- (void)playBackupStream {
  NSURL *backupStreamURL = [NSURL URLWithString:kBackupStreamURLString];
  AVPlayerItem *backupStreamItem = [AVPlayerItem playerItemWithURL:backupStreamURL];
  [self.playerViewController.player replaceCurrentItemWithPlayerItem:backupStreamItem];
  [self.playerViewController.player play];
}


#pragma mark - IMAAdsLoaderDelegate

- (void)adsLoader:(IMAAdsLoader *)loader adsLoadedWithData:(IMAAdsLoadedData *)adsLoadedData {
  // Initialize and listen to stream manager's events.
  self.streamManager = adsLoadedData.streamManager;
  self.streamManager.delegate = self;
  [self.streamManager initializeWithAdsRenderingSettings:nil];
  NSLog(@"Stream created with: %@.", self.streamManager.streamId);
}

- (void)adsLoader:(IMAAdsLoader *)loader failedWithErrorData:(IMAAdLoadingErrorData *)adErrorData {
  // Fall back to playing the backup stream.
  NSLog(@"Error loading ads: %@", adErrorData.adError.message);
  [self playBackupStream];
}


#pragma mark - IMAStreamManagerDelegate

- (void)streamManager:(IMAStreamManager *)streamManager didReceiveAdEvent:(IMAAdEvent *)event {}

- (void)streamManager:(IMAStreamManager *)streamManager didReceiveAdError:(IMAAdError *)error {}

- (void)streamManager:(IMAStreamManager *)streamManager
  adDidProgressToTime:(NSTimeInterval)time
           adDuration:(NSTimeInterval)adDuration
           adPosition:(NSInteger)adPosition
             totalAds:(NSInteger)totalAds
      adBreakDuration:(NSTimeInterval)adBreakDuration {}

@end

8- التعامل مع التسجيل وأحداث الخطأ

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

ViewController.m

...
#pragma mark - IMAStreamManagerDelegate

- (void)streamManager:(IMAStreamManager *)streamManager didReceiveAdEvent:(IMAAdEvent *)event {
  NSLog(@"StreamManager event (%@).", event.typeString);
  switch (event.type) {
    case kIMAAdEvent_STARTED: {
      // Log extended data.
      NSString *extendedAdPodInfo = [[NSString alloc]
          initWithFormat:@"Showing ad %zd/%zd, bumper: %@, title: %@, description: %@, contentType:"
                         @"%@, pod index: %zd, time offset: %lf, max duration: %lf.",
                         event.ad.adPodInfo.adPosition, event.ad.adPodInfo.totalAds,
                         event.ad.adPodInfo.isBumper ? @"YES" : @"NO", event.ad.adTitle,
                         event.ad.adDescription, event.ad.contentType, event.ad.adPodInfo.podIndex,
                         event.ad.adPodInfo.timeOffset, event.ad.adPodInfo.maxDuration];

      NSLog(@"%@", extendedAdPodInfo);
      break;
    }
    case kIMAAdEvent_AD_BREAK_STARTED: {
      // Prevent user seek through when an ad starts and show the ad controls.
      self.adContainerView.hidden = NO;
      break;
    }
    case kIMAAdEvent_AD_BREAK_ENDED: {
      // Allow user seek through after an ad ends and hide the ad controls.
      self.adContainerView.hidden = YES;
      break;
    }
    default:
      break;
  }
}

- (void)streamManager:(IMAStreamManager *)streamManager didReceiveAdError:(IMAAdError *)error {
  // Fall back to playing the backup stream.
  NSLog(@"StreamManager error: %@", error.message);
  [self playBackupStream];
}

@end

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

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

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