Get Started

The first step is to add the Android PAL SDK to your app.

Add the Android PAL SDK as a library

As of version 18.0.0, the PAL SDK is hosted on Google's Maven repository and can be added to your app as follows:

app/build.gradle

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

Alternatively, the PAL SDK can be downloaded from Google's Maven repository and manually added to your app.

Generate nonce

A "nonce" is a single encrypted string generated by PAL using the NonceLoader. The PAL SDK requires each new stream request to be accompanied by a newly generated nonce. However, nonces can be reused for multiple ad requests within the same stream. To generate a nonce using the PAL SDK, make changes to MyActivity.java. To see a sample app that uses PAL to generate a nonce, download the Android example from GitHub.

You first need to import the PAL SDK, create some private properties to store your NonceLoader and NonceManager, and then initialize your NonceLoader.

We recommend that you create only one instance of the NonceLoader class for each user session in your app unless your app has multiple pages or equivalent constructs. This keeps the page correlator (&correlator) unchanged for the lifetime of a page or a user's session on the app. You still have control over the stream correlator (&scor) which should be reset once for each new stream.

All ad requests of the same stream should share the same NonceLoader and stream correlator value for frequency capping and competitive exclusion features to work properly.

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

Next, create a function to trigger nonce generation. You only need one nonce for all the ad requests in a single stream playback. For testing purposes, you can call this function when clicking a button in your test app.

This function triggers nonce generation asynchronously, so you need to implement an AsyncTask to handle success or failure of the nonce request:

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

Once a nonce manager is created, the nonce can be retrieved at any time using nonceManager.getNonce().

Attach nonce to the ad request

To use the generated nonce, append your ad tag with a givn parameter and the nonce value before making your ad requests.

Caution: If you previously provided a nonce using the paln parameter, it is strongly recommended to migrate to givn and stop sending paln. If both parameters are included, it is undefined behavior regarding which nonce one is used.

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

Track playback events

Lastly, you need to implement various event handlers for your player. For testing purposes, you can attach these to button click events, but in a real implementation, these would be triggered by the appropriate player events:

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

Here is when to call each function in your implementation:

• sendPlaybackStart(): When your video playback session begins
• sendPlaybackEnd(): When your video playback session comes to an end
• sendAdClick(): Each time the viewer clicks an ad
• sendTouch(): On every touch interaction with the player

(Optional) Send Google Ad Manager signals through third-party ad servers

When you set up your third-party ad server to work with Google Ad Manager, refer to your server's documentation to capture and forward the nonce value in each ad request. The provided example is of an ad request URL with the nonce parameter included. The nonce parameter propagates from the PAL SDK, through your intermediary servers, and then to Ad Manager, enabling better monetization.

Note: If you use multiple third-party solutions, for example, a third-party SSAI server calling another third-party ad server, you need to make sure the PAL SDK's encrypted nonce is forwarded to each third party.

Configure your third-party ad server to include the nonce in the server's request to Ad Manager. Here's an example of an ad tag configured inside of the third-party ad server:

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

For more details, see the Google Ad Manager Server-side implementation guide.

Ad Manager looks for givn= to identify the nonce value. The third-party ad server needs to support some macro of its own, such as %%custom_key_for_google_nonce%%, and replace it with the nonce query parameter you provided in the previous step. More information on how to accomplish this should be available in the third-party ad server's documentation.