Analytics

Adobe Analytics

If your organization already subscribes to Adobe Analytics, rich PDF analytics is yours by default. You should use Analytics as you normally would; however, there are a few setup steps required to correctly map the incoming data to Adobe Analytics variables.

Set up the PDF Viewer

Since you want to track user interaction with the PDF viewer, you need to make sure events appear in the correct report suites. To automatically receive PDF analytics events, pass the Analytics report suite ID when creating the AdobeDC.View instance. You must ensure that Adobe Analytics is instrumented using the same reportSuiteId for the website where you are embedding the PDF Viewer.

var adobeDCView = new AdobeDC.View({
    clientId: "<YOUR_CLIENT_ID>",
    divId: "adobe-dc-view"
    reportSuiteId: "<YOUR_Adobe_Analytics_REPORT_SUITE ID>",
    ...
})

Find the code sample for Adobe Analytics integration in PDF Embed API here under /More Samples/Analytics/Adobe Analytics.

Configure Adobe Analytics

The current release requires a few configuration steps to correctly map PDF Embed API data collected from your PDF viewer to your report suite. Once you've logged in to Analytics, do the following:

Once you've logged in to Analytics, do the following:

1. In the top menu, go to Admin > Report Suites.
2. Select your report suite.

<br/>

3. Navigate to the Report Suite Manager.
4. Highlight your report suite.
5. Choose Edit Settings > General > Processing Rules.

<br/>

6. Click the Processing Rules tab. You'll need to create two rules and configure them so that you can map collected events and event attributes to Analytics variables.

Mapping event attibutes

You'll need to create a new rule and map event attributes sent by the PDF Embed API to an Adobe Analytics variable. For example, an event attribute might be something like a page number or title. There could be many events with the same attribute (one for each event happening on a specific page). The following attributes eventually become dimensions in your reports:

• a.dc.searchTerm
• a.action
• a.dc.pageNum
• a.dc.filename

Map event attributes as follows:

1. Choose Add Rule.
2. Add a custom rule title such as "Event Dimensions".
3. Choose Add Action until you have four (one for each attribute above).
4. Select an item (event attribute) from the With drop down list (one of those above).
5. Select an Analytics dimension variable from the drop down list on the left.
6. The left hand columns should remain set to "Overwrite value of".
7. Repeat the above steps for each incoming event attribute you track.

Mapping events

Create another new rule and map events sent by the PDF Embed API to an Adobe Analytics variable. Note that Analytics uses "metrics" and "events" interchangeably. An event is any user interaction your JavaScript event listener captures; for example, clicking on a button or commenting on a PDF. The following events eventually become metrics displayed in your reports:

• a.dc.zoomLevel
• a.dc.loadPDF
• a.dc.viewPage
• a.dc.download
• a.dc.search
• a.dc.bookmarkClicked
• a.dc.copyText
• a.dc.print

Map events as follows:

1. Choose Add Rule.
2. Add a custom rule title such as "Events".
3. Choose Add Action until you have eight (one for each attribute above).
4. Select a metric (an event) from the To drop down list (one of those above).
5. Select an Analytics event variable from the drop down list on the left.
6. The left hand column should remain set to "Set event".
7. Repeat the above steps for each metric (incoming event).

Viewing your data

Set up your reporting as usual, and view the dimensions and metrics in your workspace.

Help, support, forum

For more detail about using this Adobe Analytics UI, refer to the help docs. You can also ask questions and get help here:

• Community forum
• Analytics Support

Google Analytics

If your website is already integrated with Google Analytics, you can collect PDF analytics from PDF Embed API in Google Analytics with a few simple setup steps.

Set up the PDF Viewer

Since you want to track user interaction with the PDF viewer, you need to make sure events appear in the correct Google Analytics property. To automatically receive PDF analytics events, pass the Google Analytics 4 measurement ID when creating the AdobeDC.View instance. You must ensure that Google Analytics is instrumented using the same  measurement ID for the website where you are embedding the PDF Viewer.

data-slots=text

var adobeDCView = new AdobeDC.View({
    clientId: "<YOUR_CLIENT_ID>",
    divId: "adobe-dc-view"
    measurementId: "<YOUR_GA4_MEASUREMENT ID>",
    ...
})

Following PDF analytics will be tracked:

Find the code sample for Google Analytics integration in PDF Embed API here under /More Samples/Analytics/Google Analytics.

Configure Google Analytics

The current release requires a few configuration steps to correctly map PDF Embed API data collected from your PDF viewer to Google Analytics.

Custom Dimensions

You need to set up some custom dimensions in the Google Analytics 4 property, that will map to the attributes which are part of the event data sent by PDF Embed API.

Once you've logged in to Google Analytics, do the following:

1. From the top bar, select the Google Analytics 4 property which contains your measurement ID.
2. Click  Custom definitions  under Configure (in the left navigation pane).
3. Click Create custom dimensions.

<br/>

4. Enter Dimension name.

5. Set the scope as Event.

6. Enter a  description for this custom dimension.

