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

PAL позволяет отправлять сигналы Google в запросах объявлений и во время воспроизведения объявлений.

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

Как добавить Android PAL SDK в качестве библиотеки

Начиная с версии 18.0.0, PAL SDK размещается в репозитории Google Maven. Чтобы добавить его в приложение, выполните следующие действия:

implementation("com.google.android.gms:play-services-pal:23.1.0")
build.gradle

Также PAL SDK можно скачать из репозитория Google Maven и добавить в приложение вручную.

Как включить десахаризацию приложений

В версии 23.0.0 и более поздних для использования PAL необходимо включить десахаризацию приложения, задав значение coreLibraryDesugaringEnabled true и добавив зависимость для com.android.tools:desugar_jdk_libs в файле build.gradle. Подробнее о Java 11+ API, доступных через десахаризацию со спецификацией nio…

coreLibraryDesugaringEnabled = true
build.gradle

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

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

1. Чтобы импортировать и настроить PAL, выполните следующие действия:

   1. Импортировать курсы PAL:

      import com.google.ads.interactivemedia.pal.ConsentSettings;
      import com.google.ads.interactivemedia.pal.NonceLoader;
      import com.google.ads.interactivemedia.pal.NonceManager;
      import com.google.ads.interactivemedia.pal.NonceRequest;
      import com.google.android.gms.tasks.OnFailureListener;
      import com.google.android.gms.tasks.OnSuccessListener;
      import java.util.HashSet;
      import java.util.Set;
      MainActivity.java
      

   2. Создайте частные переменные для хранения экземпляров NonceLoader и NonceManager:

      private NonceLoader nonceLoader;
      private NonceManager nonceManager;
      MainActivity.java
      

   3. Инициализируйте экземпляр NonceLoader с помощью экземпляра ConsentSettings в методе onCreate:

      @Override
      protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);
      
        // 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
        // `ConsentSettings.Builder.forceLimitedAds` property.
        ConsentSettings consentSettings = ConsentSettings.builder().build();
      
        // It is important to instantiate the NonceLoader as early as possible to
        // allow it to initialize and preload data for a faster experience when
        // loading the NonceManager. A new NonceLoader will need to be instantiated
        // if the ConsentSettings change for the user.
        nonceLoader = new NonceLoader(this, consentSettings);
      
        adClickButton = findViewById(R.id.send_click_button);
      
        logView = findViewById(R.id.log_view);
        logView.setMovementMethod(new ScrollingMovementMethod());
      }
      MainActivity.java
      

   В приложении создайте по одному экземпляру класса NonceLoader для каждого сеанса пользователя. Если в вашем приложении несколько страниц или аналогичных элементов, создайте новый экземпляр NonceLoader для каждой страницы или ее аналога. Используя один и тот же экземпляр NonceLoader, вы сохраняете коррелятор страницы &correlator неизменным на протяжении всего времени существования страницы или сеанса пользователя в приложении. При этом вы по-прежнему можете управлять коррелятором потока &scor, который необходимо сбрасывать для каждого нового потока, генерируя новый однократно используемый номер.

   Все запросы объявлений из одного потока должны содержать один и тот же экземпляр NonceLoader и коррелятор потока, чтобы работали функции ограничения частоты показа и конкурентных исключений.

