מתחילים

דרישות מוקדמות

  • Xcode 13 ומעלה

במדריך הזה מוסבר איך להפעיל את PAL SDK כדי לקבל קוד צופן חד-פעמי (nonce) ומעקב אירועי הפעלה. כדי להמשיך להשתמש במדריך המלא, מורידים את אפליקציה לדוגמה של PAL tvOS.

הוספת PAL SDK לפרויקט

התקנת PAL SDK באמצעות Swift Package Manager

ה-SDK של ספריית הגישה הפרוגרמטית תומך ב-SWIFT Package חשבון ניהול החל מגרסה 2.5.3. פועלים לפי השלבים הבאים כדי לייבא את חבילת Swift.

  1. ב-Xcode, כדי להתקין את חבילת Swift של IMA SDK, עוברים אל קובץ > Add Packs... (הוספת חבילות).

  2. בהנחיה שמופיעה, מחפשים את IMA SDK SWIFT Package GitHub מאגר:

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

  3. בוחרים את הגרסה של PAL SDK SWIFT Package שבה רוצים להשתמש. לפרויקטים חדשים, מומלץ להשתמש ב-Up to Next Major Version.

בסיום, Xcode פותר את יחסי התלות של החבילות מוריד אותן ברקע. לפרטים נוספים על הוספת חבילה של יחסי התלות, המאמר של Apple.

הורדה והתקנה ידנית של PAL SDK

אם אתם לא רוצים להשתמש ב-Swift Package Manager, תוכלו להוריד את PAL SDK להוסיף אותו באופן ידני לפרויקט.

  1. מורידים ומחלצים את PAL SDK ל-iOS
  2. כדי לשלב את ה-framework בפרויקט שלכם, צריך לפעול לפי ההוראות במדריך למפתחים של Apple.

יצירת צופן חד-פעמי (nonce)

"אף" היא מחרוזת מוצפנת יחידה שנוצרה על ידי PAL באמצעות PALNonceLoader ל-PAL SDK נדרשת ליווי כל בקשה חדשה של סטרימינג באמצעות צופן חד-פעמי (nonce) חדש. עם זאת, אפשר לעשות שימוש חוזר בצפנים חד-פעמיים (nonce) בכמה מודעות בקשות באותו זרם.

כל קטעי הקוד הבאים הם שינויים ב- ViewController.m ב- אפליקציה לדוגמה של PAL tvOS.

כדי לבקש צופן חד-פעמי (nonce), מתחילים על ידי ייבוא ספריית ה-PAL:

@import ProgrammaticAccessLibrary;

בשלב הבא יוצרים מופע של PALNonceLoader ומוסיפים stubs עבור שיטות להענקת גישה:

@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 {
}

לאחר מכן, ליזום בקשה צופן חד-פעמי, לאכלס את המאפיינים שלה ולהשתמש בה כדי מאתחלים מנהל צופן חד-פעמי:

@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];
}

לבסוף, אכלוס את המשתמשים שקיבלו הרשאה לטעינת צפנים חד-פעמיים כדי ליצור ביומן צפנים חד-פעמיים שנוצרו:

#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. הקוד החד-פעמי (nonce) בטוח בכתובת 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 Ad Manager דרך שרתי מודעות של צד שלישי

מגדירים את הבקשה של שרת המודעות של הצד השלישי ל-Ad Manager. אחרי להשלים את השלבים הבאים, פרמטר הצופן החד-פעמי (nonce) מופץ מ-PAL SDK, דרך השרתים המתווכים, ואז אל Google Ad Manager. הפעולה הזאת מאפשרת מונטיזציה משופרת באמצעות Google Ad Manager.

צריך להגדיר את שרת המודעות של הצד השלישי כך שיכלול את הצופן החד-פעמי (nonce) של השרת בקשה ל-Ad Manager. דוגמה לתג מודעה שמוגדר בתוך שרת מודעות של צד שלישי:

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

לפרטים נוספים, אפשר לעיין במאמר הטמעה בצד השרת של Google Ad Manager guide.

מערכת Ad Manager מחפשת את givn= כדי לזהות את ערך הקוד החד-פעמי (nonce). המודעה של הצד השלישי השרת צריך לתמוך במאקרו מסוים משל עצמו, כמו %%custom_key_for_google_nonce%%, ומחליפים אותו בפרמטר השאילתה צופן חד-פעמי (nonce) שסיפקת בשלב הקודם. מידע נוסף על האופן שבו ניתן לעשות זאת צריכים להיות זמינים במסמכים של שרת המודעות של הצד השלישי.