تسهِّل حِزم تطوير البرامج (SDK) لإعلانات الوسائط التفاعلية دمج إعلانات الوسائط المتعددة في مواقعك الإلكترونية وتطبيقاتك. يمكن لحِزم تطوير البرامج لإعلانات الوسائط التفاعلية طلب الإعلانات من أيّ خادم إعلانات متوافق مع نموذج عرض إعلانات الفيديو (VAST) وإدارة تشغيل الإعلانات في تطبيقاتك. باستخدام حِزم تطوير البرامج لميزة "إدراج إعلان ديناميكي" في إعلانات الوسائط التفاعلية (IMA DAI SDK)، تقدّم التطبيقات طلبًا لبث الإعلان والفيديو، سواء كان محتوى مسجّلاً أو محتوى مباشرًا. بعد ذلك، تُرسِل حزمة تطوير البرامج (SDK) بثًا متّصلاً للفيديو، ما يُغنيك عن إدارة التبديل بين الإعلانات والفيديوهات التي تعرض محتوى داخل تطبيقك.
اختيار حلّ DAI الذي يهمّك
خدمة إدراج إعلان ديناميكي كاملة
يوضّح هذا الدليل كيفية دمج حزمة تطوير البرامج لميزة "العرض أثناء التشغيل" في إعلانات الوسائط التفاعلية (IMA DAI SDK) في تطبيق مشغّل فيديو بسيط. إذا أردت الاطّلاع على نموذج مكتمل للدمج أو اتّباعه، نزِّل BasicExample من GitHub.
نظرة عامة على ميزة "إدراج إعلان ديناميكي" في إعلانات الوسائط التفاعلية
يتضمّن تنفيذ IMA DAI ثلاثة مكوّنات رئيسية لحزمة SDK كما هو موضّح في هذا الدليل:
IMAAdDisplayContainer
: عنصر حاوية يقع أعلى عنصر تشغيل الفيديو ويضم عناصر واجهة مستخدِم الإعلان.-
IMAAdsLoader
: عنصر يطلب أحداث البث ويعالجها، والتي يتم تشغيلها بواسطة عناصر استجابة طلب البث. يجب إنشاء مثيل واحد فقط لتحميل الإعلانات، والذي يمكن إعادة استخدامه طوال مدة استخدام التطبيق. -
IMAStreamRequest
– إماIMAVODStreamRequest
أوIMALiveStreamRequest
: كائن يحدّد طلب بث. يمكن أن تكون طلبات البث لفيديوهات عند الطلب أو لأحداث بث مباشر. تحدّد الطلبات معرّف محتوى، بالإضافة إلى مفتاح واجهة برمجة التطبيقات أو رمز المصادقة وغيرها من المَعلمات. IMAStreamManager
: عنصر يعالج أحداث إدراج الإعلانات الديناميكية وتفاعلاتها مع الخلفية في ميزة "إدراج الإعلانات الديناميكية". يتعامل مدير البث أيضًا مع إشعارات التتبّع ويعيد توجيه أحداث البث والإعلانات إلى الناشر.
المتطلبات الأساسية
قبل البدء، يجب توفّر ما يلي:
- الإصدار 13 من Xcode أو إصدار أحدث
- CocoaPods (الخيار المفضّل) أو Swift Package Manager أو نسخة تم تنزيلها من حزمة تطوير البرامج لإدراج إعلان ديناميكي لإعلانات الوسائط التفاعلية لنظام التشغيل tvOS
إنشاء مشروع Xcode جديد
في Xcode، أنشئ مشروعًا جديدًا لنظام التشغيل tvOS باستخدام Objective-C. استخدِم BasicExample كاسم للمشروع.
إضافة حزمة تطوير البرامج لإعلانات الوسائط التفاعلية (IMA DAI SDK) إلى مشروع Xcode
استخدِم إحدى الطريقتَين التاليتَين لتثبيت حزمة تطوير البرامج لميزة DAI في إعلانات الوسائط التفاعلية.
تثبيت حزمة تطوير البرامج (SDK) باستخدام CocoaPods (الخيار المفضّل)
CocoaPods هو أداة لإدارة الملحقات لمشاريع Xcode، وهي الطريقة المُقترَحة لتثبيت حزمة تطوير البرامج لإعلانات الوسائط التفاعلية (IMA DAI SDK). لمزيد من المعلومات حول تثبيت CocoaPods أو استخدامه، يُرجى الاطّلاع على مستندات CocoaPods. بعد تثبيت CocoaPods، اتّبِع التعليمات التالية لتثبيت حزمة تطوير البرامج لعرض الإعلانات الديناميكية في "إعلانات الوسائط التفاعلية":
في الدليل نفسه الذي يتضمّن ملف BasicExample.xcodeproj، أنشِئ ملفًا نصيًا بعنوان Podfile وأضِف الإعدادات التالية:
source 'https://github.com/CocoaPods/Specs.git' platform :tvos, '14' target "BasicExample" do pod 'GoogleAds-IMA-tvOS-SDK', '~> 4.13.0' end
من الدليل الذي يحتوي على Podfile، شغِّل:
pod install --repo-update`
تأكَّد من نجاح عملية التثبيت من خلال فتح ملف BasicExample.xcworkspace والتأكّد من أنّه يحتوي على منصّتَي تطوير برمجي: BasicExample وPods (التبعيات التي ثبَّتها CocoaPods).
تثبيت حزمة SDK باستخدام Swift Package Manager
تتوافق حزمة تطوير البرامج لإعلانات الوسائط التفاعلية مع Swift Package Manager اعتبارًا من الإصدار 4.8.2. اتّبِع الخطوات التالية لتصدير حزمة Swift.
في Xcode، ثبِّت حزمة GoogleInteractiveMediaAds Swift من خلال الانتقال إلى ملف > إضافة حِزم.
في الطلب الذي يظهر، ابحث عن مستودع GitHub الخاص بحزمة GoogleInteractiveMediaAds Swift Package:
https://github.com/googleads/swift-package-manager-google-interactive-media-ads-tvos
اختَر إصدار حزمة GoogleInteractiveMediaAds Swift التي تريد استخدامها. بالنسبة إلى المشاريع الجديدة، ننصحك باستخدام الإصدار التالي.
عند الانتهاء، يحلّ Xcode تبعيات الحزمة وينزّلها في الخلفية. لمعرفة المزيد من التفاصيل عن كيفية إضافة متطلّبات حزمة، يُرجى الاطّلاع على مقالة Apple.
تنزيل حزمة تطوير البرامج (SDK) وتثبيتها يدويًا
إذا كنت لا تريد استخدام Swift Package Manager أو CocoaPods، يمكنك تنزيل حزمة تطوير البرامج لإعلانات الوسائط التفاعلية (IMA DAI SDK) وإضافتها يدويًا إلى مشروعك.
إنشاء مشغّل فيديو بسيط
أولاً، عليك تنفيذ مشغّل فيديو أساسي. في البداية، لا يستخدم هذا المشغّل حزمة تطوير البرامج (SDK) لبرنامج IMA DAI ولا يحتوي على أي طريقة لبدء التشغيل.
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
استيراد حزمة تطوير البرامج (SDK) وإضافة نماذج تفاعل لإعلانات الوسائط التفاعلية
بعد إضافة حزمة تطوير البرامج (SDK) لإعلانات الوسائط التفاعلية (IMA) إلى مشروعك، استورِد حزمة SDK وأضِف نماذج stubs لنقاط التفاعل الأساسية في IMA.
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
تنفيذ 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;
}
تقديم طلب بث
أنشئ بعض الثوابت لتخزين معلومات البث، ثم نفِّذ دالة طلب البث لإنشاء الطلب.
ViewController.m
#import <GoogleInteractiveMediaAds/GoogleInteractiveMediaAds.h>
static NSString *const kAssetKey = @"sN_IYUG8STe1ZzhIIE_ksA";
static NSString *const kContentSourceID = @"2548831";
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];
}
التعامل مع أحداث البث
تُطلق IMAAdsLoader
وIMAStreamManager
أحداثًا تُستخدَم لمعالجة
عمليات الإعداد والأخطاء والتغييرات في حالة البث. يتم تنشيط هذه الأحداث من خلال بروتوكولَي IMAAdsLoaderDelegate
وIMAStreamManagerDelegate
. انتظِر حدث loading ads (تحميل الإعلانات) وابدأ البث. إذا تعذّر تحميل إعلان، يمكنك تشغيل
بث احتياطي بدلاً منه.
ViewController.m
static NSString *const kAssetKey = @"sN_IYUG8STe1ZzhIIE_ksA";
static NSString *const kContentSourceID = @"2548831";
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
التعامل مع أحداث التسجيل والأخطاء
هناك العديد من الأحداث التي يمكن أن يتعامل معها المفوّض في "مدير البث"، ولكن بالنسبة إلى عمليات التنفيذ الأساسية، فإنّ أهم الاستخدامات هي تسجيل الأحداث، لمنع إجراءات التقديم أو الإيقاف أثناء تشغيل الإعلانات، وللتعامل مع الأخطاء.
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) لعرض الإعلانات الديناميكية على الشبكة الإعلانية لإعلانات الوسائط التفاعلية. للاطّلاع على معلومات إضافية عن ميزات حِزم تطوير البرامج (SDK) المتقدّمة، يمكنك الاطّلاع على الأدلة الأخرى أو على عيّنات على GitHub.