Contributors:
frontend_API
This module component fetches Google Analytics report data from your site's GA4 statistics and returns a JSON object that can be accesses via Liquid or displayed as an interactive chart.
{% component type:"frontend_API", endpoint:"<ENDPOINT>", request: "<REQUEST OBJECT>", collectionVariable: "yourLiquidVariableName" %}Parameters and Options
frontend_API/api/frontend/ga4_run_report
/api/frontend/secure_zone_subscribers_analytics
<REQUEST OBJECT><path/to/layout>Path to file that will contain the Liquid layout content to be parsed.
If the parameter is blank, has an incorrectly referenced Layout, or is removed altogether then the component will still output the modules item data to a Liquid collection which can be accessed via the collectionVariable parameter.
<yourLiquidVariableName>Assigns the data to a Liquid collection enabling further access to the data on the Page or Template using Liquid.
Your collectionVariable value must only contain English letters, numbers or underscores. Spaces or special characters are not supported.
GET Google Analytics Report API
/api/frontend/ga4_run_reportRetrieve customised report data on your site's statistics via the Google Analytics integration.
The GA4 data is only accessible if your site is configured with GA4 analytics in the site settings.
Request / Response:
Construct your request to the report API using the JSON structure described in Google's 'runReport' documentation.
Below is an example request and response:
{
"dimensions": [
{
"name": "date"
},
{
"name": "eventName"
},
{
"name": "customEvent:coupon_code"
},
{
"name": "customEvent:user"
}
],
"metrics": [
{
"name": "eventCount"
}
],
"dateRanges": [
{
"startDate": "2023-07-03",
"endDate": "2023-07-05"
}
],
"dimensionFilter": {
"andGroup": {
"expressions": [
{
"filter": {
"stringFilter": {
"matchType": "EXACT",
"value": "coupon_code_clicked"
},
"fieldName": "eventName"
}
},
{
"filter": {
"stringFilter": {
"matchType": "EXACT",
"value": "My CUSTOm CODE"
},
"fieldName": "customEvent:coupon_code"
}
}
]
}
},
"limit": "100",
"orderBys": [
{
"dimension": {
"orderType": "ALPHANUMERIC",
"dimensionName": "date"
},
"desc": false
}
],
"keepEmptyRows": true
}
{
"ErrorMessages": null,
"Error": 0,
"Response": {
"dimensionHeaders": [
{
"name": "date"
},
{
"name": "eventName"
},
{
"name": "customEvent:coupon_code"
},
{
"name": "customEvent:user"
}
],
"metricHeaders": [
{
"name": "eventCount",
"type": "TYPE_INTEGER"
}
],
"rows": [
{
"dimensionValues": [
{
"value": "20230705"
},
{
"value": "coupon_code_clicked"
},
{
"value": "My CUSTOm CODE"
},
{
"value": "33"
}
],
"metricValues": [
{
"value": "4"
}
]
},
{
"dimensionValues": [
{
"value": "20230705"
},
{
"value": "coupon_code_clicked"
},
{
"value": "My CUSTOm CODE"
},
{
"value": "22"
}
],
"metricValues": [
{
"value": "3"
}
]
},
{
"dimensionValues": [
{
"value": "20230705"
},
{
"value": "coupon_code_clicked"
},
{
"value": "My CUSTOm CODE"
},
{
"value": "11"
}
],
"metricValues": [
{
"value": "1"
}
]
},
{
"dimensionValues": [
{
"value": "20230704"
},
{
"value": "coupon_code_clicked"
},
{
"value": "My CUSTOm CODE"
},
{
"value": "22"
}
],
"metricValues": [
{
"value": "4"
}
]
},
{
"dimensionValues": [
{
"value": "20230704"
},
{
"value": "coupon_code_clicked"
},
{
"value": "My CUSTOm CODE"
},
{
"value": "11"
}
],
"metricValues": [
{
"value": "3"
}
]
},
{
"dimensionValues": [
{
"value": "20230704"
},
{
"value": "coupon_code_clicked"
},
{
"value": "My CUSTOm CODE"
},
{
"value": "(not set)"
}
],
"metricValues": [
{
"value": "2"
}
]
},
{
"dimensionValues": [
{
"value": "20230704"
},
{
"value": "coupon_code_clicked"
},
{
"value": "My CUSTOm CODE"
},
{
"value": "33"
}
],
"metricValues": [
{
"value": "1"
}
]
}
],
"totals": [
{
"dimensionValues": [
{
"value": "RESERVED_TOTAL"
},
{
"value": "RESERVED_TOTAL"
},
{
"value": "RESERVED_TOTAL"
},
{
"value": "RESERVED_TOTAL"
}
],
"metricValues": [
{
"value": "18"
}
]
}
],
"rowCount": 7,
"metadata": {
"currencyCode": "USD",
"timeZone": "America/Los_Angeles"
},
"kind": "analyticsData#runReport"
}
}
Chart Include
A chart layout of the report data can also be rendered, with start and end date controls, using the below Liquid include:
{% include "/cms-assets/includes/ga4-report-chart.inc", startDate: "", endDate: "", eventName: "", requestJSON: "" %}This include can also be generated via the Component Manager, in the "Frontend API" section, along with some other attributes to further configure the output as detailed below:
Chart Include Parameters
<YYYY-MM-DD><YYYY-MM-DD><EVENT NAME>page_view.<REQUEST OBJECT>You can optionally provide a custom request object in JSON format for more advanced report configurations (see the API request structure above).
If a value is provided here, all other parameters above will be ignored.
GET Secure Zone Subscribers API
/api/frontend/secure_zone_subscribers_analyticsRetrieve customised report data from your site's secure zone statistics via the Google Analytics integration.
The GA4 data is only accessible if your site is configured with GA4 analytics in the site settings.
Request / Response:
Construct your request to the report API using the JSON structure described below:
{
"startDate": "[[startDate]]",
"endDate": "[[endDate]]",
"filterExpression": [
{
"secureZones": [
[[secureZoneId1]],
[[secureZoneId2]],
[[secureZoneIdN]]
]
}
],
"sortExpression": [
{
"sortBy": "date",
"sortOrder": "ASC|DESC"
}
],
"groupType": "Day(default)|Week|Month|Year"
}
{
"ErrorMessages": null,
"Error": 0,
"Response": {
"rows": [
{
"dimensionValues": [
{
"value": "Date"
},
{
"value": "Total"
},
{
"value": "secure zone 1"
},
{
"value": "secure zone 2"
},
{
"value": "secure zone 3"
}
],
"metricValues": [
{
"value": "20230705"
},
{
"value": 39 //total number of subscribers to all selected secure zones
},
{
"value": 4 //number of subscribers to secure zone 1
},
{
"value": 2 //number of subscribers to secure zone 2
},
{
"value": 33 //number of subscribers to secure zone 3
}
]
}
],
"rowCount": 1
}
}
Chart Include
A chart layout of the report data can also be rendered, with group type, start and end date controls, using the below Liquid include:
{% include "/cms-assets/includes/secure-zone-analytics-chart.inc", startDate: "", endDate: "", groupType: "", secureZonesList: "", requestJSON: "" %}This include can also be generated via the Component Manager, in the "Frontend API" section, along with some other attributes to further configure the output as detailed below:
Chart Include Parameters
<YYYY-MM-DD><YYYY-MM-DD>Day (default)
Week
Month
YearDay is used.<ID1>,<ID2>,<ID3><REQUEST OBJECT>You can optionally provide a custom request object in JSON format for more advanced report configurations (see the API request structure above).
If a value is provided here, all other parameters above will be ignored.
API Restrictions
Enable/disable access to the Google Analytics API data for frontend users and control the type of users that can access it.
For more information on configuring API restrictions, see Frontend API Restrictions.
Accessing the Data
JSON Output
You can output the full JSON for your component data by referencing the root Liquid object {{this}} in your custom layout file, or directly on your page, if using the collectionVariable parameter in your component tag.
For example:
{% component type: ... collectionVariable: "myData" %}You can then render the JSON like so:
{{myData}}For more details on using this approach, see Part 2 of the free ‘Learning Liquid Course’.
Rendering Property Values
This data is accessible in two main ways:
1. Using Liquid in the specified layout file via the this object, eg:
{{this.response['rowCount']}}2. Directly on the Page or Template via a Liquid Collection if collectionVariable was added to the Component tag.
An example using collectionVariable with value "reportData":
Here we suppress any Layout file from rendering by setting layout: "" as an empty attribute.
{% component type: "frontend_API", endpoint:"/api/frontend/ga4_run_report", request: "<REQUEST OBJECT>", collectionVariable: "reportData" %}Looping through the collection to render all the dimension headers in a list, giving us:
- date
- eventName
- customEvent:coupon_code
- customEvent:user
The code:
<ul>
{% for i in reportData.response.dimensionHeaders %}
<li>{{i['name']}}</li>
{% endfor %}
</ul>
Accessing a specific item within the collection. In this case the third header item (zero based index), which in our example would render the value customEvent:coupon_code
{{reportData.response.dimensionHeaders[2]['name']}}