เริ่มต้นใช้งาน

ข้อกำหนดเบื้องต้น

  • Xcode 13 ขึ้นไป

คู่มือนี้อธิบายวิธีเรียกใช้ PAL SDK เพื่อรับ Nonce และตรวจสอบ เหตุการณ์การเล่น หากต้องการทำตามคำแนะนำที่เสร็จสมบูรณ์แล้ว ให้ดาวน์โหลดแอปพลิเคชันตัวอย่าง PAL tvOS

เพิ่ม PAL SDK ลงในโปรเจ็กต์

ติดตั้ง PAL SDK โดยใช้ Swift Package Manager

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. เลือกเวอร์ชันของแพ็กเกจ Swift ของ PAL SDK ที่ต้องการใช้ สำหรับโปรเจ็กต์ใหม่ เราขอแนะนำให้ใช้อัปเดตเป็นเวอร์ชันหลักถัดไป

เมื่อดำเนินการเสร็จแล้ว Xcode จะแก้ไขการขึ้นต่อกันของแพ็กเกจและดาวน์โหลดไว้ในเบื้องหลัง ดูรายละเอียดเพิ่มเติมเกี่ยวกับวิธีเพิ่มการอ้างอิงแพ็กเกจได้ในบทความของ Apple

ดาวน์โหลดและติดตั้ง PAL SDK ด้วยตนเอง

หากไม่ต้องการใช้ Swift Package Manager คุณสามารถดาวน์โหลด PAL SDK และ เพิ่มลงในโปรเจ็กต์ด้วยตนเองได้

  1. ดาวน์โหลดและแตกไฟล์ PAL SDK สำหรับ tvOS
  2. ทำตามคู่มือนักพัฒนาซอฟต์แวร์ของ Apple เพื่อรวมเฟรมเวิร์กลงในโปรเจ็กต์

สร้าง Nonce

"Nonce" คือสตริงที่เข้ารหัสเดียวซึ่ง PAL สร้างขึ้นโดยใช้ PALNonceLoader PAL SDK กำหนดให้คำขอสตรีมใหม่แต่ละรายการต้องมี Nonce ที่สร้างขึ้นใหม่ อย่างไรก็ตาม สามารถนำ Nonce กลับมาใช้ซ้ำสำหรับคำขอโฆษณาหลายรายการภายในสตรีมเดียวกันได้

ข้อมูลโค้ดทั้งหมดด้านล่างนี้เป็นการแก้ไข ViewController.m ในแอปพลิเคชันตัวอย่าง PAL tvOS

หากต้องการขอใช้ Nonce ให้เริ่มด้วยการนำเข้าไลบรารี PAL ดังนี้

@import ProgrammaticAccessLibrary;

จากนั้นสร้างอินสแตนซ์ของ PALNonceLoader และเพิ่ม Stub สำหรับเมธอด Delegate 2 รายการต่อไปนี้

@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

สุดท้าย คุณต้องเพิ่มเมธอดเพื่อจัดการการส่งข้อมูลเซสชันการเล่นเนื้อหาและคลิกไปยัง 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

กำหนดค่าเซิร์ฟเวอร์โฆษณาบุคคลที่สามให้รวม 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 ที่คุณระบุในขั้นตอนก่อนหน้า ดูข้อมูลเพิ่มเติมเกี่ยวกับวิธีดำเนินการนี้ได้ในเอกสารประกอบของเซิร์ฟเวอร์โฆษณาของบุคคลที่สาม