Zacznij

Pierwszym krokiem jest dodanie do aplikacji pakietu SDK Android PAL.

Dodawanie pakietu SDK PAL na Androida jako biblioteki

Od wersji 18.0.0 pakiet SDK PAL jest hostowany w repozytorium Maven Google i może zostać dodany do aplikacji w ten sposób:

app/build.gradle

...
dependencies {
    implementation 'com.google.android.gms:play-services-pal:22.0.0'
    ...
}

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

Generowanie identyfikatora nonce

„Nonce” to pojedynczy zaszyfrowany ciąg wygenerowany przez PAL za pomocą NonceLoader. Pakiet SDK PAL wymaga, aby każde nowe żądanie strumienia było poprzedzone nowo wygenerowanym identyfikatorem nonce. Jednak w ramach tego samego strumienia można używać tych samych wartości nonce do wielu żądań reklamy. Aby wygenerować nonce za pomocą pakietu PAL SDK, wprowadź zmiany w pliku MyActivity.java. Aby zobaczyć przykładową aplikację, która używa PAL do generowania nonce, pobierz przykład na Androida z GitHub.

Najpierw musisz zaimportować pakiet SDK PAL, utworzyć prywatne właściwości do przechowywania wartości NonceLoader i NonceManager, a następnie zainicjować NonceLoader.

Zalecamy tworzenie tylko 1 wystąpieni klasy NonceLoader na każdą sesję użytkownika w aplikacji, chyba że aplikacja ma wiele stron lub równoważnych konstrukcji. Dzięki temu korelator strony (&correlator) pozostaje niezmieniony przez cały czas istnienia strony lub sesji użytkownika w aplikacji. Nadal masz kontrolę nad korelatorem strumienia (&scor), który należy zresetować po każdym nowym strumieniu.

Aby funkcje ograniczenia liczby wyświetleń i wykluczenia konkurencji działały prawidłowo, wszystkie żądania reklam z tego samego strumienia powinny mieć tę samą wartość NonceLoader i tą samą wartość korelatora strumienia.

import android.app.Activity;
import android.os.Bundle;
import com.google.ads.interactivemedia.pal.NonceLoader;
import com.google.ads.interactivemedia.pal.NonceManager;
import com.google.ads.interactivemedia.pal.NonceRequest;
import com.google.ads.interactivemedia.pal.ConsentSettings;
import com.google.android.gms.tasks.OnFailureListener;
import com.google.android.gms.tasks.OnSuccessListener;

import java.util.HashSet;
import java.util.Set;

public class MainActivity extends Activity {
...
  private NonceLoader nonceLoader;
  private NonceManager nonceManager = null;
  private ConsentSettings consentSettings;

  @Override
  protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    // 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 isConsentToStorage = getConsentToStorage();

    videoView = findViewById(R.id.video_view);
    videoView.setOnTouchListener(this::onVideoViewTouch);

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

Następnie utwórz funkcję, która spowoduje wygenerowanie nonce. Wystarczy jeden losowy ciąg znaków dla wszystkich żądań reklamy w ramach jednego odtwarzania strumienia. W celu przetestowania możesz wywołać tę funkcję po kliknięciu przycisku w aplikacji testowej. Tutaj ustawione parametry NonceRequest to parametry przykładowe. Parametry należy ustawić na podstawie cech Twojej aplikacji.

Ta funkcja powoduje asynchroniczne generowanie nonce, więc musisz zaimplementować AsyncTask, aby obsłużyć powodzenie lub niepowodzenie żądania nonce:

public void generateNonceForAdRequest() {
  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();
  NonceCallbackImpl callback = new NonceCallbackImpl();
  nonceLoader
      .loadNonceManager(nonceRequest)
      .addOnSuccessListener(callback)
      .addOnFailureListener(callback);
}

private class NonceCallbackImpl implements OnSuccessListener<NonceManager>, OnFailureListener {
  @Override
  public void onSuccess(NonceManager manager) {
    nonceManager = manager;
    String nonceString = manager.getNonce();
    Log.i("PALSample", "Generated nonce: " + nonceString);
    // from here you would trigger your ad request and move on to initialize content
  }

