Başlarken

Ön koşullar

• Xcode 13 veya sonraki sürümler

Bu kılavuzda, PAL SDK'sını çağırarak nonce alma ve oynatma etkinliklerini izleme açıklanmaktadır. Tamamlanmış rehberi takip etmek için PAL tvOS örnek uygulamasını indirin.

PAL SDK'sını projenize ekleme

PAL SDK'yı Swift Package Manager'ı kullanarak yükleme

Programatik Erişim Kitaplığı SDK'sı, 2.5.3 sürümünden itibaren Swift Package Manager'ı destekler. Swift paketini içe aktarmak için aşağıdaki adımları uygulayın.

1. Xcode'da File > Add Packages... (Dosya > Paket Ekle...) seçeneğine giderek IMA SDK Swift Paketini yükleyin.

2. Görünen istemde IMA SDK Swift Package GitHub deposunu arayın:

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

3. Kullanmak istediğiniz PAL SDK Swift Paketi sürümünü seçin. Yeni projeler için Bir Sonraki Ana Sürüme Kadar'ı kullanmanızı öneririz.

İşlemi tamamladığınızda Xcode, paket bağımlılıklarınıza çözüm bulur ve bunları arka planda indirir. Paket bağımlılıklarını ekleme hakkında daha fazla bilgi için Apple'ın makalesine göz atın.

PAL SDK'sını manuel olarak indirip yükleme

Swift Package Manager'ı kullanmak istemiyorsanız PAL SDK'yı indirip projenize manuel olarak ekleyebilirsiniz.

1. tvOS için PAL SDK'sını indirip ayıklayın.
2. Çerçeveyi projenize dahil etmek için Apple Geliştirici Kılavuzu'ndaki talimatları uygulayın.

Tek kullanımlık sayı oluşturma

"Nonce", PALNonceLoader kullanılarak PAL tarafından oluşturulan tek bir şifrelenmiş dizedir. PAL SDK, her yeni akış isteğinin yeni oluşturulmuş bir nonce ile birlikte gönderilmesini gerektirir. Ancak, nonceler aynı akış içindeki birden fazla reklam isteği için yeniden kullanılabilir.

Aşağıdaki tüm kod snippet'leri, PAL tvOS örnek uygulamasındaki ViewController.m üzerinde yapılan değişikliklerdir.

Nonce istemek için öncelikle PAL kitaplığını içe aktarın:

@import ProgrammaticAccessLibrary;

Not: Uygulamanızda birden fazla sayfa veya eşdeğer yapı yoksa uygulamanızdaki her kullanıcı oturumu için PALNonceLoader sınıfının yalnızca bir örneğini oluşturmanızı öneririz. Bu sayede, sayfa korelasyonu veya &correlator parametresi, bir sayfanın veya kullanıcının uygulama oturumu süresince değişmez.

Her yeni akış için bir kez sıfırlanması gereken akış korelasyonu veya &scor üzerinde kontrolünüz devam eder. Sıklık sınırı ve rakip hariç tutma özelliklerinin düzgün çalışması için aynı yayınla ilgili tüm reklam istekleri aynı PALNonceLoader ve yayın ilişkilendirici değerini paylaşmalıdır.

Ardından PALNonceLoader örneği oluşturun ve iki temsilci yöntemi için sap ekleyin:

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

Ardından, bir nonce isteği başlatın, özelliklerini doldurun ve bir nonce yöneticisini başlatmak için kullanın:

@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];
}

Son olarak, oluşturulan nonce'ları kaydetmek için nonce yükleyici temsilcilerini doldurun:

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

Doğrudan VAST çağrınızı (DVC) yaparken nonce'unuzu givn parametresindeki değer olarak ayarlayın. Tek seferlik rastgele sayı URL için güvenlidir. URL olarak kodlamanız gerekmez.

Dikkat: Daha önce paln parametresini kullanarak tek seferlik bir sayı sağladıysanız givn parametresine geçmeniz ve paln göndermeyi bırakmanız önemle tavsiye edilir. Her iki parametre de dahil edilirse hangi nonce'un kullanılacağı tanımlanmamıştır.

Son olarak, içerik oynatma oturumu bilgilerini ve tıklamaları SDK'ya göndermeyi işleyecek yöntemler eklemeniz gerekir. sendPlaybackStart, sendPlaybackEnd ve sendAdClick yöntemlerinin uygulandığı aşağıdaki örneğe bakın:

...

// 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];
}

Uygulamanızda, oynatma ilk kez başlatıldığında, kullanıcı tarafından başlatılan bir işlem (tıkla oynat) veya uygulama tarafından başlatılan bir işlem (otomatik oynatma) sonucunda "video oynatıcı başlatma" sırasında sendPlaybackStart çağrılmalı, oynatma sona erdiğinde sendPlaybackEnd çağrılmalı ve izleyici bir reklamı her tıkladığında sendAdClick çağrılmalıdır.

(İsteğe bağlı) Google Ad Manager sinyallerini üçüncü taraf reklam sunucuları üzerinden gönderme

Üçüncü taraf reklam sunucusunun Ad Manager isteğini yapılandırın. Aşağıdaki adımları tamamladıktan sonra nonce parametresi PAL SDK'sından, aracı sunucularınızdan ve ardından Google Ad Manager'a yayılır. Bu sayede Google Ad Manager üzerinden daha iyi para kazanma olanağı elde edebilirsiniz.

Not: Örneğin, başka bir üçüncü taraf reklam sunucusunu çağıran üçüncü taraf bir SSAI sunucusu gibi birden fazla üçüncü taraf çözümü kullanıyorsanız PAL SDK'nın şifrelenmiş nonce'unun her üçüncü tarafa yönlendirildiğinden emin olmanız gerekir.

Üçüncü taraf reklam sunucunuzu, sunucunun Ad Manager'a yaptığı isteğe nonce'ı dahil edecek şekilde yapılandırın. Üçüncü taraf reklam sunucusunda yapılandırılmış bir reklam etiketi örneği aşağıda verilmiştir:

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

Daha fazla bilgi için Google Ad Manager sunucu tarafı uygulama kılavuzuna bakın.

Ad Manager, nonce değerini belirlemek için givn= karakterini arar. Üçüncü taraf reklam sunucusunun, %%custom_key_for_google_nonce%% gibi kendi makrolarından bazılarını desteklemesi ve bunları önceki adımda sağladığınız nonce sorgu parametresiyle değiştirmesi gerekir. Bu işlemin nasıl yapılacağıyla ilgili daha fazla bilgiyi üçüncü taraf reklam sunucusunun belgelerinde bulabilirsiniz.