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
:
22.1.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. The NonceRequest
parameters set here are example parameters. You should set your
parameters based on your own app characteristics.
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
();
// 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
());
}
}
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.
/**
* 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.
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.
