This article is for people that use the Google tag or Tag Manager and need to troubleshoot their tagging setup.
Tag Assistant is a tool to help you troubleshoot your tagging setup. Tag Assistant lets you:
- Review which tags are on a website.
- Review which events have fired.
- Review the data that's being passed into your data layer.
- Export a debug session so you can share it with someone else, for example, Google support.
- Import debug sessions from someone else.
- Share a debugging URL so that someone else can debug for you.
- Install the Tag Assistant Companion Chrome extension
- About the debug parameter
- Start a new debug session
- About the Tag Assistant UI
- Export a debug session
- Import a debug session
- Share debugging access with someone else
- Exit debug mode
- Verify Google Ads conversion actions with Tag Assistant
- Troubleshoot connection issues
Install the Tag Assistant Companion Chrome extension
The Tag Assistant Companion Chrome extension operates as a companion to the extension-less debugger. For optimal debugging results, install the Tag Assistant Companion Chrome extension. When the Chrome extension is present, the following features are enabled:
- Detection of the Google tag inside an iframe.
- Debugging of pop-up windows or new tabs opened from the current window.
- The debug window opens in a new browser tab instead of a pop-up. This allows the user to manipulate the browser URL bar and can help facilitate debugging of referrer-based actions.
- Multiple windows can be debugged in the same debug session. Each window is marked with a symbol in the event tree so that they can be easily identified.
About the debug parameter
Tag Assistant will automatically set a "debug" parameter (
_dbg) for hits sent to an App + Web measurement ID. This can help you see the hits displayed in other debugging surfaces such as App + Web's DebugView. To give you the ability to inspect hits individually, App + Web hits are not batched when sent.
Start a new debug session
To start a new debug session:
- Open Tag Assistant
- Click Add domain.
- Enter the URL of the page you would like to debug.
- Click Start. Tag Assistant loads the website to debug in a new tab.
- Some sites might not work when there is a debug parameter added to the URL. If so, uncheck the box Include debug signal in the URL.
To resume an active or closed debug session, click the domain name from the Active Domains or History on the Tag Assistant homepage.
Once enabled, a new window will launch for the page you entered, with the debug UI opening in the existing Tag Assistant browser window. The debug UI in the Tag Assistant window shows detailed information about your
gtag() commands and events, including how tags fired and what data is being processed. Debug information is not visible to your regular website visitors. The debug window will stay open and display debug information while you navigate within the same domain and as long as there as the Google tag is on the page.
As you click through your website, the debug window will update information about how your tags are fired. You can use this information to see if a tag fired successfully, what triggered (or did not trigger) its firing status, and what network requests were made as a result of the tag firing.
About the Tag Assistant UI
When Tag Assistant fist opens, you see the default Summary view with an overview of events and tag information for the requested page. If multiple Google tags or Tag Manager containers are detected, select one to see all hits for that specific Google tag or container.
Note: Browser events may be applied to all containers, but the hits are filtered by the container that is selected.
The left side of the screen displays a list of events. The Output section will display a card for each hit detected for the selected ID.
Events are grouped by the page where they took place. Click on a page title in the left navigation bar to view a page-level summary. A new page group is added to the top of the list as the user navigates to another page in the site that has the Google tag on the page.
Events appear in the order they were fired and are numbered accordingly. Events marked with a are built-in triggers that were emitted automatically when the Google tag loaded. Click on an event in the left column to view more detail.
Output will show where hits were sent, updates to the data layer, and any errors.
Hits Sent will show where a particular hit was sent, and what kind of hit it was:
When you click on this hit, a detail window will appear. This view shows detail about the parameters that were sent with each hit.
The Data Layer tab shows values found in the
dataLayer object. When Summary is selected, it will display the current state of the data layer, as well as the data that was pushed to the data layer for each event.
Export a debug session
Exporting a Tag Assistant session is useful when you need help debugging your tags. The exported file stores your debug history, which another person can import into their Tag Assistant browser window.
To export a debug session:
- Open Tag Assistant
- Navigate through your website to populate debug information in Tag Assistant.
- When you're ready to export your debug session, click the the overflow menu Export session.
- Read through the disclaimer and click Export. The exported file will be saved on your computer. Don't modify the file name or the file contents as that may corrupt the file contents.
- Share the file with the person that helps you debug your tagging, so that they can import the debug session.
Import a debug session
You can import a Tag Assistant debug session to learn about the steps that someone took to test their tagging setup. Imported debug sessions open in read-only mode, meaning you can't continue debugging. No new hits or tags can fire in an imported session. If you need to test a website on someone else's behalf, ask them to share debug access.
To import a debug session:
- Open Tag Assistant
- In the overflow menu , select Import session.
- Upload the debug session file. The imported session opens in read-only mode.
Share debugging access with someone else
If you need help debugging your tagging setup, you can give someone else access to Tag Assistant.
To share debugging access:
- Open Tag Assistant
- Start a new debug session.
- In the overflow menu , select Share.
- Review the debug settings and click Copy Link.
- Share the debug link with the person that helps you.
Exit debug mode
To exit debug mode:
- Switch to the web browser tab that is active for debug mode.
- Click Stop Debugging in the floating window, home page, or the X in the upper left corner of the debug window.
Verify Google Ads conversion actions with Tag Assistant
The Tag Assistant integration with Google Ads includes a guided mode to facilitate conversion action verification.
The Google Ads conversions summary page includes links to troubleshoot unverified conversion actions. This launches Tag Assistant from where you can enter debug mode as described above.
The Tag Assistant overlay within the page displays guidance for verifying conversion actions. Once complete, clicking Finish displays a summary within the Tag Assistant window that specifies the tested conversion actions. These results are reflected in the Google Ads Conversions Summary page after a short delay. Learn more.
Troubleshoot connection issues
If the debug window does not connect to your page successfully, try some of these solutions:
- The URL you entered might not have the Google tag on the page. Try a different URL on your website where you expect to have the Google tag installed.
- The debug parameter added to the page URL may interfere with page behavior. To solve this, edit the domain that you enter for debug mode, and deselect the checkbox labeled Include debug signal in the URL.
- The Google tag script is loaded after the point when Tag Assistant tries to connect to the page. Click Retry to connect again.
- Your page is an AMP page. AMP is not currently supported by Tag Assistant.
- The page loads the Google tag in an iframe. iframe-loaded tag configurations can only be debugged when the Tag Assistant Companion chrome extension is also installed.
- Multiple browser redirects can prevent the debug window from loading.
- Ad blockers installed in your web browser may prevent the Google tag from running. Disable ad blockers for the pages you need to test.
- If you have the Tag Assistant Companion installed, make sure the extension has permission to read and change site data for the pages you need to test.
- Consent management tools may block Google tags. Configure any consent management tools that you use to allow interaction with Google's consent API.