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 lengkap ini, download Aplikasi contoh PAL tvOS.

Menambahkan PAL SDK ke project

Menginstal PAL SDK menggunakan Swift Package Manager

SDK Library Akses Terprogram mendukung Paket Swift Manager mulai versi 2.5.3. Ikuti langkah-langkah di bawah ini untuk mengimpor paket Swift.

1. Di Xcode, instal IMA SDK Swift Package dengan membuka File > Tambahkan Paket....

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

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

3. Pilih versi PAL SDK Swift Package yang ingin Anda gunakan. Untuk project baru, sebaiknya gunakan Versi Utama Berikutnya.

Setelah selesai, Xcode menyelesaikan dependensi paket Anda dan mengunduhnya di latar belakang. Untuk detail selengkapnya tentang cara menambahkan paket dependensi, lihat Artikel Apple.

Download dan instal PAL SDK secara manual

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

1. Download dan ekstrak PAL SDK untuk iOS
2. Ikuti Panduan Developer Apple untuk menerapkan framework ke dalam project Anda.

Membuat nonce

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

Semua cuplikan kode di bawah ini adalah modifikasi untuk ViewController.m dalam Aplikasi contoh PAL tvOS.

Untuk meminta nonce, mulai dengan mengimpor library PAL:

@import ProgrammaticAccessLibrary;

Catatan: Sebaiknya hanya buat satu instance PALNonceLoader untuk setiap sesi pengguna di aplikasi Anda, kecuali jika aplikasi Anda memiliki beberapa halaman atau konstruksi yang setara. Cara ini menjaga korelator halaman, atau Parameter &correlator, tidak berubah selama masa aktif halaman atau pengguna sesi aplikasi.

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

Selanjutnya, buat instance PALNonceLoader, dan tambahkan stub untuk keduanya delegasikan:

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

Lalu, mulai permintaan nonce, isi propertinya, dan gunakan melakukan inisialisasi 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 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];
}

Terakhir, isi delegasi loader nonce untuk mencatat nonce yang dihasilkan ke dalam log:

#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 Anda sebagai nilai di Parameter givn. Nonce tersebut aman untuk URL—Anda tidak perlu mengenkodenya ke URL.

Perhatian: Jika sebelumnya Anda memberikan nonce menggunakan parameter paln, sangat disarankan untuk bermigrasi ke givn dan menghentikan pengiriman paln. Jika keduanya disertakan, perilaku yang tidak terdefinisi mengenai nonce mana yang data.

Terakhir, Anda perlu menambahkan metode untuk menangani pengiriman sesi pemutaran konten dan mengklik 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 implementasi Anda, sendPlaybackStart harus dipanggil di "pemutar video mulai" saat pemutaran dimulai untuk pertama kalinya, sebagai respons terhadap tindakan yang dimulai pengguna (klik untuk putar) atau tindakan yang dimulai oleh aplikasi (putar otomatis), sendPlaybackEnd harus dipanggil saat pemutaran berakhir, dan sendAdClick harus dipanggil dipanggil setiap kali penonton mengklik iklan.

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

Konfigurasikan permintaan server iklan pihak ketiga untuk Ad Manager. Setelah Anda selesaikan langkah-langkah berikut, parameter nonce yang disebarkan 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, solusi layanan pihak ketiga server SSAI yang memanggil server iklan pihak ketiga lainnya, Anda harus memastikan Nonce terenkripsi SDK diteruskan ke setiap pihak ketiga.

Konfigurasikan server iklan pihak ketiga untuk menyertakan nonce di kolom 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 detail selengkapnya, lihat Penerapan sisi Server Google Ad Manager panduan kami.

Ad Manager mencari givn= untuk mengidentifikasi nilai nonce. Iklan pihak ketiga server tersebut 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 harus tersedia dalam dokumentasi server iklan pihak ketiga.