البدء

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

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

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

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

تثبيت حزمة تطوير البرامج (SDK) الخاصة بـ PAL باستخدام Swift Package Manager

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

في Xcode، ثبِّت حزمة IMA SDK Swift Package من خلال الانتقال إلى ملف > إضافة حِزم... (File > Add Packages...).

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

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

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

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

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

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

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

إنشاء قيمة عشوائية

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

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

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

@import ProgrammaticAccessLibrary;

ملاحظة: ننصحك بإنشاء مثيل واحد فقط من الفئة PALNonceLoader لكل جلسة مستخدم في تطبيقك ما لم يكن تطبيقك يتضمّن صفحات متعدّدة أو بنى مكافئة. يؤدي ذلك إلى إبقاء معرّف ربط الصفحة أو المَعلمة &correlator بدون تغيير طوال فترة بقاء الصفحة أو جلسة المستخدم في التطبيق.

سيظل بإمكانك التحكّم في أداة ربط البث، أو &scor، التي يجب إعادة ضبطها مرة واحدة لكل بث جديد. يجب أن تتشارك جميع طلبات الإعلانات في بث الفيديو نفسه قيمة PALNonceLoader ومعرّف ربط البث نفسه لكي تعمل ميزتا الحدّ الأقصى لعدد مرات الظهور والاستبعاد التنافسي بشكلٍ سليم.

بعد ذلك، أنشئ مثيلاً من 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 'directedForChildOrUnknownAge' is
  // 'NO'. Update the value after the appropriate consent has been gathered.
  // By default, PAL automatically determines whether to enable limited ads
  // based on the user's TCF (Transparency and Consent Framework) consent data
  // on the device. If you must manually override the default behavior,
  // for example, to meet your app's requirements, use the
  // `PALSettings.forceLimitedAds` property.
  PALSettings *settings = [[PALSettings alloc] init];
  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 {
}

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

@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 integers. See reference docs for more details.
  request.supportedAPIFrameworks = [NSMutableSet setWithArray:@[ @2, @7, @9 ]];
  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];
}

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

#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)، اضبط رقم الاستخدام لمرة واحدة كقيمة في المَعلمة givn. إنّ الرقم العشوائي صالح للاستخدام في عناوين 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" من خلال خوادم إعلانات تابعة لجهات خارجية

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

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

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

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

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