Rozpocznij

PAL umożliwia wysyłanie sygnałów reklam Google w żądaniach reklamy i podczas odtwarzania reklam.

Ten przewodnik zawiera informacje o dodawaniu pakietu Android PAL SDK do aplikacji. Aby zobaczyć przykładową aplikację, która używa PAL do generowania liczby jednorazowej, pobierz przykład na Androida z GitHub.

Dodawanie pakietu SDK PAL na Androida jako biblioteki

Od wersji 18.0.0 pakiet SDK PAL jest hostowany w repozytorium Maven Google i można go dodać do aplikacji w ten sposób:

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

Pakiet SDK PAL można też pobrać z repozytorium Google Maven i ręcznie dodać do aplikacji.

Włączanie desugaryzacji aplikacji

Od wersji 23.0.0 system PAL wymaga włączenia odcukrzania aplikacji przez ustawienie coreLibraryDesugaringEnabled true i dodanie zależności do com.android.tools:desugar_jdk_libs w pliku build.gradle. Więcej informacji znajdziesz w artykule Interfejsy API Java 11+ dostępne dzięki odcukrzaniu ze specyfikacją nio.

coreLibraryDesugaringEnabled = true

Generowanie wartości nonce

Wartość nonce to pojedynczy zaszyfrowany ciąg tekstowy generowany przez PAL za pomocą NonceLoaderklasy. PAL wymaga, aby każdemu żądaniu strumienia towarzyszył niepowtarzalny identyfikator nonce. Możesz jednak ponownie użyć wartości nonce w przypadku wielu żądań reklam w tym samym strumieniu. Aby wygenerować wartość nonce za pomocą pakietu SDK PAL, wprowadź te zmiany, aby zaimportować i skonfigurować PAL oraz utworzyć funkcję generowania wartości nonce:

  1. Aby zaimportować i skonfigurować PAL:

    1. Importowanie zajęć 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;

    2. Utwórz zmienne prywatne do przechowywania instancji NonceLoader i NonceManager:

      private NonceLoader nonceLoader;
private NonceManager nonceManager;

    3. Zainicjuj instancję NonceLoader za pomocą instancji ConsentSettings w metodzie 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());
}

    W aplikacji utwórz po 1 instancji klasy NonceLoader dla każdej sesji użytkownika. Jeśli Twoja aplikacja ma wiele stron lub podobnych elementów, utwórz nowy obiekt NonceLoader dla każdej strony lub elementu. Używając tego samego wystąpienia NonceLoader, zachowujesz korelację strony &correlator niezmienioną przez cały czas istnienia strony lub sesji użytkownika w aplikacji. Nadal masz kontrolę nad korelacją strumienia &scor, którą musisz zresetować w przypadku każdego nowego strumienia, generując nowy nonce.

    Wszystkie żądania reklam w tym samym strumieniu muszą mieć tę samą instancję NonceLoader i wartość korelatora strumienia, aby można było korzystać z funkcji ograniczenia liczby wyświetleń i wykluczeń konkurencji.

  2. Wygeneruj nonce:

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

    W przypadku wszystkich żądań reklamy w ramach odtwarzania pojedynczego strumienia wystarczy jedna liczba jednorazowa. Na potrzeby testowania wywołaj tę funkcję po kliknięciu przycisku w aplikacji testowej. Parametry NonceRequest podane w tym przewodniku są przykładowe. Ustaw parametry na podstawie cech własnej aplikacji.

    Ta funkcja generuje wartość nonce asynchronicznie. Musisz obsługiwać zarówno przypadki powodzenia, jak i niepowodzenia żądania liczby jednorazowej. Gdy menedżer nonce jest dostępny, pobierz nonce przed wysłaniem żądania reklamy za pomocą metody nonceManager.getNonce().

Dołączanie wartości nonce do żądania reklamy

Aby użyć wygenerowanej wartości nonce, przed wysłaniem żądań reklamy dołącz do tagu reklamy parametr givn i wartość nonce:

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

Jeśli wysyłasz żądania reklam do Google i je renderujesz, musisz renderować ikonę i nakładkę AdChoices. Szczegółowe informacje o analizowaniu odpowiedzi VAST i renderowaniu ikon znajdziesz w sekcji Ikona Informacja i nakładka.

Śledzenie zdarzeń odtwarzania

Aby śledzić zdarzenia odtwarzania, musisz skonfigurować procedury obsługi zdarzeń, które będą wysyłać sygnały reklamowe do 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();
  }
}

Oto, kiedy należy wywoływać poszczególne funkcje w implementacji:

  • sendPlaybackStart(): gdy rozpoczyna się sesja odtwarzania filmu;
  • sendPlaybackEnd(): po zakończeniu sesji odtwarzania filmu;
  • sendAdClick(): za każdym razem, gdy widz kliknie reklamę;
  • sendAdTouch(): przy każdej interakcji dotykowej z odtwarzaczem;

Na potrzeby testowania dołącz metody obsługi zdarzeń do zdarzeń kliknięcia przycisku. W implementacji produkcyjnej skonfiguruj aplikację tak, aby w przypadku zdarzeń odtwarzacza wywoływała metody modułu obsługi zdarzeń.

(Opcjonalnie) Wysyłanie sygnałów Google Ad Managera przez serwery reklamowe firm zewnętrznych

Podczas konfigurowania serwera reklamowego firmy zewnętrznej do współpracy z Google Ad Managerem zapoznaj się z dokumentacją serwera, aby przechwytywać i przekazywać wartość nonce w każdym żądaniu reklamy. Podany przykład to adres URL żądania reklamy z parametrem nonce. Parametr nonce jest przekazywany z pakietu PAL SDK przez serwery pośredniczące do Ad Managera, co umożliwia lepsze zarabianie.

Skonfiguruj serwer reklamowy firmy zewnętrznej tak, aby w żądaniu wysyłanym do Ad Managera uwzględniał wartość nonce. Oto przykład tagu reklamy skonfigurowanego na serwerze reklamowym firmy zewnętrznej:

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

Więcej informacji znajdziesz w przewodniku po implementacji po stronie serwera w Google Ad Managerze.

Ad Manager szuka znaku givn=, aby zidentyfikować wartość nonce. Serwer reklamowy firmy zewnętrznej musi obsługiwać własne makro, np. %%custom_key_for_google_nonce%%, i zastąpić je parametrem zapytania nonce podanym w poprzednim kroku. Więcej informacji o tym, jak to zrobić, znajdziesz w dokumentacji serwera reklam firmy zewnętrznej.