/
Google Analytics 4 (GA4) Integration

Google Analytics 4 (GA4) Integration

⭐️ Overview

Google Analytics 4 was added to Hyku in v6.0. Google Analytics is enabled at the global application level. Currently, this requires the application/repository administrator and a developer to work in tandem to configure the application. Once the application is configured, tenants can create their own analytics accounts.

Setting up Google Analytics requires configurations in Google Cloud Console, Google Analytics, and the Hyku application. Each tenant will create a Google Analytics account and configure the Hyku application.

What is Google Analytics?

Google Analytics (GA4) is a free tool that tracks users' interactions with the Hyku application.

Hyku can be configured to use Google Analytics to track the following:

  • Visits to the application

  • Work views

  • Collection views

  • File set views

  • File set downloads

There is an optional configuration to issue batch emails to depositors with the analytics relating to their works.

Quick Reference

  • Google Cloud Console

  • Google Analytics

  • Service Account email address - ends with gserviceaccount.com

  • Measurement ID - G-XXXXXXXXXX

  • JSON key file is sent to the developers, encoded, and added to the application ENV secrets in GitHub

  • Admin and tenant Service Account email address need to be added to Google Analytics Account access management

🌎 System Admin

If you are the admin of an individually hosted Hyku application, this is your to-do list.

Task Checklist Overview

  1. Set up Google Cloud Console

    • Create a Service Account project

    • Create a Service Account email address

    • Generate JSON key file

      • Send JSON key file to the developer

    • Enable Google Analytics Data API

  2. Create a Google Analytics account

    • Create a new Account

    • Create a new Property

    • Get Measurement ID - G-XXXXXXXXXX

    • Get Google Analytics Property ID

    • Add the Service Account email address to the Account access management

  3. Add Google Analytics to Hyku

    • Enable analytics in Hyku

  4. Enable Google Analytics for a tenant

    1. Provide Service Account email

1. Set up Google Cloud Console

Already have one?

  1. Create a Service Account project

    1. Go to Google Cloud Console and sign in

    2. Select an existing project or create a new project by providing a name, connect it to an organization, if available, and Create.

    3. The project name should now be visible in the top navigation bar. If not, Click on the Select a project link next to Google Cloud and choose your project name.

      selecta-20250827-180313.png

  2. Create a Service Account email address

    1. Click the menu icon in the top left corner to open the sidebar.

      image-20250827-181526.png

    2. In the sidebar > IAM & Admin > Service Accounts

    3. Click + Create service account

      image-20250827-182914.png

    4. Insert a name for the service account in Service account name > Done. Providing a Service account description can be helpful if you expect to have multiple service accounts.

      1. The Service Account email address will display on this page, ending with gserviceaccount.com.

      2. ✅ Keep this handy for later in the process.

        service_email_address_obf.png

  3. Generate JSON key file

    1. Click on the Service Account email address URL.

      2025-11-04 17_56_59-service_account_email_obf.png

    2. Keys > Add Key > Create new key > select JSON > Create

      1. The file will have a .json extension. Download the file.

      2. ✅ Send the JSON file to the development team to be added to the Hyku application ENV secrets in GitHub.

  4. Enable Google Analytics Data API

    1. Click on the Google Cloud icon in the upper left corner.

    2. Click on APIs & Services in the Quick access area. After this initial usage, APIs & Services should display in the left sidebar. If it is not there, click on View all products at the bottom of the page and click on APIs & Services.

      apis.png

    3. Click on + Enable APIs and services.

      enable_apis.png

    4. Search for google analytics.

      api_analytics.png

    5. Select Google Analytics Data API.

    6. Click Enable.

      api_enable.png

    7. When done, the Google Analytics Data API screen should appear. Click on the Credentials tab near the bottom to reveal the email address and name of the service account. This should match the account you created earlier.

      api_credentials.png

2. Create a Google Analytics account

