Use case: Analyze Page parameters with the API

Last updated:

Parameterizing URLs can save a significant amount of time in cases where the number of possible parameters is high. In some cases, it's the only feasible option to analyze Page data.

When parameterizing, Pendo’s UI allows you to view the top 100 parameters for a certain Page rule and the number of associated Page views. If the number of parameters exceeds 100, you can use our aggregations endpoint to view the full list of parameters.

This article reviews how to analyze Page parameters through the API.

Requirements

Before continuing with the guidelines below, confirm the following:

  • API access is included in your Pendo contract. If you’re unsure, contact your Pendo representative.
  • You have a Pendo integration key. This isn’t the key that appears in the Pendo install script, and only Admins can create integration keys. To create an integration key in Pendo Engage, navigate to Settings > Integrations > Integration Keys and select Add Integration Key
  • Select Allow Write Access so that you can properly push data to Pendo with the key.

Tip: If you aren’t familiar with the concept of Page parameters, we recommend reviewing URLs for Page tagging.

Guidelines

The PageEvents source in our aggregations endpoint (https://app.pendo.io/api/v1/aggregation) provides a breakdown of the different page parameters aggregated at the hour or day level.

First, add your integration key in the Headers section of the API call next to x-pendo-integration-key. Here’s an example using Postman:

Postman_Example.png

Next, fill out the Body of the request based on your desired outcome. Below are a few examples that you can copy-paste to fit your needs.

View events for a specific Page and time period

Here’s an example call that requests events for a specific Page for the previous day. You can find the Page ID in the page URL: https://app.pendo.io/s/SUBSCRIPTION-ID/pages/PAGE-ID.

{
   "response": {},
   "request": {
       "name": "ExampleAggregation",
       "pipeline": [
          {
               "source": {
                   "pageEvents": {
                       "pageId": "ENTER PAGE ID"
                  },
                   "timeSeries": {
                       "period": "dayRange",
                       "first": "now()",
                       "count": -1
                  }
              }
          }
      ],
       "requestId": "ExampleAggregation"
  }
}

Here’s an excerpt of an example response from the call above. A unique visitor may return more than one response if they’ve accessed more than one Page parameter:

{
   "startTime": 1647475200000,
   "results": [
      {
           "accountId": "XXX",
           "appId": -323232,
           "day": 1647475200000,
           "pageId": "XXX",
           "numEvents": 1,
           "numMinutes": 1,
           "remoteIp": "XXX",
           "server": "XXX",
           "userAgent": "XXX",
           "visitorId": "XXX",
           "parameters": {
               "parameter": "XXX"
          }
      },
      {
           "accountId": "XXX",
           "appId": -323232,
           "day": 1647475200000,
           "pageId": "XXX",
           "numEvents": 1,
           "numMinutes": 1,
           "remoteIp": "XXX",
           "server": "XXX",
           "userAgent": "XXX",
           "visitorId": "XXX",
           "parameters": {
               "parameter": "XXX"
          }
      }
  ]
}

Filter for specific parameters in a particular Page

If you want to filter for a specific parameter in a particular Page and limit the number of responses pulled, here’s an example call:

{
   "response": {},
   "request": {
       "name": "ExampleAggregation",
       "pipeline": [
          {
               "source": {
                   "pageEvents": {
                       "pageId": "ENTER PAGE ID"
                  },
                   "timeSeries": {
                       "period": "dayRange",
                       "first": "now()"
                      "count": -1
                  }
              }
          },
          {
               "filter": "parameters.parameter == `ENTER PARAMETER`"
          },
          {
               "limit": 1
          }
      ],
       "requestId": "ExampleAggregation"
  }
}

And here's an example response:

{
   "startTime": 1647475200000,
   "results": [
      {
           "accountId": "XXX",
           "appId": -323232,
           "day": 1647475200000,
           "pageId": "XXX",
           "numEvents": 1,
           "numMinutes": 1,
           "remoteIp": "XXX",
           "server": "XXX",
           "userAgent": "XXX",
           "visitorId": "XXX",
           "parameters": {
               "parameter": "XXX"
          }
      }
  ]
}

To analyze the results in a table format, replace this section:

{
   "response": {},

}

With this one:

{
   "response": {
       "location": "request",
       "mimeType": "text/csv"
  }

}

You can then download the results as a CSV file:

CSV_Example.png

View top parameters

You can also obtain the Top Parameters list and the corresponding number of Page views that’s available when viewing the Page details in the Pendo UI.

Here's an example call:

{
   "response": {
       "location": "request",
       "mimeType": "text/csv"
  },
   "request": {
       "name": "TopPageParameters",
       "pipeline": [
          {
               "source": {
                   "pageEvents": {
                       "pageId": "ENTER PAGE ID",
                       "blacklist": "apply"
                  },
                   "timeSeries": {
                       "period": "dayRange",
                       "first": "now()",
                       "count": -30
                  }
              }
          },
          {
               "identified": "visitorId"
          },
          {
               "filter": "!isNull(parameters.parameter) && parameters.parameter != \"\""
          },
          {
               "group": {
                   "group": [
                       "pageId",
                       "parameters.parameter"
                  ],
                   "fields": [
                      {
                           "numEvents": {
                               "sum": "numEvents"
                          }
                      }
                  ]
              }
          },
          {
               "sort": [
                   "-numEvents"
              ]
          },
          {
               "limit": 100
          }
      ],
       "requestId": "TopPageParameters"
  }
}

And here's an example response in CSV format:

numEvents,pageId,parameters
67,mNZtq33uzglPEMxv1_emyn-ytig,"{""parameter"":""index.html""}"
27,mNZtq33uzglPEMxv1_emyn-ytig,"{""parameter"":""login.html""}"
9,mNZtq33uzglPEMxv1_emyn-ytig,"{""parameter"":""buttons.html""}"
3,mNZtq33uzglPEMxv1_emyn-ytig,"{""parameter"":""tables.html""}"
2,mNZtq33uzglPEMxv1_emyn-ytig,"{""parameter"":""charts.html""}"
1,mNZtq33uzglPEMxv1_emyn-ytig,"{""parameter"":""cards.html""}"
1,mNZtq33uzglPEMxv1_emyn-ytig,"{""parameter"":""utilities-color.html""}"

 

Was this article helpful?
0 out of 1 found this helpful