Начало работы

Требования

• Xcode 13 или более поздней версии

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

Как добавить PAL SDK в проект

Как установить PAL SDK с помощью Swift Package Manager

Начиная с версии 2.5.3, Programmatic Access Library SDK поддерживает Swift Package Manager. Чтобы импортировать пакет Swift, выполните следующие действия:

1. В Xcode установите пакет IMA SDK Swift, выбрав File (Файл) > Add Packages (Добавить пакеты).

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

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

3. Выберите версию пакета Swift PAL SDK, которую вы хотите использовать. Для новых проектов мы рекомендуем использовать вариант До следующей основной версии.

Когда все будет готово, Xcode начнет распознавать зависимости пакета и скачивать их в фоновом режиме. Подробнее о том, как добавить зависимости пакетов, можно узнать из статьи Apple.

Как вручную скачать и установить PAL SDK

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

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

Как сгенерировать одноразовый код

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

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

Чтобы запросить одноразовый код, сначала импортируйте библиотеку 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, заполните его свойства и используйте его для инициализации менеджера 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. Однократно используемое число не требует кодирования при добавлении в URL.

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

Если вы запрашиваете и показываете объявления Google, то должны отображать значок и оверлей AdChoices. Подробнее о том, как анализировать ответ VAST и отображать значки, рассказывается в статье Значок "Выбор рекламы" и оверлей.

Наконец, вам нужно добавить методы для отправки в 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 Менеджера рекламы через сторонние серверы объявлений (необязательно)

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

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

Настройте сторонний сервер объявлений так, чтобы он включал одноразовый код в запрос к Менеджеру рекламы. Вот пример тега объявления, настроенного на стороннем сервере объявлений:

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

Подробнее о реализации на стороне сервера в Google Менеджере рекламы…

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