Already have one?

  1. Create a new Account

    1. Go to Google Analytics

    2. In the sidebar > Admin (gear icon) > + Create > Account

    3. Create a name for this Google Analytics account. This is the highest level of organization and can contain multiple properties, each representing a specific repository, website, or app for tracking and analysis. The Account Data Sharing Options below can be filled out per your institution’s guidelines.

      create_account.png

  2. Create a new Property

    1. In the sidebar > Admin (gear icon) > + Create > Property

    2. Create a Property name. Properties collect data about a specific repository or website. Note that you can change this information later in the Admin section.

      image-20251107-185503.png

    3. Choose an industry category and business size.

      image-20251107-190424.png

    4. Choose at least one business objective.

    5. Click Create.

    6. On the Start collecting data page, click on Web under Choose a platform.

    7. Provide the homepage (root) Website URL for your repository and a Stream name. Note that the protocol is chosen in the drop-down menu and not included in the URL textbox.

      image-20251107-192410.png

    8. Click Create and continue.

    9. Cancel out of the Set up a Google tag modal unless your institution uses this.

      image-20251107-195532.png

  3. ✅ Get Measurement ID - G-XXXXXXXXXX

    1. After creating your Property ID, a the Web stream details view will display Measurement ID. This ID will be added to Hyku.

      image-20251107-200150.png

    2. If the account and property were successfully created, a message should display stating Data collection is pending. Data collection should begin within 48 hours.

      image-20251107-201656.png

  4. ✅ Get Google Analytics Property ID

    1. In the sidebar > Admin (gear icon) > Property settings > Property > Property details

      image-20251107-202154.png

    2. Copy the Property ID, which should be displayed in the upper right corner. This ID will be added to Hyku.

      image-20251107-202534.png

  5. Add the Service Account email to Google Analytics

    1. In the sidebar > Admin (gear icon) > Account settings > Accounnt > Account access management

      image-20251107-203839.png

    2. Click the + icon in the upper right corner and choose Add users.

      image-20251107-204225.png

    3. Add the Service Account email in the Email addresses input. Choose the Administrator role.

      image-20251107-204440.png

Add Data Visualization (Optional)

3. Add Google Analytics to Hyku

Prerequisite tasks (a quick double check of the previous steps)

  1. Create Service Account email in Google Cloud Console

  2. Create Google Analytics account

  3. Get Measurement ID

  4. Get Property ID

  5. Add the Service Account email address to the Google Analytics Account access management as Administrator

  1. Enable analytics in Hyku

    1. Dashboard > Settings > Accounts

    2. Check box for Analytics

    3. Enter Measurement ID G-XXXXXXXXXX

    4. Enter Property ID

    5. Option to check Batch email notifications to allow depositors to receive analytics reports on their works

    6. Save changes

4. Enable Google Analytics for a tenant

  1. Provide the tenant with the global application Service Account email address - ends with gserviceaccount.com

    1. Tenant will add the global Service Account email to their Google Analytics account

      1. In the sidebar > Admin (gear icon) > Account > Account Access Management

      2. Add global Service Account email (ends with gserviceaccount.com) > set as Administrator

📚 Tenant

If you are the tenant of the application, this is your to do list.

NOTE: If you are on a manage instance of Hyku, this is your do to list.

Task Checklist Overview

  1. Create a Service Account email address in Google Cloud Console

    • Create Service Account email address

  2. Create a Google Analytics account

    • Create a new Property

    • Get Measurement ID - G-XXXXXXXXXX

    • Get Google Analytics Property ID

    • Add the Service Account email address to the Account access management

    • Add the global admin (or hosted service provider) Service Account email address to the Account access management

  3. Configure Hyku settings

1. Create a Service Account email address in Google Cloud Console

Already have one?

  1. Create a Service Account project

    1. Go to Google Cloud Console and sign in

    2. Select an existing project or create a new project by providing a name, connect it to an organization, if available, and Create.

    3. The project name should now be visible in the top navigation bar. If not, Click on the Select a project link next to Google Cloud and choose your project name.

      selecta-20250827-180313.png

  2. Create a Service Account email address

    1. Click the menu icon in the top left corner to open the sidebar.

      image-20250827-181526.png

    2. In the sidebar > IAM & Admin > Service Accounts

    3. Click + Create service account

      image-20250827-182914.png

    4. Insert a name for the service account in Service account name > Done. Providing a Service account description can be helpful if you expect to have multiple service accounts.

      1. The Service Account email address will display on this page, ending with gserviceaccount.com.

      2. ✅ Keep this handy for later in the process.

        service_email_address_obf.png

2. Creating a New Google Analytics Account

