Rozpocznij

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

Z tego przewodnika dowiesz się, jak dodać do aplikacji pakiet PAL SDK na Androida. Aby zobaczyć przykładową aplikację, która używa PAL do generowania wartości nonce, pobierz przykład na Androida z GitHub.

Dodawanie pakietu SDK PAL na Androida jako biblioteki

Od wersji 18.0.0 pakiet PAL SDK 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:22.1.0'
build.gradle

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

Generowanie wartości nonce

Wartość nonce to pojedynczy zaszyfrowany ciąg znaków generowany przez PAL za pomocą klasy NonceLoader. PAL wymaga, aby każdemu żądaniu strumienia towarzyszył unikalny nonce. Możesz jednak używać nonce w wielu żądaniach reklamy w tym samym strumieniu. Aby wygenerować wartość nonce za pomocą pakietu PAL SDK, wprowadź te zmiany w importowaniu i konfigurowaniu pakietu PAL oraz utwórz funkcję generowania wartości nonce:

  1. Aby zaimportować i skonfigurować PAL, wykonaj te czynności:

    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;

      MainActivity.java

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

      private NonceLoader nonceLoader;
private NonceManager nonceManager;
      MainActivity.java

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

  // The default value for allowStorage() is false, but can be
  // changed once the appropriate consent has been gathered. The
  // getConsentToStorage() method is a placeholder for the publisher's own
  // method of obtaining user consent, either by integrating with a CMP or
  // based on other methods the publisher chooses to handle storage consent.
  boolean isStorageAllowed = getConsentToStorage();

  ConsentSettings consentSettings =
      ConsentSettings.builder().allowStorage(isStorageAllowed).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

    W aplikacji utwórz po jednej 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 podobnego elementu. Używając tego samego wystąpienia NonceLoader, zachowujesz korelację strony &correlator bez zmian przez cały czas trwania 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 reklamy 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 wykluczania konkurencji.

  2. Wygeneruj wartość 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());
            }
          });
}

    MainActivity.java

    W przypadku wszystkich żądań reklam w ramach odtwarzania pojedynczego strumienia wystarczy jeden ciąg losowy. Na potrzeby testów wywołaj tę funkcję, gdy klikniesz przycisk w aplikacji testowej. Parametry NonceRequest podane w tym przewodniku są przykładowe. Ustaw parametry na podstawie charakterystyki swojej 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);
MainActivity.java

Śledzenie zdarzeń odtwarzania

Aby śledzić zdarzenia odtwarzania, musisz skonfigurować procedury obsługi zdarzeń, które będą wysyłać do Google sygnały reklamowe:

// 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

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ę;
  • sendTouch(): 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ę pod kątem zdarzeń odtwarzacza, aby wywoływać 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 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 wysyłanym do Ad Managera żądaniu 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 symbolu 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 reklamowego firmy zewnętrznej.