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

type

frontend_API

This system parameter identifies the type of component for retrieving data from the CMS

endpoint

/api/frontend/ga4_run_report

/api/frontend/secure_zone_subscribers_analytics

The system resource used for the data collection.

request

<REQUEST OBJECT>

A JSON object that represents the request to the Google Analytics report API, as per Google's API documentation.

layout

<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.

collectionVariable

<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_report

Retrieve 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

startDate

<YYYY-MM-DD>

The starting date of the report data.

When constructing the include tag via the Component Manager, if no date provided, the default date is set to today's date minus 1 month.

endDate

<YYYY-MM-DD>

The end date of the report data.

When constructing the include tag via the Component Manager, if no date provided, the default date is set to today's date.

eventName

<EVENT NAME>

The name of the analytics tracking event you wish to report on.

When constructing the include tag via the Component Manager, if no value if provided, the default event used is page_view.

requestJSON

<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_analytics

Retrieve 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

startDate

<YYYY-MM-DD>

The starting date of the report data. If no date provided, the default date is set to today's date minus 1 month.

endDate

<YYYY-MM-DD>

The end date of the report data.

When constructing the include tag via the Component Manager, if no date provided, the default date is set to today's date.

groupType

Day (default)
Week
Month
Year

The grouping period you wish the report to start on.

When constructing the include tag via the Component Manager, if no value if provided, the default of Day is used.

secureZonesList

<ID1>,<ID2>,<ID3>

A comma-separated string of the secure zone IDs you wish to report on.

When constructing the include tag via the Component Manager, if no value if provided, the default will report on all secure zones.

requestJSON

<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']}}

Parameters and Options

GET Google Analytics Report API

Request / Response:

Chart Include

Chart Include Parameters

GET Secure Zone Subscribers API

Request / Response:

Chart Include

Chart Include Parameters

API Restrictions

Accessing the Data

JSON Output

Rendering Property Values

`GET` Google Analytics Report API

`GET` Secure Zone Subscribers API