How to Add Google Analytics to Chrome Extension

Tracking your Chrome extension's usage is essential for understanding how people interact with it, but setting up analytics can feel tricky due to Google's new security rules. This guide walks you through the entire process of adding Google Analytics 4 to your Chrome extension. We'll cover everything from initial setup to implementing tracking code that works with Manifest V3 and debugging your events to make sure your data is accurate.

Graphed

Still Building Reports Manually?

Watch how growth teams are getting answers in seconds — not days.

Watch the Demo

Why Track Your Chrome Extension's Usage?

Before jumping into the technical steps, let’s briefly cover why you’d want to do this in the first place. You’ve built an extension to solve a problem, but without data, you’re flying blind. Analytics helps you:

• Understand User Engagement: Discover which features are the most popular and which are being ignored. This insight helps you prioritize what to improve or promote.
• Identify Usability Issues: By tracking user workflows, you can spot where users might be getting stuck or dropping off, giving you clear signals on what to fix.
• Make Data-Driven Decisions: Instead of guessing what to build next, you can use real data to validate ideas and confidently invest your development time where it matters most.
• Measure a Feature's Success: When you roll out a new feature, you can concretely measure its adoption and impact on user behavior.

In short, data transforms your extension from a project into a product that can evolve based on real user feedback.

Choosing the Right Tool: Google Analytics 4

For years, developers have used various analytics tools, but with Google deprecating its old Universal Analytics (UA), Google Analytics 4 is the current standard. GA4 is perfect for a Chrome extension for one simple reason: it's built around an event-based model.

Unlike old analytics platforms that were centered on "page views," GA4 treats every interaction - a button click, a setting change, a form submission - as a distinct event. This is exactly how we need to think about user interactions within an extension. Clicks in a popup window, option changes, and background script actions are all events we can track to create a complete picture of user activity.

Step 1: Create a Google Analytics 4 Property

First things first, you need a place in Google Analytics for your extension's data to live. This is called a "Property." If you already have a GA4 account, you can add a new property to it. If not, you'll need to create an account first.

Here’s how to set up the property:

1. Log in to your Google Analytics account.
2. Navigate to the Admin section by clicking the gear icon in the bottom-left corner.
3. In the "Property" column, click the blue + Create Property button.
4. Give your property a clear name, like "My Awesome Extension Analytics," and select your reporting time zone and currency. Click Next.
5. Fill out the optional business details and click Create.

Now, Google will ask you to set up a "data stream." This is the source that will feed data into your new property.

Setting Up Your Data Stream

Data streams are connectors to your websites and apps. A Chrome extension isn't a traditional website, but we will choose "Web" to get the credentials we need.

1. Under "Choose a platform," select Web.
2. For the website URL, you can enter a placeholder since the extension doesn't have a URL in the traditional sense. You could use your extension’s marketing homepage or something like https://my-extension-analytics.com. This field is just required to proceed.
3. Give the stream a name, like "Chrome Extension."
4. Click Create stream.

After creating the stream, you'll see a panel with your stream details. Find and copy the Measurement ID (it will look something like G-XXXXXXXXXX). Keep this safe, you’ll need it very soon.

Graphed

Still Building Reports Manually?

Watch how growth teams are getting answers in seconds — not days.

Watch the Demo

Step 2: Addressing Manifest V3 and Its Restrictions

This is where things get interesting. Chrome's new Manifest V3 specification introduced stricter security policies to make extensions safer. One of its key rules is a default prohibition on remotely hosted code. This means you can't just drop in the standard GTag.js tracking snippet that Google provides for websites.

The standard GTag script fetches other scripts from Google's servers to function, which violates Manifest V3's policy. Trying to use it will result in Content Security Policy (CSP) errors in your extension’s console.

So, how do we track events without the official JavaScript library? We use the GA4 Measurement Protocol.

The Measurement Protocol is a raw endpoint that lets you send event data directly to Google's servers using simple HTTP requests. By sending data this way, we are not executing any remote code, making our implementation fully compliant with Manifest V3. This is the official and recommended way to integrate analytics into environments like a Chrome extension.

Step 3: Implementing Analytics with the Measurement Protocol

Now we're ready to write some code. The goal is to create a function that builds and sends an event to the Measurement Protocol endpoint whenever a user takes a meaningful action.

Get Your API Secret

Besides the Measurement ID, you need an API secret for authenticating your requests. To get it:

1. Go to Admin > Data Streams and click on your web stream.
2. Under the "Events" section, find and click on Measurement Protocol.
3. Click the Create button. Give your API secret a nickname (e.g., "Extension_Secret") and copy the generated Secret value.

Important: Keep this API secret secure. Do not expose it in client-side code that could be easily inspected if your extension uses content scripts on public pages.

Update Your manifest.json

To send data to Google's servers, your extension needs permission. Open your manifest.json file and add the Google Analytics URL to host_permissions:

{
  "name": "My Awesome Extension",
  "version": "1.0",
  "manifest_version": 3,
  ...
  "host_permissions": [
    "https://www.google-analytics.com/"
  ]
}

Create and Store a client_id

Google Analytics needs a way to anonymously identify a unique user across multiple sessions. On the web, this is done with a cookie. In an extension, we have to create and manage this ID ourselves.

