Erste Schritte

Der erste Schritt besteht darin, Ihrer App das Android PAL SDK hinzuzufügen.

Android PAL SDK als Bibliothek hinzufügen

Ab Version 18.0.0 wird das PAL SDK im Maven-Repository von Google gehostet und kann Ihrer App wie folgt hinzugefügt werden:

app/build.gradle

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

Alternativ kann das PAL SDK aus dem Maven-Repository von Google heruntergeladen und Ihrer App manuell hinzugefügt werden.

Nonce generieren

Eine „Nonce“ ist ein einzelner verschlüsselter String, der von PAL mit NonceLoader generiert wird. Das PAL SDK setzt voraus, dass jede neue Streamanfrage von einer neu generierten Nonce begleitet wird. Nonces können jedoch für mehrere Anzeigenanfragen im selben Stream wiederverwendet werden. Wenn Sie eine Nonce mit dem PAL SDK generieren möchten, nehmen Sie Änderungen an MyActivity.java vor. Wenn Sie eine Beispielanwendung sehen möchten, die PAL zum Generieren einer Nonce verwendet, laden Sie das Android-Beispiel von GitHub herunter.

Zuerst müssen Sie das PAL SDK importieren, einige private Properties erstellen, um NonceLoader und NonceManager zu speichern, und dann NonceLoader initialisieren.

Wir empfehlen, für jede Nutzersitzung in Ihrer Anwendung nur eine Instanz der NonceLoader-Klasse zu erstellen, es sei denn, Ihre Anwendung hat mehrere Seiten oder gleichwertige Konstrukte. Dadurch bleibt der Seitenkorrelator (&correlator) über die Lebensdauer einer Seite oder die Sitzung eines Nutzers in der App unverändert. Sie haben weiterhin die Kontrolle über den Streamkorrelator (&scor), der einmal für jeden neuen Stream zurückgesetzt werden sollte.

Alle Anzeigenanfragen für denselben Stream sollten denselben NonceLoader- und Streamkorrelatorwert haben, damit das Frequency Capping und die Konkurrenzausschluss-Funktionen ordnungsgemäß funktionieren.

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

Erstellen Sie als Nächstes eine Funktion, um die Nonce-Generierung auszulösen. Sie benötigen nur eine Nonce für alle Anzeigenanfragen in einer einzelnen Streamwiedergabe. Zu Testzwecken können Sie diese Funktion aufrufen, wenn Sie auf eine Schaltfläche in Ihrer Test-App klicken.

Diese Funktion löst die Nonce-Generierung asynchron aus. Daher müssen Sie einen AsyncTask implementieren, um den Erfolg oder Fehler der Nonce-Anfrage zu verarbeiten:

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

Nachdem ein Nonce-Manager erstellt wurde, kann die Nonce jederzeit mit nonceManager.getNonce() abgerufen werden.

Nonce an die Anzeigenanfrage anhängen

Wenn Sie die generierte Nonce verwenden möchten, hängen Sie das Anzeigen-Tag mit einem givn-Parameter und dem Nonce-Wert an, bevor Sie Ihre Anzeigenanfragen senden.

Achtung: Wenn Sie zuvor mit dem Parameter paln eine Nonce angegeben haben, wird dringend empfohlen, zu givn zu migrieren und paln nicht mehr zu senden. Wenn beide Parameter enthalten sind, ist das Verhalten undefiniert dazu, welche Nonce verwendet wird.

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

Wiedergabeereignisse verfolgen

Schließlich müssen Sie noch verschiedene Event-Handler für Ihren Player implementieren. Zu Testzwecken können Sie diese Schaltflächen an Klickereignisse anhängen, in einer echten Implementierung werden sie jedoch durch die entsprechenden Player-Ereignisse ausgelöst:

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

Wann die einzelnen Funktionen in Ihrer Implementierung aufgerufen werden sollten:

• sendPlaybackStart(): Beginn der Videowiedergabe
• sendPlaybackEnd(): Wenn die Videowiedergabe zu Ende ist
• sendAdClick(): Jedes Mal, wenn der Zuschauer auf eine Anzeige klickt
• sendTouch(): bei jeder Berührung mit dem Player

Optional: Google Ad Manager-Signale über Ad-Server eines Drittanbieters senden

Wenn Sie den Ad-Server eines Drittanbieters für Google Ad Manager einrichten, lesen Sie in der Dokumentation Ihres Servers nach, wie Sie den Nonce-Wert in jeder Anzeigenanfrage erfassen und weiterleiten. Das Beispiel zeigt eine Anzeigenanfrage-URL mit dem Parameter nonce. Der Nonce-Parameter wird vom PAL SDK über Ihre Zwischenserver und anschließend an Ad Manager weitergegeben, was eine bessere Monetarisierung ermöglicht.

Hinweis: Wenn Sie mehrere Drittanbieterlösungen verwenden, z. B. wenn ein Drittanbieter-SSAI-Server einen anderen Ad-Server eines Drittanbieters aufruft, müssen Sie dafür sorgen, dass die verschlüsselte Nonce des PAL SDK an jeden Drittanbieter weitergeleitet wird.

Konfigurieren Sie den Ad-Server eines Drittanbieters so, dass die Nonce in die Serveranfrage an Ad Manager aufgenommen wird. Hier sehen Sie ein Beispiel für ein Anzeigen-Tag, das im Ad-Server eines Drittanbieters konfiguriert wird:

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

Weitere Informationen finden Sie im Google Ad Manager-Leitfaden zur serverseitigen Implementierung.

In Ad Manager wird nach givn= gesucht, um den Nonce-Wert zu ermitteln. Der Ad-Server des Drittanbieters muss ein eigenes Makro unterstützen, z. B. %%custom_key_for_google_nonce%%, und durch den Nonce-Abfrageparameter ersetzen, den Sie im vorherigen Schritt angegeben haben. Weitere Informationen dazu finden Sie in der Dokumentation des Ad-Servers des Drittanbieters.