Başlarken

Ön koşullar

  • Xcode 13 veya daha yeni bir sürüm

Bu kılavuzda, tek seferlik rastgele sayı almak ve oynatma etkinliklerini izlemek için PAL SDK'nın nasıl çağrılacağı açıklanmaktadır. Tamamlanmış kılavuzu takip etmek için PAL tvOS örnek uygulamasını indirin.

PAL SDK'sını projenize ekleme

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

Programatik Erişim Kitaplığı SDK'sı, 2.5.3 sürümünden itibaren Swift Package Manager'ı desteklemektedir. 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 Up to Next Major Version'ı 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 bakı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'yı indirip ayıklayın.
  2. Çerçeveyi projenize dahil etmek için Apple Geliştirici Kılavuzu'ndaki talimatları uygulayın.

Tek seferlik rastgele sayı oluşturma

"Nonce", PAL tarafından PALNonceLoader kullanılarak oluşturulan tek bir şifrelenmiş dizedir. PAL SDK'sı, her yeni akış isteğinin yeni oluşturulmuş bir nonce ile birlikte gönderilmesini gerektirir. Ancak tek kullanımlık sayılar, 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.

Tek seferlik rastgele sayı istemek için PAL kitaplığını içe aktararak başlayın:

@import ProgrammaticAccessLibrary;

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

Ardından, PALNonceLoader öğesinin bir örneğini oluşturun ve iki temsilci yöntemi için saplar 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 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 tek seferlik rastgele sayınızı givn parametresindeki değer olarak ayarlayın. Tek seferlik rastgele sayı URL için güvenlidir. URL olarak kodlamanız gerekmez.

Google'dan reklam isteğinde bulunuyor ve reklam oluşturuyorsanız AdChoices simgesini ve yer paylaşımını oluşturmanız gerekir. VAST yanıtını ayrıştırma ve simgeleri oluşturma hakkında ayrıntılı bilgi için Reklam Seçenekleri simgesi ve yer paylaşımı başlıklı makaleyi inceleyin.

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 sendPlaybackStart çağrılmalıdır. 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.

Üçü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ğini aşağıda bulabilirsiniz:

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= öğesini arar. Üçüncü taraf reklam sunucusunun, %%custom_key_for_google_nonce%% gibi kendi makrolarından birini desteklemesi ve bunu önceki adımda sağladığınız nonce sorgu parametresiyle değiştirmesi gerekir. Bunu nasıl yapacağınızla ilgili daha fazla bilgiyi üçüncü taraf reklam sunucusunun belgelerinde bulabilirsiniz.