Already have one?

  1. Create a new Account

    1. Go to Google Analytics

    2. In the sidebar > Admin (gear icon) > + Create > Account

    3. Create a name for this Google Analytics account. This is the highest level of organization and can contain multiple properties, each representing a specific repository, website, or app for tracking and analysis. The Account Data Sharing Options below can be filled out per your institution’s guidelines.

      create_account.png

  2. Create a new Property

    1. In the sidebar > Admin (gear icon) > + Create > Property

    2. Create a Property name. Properties collect data about a specific repository or website. Note that you can change this information later in the Admin section.

      image-20251107-185503.png

    3. Choose an industry category and business size.

      image-20251107-190424.png

    4. Choose at least one business objective.

    5. Click Create.

    6. On the Start collecting data page, click on Web under Choose a platform.

    7. Provide the homepage (root) Website URL for your repository and a Stream name. Note that the protocol is chosen in the drop-down menu and not included in the URL textbox.

      image-20251107-192410.png

    8. Click Create and continue.

    9. Cancel out of the Set up a Google tag modal unless your institution uses this.

      image-20251107-195532.png

  3. ✅ Get Measurement ID - G-XXXXXXXXXX

    1. After creating your Property ID, a the Web stream details view will display Measurement ID. This ID will be added to Hyku.

      image-20251107-200150.png

    2. If the account and property were successfully created, a message should display stating Data collection is pending. Data collection should begin within 48 hours.

      image-20251107-201656.png

  4. ✅ Get Google Analytics Property ID

    1. In the sidebar > Admin (gear icon) > Property settings > Property > Property details

      image-20251107-202154.png

    2. Copy the Property ID, which should be displayed in the upper right corner. This ID will be added to Hyku.

      image-20251107-202534.png

  5. Add the Service Account email to Google Analytics

    1. In the sidebar > Admin (gear icon) > Account settings > Accounnt > Account access management

      image-20251107-203839.png

    2. Click the + icon in the upper right corner and choose Add users.

      image-20251107-204225.png

    3. Add the Service Account email in the Email addresses input. Choose the Administrator role.

      image-20251107-204440.png

  6. Add the global admin Service Account email to Google Analytics

    1. In the sidebar > Admin (gear icon) > Account > Account Access Management

    2. Add Service Account email (ends with gserviceaccount.com) > set as Administrator

Add Data Visualization (Optional)

3. Configure Hyku settings

  1. Enable analytics in Hyku

    1. Dashboard > Settings > Accounts

    2. Check box for Analytics

    3. Enter Measurement ID G-XXXXXXXXXX

    4. Enter Property ID

    5. Option to check Batch email notifications to allow depositors to receive analytics reports on their works

    6. Save changes

💻 Developer

If you are the developer with access to GitHub, this is your to do list.

Task Checklist

  • Encode the JSON key

  • Add JSON key to ENV variables in GitHub

Encoding the JSON Key

  1. Download the JSON key file.

    1. The admin of the Hyku account should create this file in Google Cloud Console and provide it to the developer.

  2. In terminal, run the following: base64 -b 0 -i ~/Downloads/<file-name>.json | pbcopy

    1. This will copy the encoded key to your clipboard.

Adding JSON Key to Enable Google Analytics in Hyku

  1. Update ENV['GOOGLE_ACCOUNT_JSON']with the encoded JSON key

    1. GitHub > Settings > Environments > Add or edit Environment secrets

🔎 Retrieving Existing Account Information

Google Cloud Console

  • Service account email address - ends with gserviceaccount.com

  • JSON private key file

    • The JSON cannot be retrieved or recreated. If you don't have access to the JSON, create a new key and sent the new JSON file to the development team.

    • Go to Google Cloud Console

    • In the sidebar > IAM & Admin > Service Accounts

    • Click on the newly created Email link > Keys > Add Key > Create new key > JSON > file will be downloaded

Google Analytics

  • Google Analytics Measurement ID G-XXXXXXXXXX

    • In the sidebar > Admin (gear icon) > Property settings > Data collection and modification > Data streams

    • Click on the side arrow > the Web stream details page will have the Measurement ID G-XXXXXXXXXX

  • Google Analytics Property ID

    • In the sidebar > Admin (gear icon) > Property > Property Details > Property ID is in the upper right corner

Data Visualization (Optional)

  1. In the left navigation, choose “Explore.”

    image-20251107-214215.png

  2. Choose “Blank (Create a new exploration).”

    image-20251107-214330.png

  3. Under “Variables,” click the plus sign ( + ) to the right of “Dimensions.”

    image-20251107-214631.png

  4. Open “Event” and check “Event name.”
    Open “Page/Screen” and check “Content ID” and “Content type.”

    image-20251107-214949.png

  5. Click “Confirm” in upper right corner.

  6. Under “Variables,” click the plus sign ( + ) to the right of “Metrics.

    image-20251107-215350.png

  7. Open “Event” and check “Event count.”

    image-20251107-215501.png

  8. Click “Confirm” in the upper right corner.

  9. Settings

    1. Drag and drop the Event name, Content type, and Content ID under Rows.

      image-20251108-034447.png

    2. Drag and drop the Event count under Values.

      image-20251108-034847.png

    3. Find “Show rows” and update it to 500.

      image-20251108-035118.png

    4. In the left Navigation choose “Explore” again.

    5. Click the vertical ellipsis / three dots on the right side of the exploration you created and select “Share” from the dropdown. This will read-only share with all users on this GA4 property.

      Explore_Share_GA4_screenshot.png