Mulai

Prasyarat

• Xcode 13 atau yang lebih baru

Panduan ini menjelaskan cara memanggil PAL SDK untuk menerima nonce dan memantau peristiwa pemutaran. Untuk mengikuti panduan yang sudah selesai, download aplikasi contoh PAL tvOS.

Menambahkan PAL SDK ke project Anda

Menginstal PAL SDK menggunakan Swift Package Manager

SDK Programmatic Access Library mendukung Swift Package Manager mulai dari versi 2.5.3. Ikuti langkah-langkah di bawah untuk mengimpor paket Swift.

1. Di Xcode, instal Paket Swift IMA SDK dengan membuka File > Add Packages....

2. Pada perintah yang muncul, telusuri repositori GitHub Paket Swift IMA SDK:

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

3. Pilih versi Paket Swift PAL SDK yang ingin Anda gunakan. Untuk project baru, sebaiknya gunakan Up to Next Major Version.

Setelah selesai, Xcode akan menyelesaikan dependensi paket Anda dan mendownloadnya di latar belakang. Untuk mengetahui detail selengkapnya tentang cara menambahkan dependensi paket, lihat artikel Apple.

Mendownload dan menginstal PAL SDK secara manual

Jika tidak ingin menggunakan Swift Package Manager, Anda dapat mendownload PAL SDK dan menambahkannya secara manual ke project Anda.

1. Download dan ekstrak PAL SDK untuk tvOS
2. Ikuti Panduan Developer Apple untuk menyertakan framework dalam project Anda.

Membuat nonce

"Nonce" adalah satu string terenkripsi yang dibuat oleh PAL menggunakan PALNonceLoader. PAL SDK mewajibkan setiap permintaan streaming baru disertai dengan nonce yang baru dibuat. Namun, nonce dapat digunakan kembali untuk beberapa permintaan iklan dalam streaming yang sama.

Semua cuplikan kode di bawah adalah modifikasi pada ViewController.m di aplikasi contoh tvOS PAL.

Untuk meminta nonce, mulailah dengan mengimpor library PAL:

@import ProgrammaticAccessLibrary;

Catatan: Sebaiknya Anda hanya membuat satu instance class PALNonceLoader untuk setiap sesi pengguna di aplikasi Anda, kecuali jika aplikasi Anda memiliki beberapa halaman atau konstruksi yang setara. Hal ini membuat parameter page correlator, atau &correlator, tetap tidak berubah selama masa aktif halaman atau sesi pengguna di aplikasi.

Anda tetap memiliki kontrol atas korelator streaming, atau &scor, yang harus direset sekali untuk setiap streaming baru. Semua permintaan iklan dari streaming yang sama harus menggunakan nilai korelator streaming dan PALNonceLoader yang sama agar fitur pembatasan frekuensi dan pengecualian kompetitif berfungsi dengan baik.

Selanjutnya, buat instance PALNonceLoader, dan tambahkan stub untuk dua metode delegasi:

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

Kemudian, mulai permintaan nonce, isi propertinya, dan gunakan untuk menginisialisasi pengelola 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];
}

Terakhir, isi delegasi pemuat nonce untuk mencatat nonce yang dibuat:

#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);
}

Saat membuat panggilan VAST langsung (DVC), tetapkan nonce sebagai nilai pada parameter givn. Nonce aman untuk URL—Anda tidak perlu mengenkodenya ke URL.

Perhatian: Jika sebelumnya Anda memberikan nonce menggunakan parameter paln, sebaiknya bermigrasi ke givn dan berhenti mengirim paln. Jika kedua parameter disertakan, perilaku yang tidak ditentukan akan terjadi terkait nonce mana yang digunakan.

Terakhir, Anda perlu menambahkan metode untuk menangani pengiriman informasi dan klik sesi pemutaran konten ke SDK. Lihat contoh berikut yang menerapkan metode sendPlaybackStart, sendPlaybackEnd, dan 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];
}

Dalam penerapan Anda, sendPlaybackStart harus dipanggil saat "pemutar video dimulai" saat pemutaran dimulai untuk pertama kalinya, sebagai respons terhadap tindakan yang dimulai pengguna (klik untuk putar) atau tindakan yang dimulai aplikasi (putar otomatis), sendPlaybackEnd harus dipanggil saat pemutaran berakhir, dan sendAdClick harus dipanggil setiap kali penonton mengklik iklan.

(Opsional) Mengirim sinyal Google Ad Manager melalui server iklan pihak ketiga

Konfigurasi permintaan server iklan pihak ketiga untuk Ad Manager. Setelah Anda menyelesaikan langkah-langkah berikut, parameter nonce akan diteruskan dari PAL SDK, melalui server perantara Anda, lalu ke Google Ad Manager. Hal ini memungkinkan monetisasi yang lebih baik melalui Google Ad Manager.

Catatan: Jika Anda menggunakan beberapa solusi pihak ketiga, misalnya, server SSAI pihak ketiga memanggil server iklan pihak ketiga lain, Anda harus memastikan nonce terenkripsi PAL SDK diteruskan ke setiap pihak ketiga.

Konfigurasi server iklan pihak ketiga Anda untuk menyertakan nonce dalam permintaan server ke Ad Manager. Berikut contoh tag iklan yang dikonfigurasi di dalam server iklan pihak ketiga:

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

Untuk mengetahui detail selengkapnya, lihat Panduan penerapan sisi server Google Ad Manager.

Ad Manager mencari givn= untuk mengidentifikasi nilai nonce. Server iklan pihak ketiga harus mendukung beberapa makronya sendiri, seperti %%custom_key_for_google_nonce%%, dan menggantinya dengan parameter kueri nonce yang Anda berikan pada langkah sebelumnya. Informasi selengkapnya tentang cara melakukannya seharusnya tersedia dalam dokumentasi server iklan pihak ketiga.