|
|
Google Analytics 4 Installation
|
|
NOTE: These instructions pertain to Google Analytics 4, Google's replacement for their Universal Analytics
product. Google has announced their intention to discontinue Universal Analytics on July 1, 2023. After that date,
only Google Analytics 4 will be supported by Google. To view the old instructions to access Universal Analytics using
Warehouse and DataBridger Studio, see here.
For information on migrating to Google Analytics 4, see here.
Taurus Software's Warehouse program can access data from Google Analytics 4,
however getting it working can be tricky because it requires software from both Google and Oracle.
This page documents the steps required for Warehouse and DataBridger Studio to access Google data.
|
|
Contents
|
| |
0 |
Prerequisites |
| |
0.3 |
Giving access to your Google Analytics data |
| |
1 |
System Requirements |
|
0 Prerequisites
|
|
This section lists the tasks that must be completed before DataBridger or Warehouse can access Google Analytics 4 data.
Before you can use Google Analytics 4
data, the Google Analytics 4 setup
process must be completed.
Setting up access to your Google Analytics data is a multi-step process. Follow the steps below:
This process can be confusing. There is additional documentation at Google.
Go to the Google Cloud Platform
dashboard and login using your Google login.
Create a new project by on the project seclector in the upper left of the window, to the
right of the menu selector. This will show a list of existing projects.
Click the "New Project" button.
0.2.3 Name the New Project
Enter a project name for the new project.
This may be any name such as: TaurusAccessProject.
You may change the project location or leave the default.
Click the Create button.
Make certain your new
project is the one active by checking the project name in upper left corner.
Enter the Google API
manager by opening the menu on the upper left of the screen and select APIs & Services
followed by Library.
In the search box, enter: "Analytics" and press enter.
Click on Google Analytics Data API, being careful not to click on an API with a similar name.
Click the Enable button. After the project is enabled,
the Google Analytics Data API dashboard is displayed.
0.2.5 Get Your Credentials
The credentials for the project must now be obtained.
Click on Credentials on the left panel, followed by Create Credentials in the upper middle
part of the dashboard.
A menu of choices is displayed. Select Service Account.
Enter a
new service account name. This may be any name such as: TaurusServiceAccount
Enter a new service account ID, or use the default.
Enter the service account description.
Note the email address associated with this service account. It is used lated in the setup. You may press
the copy icon to copy the email address to your clipboard.
Click the Create and Continue button.
Grant the new service account access to yor project by assigning it a role. To give it
owner access, click on the role box and select Owner.
Click the Continue button to assign the role.
You may now assign additional users and groups access to this service account.
Click the Done button.
You should now be at the Credentials dashboard for yor project. You can get to this
dashboard by clicking Google Analytics Data API --> Credentials.
Click on the little pencil on the right of yor service account to edit the service xaccount
details. You should now be in the Service account details screen.
Click on the Keys tab.
Click on Add Key --> Create New Key.
Click on JSON to download a new key file.
IMPORTANT: This downloaded .json file is REQUIRED to access your analytics
data with Warehouse or DataBridger Studio. You should move this file to a place of your choosing
on your system and note the fully qualified file name.
To access your Google Analytics data, your service account must be given access to your data. To do this:
1. Login to your Google account and go to the Google Analytics Administrator Dashboard
2. Make certain you are accessing the correct account by checking the account selector in the upper left of the window.
3. IMPORTANT: The client ID needed by DataBridger and Warehouse is enclosed in parentheses after the account name.
Make a note of this number and use it to connect to your Google Analytics 4 data.
4. Enter the Admin screen by pressing the gear button in the lower left.
5. Click on Property Access Management in the list in the middle of the window. If you do not see this, your user does not
have Administrator privileges. You must either give you user Administrator privileges or login to Google again
under a user that has those privileges.
6. You must now add the email address associated with the service account you created earlier. Press
the "+" button in the upper right, then select Add Users.
7. Enter the email address associated with the service account.
8. Select the role for this account. Viewer is good for just seeing the data.
9. Click Add in the upper right.
|
|
1 System Requirements
|
|
This section lists the items that need to be acquired before Warehouse can access Google Analytics 4 data.
This assumes that your web pages have been setup
to collect Google Analytics data and that data is available on Google's servers.
Warehouse release 7.00 or later from Taurus Software is required. DataBridger Studio
version 7.0 or later can also access Google Analytics 4 data. These may be obtained from our
DataBridger download site (login required).
You should also be aware of your installation directory. On a Microsoft Windows system, this will usually be:
| |
| |
C:\Program Files\Taurus\Warehouse |
Warehouse installation directory |
| |
C:\Program Files\Taurus\DataBridger |
DataBridger installation directory |
| |
| |
C:\Program Files (x86)\Taurus\DataBridger |
DataBridger Studio on 64-bit Windows |
| |
On Unix/Linux systems, the installation directory is where the administrator installed the software and
may be something like:
| |
| |
/var/taurus/warehouse |
Warehouse installation directory example |
A special file called MSG992 that describes the Google Analytics 4 data items is required. It is included in your
installation, so you should not usually be concerned about this file. If MSG992 is not in your Warehouse installation
directory, or if you wish to obtain the most recent version, contact Taurus customer support.
MSG992 lists all dimensions and metrics available from
the Google Analytics Data API and maps them to Warehouse names.
MSG992 is a comma separated value (CSV) text file, and can viewed using a text editor.
Warehouse accesses the Google Analytics Data API through the use of Java from Oracle, therefore Java
must be installed before Google Analytics 4 data can be accessed. If you do not know if Java
is installed, it can be difficult to tell for certain.
In addition, the Google libraries require a Java version of 1.6 or greater. If
you already have a Java version installed that is older than 1.8, it is strongly recommended that
you upgrade to the latest version using one of the links below.
To determine if Java is installed on a Windows system, simply open the Control Panel and look for a control
called Java. If Java is there, Java is installed and you can close the control panel. If Java is not there, it needs to be installed.
To install Java, go to the Java download page and follow the instructions.
If this a 64-bit Microsoft Windows OS (most are) and you wish to use DataBridger Studio
to access Google Analytics data, you will also need to install 32-bit Java. (Having two Java
installations is not a problem.) To check if you need to install 32-bit Java for DataBridger Studio
check to see if you have a directory called:
| |
C:\Program Files (x86)\Java |
If "C:\Program Files (x86)" exists, you are on a 64-bit version of Windows and
need "C:\Program Files (x86)\Java" to exist in order to access Google data with DataBridger Studio.
To install 32-bit Java, use this Java download page
to download the JRE (Java Runtime Environment) and install the Java Standard Edition (Java SE) for "Windows x86".
On Unix/Linux systems, it can be difficult to determine if Java is installed on your system. In addition,
once Java is installed, you need to know the installation directory. One way is to follow these steps:
| |
| |
1. Open a command terminal/window. |
| |
2. Enter the command: |
java -version |
| |
If this command does not display a Java version, you should
download Java from this
Java Download page. Then install Java for your system. Java SE is the
Standard edition, and JRE refers to the Java Runtime Environment.
Once Java is installed and working, we need to find the Java Virtual Machine (JVM)
library required by Warehouse. To do this, open a command/terminal window and enter the command:
| |
java -verbose -version 2>&1 | grep java.lang.Object |
If successful, this command shows where the Java runtime library (rt.jar) is installed.
The library needed (libjvm) is nearby. What we need to do is find it. To do this, use the find command
on the Java directory looking for libjvm. For example, if the command above showed:
| |
[Loaded java.lang.Object from /usr/jdk/instances/jdk1.6.0/jre/lib/rt.jar] |
The find command to look for libjvm would be:
| |
find /usr/jdk/instances/jdk1.6.0 | grep libjvm |
Look for a library file called libjvm.so. If there is more than one, choose one to be used later in the installation.
Warehouse requires the Google Analytics Java
client libraries to be on your system to access Google Analytics
data. These libraries are distributed with DataBridger and Warehouse
in the ga4javalib directory and no action by you is required.
|
|
|
2 Steps to Access Google Analytics
|
|
The following is a list of steps required to implement Warehouse access to Google Analytics data.
To begin, we need to make certain we have everything required. If you are missing anything, see the
Requirements section above. Note that the Java Virtual Machine library name is usually not needed on Microsoft Windows because the Java installation writes the name to the Windows registry. (If there is an issue on Windows, the library is in a file called jvm.dll, e.g.
C:\Program Files\Java\jre7\bin\client\jvm.dll)
| |
Item required |
Example |
|
Java Virtual Machine library (not needed on Windows) |
/usr/jdk/instances/jdk1.6.0/jre/lib/i386/libjvm.so |
| |
ID for Google Analytics |
306757946 |
|
Credentials file name |
"C:\Program Files\Taurus\ga4credentials.json" |
Warehouse finds the Java libraries it needs by looking in the ga4javalib directory in the Warehouse installation directory.
Java .jar files may also be listed in the wh.ini file.
The wh.ini file resides in the Warehouse installation directory.
Setup of wh.ini is not typically necessary on Microsoft Windows systems.
To edit wh.ini, use a text file editor such as Notepad on Windows or gedit on Linux.
The first line of the file must be:
[Warehouse]
After that, you need another line pointing to your libraries. Long lines may be continued by putting an ampersand (&) at the end of a line to be continued. JVMCLASSPATH
is a list of .jar files separated by semicolons (;) like this:
JVMCLASSPATH=JarFile1;JarFile2;...
On Unix/Linux systems you need another line pointing to your Java Virtual Machine library using JVMLIB:
JVMLIB=JavaVirtualMachineLibrary
Here is an example snippet from wh.ini on Unix/Linux:
| |
[Warehouse]
JVMCLASSPATH=&
/var/taurus/warehouse/ga4java/animal-sniffer-annotations-1.21.jar;&
/var/taurus/warehouse/ga4java/guava-31.0.1-jre.jar;&
/var/taurus/warehouse/ga4java/threetenbp-1.5.2.jar
JVMLIB=/usr/jdk/instances/jdk1.6.0/jre/lib/i386/libjvm.so |
A simple Warehouse script can be used to verify your Google Analytics setup. The following script displays the number of visits to your website within the last 30 days:
|
open g ga4 id=yourGoogleViewID credentials=yourGoogleCredentialsFileName
|
| |
format ga4fmt : record
au : ga4 metric activeUsers
end
read gr = g format ga4fmt for &
StartDate = "2022-01-01" and EndDate = "today"
print au
endread
|
The Google ID is required to access data, but not to establish a connection to Google. A Warehouse FORMAT statement is required to specify the dimensions and metrics to return. Google Analytics access must always have a start date and end date in YYYY-MM-DD format or Google returns an error.
2.3.1 Request for Permission
You may be required to grant permission the first time DataBridger or Warehouse accesses your Google Analytics 4 data.
To allow access, use a browser to login to your Google Analytics administrator and grant access to your new system.
This step is only required once per system.
A 32-bit version of Warehouse is shipped with DataBridger Studio.
DataBridger Studio version 7.0 supports local Google Analytics 4 data sources. On older 32-but version of Windows, simply follow these instructions
using the Warehouse program shipped with DataBridger Studio.
If your DataBridger Studio installation directory is C:\Program Files\Taurus\DataBridger
you should be able to put the wh.ini here with no trouble.
However, if your DataBridger Studio installation directory is C:\Program Files (x86)\Taurus\DataBridger
(note the x86), you are running on a 64-bit Windows operating system. Since DataBridger Studio is a 32-bit program,
32-bit Java must be installed.
You can test by checking the directory
"C:\Program Files (x86)\Java" If this directory does not exist, you need to install 32-bit Java by following the instructions at Java on Microsoft Windows.
The Warehouse server program resides in the same directory as the Warehouse
client program and shares the wh.ini file.
Therefore no special setup is required for the Warehouse server. Once the wh.ini file has been setup and
the test script runs correctly, the Warehouse server needs only to be stopped and restarted since
wh.ini is only read at startup.
Once the server is running, you can verify it by using the instructions here: Checking the Warehouse Server.
|
3 Troubleshooting
|
|
This section describes ways to diagnose and solve problems. The methods assume
access to a command prompt or terminal window so commands can be entered to diagnose
problems. After opening the command window, you should then change directory (cd command)
to the Warehouse installation directory. Example:
| |
| |
cd C:\Program Files\Taurus\Warehouse |
Windows example |
| |
cd /var/taurus/whii/warehouse |
Unix/Linux example |
| |
To check if Warehouse can access the Java virtual machine, run Warehouse with the
-showinfo parameter which shows a list of diagnostic information.
Look near the bottom for an item called Java Virtual Machine.
If it says Available, the Java virtual machine is available and you may move to the next step.
If it says Unavailable, then either Java is not installed or Warehouse could not find the virtual machine library.
If you cannot find "Java Virtual Machine", then look at the first line Program version.
Warehouse versions prior to 3.04 cannot access Java, so you will need to upgrade Warehouse. Example:
| |
wh.exe -showinfo |
Windows example |
| |
./warehouse -showinfo |
Unix/Linux example |
If Java is unavailable on Windows, the typical cause is that Java is not installed or that you are running 64-bit Windows,
but a 32-bit Warehouse (shipped with DataBridger Studio). To install, see
above Java on Microsoft Windows.
If you need 32-bit Java on a 64-bit system, the -showinfo above will show:
| |
| |
Java Virtual Machine : Unavailable (Need 32-bit Java) |
If this is the case, see the instructions for installing 32-bit Java above Java on Microsoft Windows.
If Java is installed, you may have a more unusual
problem and should contact Taurus Software customer support at (650) 482-2022 x200.
The file MSG992 is required. It is included in your installation, so you should not usually be concerned about this file. Once Java is available, you can test for MSG992
by running Warehouse with -c and pressing ENTER at the first prompt. After ENTER, Warehouse checks for MSG992 and if it finds it, then prompts for Google login information. If MSG992 is not found, Warehouse silently quits.
Example, showing MSG992 installed correctly:
|
.\wh.exe -c |
| |
Enter name or IP address of server -> |
| |
Enter Google Analytics 4 ID (optional) -> |
-
Java code is compiled into class files and class files are often grouped in .jar files.
Google distributes their libraries as .jar files. Warehouse needs to know where the Google .jar files
are so Warehouse can tell the Java Virtual Machine. This is done by adding the .jar file locations to the wh.ini file. We can test the Google libraries
by running Warehouse with -c and entering our Google login information. Example:
.\wh.exe -c
Warehouse 7.00.0050-U (c) Taurus Software, Inc. 2022
Warehouse Server Connection Verification.
Enter name or IP address of server ->
Enter Google Analytics 4 ID (optional) -> 503667957
Enter Google credentials file name -> C:\Wh\credentials\mycreds.json
Warehouse OPEN statement with encrypted password:
OPEN dbtag GA4 ID=503667957 &
CREDENTIALS="C:\Wh\credentials\mycreds.json"
Connection to Google Analytics 4 SUCCESSFUL.
If you see an error that looks like the one below, the Google Analytics libraries could not be found.
This is usually because your wh.ini file does not point to the Google Analytics .jar files in he JVMCLASSPATH section. Verify
the JVMCLASSPATH section in the wh.ini file.
| |
Error opening GA 4 connection (step new com.google.analytics.data.v1beta.BetaAnalyticsDataClient): Error finding class com/google/an
alytics/data/v1beta/BetaAnalyticsDataClient: java.lang.NoClassDefFoundError: com/google/analytics/data/v1beta/BetaAnalyticsDataClient DJERR 8431 (WHERR 19606)
|
| |
| |
*** Connection to Google Analytics 4 FAILED!.
|
Decoding the meaning of error messages from Google can be trying.
Here is a list of some of the more common script errors and what they mean:
Example 1: |
Error message: |
Error getting Google Analytics data: Exception occurred in method get: java.lang .IllegalArgumentException: Parameter ids must conform to the pattern ga:[0-9]+ D JERR 8442 |
Cause: |
This error message is caused when attempting to read data without specifying an ID on the OPEN statement |
Solution: |
Provide a valid ID on the OPEN statement in your Warehouse script.
See Google Analytics ID.
|
Example 2: |
Error message: |
Error setting up to read GA 4 call RunReportRequest.build(): Exception occurred in method runReport: com.google.api.gax.rpc.InvalidA
rgumentException: io.grpc.StatusRuntimeException: INVALID_ARGUMENT: Invalid property ID: . A numeric Property ID is required. To lea
rn more about Property ID, see https://developers... (WHERR 19608) |
Cause: |
This error message is caused when attempting to read data
with an invalid ID specified on the OPEN statement. |
Solution: |
Provide a valid ID on the OPEN statement in your Warehouse script.
See step 3 here: Giving access to your Google Analytics data.
|
Example 3: |
Error message: |
Error opening GA 4 connection (step call create()): Exception occurred in method create: java.io.IOException: The Application Default Credentials are not available. They are available if running in Google Compute Engine. Otherwise, the environment variable GOOGLE_
APPLICATION_CREDENTIALS must be defined ... (WHERR 19606) |
Cause: |
This error message is caused when attempting to read data
without specifying a credentials .json file on the OPEN statement. A credentials .json must be obtained
from Google before Google Analytics 4 data may be accessed.
|
Solution: |
Provide a valid credentials .json file on the OPEN statement in your Warehouse script.
See Get Your Credentials.
|
Example 4: |
Error message: |
Start date end end date are both required. (WHERR 19633) |
Cause: |
This error message is caused when attempting to read data
without specifying both a start date and an end date.
The important part of this message is where it says required.
|
Solution: |
Provide both a start date and an end date on the READ statement in your Warehouse script.
|
Since the Warehouse server program resides in the same directory as the Warehouse client program, once the wh.ini file has been setup and
the test script runs correctly, the Warehouse server needs only to be stopped and restarted. Run the Warehouse client program with the -serverinfo serverName parameter to show diagnostic information from the server. Example:
| |
wh.exe -serverinfo myserver |
Windows example |
| |
./warehouse -serverinfo myserver |
Unix/Linux example |
If -serverinfo fails, either the Warehouse server
is not running or you have a network/firewall issue.
In this case, please check with your network administrator.
Look near the bottom of the -serverinfo output for an item called Java Virtual Machine. If it says Available Warehouse can access Java. If it says Unavailable, then use a window to login to the server and troubleshoot the Warehouse client program.
We can test the Google access to a Warehouse Server
by running Warehouse with -c and entering our Google login information.
|
.\wh.exe -c |
| |
Enter name or IP address of server -> |
Enter server name |
| |
Enter user name on server (Optional) -> |
Enter server user name |
| |
Enter password -> |
Enter server user password |
| |
Enter remote database type (optional) -> |
Enter GA4 |
| |
Enter Google Analytics 4 ID (optional) -> |
Enter Google ID |
| |
Enter Google credentials file name -> |
Enter full name of credentials .json file |
If everything is correct, you will see a sample OPEN statement with an encrypted password followed by:
| |
Connection to Warehouse server myserver SUCCESSFUL. |
If the connection is unsuccessful, use a window to login to the server and troubleshoot the Warehouse client program.
A simple Warehouse script can be used to verify Warehouse server access to your Google Analytics data.
The following script displays the number of visits to your website within the last 30 days:
| |
open g remote user=yourServerUser pass=yourServerPassword & |
| |
ga4 id=yourGoogleClientID credentials=yourGoogleCredentialsFile |
| |
format ga4fmt : record
au : ga4 metric activeUsers
se : ga4 metric sessions
end
read gr = g format gafmt for StartDate = &
($now - convert(str2date("30","NN"),"interval") pic "YYYY-MM-DD") &
and EndDate = "today"
print au, se
endread
|
If your server has been setup correctly and the connection informatiom in this script is correct,
then this script will complete successfully.
|
|
Last updated 06/21/2022
| | | | | |