We’ll use chrome.storage.local to store a persistent client_id. The following function checks if an ID already exists, and if not, it generates a new one. This ensures we don’t create a new "user" every time the extension is opened.

Create a helper file (e.g., analytics.js) and add this function:

async function getOrCreateClientId() {
  const result = await chrome.storage.local.get('clientId'),
  let clientId = result.clientId,
  if (!clientId) {
    // Generate a new client ID and store it.
    clientId = self.crypto.randomUUID(),
    await chrome.storage.local.set({ clientId }),
  }
  return clientId,
}

Graphed

Still Building Reports Manually?

Watch how growth teams are getting answers in seconds — not days.

Watch the Demo

Build the Event Sending Function

This is the core of our implementation. This function will take an event name and its parameters, construct the request body, and send it to the Measurement Protocol.

In the same analytics.js file, add the main function:

async function sendGAEvent(name, params = {}) {
  // Be sure to replace these with your actual Measurement ID and API secret.
  const MEASUREMENT_ID = 'G-XXXXXXXXXX',
  const API_SECRET = 'YOUR_API_SECRET', // Replace with a real one

  // Get the client ID or create a new one.
  const clientId = await getOrCreateClientId(),

  const eventData = {
    client_id: clientId,
    events: [{
      name: name,
      params: {
        // Required parameters for GA4 to handle the event correctly
        session_id: "12345", // A static session ID is used here for simplicity
        engagement_time_msec: '100', // A nominal engagement time
        ...params
      },
    }],
  },

  try {
    await fetch(`https://www.google-analytics.com/mp/collect?measurement_id=${MEASUREMENT_ID}&api_secret=${API_SECRET}`, {
      method: 'POST',
      body: JSON.stringify(eventData),
    }),
  } catch (error) {
    console.error('Google Analytics request failed:', error),
  }
}

Note: For more advanced usage, you'd want to dynamically manage the session_id to properly group events in your reports, but a static value works for getting started.

Step 4: Putting It All Together: Tracking Real Events

Now that you have your sendGAEvent function, you can call it from anywhere in your extension to track meaningful user actions.

Tracking Extension Installation

A great first event to track is the initial installation. This is done inside your background script (service worker) using the chrome.runtime.onInstalled API.

In your background.js:

// Assuming analytics.js is correctly imported/available.
import './analytics.js',

chrome.runtime.onInstalled.addListener((details) => {
  if (details.reason === 'install') {
    // Call our event function with a descriptive name.
    sendGAEvent('extension_installed'),
  }
}),

Graphed

Still Building Reports Manually?

Watch how growth teams are getting answers in seconds — not days.

Watch the Demo

Tracking A Button Click in Your Popup

Let's say your popup has a button with an ID of exportBtn. You can track clicks on it inside your popup's JavaScript file (popup.js).

// In popup.js

document.addEventListener('DOMContentLoaded', () => {
  const exportButton = document.getElementById('exportBtn'),
  if (exportButton) {
    exportButton.addEventListener('click', () => {
      // Send an event with a custom parameter
      sendGAEvent('export_button_clicked', {
        export_type: 'csv'
      }),
      
      // Your button's actual functionality goes here
    }),
  }
}),

Tracking "Page" Views

If your extension's popup has multiple views or tabs, you can track these as screen_view events. This helps you understand which parts of your UI are being used.

// e.g., When the user navigates to the 'Settings' tab in your popup
function showSettingsView() {
  sendGAEvent('screen_view', {
    screen_name: 'Settings Page'
  }),
  // Code to render the settings view
}

Step 5: Verifying and Debugging Your Events

You’ve done all the work, but how do you know if the events are actually reaching Google Analytics? Don't just deploy and hope for the best - use GA4’s DebugView.

To make your events appear in DebugView, we'll temporarily send them to a special debug endpoint. Modify your fetch URL like so:

FROM:

https://www.google-analytics.com/mp/collect?measurement_id=...&api_secret=...

TO:

https://www.google-analytics.com/debug/mp/collect?measurement_id=...&api_secret=...

After making this change, reload your extension and perform the actions you want to test (e.g., click a tracked button). Now, follow these steps:

1. Go to your GA4 property in Google Analytics.
2. Navigate to Admin > DebugView.
3. You should see your events stream in real-time, appearing as blue icons on the timeline. You can click on an event to inspect all the parameters you sent with it.

If events are not showing up:

• Check the service worker console and the popup console for any error messages related to the fetch request.
• Double-check that your Measurement ID and API Secret are correct.
• Ensure you've reloaded your extension after changing the manifest.json file.

Once you've confirmed everything is working, remember to remove /debug from the URL before publishing your extension.

Final Thoughts

By using the GA4 Measurement Protocol, you can effectively bypass Manifest V3's limitations and gather crucial usage data from your Chrome extension. This setup not only ensures compliance with Google's latest security standards but also empowers you to make smarter, data-driven decisions that will help your extension thrive.

Of course, collecting data is just the first step. The real challenge often lies in making sense of it all, especially when your extension data is just one piece of the puzzle. That's why we built Graphed to help. We make it easy to connect your Google Analytics account along with all your other marketing and sales tools. Instead of wrestling with complex reports, you can just ask questions in plain English - like "Which features are most used by paying customers?" - and get instant dashboards and insights, helping you see the full picture without any of the manual work.