תחילת עבודה

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

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

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

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

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

ערכת PAL SDK תומכת ב-Swift Package Manager החל מגרסה 2.5.3. כדי לייבא את חבילת Swift, פועלים לפי השלבים הבאים.

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

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

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

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

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

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

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

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

יצירת מספר חד-פעמי

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

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

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

@import ProgrammaticAccessLibrary;

הערה: מומלץ ליצור רק מופע אחד של המחלקה PALNonceLoader לכל סשן משתמש באפליקציה, אלא אם באפליקציה יש כמה דפים או מבנים מקבילים. כך פרמטר המתאם של הדף, או &correlator, נשאר ללא שינוי למשך חיי הדף או למשך סשן של משתמש באפליקציה.

עדיין יש לכם שליטה על מתאם הנתונים, או &scor, שצריך לאפס אותו פעם אחת לכל נתונים חדשים. כדי שהתכונות של מכסת תדירות והחרגת מודעות של מתחרים יפעלו בצורה תקינה, כל הבקשות להצגת מודעות באותו סטרימינג צריכות לכלול את אותו ערך של PALNonceLoader ואת אותו ערך של מתאם הסטרימינג.

לאחר מכן, יוצרים מופע של PALNonceLoader ומוסיפים stub לשתי שיטות ההעברה:

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

לאחר מכן, יוצרים בקשת nonce, מאכלסים את המאפיינים שלה ומשתמשים בה כדי לאתחל מנהל 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 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];
}

לבסוף, מאכלסים את הנציגים של רכיב טעינת ה-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. ה-nonce בטוח לשימוש בכתובת URL, כך שאין צורך לבצע קידוד URL.

שימו לב: אם סיפקתם בעבר ערך חד-פעמי באמצעות הפרמטר paln, מומלץ מאוד לעבור לפרמטר givn ולהפסיק לשלוח את הפרמטר paln. אם שני הפרמטרים האלה נכללים, ההתנהגות לא מוגדרת לגבי ה-nonce שבו נעשה שימוש.

אם אתם שולחים בקשות להצגת מודעות מ-Google ומציגים אותן, אתם חייבים להציג את הסמל ואת שכבת העל של AdChoices. פרטים על ניתוח תגובת VAST ועיבוד סמלים מופיעים במאמר בנושא הסמל של AdChoices ושכבת-על.

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

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

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

הערה: אם אתם משתמשים בכמה פתרונות של צד שלישי, למשל שרת SSAI של צד שלישי שקורא לשרת מודעות של צד שלישי אחר, אתם צריכים לוודא שערך ה-nonce המוצפן של PAL SDK מועבר לכל צד שלישי.

מגדירים את שרת המודעות של הצד השלישי כך שיכלול את המספר החד-פעמי בבקשה של השרת אל 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%%, ולהחליף אותו בפרמטר השאילתה של הצופן החד-פעמי שסיפקתם בשלב הקודם. מידע נוסף על האופן שבו אפשר לעשות את זה אמור להיות זמין במסמכי התיעוד של שרת המודעות של הצד השלישי.