ERIN WALSH: Hello.
My name is Erin, and I'm a developer relations engineer
on the Privacy Sandbox team here at Google.
In this video, I will show you how
to get started with testing the Attribution Reporting API.
Before watching this video, you should
get familiar with the Attribution Reporting API
by reading the design proposal, which is linked below
in the video description.
The design proposal provides an overview
of the API and its uses.
In this video, you will learn the basics of the Attribution
Reporting API by setting up and running the provided sample app
and server spec.
To do this, you will set up a development environment
for the Privacy Sandbox, mock an Attribution Reporting server,
register a source and a trigger in the Attribution Reporting
sample app, receive an event level and aggregate report.
Let's get started.
Let's begin by setting up your development environment
to use the Privacy Sandbox.
First, you'll need to have Android Studio installed.
You will also need to have the latest versions of the Privacy
Sandbox SDK and device images installed.
To do this, open up the SDK Manager in Android Studio,
download the latest Privacy Sandbox SDK and device images,
and click Apply.
Developers may test using a test device, but for this example,
you will need to use an emulator that
has been created with the Privacy Sandbox emulator image.
To create one, open up the Virtual Device Manager.
Click the Create Device button.
Privacy Sandbox APIs are shipped only
with the device definition with the Play Store.
This is indicated by the icon in the Play Store column.
Here you can see that the Pixel 4 has a device definition,
so that's what I will choose.
Click Next, and it takes you to the system image page.
Select the Privacy Sandbox system
image that you downloaded earlier, then click Next again.
Give your device a new name if you wish.
I'll call my attribution test device.
And click Finish to create your emulator.
Next, go to the Privacy Sandbox sample's GitHub page.
Click the Attribution Reporting folder.
Here there are three folders that you
can use to run an end-to-end example of Attribution
Reporting.
The first, MeasurementAdTechServer,
is a Spring Boot-based application
that you can use to run a standalone microservice.
The MeasurementAdTechServerSpec folder
contains open API JSON specs that
can be used to mock a server for testing.
And the MeasurementSampleApp folder
contains the code for your sample Android app.
For this example, you'll be mocking a server for testing.
Click into the MeasurementAdTechServerSpec
folder, then open up the MeasurementAdTechServerSpec
JSON file.
Click the Raw button at the top of the file contents.
Then right-click the page and select Save As.
There are many tools online you can
use to mark a server using open API for testing purposes.
For this demonstration, I'm going to be using Postman,
but feel free to use whichever tool
you're most comfortable with.
Import the MeasurementAdTechServerSpec
JSON file you just saved into your tool of choice.
In your tool, you'll be able to view
the MeasurementAdTechServerSpec as a collection of requests.
Let's take a look at each of the endpoints.
Here you have an example endpoint
to register a source, such as a click or view,
and an example endpoint to register a trigger,
such as a conversion.
You can call just an endpoint or add one or more
optional parameters to the URL.
If you're using the provided example server,
the endpoint does not need to be enrolled,
but for your own server, you will
need to enroll your endpoints.
In this example, let's say you want
to pass in campaign information associated with the source,
so you add the optional parameter for an identifier
to the end of the register source URL, a shown highlighted
in yellow.
Let's say you also want to add conversion information
associated with the trigger, so you
add an optional parameter for an identifier
at the end of the register trigger your URL,
also highlighted in yellow.
You also have an endpoint which will
be used to deliver an event report,
an endpoint to deliver an aggregate report.
These reports are available only after the user views, clicks,
or converts.
You will simulate those events a little later in the demo.
Now that you've walked through a mock server setup, let's look
at the provided example app.
Go ahead and clone the Privacy Sandbox GitHub repo.
After you have cloned the GitHub repo,
open up the measurement sample app project in Android Studio.
Go ahead and run the project on the emulator
you created earlier.
The first thing you need to do is
configure the server URL and the sample
app with the URL of the mock server that you just created.
To do this, click the overflow menu
in the upper right-hand corner of the sample app
and select Server URL.
Then open up your tool of choice to view your mock server.
My mock URL looks something like this.
Copy your mock URL and then switch back
to your emulator window.
Enter in the mock URL you just copied.
An easy way to do this is by using your terminal
and typing the command adb shell input text, and then the URL
that you want to use.
Once your URL is in the text field, click Save.
Let's look at the screens of the sample app.
The first screen represents what could
happen when a user sees or clicks
an advertisement in your application, otherwise known
as registering a source.
In this example, let's say the user
has clicked the advertisement.
So to simulate that, you will click the Register Click Event
button.
You'll see a toast that lets us know
that the API has been called.
You can configure the source register
ID to be another value if you'd like,
but let's leave it at 1 for this example.
Now let's say that, after clicking the advertisement,
the user went on to purchase the product being advertised.
The tab on the bottom right shows a screen
that represents what happens when
a conversion, like the one in this example, is made--
otherwise known as registering a trigger.
To simulate the conversion, click the Register Trigger
button and see the toast confirming the API call.
You could configure the conversion registration ID
to be another value, but in this example, let's leave it at 1.
Now that you've seen where sources and triggers are
registered in the UI, let's take a look at the sample app code.
The MeasurementViewModel class hosts the methods
you need in order to use the Attribution Reporting
API to register our sources and triggers.
Here in the MeasurementViewModel's
registerSource function, you use the injected measurementManager
object to invoke its registers force function.
You are passing at the base URL, which
is concatenated with backslash source,
as defined in the MeasurementAdTechServerSpec,
and an identifier as a parameter.
You also pass in an optional inputEvent.
You also have the registerTrigger function,
where you invoke measurementManager's
registerTrigger function and pass it the [INAUDIBLE] URL,
this time concatenated with backslash trigger,
as defined in the MeasurementAdTechServerSpec,
and an identifier as a parameter.
Now let's look at the UI.
In the source fragment of the sample app,
you invoke the measurementViewModel's
registerSource function and the click listener
that is attached to the Register Click Event button.
You also pass the source registration
ID that you can configure in the text field of this page.
Similarly, in the TriggerFragment,
you invoke measurementViewModel's
registerTrigger function in the click listener that
is attached to the registered trigger button
and the conversion ID that you can configure
in the text field of this page.
Now that your hypothetical user has
clicked through an advertisement and purchased the item,
you have registered the source and the trigger
of that purchase.
You'll want to receive an event level and aggregate
report of these interactions.
These reports are generated in a time window that is
set in the attribution service.
You can read more about expiry windows in the design proposal.
In this example, your reports will be generated in two days.
You can see this in the register source response header
in the MeasurementAdTechServerSpec
JSON file.
You don't want to actually wait two days to finish your test,
so you'll simulate the time window.
You will need the adb commands that you
can find in the readme file of the sample app.
First, you open up a terminal and run the first command
to force the AttributionJobService.
Then you open the emulator window
and click Settings, System, Date and Time,
and untoggle Set Time Automatically.
Click Date and change the date to be three days forward.
Return to your terminal window and run the second adb command
to force the event level reporting job service.
Finally, run the third adb command
to force the aggregate reporting job service.
Then return to your tool of choice
to look at the traffic on your mock server.
Here you can see the calls you have made
to register source and trigger.
You also see the event level in aggregate reports
returned by the attribution server mock
that we set up earlier.
Let's take a closer look at the event level report.
In the request body, attribution_destination
refers to the app that the event happened in-- in this case,
your measurement sample app.
The source_event_id refers to the ad
which led to this report.
The trigger_data field holds the trigger metadata,
which is low fidelity data for the clicks reviews.
The source_type refers to whether the interaction
is a click or view.
The value navigation is shown here,
which corresponds to a click.
The randomized_trigger_rate is a noise parameter
for adding noise to event reports.
Let's also take a look at the aggregate report.
In the request body, you see the attribution_destination,
which also refers to where the event happened--
in this case, your sample app.
Also take a look at the reporting_origin,
which refers to the adtech URL where the report was sent.
And that concludes our introduction
to the Attribution Reporting API.
You should now have an understanding
of how to test the Attribution Reporting API,
set up source and trigger registration, and receive event
level and aggregate reports.
Now that you've seen the Attribution Reporting
API in action, I encourage you to check out
the integration guide, which is linked below
in the video description.
This guide will provide step-by-step guidance
on implementing the Attribution Reporting API with regards
to your tech stack and use cases.
We appreciate your feedback as we
continue to iterate on the privacy preserving APIs.
If you have any feedback for us as you go through testing,
please submit it via the link below.
Thanks for watching.