התחל בעבודה

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

  • ‫Xcode 13 ואילך

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

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

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

ערכת ה-SDK‏ Programmatic Access Library תומכת ב-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. בוחרים את הגרסה של חבילת ה-Swift של PAL SDK שרוצים להשתמש בה. לפרויקטים חדשים, מומלץ להשתמש באפשרות עד הגרסה הראשית הבאה.

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

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

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

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

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

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

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

כדי לבקש nonce, מתחילים בייבוא של ספריית PAL:

@import ProgrammaticAccessLibrary;

לאחר מכן, יוצרים מופע של 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 {
}

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

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

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

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

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