מתחילים

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

  • Xcode מגרסה 13 ואילך

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

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

התקנת ה-SDK של PAL באמצעות מנהל החבילות של Swift

ה-SDK של ספריית הגישה הפרוגרמטית תומך ב-Swift Package Manager החל מגרסה 2.5.3. על מנת לייבא את חבילת Swift, יש לבצע את השלבים הבאים.

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

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

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

  3. יש לבחור בגרסה של חבילת Swift של PAL SDK שבה ברצונך להשתמש. לפרויקטים חדשים, מומלץ להשתמש בגרסה הראשית הבאה.

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

הורדה והתקנה של PAL SDK באופן ידני

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

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

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

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

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

כדי לבקש צופן חד-פעמי (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 {
}

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

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

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

#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 במצב 'התחלת נגן וידאו' בזמן ההפעלה הראשונה, בתגובה לפעולה שהמשתמש מפעיל (לחיצה להפעלה) או פעולה שמופעלת על ידי אפליקציה (הפעלה אוטומטית). יש להפעיל את sendPlaybackEnd בסיום ההפעלה, ואת הפקודה sendAdClick בכל פעם שהצופה לוחץ על מודעה.

(אופציונלי) שליחת אותות של Google Ad Manager דרך שרתי מודעות של צד שלישי

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

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

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

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

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