البدء

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

  • Xcode 13 أو إصدار أحدث

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

إضافة حزمة PAL SDK إلى مشروعك

تثبيت حزمة PAL SDK باستخدام "مدير الحزم" في Swift

تتوافق حزمة SDK لمكتبة الوصول الآلي مع خدمة Swift Package Manager بدايةً من الإصدار 2.5.3. اتبع الخطوات أدناه لاستيراد حزمة Swift.

  1. في Xcode، ثبِّت حزمة IMA SDK Swift من خلال الانتقال إلى ملف > إضافة حِزم....

  2. في المطالبة التي تظهر، ابحث عن مستودع GitHub لحزمة IMA SDK Swift:

    https://github.com/googleads/swift-package-manager-google-programmatic-access-library-tvos

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

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

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

إذا كنت لا ترغب في استخدام Swift Package Manager، يمكنك تنزيل PAL SDK وإضافته يدويًا إلى مشروعك.

  1. تنزيل PAL SDK لنظام التشغيل iOS واستخراجه
  2. اتبع دليل المطوّر من Apple لدمج إطار العمل في مشروعك.

إنشاء رقم خاص

سلسلة "nonce" هي سلسلة مشفّرة واحدة يتم إنشاؤها بواسطة PAL باستخدام PALNonceLoader. تتطلّب حزمة PAL SDK أن يكون كل طلب بث جديد مصحوبًا برقم تعريفي تم إنشاؤه حديثًا. مع ذلك، يمكن إعادة استخدام nonces لطلبات إعلان متعددة ضمن البث المباشر نفسه.

تُعد كل مقتطفات الرمز أدناه تعديلات على ViewController.m في نموذج تطبيق tvOS PAL.

لطلب nonce، ابدأ باستيراد مكتبة PAL:

@import ProgrammaticAccessLibrary;

بعد ذلك، أنشئ مثيلاً لـ PALNonceLoader، وأضف تنويهات لطريقتي التفويض:

@interface ViewController () <PALNonceLoaderDelegate>
// The nonce loader to use for nonce requests.
@property(nonatomic) PALNonceLoader *nonceLoader;
// The view in which a video would play.
// In this sample, it is mocked for simplification.
@property(nonatomic, weak) IBOutlet UIView *videoView;
@end
...
- (void) viewDidLoad {
  [super viewDidLoad];
  // The default value for 'allowStorage' and
  // 'directedForChildOrUnknownAge' is 'NO', but should be updated once the
  // appropriate consent has been gathered. Publishers should either
  // integrate with a CMP or use a different method to handle storage consent.
  PALSettings *settings = [[PALSettings alloc] init];
  settings.allowStorage = YES;
  settings.directedForChildOrUnknownAge = NO;

  self.nonceLoader = [[PALNonceLoader alloc] initWithSettings:settings];
  self.nonceLoader.delegate = self;
}

#pragma mark - PALNonceLoaderDelegate methods

- (void)nonceLoader:(PALNonceLoader *)nonceLoader
            withRequest:(PALNonceRequest *)request
    didLoadNonceManager:(PALNonceManager *)nonceManager {
}

- (void)nonceLoader:(PALNonceLoader *)nonceLoader
         withRequest:(PALNonceRequest *)request
    didFailWithError:(NSError *)error {
}

بعد ذلك، ابدأ طلبًا خاصًا وتعبئة خصائصه واستخدمه لإعداد مدير nonce:

@interface ViewController () <PALNonceLoaderDelegate>
// The nonce loader to use for nonce requests.
@property(nonatomic) PALNonceLoader *nonceLoader;
// The nonce manager result from the last successful nonce request.
@property(nonatomic) PALNonceManager *nonceManager;
// The view in which a video would play. In this sample, it is mocked for
// simplification.
@property(nonatomic, weak) IBOutlet UIView *videoView;
@end

...

- (void)viewDidLoad {
  ...
  self.nonceLoader.delegate = self;
  [self requestNonceManager];
}

...

#pragma mark - UI Callback methods

/**
 * Requests a new nonce manager with a request containing arbitrary test values
 * like a (sane) user might supply. Displays the nonce or error on success. This
 * should be called once per stream.
 */