7. Enter the name of the event attribute sent from PDF Embed API. Custom dimensions need to be created for these event attributes: filename, pageNum, searchTerm and zoomLevel.

8. Click Save. (Note: You will see a value of "Not set" for a custom dimension during the first 48 hours. )

9. You need to set up four custom dimensions, as follows:

• File Name
• Page Number
• Search Term, and,
• Zoom Level

10. Map these custom dimensions with the correct event attributes sent from PDF Embed API, as shown in the table below:

<br/>

Viewing your data in Google Analytics 4

Once you start receiving PDF analytics in Google Analytics 4, set up your reporting as usual and view the dimensions and metrics in your workspace.

Creating a sample exploration to track page views

You can set up reports for different dimensions and metrics and view the data. This example below creates a sample exploration to track page views in the PDF.

1. Select Explore from the left navigation pane and click the plus sign to create a new blank report.
2. Select a custom timeline.
3. Select Line Chart from the Visualisation.
4. Drag and drop Event Name from Dimensions in Breakdowns.
5. Remove Active Count from Values.
6. Drag and drop Event Count from Metrics in Values.
7. Go to Filters and select Event Name.
8. Select match type 'contains' and enter 'Page View' in expression.
9. Click Apply.

data-slots=text

Control analytics collection

If your website is already integrated with analytics tools such as Adobe Analytics or Google Analytics, then you can collect PDF analytics with few additional setup steps. To know more about the setup steps, see the sections Adobe Analytics and Google Analytics.

The sendAutoPDFAnalytics configuration controls the PDF analytics collection in these tools. The default value of sendAutoPDFAnalytics is true. Set this configuration to false if you would like to disable PDF analytics collection.

var adobeDCView = new AdobeDC.View({
    clientId: "<YOUR_CLIENT_ID>",
    divId: "adobe-dc-view"
    sendAutoPDFAnalytics: false,
    ...
})

Default analytics

If you are not subscribed to Adobe Analytics or Google Analytics, you can still collect PDF analytics events as users interact with PDFs. You enable PDF analytics events by registering a callback with the API to listen the events. Tracking PDF events provides insight into user actions and thereby helps you manage and evolve the PDF experience you're delivering to customers.

As always, initialize the AdobeDC.View object with your client ID, and then invoke the previewFile API on AdobeDC.View object as usual. Finally, register the callback to receive the events and set enablePDFAnalytics to true:

const eventOptions = {
  //Pass the PDF analytics events to receive.
  //If no event is passed in listenOn, then all PDF analytics events will be received.
  listenOn: [ AdobeDC.View.Enum.PDFAnalyticsEvents.PAGE_VIEW, AdobeDC.View.Enum.PDFAnalyticsEvents.DOCUMENT_DOWNLOAD],
  enablePDFAnalytics: true
}

adobeDCView.registerCallback(
  AdobeDC.View.Enum.CallbackType.EVENT_LISTENER,
  function(event) {
    console.log("Type " + event.type);
    console.log("Data " + event.data);
  }, eventOptions
);

Find the working example in the samples repo under /More Samples/Capture PDF Embed API Events/.

Supported analytics events

Basic events

In addition to the PDF analytics events, the PDF Embed API supports events which provide insight into user actions taken related to file preview. These events can be received through the events callback. After registering the events callback, the following file preview events are generated:

In order to receive additional file preview events, set enableFilePreviewEvents to true and pass it to the events callback. To receive specific events, pass the list of event types in the listenOn parameter. If nothing is passed to listenOn, then the API returns all the file preview events.

const eventOptions = {
     //Pass the events to receive.
     //If no event is passed in listenOn, then all file preview events will be received.
     listenOn: [ AdobeDC.View.Enum.Events.APP_RENDERING_START, AdobeDC.View.Enum.FilePreviewEvents.PREVIEW_KEY_DOWN,  AdobeDC.View.Enum.FilePreviewEvents.PREVIEW_PAGE_VIEW_SCROLLED ],
     enableFilePreviewEvents: true
}

adobeDCView.registerCallback(
     AdobeDC.View.Enum.CallbackType.EVENT_LISTENER,
     function(event) {
        console.log(event)
     }, eventOptions
);

List of file preview events

Annotation events

Web developers can receive events when a user interacts with an annotation. These events are generated for annotation actions performed through the UI.

To register the events callback, set enableAnnotationEvents to true and pass it to the callback. To receive specific events, pass the list of annotation event types in the listenOn parameter. If nothing is passed to listenOn, then the API returns all the annotation events.

const eventOptions = {
   //Pass the events to receive.
   //If no event is passed in listenOn, then all annotation events will be received.
   listenOn: [ AdobeDC.View.Enum.AnnotationEvents.ANNOTATION_ADDED, AdobeDC.View.Enum.AnnotationEvents.ANNOTATION_UPDATED ],
   enableAnnotationEvents: true
 }

 adobeDCView.registerCallback(
   AdobeDC.View.Enum.CallbackType.EVENT_LISTENER,
   function(event) {
     console.log(event.type, event.data)
   }, eventOptions
 );

List of annotation events

data-slots=text