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

البدء

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

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

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

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

تثبيت PAL SDK باستخدام Swift Package Manager

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

في Xcode، ثبِّت حزمة PAL SDK Swift Package من خلال الانتقال إلى File > Add Packages...‎.
في الطلب الذي يظهر، ابحث عن مستودع PAL SDK Swift Package GitHub:
```
https://github.com/googleads/swift-package-manager-google-programmatic-access-library-ios
```
اختَر إصدار حزمة PAL SDK Swift Package الذي تريد استخدامه. بالنسبة إلى المشاريع الجديدة، ننصحك باستخدام حتى الإصدار الرئيسي التالي.

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

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

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

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

إنشاء رقم خاص

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

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

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

@import ProgrammaticAccessLibrary;

سيظل بإمكانك التحكّم في أداة ربط البث، أو &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 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;
  request.OMIDPartnerName = @"SamplePartner";
  request.OMIDPartnerVersion = @"6.2.1";

  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)، اضبط قيمة nonce على أنّها قيمة المَعلمة givn. إنّ الرقم الخاص صالح للاستخدام في عناوين URL، ولست بحاجة إلى ترميزه.

إذا كنت تطلب إعلانات وتعرضها من Google، عليك عرض رمز AdChoices والتراكب. للحصول على تفاصيل حول تحليل استجابة VAST وعرض الرموز، يُرجى الاطّلاع على رمز "خيارات الإعلان" والتراكب.

أخيرًا، عليك إضافة طرق للتعامل مع إرسال معلومات جلسة تشغيل المحتوى والنقرات إلى حزمة 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".

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

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

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

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