2. Сгенерируйте одноразовый код:

   public void generateNonceForAdRequest(View view) {
     logMessage("Generate Nonce Request");
     Set supportedApiFrameWorksSet = new HashSet();
     // The values 2, 7, and 9 correspond to player support for VPAID 2.0,
     // OMID 1.0, and SIMID 1.1.
     supportedApiFrameWorksSet.add(2);
     supportedApiFrameWorksSet.add(7);
     supportedApiFrameWorksSet.add(9);
   
     NonceRequest nonceRequest =
         NonceRequest.builder()
             .descriptionURL("https://example.com/content1")
             .iconsSupported(true)
             .omidPartnerVersion("6.2.1")
             .omidPartnerName("Example Publisher")
             .playerType("ExamplePlayerType")
             .playerVersion("1.0.0")
             .ppid("testPpid")
             .sessionId("Sample SID")
             .supportedApiFrameworks(supportedApiFrameWorksSet)
             .videoPlayerHeight(480)
             .videoPlayerWidth(640)
             .willAdAutoPlay(true)
             .willAdPlayMuted(false)
             .build();
   
     nonceLoader
         .loadNonceManager(nonceRequest)
         .addOnSuccessListener(
             new OnSuccessListener<NonceManager>() {
               @Override
               public void onSuccess(NonceManager manager) {
                 nonceManager = manager;
                 String nonceString = manager.getNonce();
                 logMessage("Nonce generated");
                 logMessage(nonceString.substring(0, 20) + "...");
                 Log.i(LOG_TAG, "Generated nonce: " + nonceString);
   
                 // From here you would trigger your ad request and move on to initialize content.
                 exampleMakeAdRequest(DEFAULT_AD_TAG + "&givn=" + nonceString);
   
                 adClickButton.setEnabled(true);
               }
             })
         .addOnFailureListener(
             new OnFailureListener() {
               @Override
               public void onFailure(Exception error) {
                 logMessage("Nonce generation failed");
                 Log.e(LOG_TAG, "Nonce generation failed: " + error.getMessage());
               }
             });
   }
   MainActivity.java
   

   Для всех запросов объявлений в одном потоке воспроизведения достаточно одного одноразового кода. Для тестирования вызовите эту функцию, нажав кнопку в тестовом приложении. Параметры NonceRequest, заданные в этом руководстве, являются примерами. Настройте параметры в соответствии с особенностями вашего приложения.

   Эта функция генерирует однократно используемый номер асинхронно. Вам необходимо обрабатывать как успешные, так и неудачные запросы одноразового кода. После того как менеджер nonce станет доступен, получите nonce перед отправкой запроса объявления с помощью метода nonceManager.getNonce().

Как прикрепить одноразовый код к запросу объявления

Чтобы использовать сгенерированное одноразовое число, добавьте к тегу объявления параметр givn и значение одноразового числа перед отправкой запросов объявлений:

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

// From here you would trigger your ad request and move on to initialize content.
exampleMakeAdRequest(DEFAULT_AD_TAG + "&givn=" + nonceString);
MainActivity.java

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

Отслеживание событий воспроизведения

Чтобы отслеживать события воспроизведения, необходимо настроить обработчики событий для отправки рекламных сигналов в Google:

// Triggered when a user clicks-through on an ad which was requested using a PAL nonce.
public void sendAdClick(View view) {
  logMessage("Ad click sent");
  if (nonceManager != null) {
    nonceManager.sendAdClick();
  }
}

// In a typical PAL app, this is called when a user touch or click is detected,
// on the ad other than an ad click-through.
public void onVideoViewTouch(MotionEvent e) {
  if (nonceManager != null) {
    nonceManager.sendAdTouch(e);
  }
}

// In a typical PAL app, this is called when a content playback session starts.
public void sendPlaybackStart() {
  logMessage("Playback start");
  if (nonceManager != null) {
    nonceManager.sendPlaybackStart();
  }
}

// In a typical PAL app, this is called when a content playback session ends.
public void sendPlaybackEnd() {
  logMessage("Playback end");
  if (nonceManager != null) {
    nonceManager.sendPlaybackEnd();
  }
}
MainActivity.java

Ниже описано, когда следует вызывать каждую функцию в вашей реализации.

• sendPlaybackStart(): когда начинается сеанс воспроизведения видео.
• sendPlaybackEnd(): когда сеанс воспроизведения видео завершается.
• sendAdClick(): каждый раз, когда зритель нажимает на объявление;
• sendAdTouch() – при каждом взаимодействии с проигрывателем с помощью касания.

Для тестирования прикрепите методы обработчика событий к событиям клика по кнопке. В рабочей версии приложения настройте события игрока так, чтобы вызывались методы обработчика событий.

Как отправлять сигналы Google Менеджера рекламы через сторонние серверы объявлений (необязательно)

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

Примечание. Если вы используете несколько сторонних решений, например сторонний сервер 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, указанным на предыдущем шаге. Дополнительную информацию о том, как это сделать, можно найти в документации стороннего сервера объявлений.