How is your experience with the OutSystems Community?
google-analytics-library
Reactive icon

Google Analytics Library

Stable version 1.0.3 (Compatible with OutSystems 11)
Uploaded
 on 18 Nov (2 days ago)
 by 
4.4
 (7 ratings)
google-analytics-library

Google Analytics Library

Documentation
1.0.3

Overview

Google Analytics Library wraps the official Google tag (gtag.js) for GA4 in a small set of client actions. It has no dependencies, adds no screens or entities to your app, and makes only one server call (in Init, to read the GAIsEnabled site property).

Setup in Google Analytics

  1. In Google Analytics, open Admin > Create > Property and create a GA4 property.
  2. In Admin > Data streams, add a Web stream with the URL of your app.
  3. Copy the Measurement ID of the stream (format G-XXXXXXXXXX).
  4. Optional: in the stream's Enhanced measurement settings, decide whether "Page changes based on browser history events" stays on. If you call TrackScreen on every screen, turn it off to avoid duplicate page views.

Setup in OutSystems

  1. Install the component from the Forge.
  2. In your app, open Manage Dependencies, select GoogleAnalytics_Lib and add the actions you need (Init, TrackScreen, TrackEvent, UpdateConsent, SetUserId, SetUserProperties) and the EventProperty structure.
  3. Create a Text site property in your app, for example, GAMeasurementId, and a server action that returns it (site properties can't be read in client actions). Set its value per environment in Service Center.
  4. In the OnApplicationReady event of your app, call the server action and then Init with the Measurement ID.

Actions

  • Init: loads gtag.js and configures the Measurement ID. Call it once, before any other action.
    • MeasurementId (Text, mandatory): the GA4 Measurement ID, G-XXXXXXXXXX.
    • ConsentDefaultDenied (Boolean, default False): sets every Consent Mode v2 type to denied until UpdateConsent is called.
    • DebugMode (Boolean, default False): sends the events to GA4 DebugView. Use only in development.
    • SendPageView (Boolean, default True): lets gtag send the automatic page_view on load. Set it to False when you call TrackScreen on every screen.
  • TrackScreen: sends a page_view for the current screen. Call it in the OnReady event of each screen or of the layout block.
    • ScreenName (Text, optional): sent as the screen_name parameter.
    • PageTitle (Text, optional): default is the document title.
    • PagePath (Text, optional): default is the current URL. Use it to remove identifiers from the URL, for example /Orders/Detail.
  • TrackEvent: sends a custom or recommended event.
    • Name (Text, mandatory): up to 40 letters, digits or underscores, starting with a letter.
    • Properties (EventProperty List, optional): event parameters as Key/Value pairs, up to 25 per event. Numeric text such as 10 or 2.5 is sent as a number.
    • Value (Decimal, optional): numeric value of the event, for example the purchase amount. 0 means not sent.
    • Currency (Text, optional): ISO 4217 code of Value, for example EUR.
  • UpdateConsent: updates the Consent Mode v2 state after the user answers the cookie banner. Can be called before or after Init.
    • AnalyticsStorage (Boolean, mandatory), AdStorage, AdUserData and AdPersonalization (Boolean, default False).
    • SetUserId: sets the user_id for the next events. Pass an empty text on logout to clear it.
    • UserId (Text, mandatory): an opaque identifier, for example the OutSystems user Id. Never an e-mail, name or phone number.
  • SetUserProperties: sets user properties, for example plan or user_type.
    • Properties (EventProperty List, mandatory): Key/Value pairs. GA4 limits user property names to 24 characters and values to 36.


Consent and GDPR

  • If your app has users in the EEA or the UK, call Init with ConsentDefaultDenied = True. Until consent is given, gtag sends only cookieless pings and stores no analytics cookies.
  • When the user answers your cookie banner, call UpdateConsent with the user's choices, and call it again on every app start with the stored choice.
  • The library does not include a cookie banner and does not store the user's choice. Use your own banner or a consent management platform.
  • Do not send personal data (e-mails, names, phone numbers, national IDs) in events, user properties, user_id or page paths. This is against the Google Analytics terms.


Debugging

  • Set DebugMode = True in Init (only in development) and open GA4 Admin > DebugView.
  • The library writes warnings to the browser console, prefixed with [GoogleAnalytics_Lib], when the Measurement ID or an event name is invalid, or when an ad blocker stops gtag.js from loading.
  • Set the GAIsEnabled site property to False to turn tracking off without changing code.


Notes

  • Works in Reactive Web apps and in the web view of Mobile apps. In a native mobile app, consider Firebase Analytics for app-stream reports.
  • TrackScreen and TrackEvent are ignored until Init has run. UpdateConsent, SetUserId, and SetUserProperties are queued and applied when gtag.js loads.
  • Version 1.1.0 keeps the existing action signatures, so apps using 1.0.x keep working. Only new, optional inputs were added.

1.0.2

Requirements:

Google Tag ID: The plugin allows you to input your Google Analytics tracking ID to ensure the data is sent to the correct Google Analytics property. Check the link to view the instructions about How to Find your Google tag ID.

How to configure a GA4 property:

Step 1. Create a Google Analytics 4 Property:

  1. Go to the Google Analytics website.
  2. Sign in with your Google account.
  3. Click on "Admin" in the lower-left corner.
  4. In the "Account" column, select the account where you want to create the property.
  5. In the "Property" column, click on "Create Property."
  6. Choose the "Web" option for a website or select the relevant platform for your 


Step 2: Fill in Property Details:

  1. Enter a name for your property.
  2. Choose your reporting time zone and currency.
  3. Enter the business details and objectives

Step 3. Configure Data Streams:

  • After creating the property, set up a data stream to collect data.
  • Enter a stream name (usually the name of your website or app).
  • Choose the platform (web, iOS, Android) and follow the provided instructions to set up the stream.


How to use this library

This library has three actions that can be consumed:

  1. Init
  2. TrackScreen
  3. TrackEvent

Init

Parameters:

MeasurementId - is an identifier (e.g., G-12345) for a web data stream. You can use the Measurement ID to send data to a specific web data stream. You can get this value on the web stream detail page visible on the image of the config step.

Where to Call: Typically can be placed in the OnApplicationReady global event



Note: You can test if the config is working, by changing the stream URL for your current personal/development environment. Next, click on the option View tag instructions, select the tab Install manually, and on the option "Test your website (optional)" insert the URL for your app.


TrackScreen: Tracks a specific screen.

Where to Call: This action can be placed on the OnReady event on the screen to track or on a common layout used by the screens.


TrackEvent: Tracks a specific event.

Info: https://developers.google.com/tag-platform/devguides/events

Parameters: 

  1. Category: Google Analytics 4 event name.
  2. Properties: A name/value pairs object that contains data describing the event.
  3. Where to Call: On a client action where we need to track the action.

In the following example, we will add an action to the Home screen associated with the "Add" button.


This action tracks an event that will be called "actions" and has two properties (the action name and the user).

 

View the data

After all this configuration and some application usage, all data will be available at the Google Analytics console. You can access the real-time report and confirm that the data is present!


1.0.1

Requirements:

Google Tag ID: The plugin allows you to input your Google Analytics tracking ID to ensure the data is sent to the correct Google Analytics property. Check the link to view the instructions about How to Find your Google tag ID.


How to configure a GA4 property:

Step 1. Create a Google Analytics 4 Property:

  1. Go to the Google Analytics website.
  2. Sign in with your Google account.
  3. Click on "Admin" in the lower-left corner.
  4. In the "Account" column, select the account where you want to create the property.
  5. In the "Property" column, click on "Create Property."
  6. Choose the "Web" option for a website or select the relevant platform for your 


Step 2: Fill in Property Details:

  1. Enter a name for your property.
  2. Choose your reporting time zone and currency.
  3. Enter the business details and objectives


Step 3. Configure Data Streams:

  • After creating the property, set up a data stream to collect data.
  • Enter a stream name (usually the name of your website or app).
  • Choose the platform (web, iOS, Android) and follow the provided instructions to set up the stream.


How to use this library

This library has three actions that can be consumed:

  1. Init
  2. TrackScreen
  3. TrackEvent

Init

Parameters:

MeasurementId - is an identifier (e.g., G-12345) for a web data stream. You can use the Measurement ID to send data to a specific web data stream. You can get this value on the web stream detail page visible on the image of the config step.

Where to Call: Typically can be placed in the OnApplicationReady global event



Note: You can test if the config is working, by changing the stream URL for your current personal/development environment. Next, click on the option View tag instructions, select the tab Install manually, and on the option "Test your website (optional)" insert the URL for your app.


TrackScreen: Tracks a specific screen.

Where to Call: This action can be placed on the OnReady event on the screen to track or on a common layout used by the screens.


TrackEvent: Tracks a specific event.

Info: https://developers.google.com/tag-platform/devguides/events

Parameters: 

  1. Category: Google Analytics 4 event name.
  2. Properties: A name/value pairs object that contains data describing the event.
  3. Where to Call: On a client action where we need to track the action.

In the following example, we will add an action to the Home screen associated with the "Add" button.


This action tracks an event that will be called "actions" and has two properties (the action name and the user).

 


View the data

After all this configuration and some application usage, all data will be available at the Google Analytics console. You can access the real-time report and confirm that the data is present!


1.0.0

Requirements:

Google Tag ID: The plugin allows you to input your Google Analytics tracking ID to ensure the data is sent to the correct Google Analytics property. Check the link to view the instructions about How to Find your Google tag ID.


How to configure a GA4 property:

Step 1. Create a Google Analytics 4 Property:

  1. Go to the Google Analytics website.
  2. Sign in with your Google account.
  3. Click on "Admin" in the lower-left corner.
  4. In the "Account" column, select the account where you want to create the property.
  5. In the "Property" column, click on "Create Property."
  6. Choose the "Web" option for a website or select the relevant platform for your 


Step 2: Fill in Property Details:

  1. Enter a name for your property.
  2. Choose your reporting time zone and currency.
  3. Enter the business details and objectives


Step 3. Configure Data Streams:

  • After creating the property, set up a data stream to collect data.
  • Enter a stream name (usually the name of your website or app).
  • Choose the platform (web, iOS, Android) and follow the provided instructions to set up the stream.


How to use this library

This library has three actions that can be consumed:

  1. Init
  2. TrackScreen
  3. TrackEvent

Init

Parameters:

MeasurementId - is an identifier (e.g., G-12345) for a web data stream. You can use the Measurement ID to send data to a specific web data stream. You can get this value on the web stream detail page visible on the image of the config step.

Where to Call: Typically can be placed in the OnApplicationReady global event



Note: You can test if the config is working, by changing the stream URL for your current personal/development environment. Next, click on the option View tag instructions, select the tab Install manually, and on the option "Test your website (optional)" insert the URL for your app.


TrackScreen: Tracks a specific screen.

Where to Call: This action can be placed on the OnReady event on the screen to track or on a common layout used by the screens.


TrackEvent: Tracks a specific event.

Info: https://developers.google.com/tag-platform/devguides/events

Parameters: 

  1. Category: Google Analytics 4 event name.
  2. Properties: A name/value pairs object that contains data describing the event.
  3. Where to Call: On a client action where we need to track the action.

In the following example, we will add an action to the Home screen associated with the "Add" button.


This action tracks an event that will be called "actions" and has two properties (the action name and the user).

 

View the data

After all this configuration and some application usage, all data will be available at the Google Analytics console. You can access the real-time report and confirm that the data is present!