- (void)requestNonceManager {
  PALNonceRequest *request = [[PALNonceRequest alloc] init];
  request.continuousPlayback = PALFlagOff;
  request.descriptionURL = [NSURL URLWithString:@"https://example.com/desc?key=val"];
  request.iconsSupported = YES;
  request.playerType = @"AwesomePlayer";
  request.playerVersion = @"4.2.1";
  request.PPID = @"123987456";
  request.sessionID = @"Sample SID";
  // Sample API framework integer. See reference docs for more details.
  NSInteger SampleAPIFramework = 501;
  request.supportedApiFrameworks = [NSMutableSet setWithArray:@[ SampleAPIFramework ]];
  request.videoPlayerHeight = 480;
  request.videoPlayerWidth = 640;
  request.willAdAutoPlay = PALFlagOn;
  request.willAdPlayMuted = PALFlagOff;

  if (self.nonceManager) {
    // Detach the old nonce manager's gesture recognizer before destroying it.
    [self.videoView removeGestureRecognizer:self.nonceManager.gestureRecognizer];
    self.nonceManager = nil;
  }
  [self.nonceLoader loadNonceManagerWithRequest:request];
}

وأخيرًا، عليك تعبئة العناصر المفوَّضة بتحميل nonce من أجل تسجيل الأرقام الخاصة التي تم إنشاؤها:

#pragma mark - PALNonceLoaderDelegate methods

- (void)nonceLoader:(PALNonceLoader *)nonceLoader
            withRequest:(PALNonceRequest *)request
    didLoadNonceManager:(PALNonceManager *)nonceManager {
  NSLog(@"Programmatic access nonce: %@", nonceManager.nonce);
  // Capture the created nonce manager and attach its gesture recognizer to the video view.
  self.nonceManager = nonceManager;
  [self.videoView addGestureRecognizer:self.nonceManager.gestureRecognizer];
}

- (void)nonceLoader:(PALNonceLoader *)nonceLoader
         withRequest:(PALNonceRequest *)request
    didFailWithError:(NSError *)error {
  NSLog(@"Error generating programmatic access nonce: %@", error);
}

عند إجراء طلب نموذج عرض إعلانات فيديو (DVC) مباشر، يجب ضبط رقم التعريف الخاص بك كقيمة في معلَمة givn. رقم التعريف الخاص هو عنوان URL آمن، ولا تحتاج إلى ترميزه باستخدام عنوان URL.

أخيرًا، تحتاج إلى إضافة طرق للتعامل مع إرسال معلومات جلسات تشغيل المحتوى والنقرات إلى SDK. اطّلِع على المثال التالي لتنفيذ الطرق sendPlaybackStart وsendPlaybackEnd وsendAdClick:

...

// Reports the start of playback for the current content session.
- (void)sendPlaybackStart {
  [self.nonceManager sendPlaybackStart];
}

// Reports the end of playback for the current content session.
- (void)sendPlaybackEnd {
  [self.nonceManager sendPlaybackEnd];
}

// Reports an ad click for the current nonce manager, if not nil.
- (void)sendAdClick {
  [self.nonceManager sendAdClick];
}

أثناء التنفيذ، يجب استدعاء sendPlaybackStart عند "بدء مشغّل الفيديو" عند بدء التشغيل للمرة الأولى، وذلك استجابةً لإجراء يبدأه المستخدم (النقر للتشغيل) أو إجراء يبدأه التطبيق (التشغيل التلقائي)، ويجب استدعاء sendPlaybackEnd عند انتهاء التشغيل، ويجب استدعاء sendAdClick في كل مرة ينقر فيها المشاهد على إعلان.

(اختياري) إرسال إشارات "مدير إعلانات Google" من خلال خوادم إعلانات تابعة لجهات خارجية

اضبط طلب خادم الإعلانات التابع لجهة خارجية إلى "مدير الإعلانات". بعد إكمال الخطوات التالية، يتم نشر المعلمة nonce من حزمة PAL SDK، عبر الخوادم الوسيطة ثم إلى "مدير إعلانات Google". يتيح ذلك إمكانية تحقيق ربح أفضل من خلال "مدير إعلانات Google"

اضبط خادم الإعلانات التابع لجهة خارجية لتضمين رقم التعريف الخاص بك في طلب الخادم إلى "مدير الإعلانات". في ما يلي مثال على علامة إعلان تم ضبطها داخل خادم إعلانات الجهة الخارجية:

https://pubads.serverside.net/gampad/ads?givn=%%custom_key_for_google_nonce%%&...

ولمزيد من التفاصيل، يُرجى الاطّلاع على دليل التنفيذ من جهة خادم "مدير إعلانات Google".

يبحث "مدير الإعلانات" عن givn= لتحديد القيمة الخاصة. يجب أن يوفّر خادم الإعلانات التابع لجهة خارجية وحدات ماكرو خاصة به، مثل %%custom_key_for_google_nonce%%، واستبدلها بمعلمة طلب البحث nonce التي أدخلتها في الخطوة السابقة. يجب توفير مزيد من المعلومات حول كيفية تحقيق ذلك في وثائق خادم الإعلانات التابع لجهة خارجية.