Начать

Предварительные требования

• Xcode 13 или выше

В этом руководстве описано, как использовать PAL SDK для получения одноразового числа (nonce) и мониторинга событий воспроизведения. Чтобы следовать инструкциям, загрузите пример приложения PAL tvOS .

Добавьте PAL SDK в свой проект.

Установите PAL SDK с помощью Swift Package Manager.

SDK библиотеки программного доступа поддерживает Swift Package Manager , начиная с версии 2.5.3. Выполните следующие шаги для импорта пакета Swift.

1. В Xcode установите пакет IMA SDK Swift, перейдя в меню Файл > Добавить пакеты... .

2. В появившемся окне найдите репозиторий IMA SDK Swift Package на GitHub:

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

3. Выберите версию пакета PAL SDK Swift, которую вы хотите использовать. Для новых проектов мы рекомендуем использовать версию «Up to Next Major Version» .

После завершения Xcode разрешит зависимости ваших пакетов и загрузит их в фоновом режиме. Более подробную информацию о добавлении зависимостей пакетов см. в статье Apple .

Загрузите и установите PAL SDK вручную.

Если вы не хотите использовать Swift Package Manager, вы можете загрузить PAL SDK и добавить его в свой проект вручную.

1. Загрузите и распакуйте PAL SDK для tvOS.
2. Чтобы интегрировать фреймворк в свой проект, следуйте инструкциям в руководстве для разработчиков Apple .

Сгенерировать одноразовый код (nonce)

«Nonce» — это одна зашифрованная строка, сгенерированная PAL с помощью PALNonceLoader . SDK PAL требует, чтобы каждый новый запрос потока сопровождался вновь сгенерированным nonce. Однако nonce можно использовать повторно для нескольких запросов рекламы в рамках одного потока.

Все приведенные ниже фрагменты кода представляют собой модификации файла ViewController.m из примера приложения PAL tvOS .

Чтобы запросить одноразовый код (nonce), начните с импорта библиотеки PAL:

@import ProgrammaticAccessLibrary;

Примечание: Мы рекомендуем создавать только один экземпляр класса PALNonceLoader для каждой пользовательской сессии в вашем приложении, если только ваше приложение не содержит несколько страниц или аналогичных конструкций. Это позволит сохранить параметр &correlator страницы) неизменным на протяжении всего времени существования страницы или пользовательской сессии приложения.

Вы по-прежнему можете контролировать параметр &scor (коррелятор потока), который следует сбрасывать один раз для каждого нового потока. Все рекламные запросы одного и того же потока должны использовать одно и то же значение PALNonceLoader и значение коррелятора потока для корректной работы функций ограничения частоты показов и исключения конкурентов.

Далее создайте экземпляр PALNonceLoader и добавьте заглушки для двух методов делегата:

@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), заполните его свойства и используйте его для инициализации менеджера одноразовых чисел:

@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.

Внимание: Если вы ранее указывали nonce с помощью параметра paln , настоятельно рекомендуется перейти на givn и прекратить отправку paln . Если указаны оба параметра, поведение системы в отношении того, какой из nonce будет использоваться, будет неопределенным.

Наконец, вам необходимо добавить в 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 должна вызываться при «запуске видеоплеера», когда воспроизведение начинается впервые, в ответ на действие, инициированное пользователем (клик для воспроизведения), или действие, инициированное приложением (автовоспроизведение), sendPlaybackEnd должна вызываться по завершении воспроизведения, а sendAdClick должна вызываться каждый раз, когда зритель кликает на рекламу.

(Необязательно) Отправляйте сигналы Google Ad Manager через сторонние рекламные серверы.

Настройте запрос стороннего рекламного сервера к Ad Manager. После выполнения следующих шагов параметр nonce будет передаваться из PAL SDK через ваши промежуточные серверы, а затем в Google Ad Manager. Это позволит улучшить монетизацию через Google Ad Manager.

Примечание: Если вы используете несколько сторонних решений, например, сторонний SSAI-сервер обращается к другому стороннему рекламному серверу, необходимо убедиться, что зашифрованный nonce из PAL SDK передается каждому стороннему решению.

Настройте сторонний рекламный сервер таким образом, чтобы он включал nonce в запрос к Ad Manager. Вот пример рекламного тега, настроенного на стороннем рекламном сервере:

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

Для получения более подробной информации см. руководство по реализации на стороне сервера Google Ad Manager .

Менеджер рекламы ищет параметр givn= для идентификации значения nonce. Сторонний рекламный сервер должен поддерживать собственный макрос, например %%custom_key_for_google_nonce%% , и заменить его параметром запроса nonce, который вы указали на предыдущем шаге. Более подробная информация о том, как это сделать, должна быть доступна в документации стороннего рекламного сервера.