الخطوات الأولى

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

  • Xcode 13 أو أحدث

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

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

تثبيت حزمة تطوير البرامج (SDK) لنظام التشغيل PAL باستخدام أداة "مدير حزم Swift"

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

  1. في Xcode، ثبِّت حزمة Swift لحزمة تطوير البرامج لإعلانات الوسائط التفاعلية من خلال الانتقال إلى ملف > إضافة حِزم....

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

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

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

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

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

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

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

إنشاء رقم Nonce

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

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

لطلب رقم خاص، ابدأ باستيراد مكتبة 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.
 *
 * The PALNonceRequest parameters set here are example parameters.
 * You should set your parameters based on your own app characteristics.
 */
- (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 إلى تسجيل أرقام 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);
}

عند إجراء مكالمة VAST المباشرة (DVC)، يمكنك ضبط nonce كقيمة على مَعلمة 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 إلى "مشغّل الفيديو" Start (بدء) عند بدء التشغيل للمرة الأولى، استجابةً لأي من إجراء ينفّذه المستخدم (النقر للتشغيل) أو إجراء يبدأه التطبيق (التشغيل التلقائي)، يجب استدعاء الدالة sendPlaybackEnd عند انتهاء التشغيل، بينما يجب استدعاء sendAdClick عند انتهاء التشغيل. الاسم في كل مرة ينقر فيها المشاهد على الإعلان.

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

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

يجب إعداد خادم الإعلانات التابع لجهة خارجية لتضمين nonce في خادم الإعلانات الخاص بالخادم المرسَل إلى "مدير الإعلانات" في ما يلي مثال على علامة إعلان تم ضبطها داخل خادم إعلانات الجهة الخارجية:

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

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

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