Rozpocznij

Pierwszym krokiem jest dodanie do aplikacji pakietu Android PAL SDK.

Dodawanie pakietu Android PAL SDK jako biblioteki

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

app/build.gradle

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

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

Wygeneruj liczbę jednorazową

Argument „jednorazowa” to pojedynczy zaszyfrowany ciąg znaków wygenerowany przez platformę PAL za pomocą metody NonceLoader. Pakiet PAL SDK wymaga, aby każde nowe żądanie strumienia znajdowało się w nowo wygenerowanej liczbie jednorazowej. Jednorazowych możesz jednak używać wielokrotnie na potrzeby wielu żądań reklam w tym samym strumieniu. Aby wygenerować liczbę jednorazową za pomocą pakietu PAL SDK, wprowadź zmiany w MyActivity.java. Aby zobaczyć przykładową aplikację, która używa platformy PAL do generowania liczby jednorazowej, pobierz z GitHub przykładową aplikację na Androida.

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

Zalecamy utworzenie tylko jednej instancji klasy NonceLoader na potrzeby każdej sesji użytkownika w aplikacji, chyba że aplikacja ma wiele stron lub równoważne konstrukcje. Dzięki temu korelator strumienia (&correlator) pozostaje niezmieniony przez cały czas istnienia strony lub sesji użytkownika w aplikacji. Nadal masz kontrolę nad korelatorem strumieni (&scor), który należy zresetować raz przy każdym nowym strumieniu.

Aby funkcje ograniczania liczby wyświetleń i wykluczania konkurencji działały prawidłowo, wszystkie żądania reklam z tego samego strumienia powinny mieć tę samą wartość parametru NonceLoader i 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ę aktywującą generowanie liczb jednorazowych. Potrzebujesz tylko 1 liczby jednorazowej na wszystkie żądania reklam w ramach pojedynczego odtworzenia strumienia. Do celów testowych możesz wywoływać tę funkcję po kliknięciu przycisku w aplikacji testowej.

Ta funkcja aktywuje asynchronicznie generowanie kodów jednorazowych, więc musisz wdrożyć AsyncTask do obsługi skutecznego lub nieudanego żądania liczby jednorazowej:

public void generateNonceForAdRequest() {
  Set supportedApiFrameWorksSet = new HashSet();
  supportedApiFrameWorksSet.add(2);
  supportedApiFrameWorksSet.add(7);
  supportedApiFrameWorksSet.add(9);

  NonceRequest nonceRequest = NonceRequest.builder()
      .descriptionURL("https://example.com/content1")
      .iconsSupported(true)
      .omidVersion("1.0.0")
      .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(true)
      .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 liczb jednorazowych można ją pobrać w każdej chwili za pomocą funkcji nonceManager.getNonce().

Dołącz liczbę jednorazową do żądania reklamy

Aby użyć wygenerowanej liczby jednorazowej, przed wysłaniem żądań reklamy dołącz do tagu reklamy parametr givn i wartość jednorazową.

Uwaga: jeśli liczba jednorazowa była wcześniej podana za pomocą parametru paln, zdecydowanie zalecamy przejście na givn i zaprzestanie wysyłania paln. Jeśli uwzględnisz oba parametry, nie będzie można określić, która liczba jednorazowa zostanie użyta.

/**
 * 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);
}

Śledź zdarzenia odtwarzania

Na koniec musisz zaimplementować różne moduły obsługi zdarzeń dla odtwarzacza. Do celów testowych możesz dołączać je 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);
  }
}

Kiedy należy wywoływać poszczególne funkcje w implementacji:

• sendPlaybackStart(): po rozpoczęciu sesji odtwarzania filmu
• sendPlaybackEnd(): po zakończeniu sesji odtwarzania filmu
• sendAdClick(): za każdym razem, gdy widz kliknie reklamę
• sendTouch(): przy każdej interakcji z odtwarzaczem

(Opcjonalnie) Wysyłanie sygnałów do Google Ad Managera za pomocą serwerów reklamowych firm zewnętrznych

Podczas konfigurowania zewnętrznego serwera reklam do współpracy z Google Ad Managerem zapoznaj się z dokumentacją serwera, aby przechwycić i przekierować wartość jednorazową w każdym żądaniu reklamy. Podany przykład to URL żądania reklamy z dołączonym parametrem jednorazowym. Parametr jednorazowy jest przesyłany z pakietu SDK PAL przez serwery pośredniczące, a następnie do Ad Managera, co zwiększa przychody.

Uwaga: jeśli korzystasz z wielu rozwiązań innych firm, np. z serwera SSAI innej firmy wywołującego inny serwer reklamowy firmy zewnętrznej, musisz się upewnić, że zaszyfrowana liczba jednorazowa z pakietu PAL SDK jest przekazywana do każdej firmy zewnętrznej.

Skonfiguruj serwer reklamowy firmy zewnętrznej tak, by uwzględniał liczbę jednorazową w żądaniu serwera wysyłanym do Ad Managera. 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 Google Ad Managera.

Ad Manager wyszukuje wartość givn=, aby zidentyfikować wartość jednorazową. Zewnętrzny serwer reklamowy musi obsługiwać własne makro, np. %%custom_key_for_google_nonce%%, i zastąpić je parametrem zapytania jednorazowym podanym w poprzednim kroku. Więcej informacji na ten temat można znaleźć w dokumentacji serwera reklamowego firmy zewnętrznej.