  @Override
  public void onFailure(Exception error) {
    Log.e("PALSample", "Nonce generation failed: " + error.getMessage());
  }
}

Po utworzeniu menedżera wartości cząstkowych można je w dowolnym momencie pobrać za pomocą funkcji nonceManager.getNonce().

Załączanie nonce do żądania reklamy

Aby użyć wygenerowanego identyfikatora nonce, przed wysłaniem żądań reklamy dodaj do tagu reklamy parametr givn i wartość nonce.

Uwaga: jeśli wcześniej przesłano liczbę jednorazową za pomocą parametru paln, zdecydowanie zalecamy przejście na parametr givn i zaprzestanie wysyłania parametru paln. Jeśli podasz oba parametry, nieokreślone jest, który z nich zostanie użyty.

/**
 * The ad tag for your ad request, for example:
 * https://pubads.g.doubleclick.net/gampad/ads?sz=640x480&iu=/124319096/external\
 * /single_ad_samples&ciu_szs=300x250&impl=s&gdfp_req=1&env=vp&output=vast&unviewed_position_start=1\
 * &cust_params=deployment%3Ddevsite%26sample_ct%3Dlinear&correlator=
 *
 * For more sample ad tags, see
 * developers.google.com/interactive-media-ads/docs/sdks/html5/client-side/tags
 */
private static final String DEFAULT_AD_TAG = "Your ad tag";
...
@Override
public void onSuccess(NonceManager manager) {
  nonceManager = manager;
  String nonceString = manager.getNonce();
  Log.i("PALSample", "Generated nonce: " + nonceString);
  // Append the nonce to the ad tag URL.
  makeAdRequest(DEFAULT_AD_TAG + "&givn=" + nonceString);
}

Śledzenie zdarzeń odtwarzania

Na koniec musisz zaimplementować różne moduły obsługi zdarzeń dla odtwarzacza. W celu przetestowania możesz je dołączyć do zdarzeń kliknięcia przycisku, ale w rzeczywistej implementacji będą one wywoływane przez odpowiednie zdarzenia odtwarzacza:

public void sendAdClick() {
  if (nonceManager != null) {
    nonceManager.sendAdClick();
  }
}

public void sendPlaybackStart() {
  if (nonceManager != null) {
    nonceManager.sendPlaybackStart();
  }
}

public void sendPlaybackEnd() {
  if (nonceManager != null) {
    nonceManager.sendPlaybackEnd();
  }
}

public void onVideoViewTouch(MotionEvent e) {
  if (nonceManager != null) {
    nonceManager.sendTouch(e);
  }
}

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

• sendPlaybackStart(): gdy rozpoczyna się sesja odtwarzania filmu
• sendPlaybackEnd(): gdy sesja odtwarzania filmu dobiegnie końca
• sendAdClick(): za każdym razem, gdy widz klika reklamę
• sendTouch(): przy każdym dotknięciu odtwarzacza

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

Gdy skonfigurujesz serwer reklam zewnętrznych do współpracy z Google Ad Manager, zapoznaj się z dokumentacją serwera, aby rejestrować 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 lepszą monetyzację.

Uwaga: jeśli korzystasz z wielu rozwiązań firm zewnętrznych, np. serwera SSAI firmy zewnętrznej wywołującego inny serwer reklamowy firmy zewnętrznej, musisz się upewnić, że zaszyfrowany nonce w SDK usługi PAL jest przekazywany do każdej firmy zewnętrznej.

Skonfiguruj serwer reklamowy firmy zewnętrznej, aby uwzględniał wartość nonce w żądaniu wysyłanym do Ad Managera. Oto przykład tagu reklamy skonfigurowanego w 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 wyszukuje wartość givn=, aby zidentyfikować wartość nonce. Serwer reklam zewnętrzny musi obsługiwać własne makro, np. %%custom_key_for_google_nonce%%, i zastępować je parametrem zapytania nonce podanym w poprzednim kroku. Więcej informacji o tym, jak to zrobić, powinno być dostępnych w dokumentacji serwera reklamowego firmy zewnętrznej.