JP Agent Tracking Bridge (docs)

Article Index

JP Agent Tracking Bridge connects a WordPress or Joomla website to an AI agent and gives the agent controlled tools for configuring, managing and verifying website tracking.

Instead of manually creating tracking rules, Google Tag Manager triggers and Google Analytics events, you can describe what you want to measure in normal language. The AI agent can inspect the website and the existing tracking setup, recommend a suitable configuration, implement approved changes and help verify that the tracking works.

JP Agent Tracking Bridge is designed to work with Google Analytics 4, Google Tag Manager and compatible AI agent environments such as Hermes, Claude and Codex.

The WordPress edition also includes optional WooCommerce ecommerce tracking.

How JP Agent Tracking Bridge Works

JP Agent Tracking Bridge is built around a simple workflow:

Inspect → Discuss → Approve → Implement → Verify

The plugin itself does not try to replace Google Analytics or Google Tag Manager. Instead, it provides a controlled bridge between:

Your WordPress or Joomla website
Your AI agent
Google Tag Manager
Google Analytics 4

A typical request can be very simple:

Inspect my website and help me track successful contact forms, email clicks and phone clicks. Tell me what you recommend before making changes.

The AI agent can then inspect the actual website, review existing tracking, discuss the recommended setup with you and implement the configuration after approval.

Requirements

To use JP Agent Tracking Bridge you need:

A supported WordPress or Joomla website
A Google Analytics 4 property if GA4 tracking is required
A Google Tag Manager container if GTM configuration is required
A compatible AI agent environment
The JP Agent Tracking Bridge Google Tools / MCP integration for automated Google Analytics and Google Tag Manager access

For the full AI-assisted workflow, your AI agent needs access to the JP Agent Tracking Bridge tools. This allows the agent to work with the website and, after Google authorization, with the Google Analytics and Google Tag Manager resources connected to your account.

Customers do not need to create Google service accounts or manually share their Analytics and Tag Manager accounts with a technical service user.

WordPress Installation

Download the latest WordPress version of JP Agent Tracking Bridge from your JPro Studio account.
Log in to your WordPress administrator.
Go to Plugins → Add New Plugin.
Click Upload Plugin.
Select the JP Agent Tracking Bridge WordPress ZIP package.
Install the plugin.
Activate JP Agent Tracking Bridge.

After activation, open the JP Agent Tracking Bridge settings page in WordPress.

The plugin is designed to remain presentation-neutral. Activating JP Agent Tracking Bridge should not change the appearance or layout of the public website.

Joomla Installation

Download the latest Joomla version of JP Agent Tracking Bridge from your JPro Studio account.
Log in to the Joomla administrator.
Go to System → Extensions.
Upload the JP Agent Tracking Bridge Joomla ZIP package.
Install the package.

The Joomla ZIP is a package installer. It installs the required JP Agent Tracking Bridge component and supporting plugins in one installation.

After installation, open JP Agent Tracking Bridge from the Joomla administrator and complete the Google Analytics and Google Tag Manager configuration.

Basic Configuration

JP Agent Tracking Bridge stores the Google identifiers that belong to the current website.

GA4 Measurement ID

Enter the Google Analytics 4 Measurement ID used by the website.

Example:

G-XXXXXXXXXX

GTM Container ID

Enter the Google Tag Manager container used by the website.

Example:

GTM-XXXXXXX

These identifiers allow JP Agent Tracking Bridge and the connected AI tools to verify that they are working with the correct Google resources.

The Bridge should never silently select another Google Analytics property or Google Tag Manager container if the configured IDs cannot be found.

Connecting Google

JP Agent Tracking Bridge uses Google OAuth to connect to Google Analytics and Google Tag Manager.

The normal customer workflow is:

Open JP Agent Tracking Bridge.
Click Connect Google.
Sign in with the Google account that has access to the website's Analytics and Tag Manager resources.
Review the requested Google permissions.
Approve the connection.
Return to JP Agent Tracking Bridge.

The Bridge can then verify whether the signed-in Google account has access to the configured GA4 Measurement ID and GTM Container ID.

No Google service account, JSON credential file or customer-created Google Cloud project is required for the normal product workflow.

Google Permissions

JP Agent Tracking Bridge requests only the Google permissions required for its tracking workflow.

Current Google capabilities include:

Google Analytics read-only access - Used to identify Analytics properties and verify that tracking events are being received.
Google Tag Manager container editing - Used to inspect, create and update tags, triggers and related tracking resources.
Google Tag Manager container version access - Used to prepare approved changes as a GTM version.
Google Tag Manager publishing - Allows an approved GTM version to be published.

Google Analytics access is read-only.

Google Tag Manager publishing is treated as a separate privileged action. The AI agent should not publish a GTM container without explicit user approval.

Disconnecting Google

Google authorization is separate from temporary Agent Access.

Use Disconnect Google when you want to revoke the Google connection completely.

Disconnecting Google should:

Revoke or invalidate the stored Google authorization where possible
Remove the stored Google connection
Prevent future Google API requests through that connection

Stopping an Agent Tagging session does not automatically disconnect Google.

Installing the Agent Tools

For full Google Analytics and Google Tag Manager automation, the AI agent needs the JP Agent Tracking Bridge Google Tools integration.

The public MCP package is maintained separately from the proprietary WordPress and Joomla plugin source.

Public repository:

https://github.com/joomlapro/jp-agent-tracking-bridge-mcp

The exact installation method depends on the AI environment.

For environments that support uvx, the installation command can use the public GitHub repository:

uvx --from 'git+https://github.com/joomlapro/jp-agent-tracking-bridge-mcp.git' jptb-google-tools

Always check the public repository documentation for the latest Hermes, Claude and Codex setup instructions.

The Google Tools integration communicates with the JPro Studio control plane. Google OAuth tokens remain server-side and are not provided to the AI model.

Start Tagging

Remote AI configuration access is disabled by default.

When you are ready to work with your AI agent:

Open JP Agent Tracking Bridge.
Click Start Tagging.
Copy the generated Agent Connection information.
Provide the connection to your AI agent.

Starting a tagging session creates temporary authenticated access for the agent.

The connection credential is generated using a high-entropy random value and is designed for temporary use.

The connection process uses a two-step bootstrap flow. Simply previewing or fetching the connection URL does not consume the one-time credential. The credential is consumed only when the agent explicitly establishes a session.

Talking to Your AI Agent

You do not need to provide a large technical prompt.

A normal request can be:

Connect to my website and inspect the existing tracking. I want to track contact forms, email clicks and phone clicks. Tell me what you recommend before changing anything.

A properly configured agent should:

Inspect the website.
Inspect the current JP Agent Tracking Bridge configuration.
Inspect relevant Google Tag Manager resources.
Inspect Google Analytics where useful.
Identify existing tracking and possible duplicates.
Discuss the proposed tracking plan with you.
Wait for approval before making material changes.
Implement the approved configuration.
Verify the result.

Tracking Overview

The Tracking section shows tracking functionality currently managed by JP Agent Tracking Bridge.

Tracking can be implemented using structured rules or controlled custom scripts.

Examples include:

Email clicks
Phone clicks
Successful form submissions
CTA interactions
File downloads
Custom frontend events

Customers do not normally need to understand whether an event is internally implemented as a structured rule or a custom script. The Tracking overview is intended to show what is being tracked.

Structured Tracking Rules

Structured rules are preferred whenever the requested tracking can be expressed safely without custom JavaScript.

For example, email tracking can use:

Selector: a[href^="mailto:"]
Event: contact_email_click

Phone tracking can use:

Selector: a[href^="tel:"]
Event: contact_phone_click

Structured rules are easier to understand, version and maintain than arbitrary custom scripts.

Custom Tracking Scripts

Some frontend interactions cannot be reliably detected using a simple click or page rule.

JP Agent Tracking Bridge therefore supports controlled custom tracking scripts for cases such as:

AJAX form success events
Custom frontend widgets
JavaScript application state changes
Third-party components that expose their own browser events

Custom scripts should be used only when a structured Bridge rule cannot represent the required behavior cleanly.

Custom JavaScript added through the Bridge is still managed as a Bridge tracking resource and can be reviewed, disabled or removed.

Successful Form Tracking

A submit-button click is not the same as a successful form submission.

JP Agent Tracking Bridge is designed to track the confirmed success state whenever possible.

Preferred methods include:

A real form success event or callback
An AJAX success response
A confirmed success state in the page
A dedicated thank-you page

Only when a real success state cannot be detected should a submit interaction be considered as a fallback.

For normal lead forms, the recommended GA4 event is:

generate_lead

YOOtheme Essentials Forms

JP Agent Tracking Bridge works well with YOOtheme Pro websites and can track successful YOOtheme Essentials AJAX form submissions.

YOOtheme Essentials exposes the frontend event:

yooessentials-form:submitted

The AI agent can use this event to detect the successful form response instead of tracking only the submit-button click.

This is particularly useful for contact forms that submit through AJAX and do not redirect to a separate thank-you page.

Email Click Tracking

Email links can be tracked using normal mailto: links.

Recommended event:

contact_email_click

A common site-wide rule is:

a[href^="mailto:"]

The agent can inspect the website first and help decide whether all email addresses should be tracked or only selected business-critical addresses.

Phone Click Tracking

Telephone links can be tracked using normal tel: links.

Recommended event:

contact_phone_click

A common site-wide rule is:

a[href^="tel:"]

The agent can inspect the website and determine whether one or several phone numbers are present before creating the final tracking rule.

Google Tag Manager

JP Agent Tracking Bridge can work with the website's existing Google Tag Manager container.

The AI agent can use the Google Tools integration to:

List GTM accounts and containers available to the connected Google user
Inspect existing workspaces
Inspect existing tags
Inspect existing triggers
Inspect existing variables
Create or update JP Agent Tracking Bridge tags
Create or update JP Agent Tracking Bridge triggers
Create a GTM container version
Publish an approved container version

The agent should inspect the existing container before creating anything.

Existing GTM Tags

Real Google Tag Manager containers often already contain tracking from several services.

Examples include:

Google Ads
Meta
Facebook Pixel
Pinterest
TikTok
Existing GA4 tags
Custom marketing integrations

JP Agent Tracking Bridge is designed around an inspect-first policy.

Existing unrelated tags, triggers and variables should remain untouched unless you explicitly ask the agent to modify them.

The agent should also check for equivalent existing tracking before creating new resources to avoid duplicate events.

Publishing Google Tag Manager

Creating tracking resources and publishing them are separate operations.

A recommended workflow is:

Inspect → Configure → Create Version → Review → Approve → Publish

The AI agent should not publish a Google Tag Manager container simply because it technically has permission to do so.

Publishing should require explicit approval from the user.

Google Analytics Verification

Google Analytics access is used primarily to verify that the configured tracking is actually reaching GA4.

The agent can inspect:

Accessible Analytics accounts
Properties
Property details
Realtime data where available
Events used to confirm tracking

JP Agent Tracking Bridge does not need write access to Google Analytics for its normal tracking workflow.

Tracking Verification

A configured event is not automatically a verified event.

JP Agent Tracking Bridge uses several verification levels:

CONFIGURED - The required configuration exists.
BROWSER VERIFIED - A real browser interaction produced the expected Bridge/dataLayer event.
GTM VERIFIED - Google Tag Manager processed the expected event and tag.
DESTINATION VERIFIED - The destination, such as Google Analytics, received the event.
END-TO-END VERIFIED - The complete real interaction has been verified through the full tracking chain.
INCONCLUSIVE - Available testing was not sufficient to confirm the result.

Configured does not mean verified.

Recommended Verification Chain

For important tracking, verify as much of the real chain as possible:

Real user interaction
↓
JP Agent Tracking Bridge
↓
dataLayer event
↓
Google Tag Manager trigger
↓
Google Tag Manager tag
↓
Google Analytics request
↓
GA4 Realtime / DebugView

Synthetic event injection may be useful for debugging configuration, but it does not prove that the real website interaction works correctly.

Use real buttons, forms, links and ecommerce interactions whenever possible.

WooCommerce Tracking

The WordPress edition includes optional WooCommerce ecommerce tracking.

If WooCommerce is installed, enable WooCommerce tracking in JP Agent Tracking Bridge.

The Bridge can provide structured GA4-compatible ecommerce events to the dataLayer.

Supported events include:

view_item_list
view_item
add_to_cart
remove_from_cart
view_cart
begin_checkout
purchase

The ecommerce adapter uses WooCommerce data where appropriate rather than relying only on visual DOM scraping.

WooCommerce Ecommerce Data

WooCommerce events can include GA4 ecommerce information such as:

Product ID / SKU
Product name
Product category
Quantity
Price
Value
Currency

Purchase tracking can also include:

Transaction ID
Total value
Tax
Shipping
Purchased items

Purchase tracking includes duplicate protection so a normal order confirmation page reload does not repeatedly emit the same purchase event.

WooCommerce Purchase Statuses

The WordPress plugin can control which WooCommerce order statuses qualify for the purchase event.

This is useful because an order being created does not always mean it should immediately be counted as a completed sale.

Statuses such as:

Processing
On hold
Completed

can be included depending on the webshop workflow.

Statuses such as:

Pending payment
Failed
Cancelled

should normally not be counted as completed purchases.

Consent and Cookie Management

JP Agent Tracking Bridge is not a cookie consent manager.

The website's existing consent system remains responsible for determining when Google Analytics, Google Tag Manager and marketing scripts are allowed to run.

The Bridge should not bypass the website's consent configuration.

It can work with consent setups provided by systems such as:

YOOtheme Pro
Dedicated WordPress consent plugins
Dedicated Joomla consent extensions
Google Consent Mode compatible setups

If several consent systems are active on the same website, verify that they do not conflict with each other.

YOOtheme Pro

JP Agent Tracking Bridge is designed to work well on YOOtheme Pro websites.

The Bridge does not replace YOOtheme's layout system and should not modify UIkit layout classes, responsive breakpoints or frontend styling.

If YOOtheme is being used for consent management, keep the existing YOOtheme consent configuration unless there is a deliberate reason to change it.

Bridge tracking events can still be routed through Google Tag Manager while GTM itself remains subject to the site's consent settings.

Stop Tagging

When the AI agent has completed the tracking task, click Stop Tagging.

Stop Tagging immediately revokes temporary remote agent access.

Stopping the agent session does not disable the tracking that has already been configured.

After Stop Tagging:

Existing Bridge tracking rules continue working
Existing custom tracking scripts continue working
WooCommerce tracking continues working if enabled
The temporary agent session can no longer make Bridge changes
Session-bound Google tool access is no longer available to that agent session

Use Start Tagging again whenever another remote configuration session is required.

Security

JP Agent Tracking Bridge separates normal tracking runtime from temporary remote configuration access.

Important security principles include:

Remote Agent Access is disabled by default.
Start Tagging generates temporary high-entropy credentials.
Bootstrap credentials are one-time exchange credentials.
Connection previews do not consume bootstrap credentials.
Stop Tagging revokes active remote access.
Old credentials do not become valid again.
Google OAuth tokens remain server-side.
Google refresh tokens are not exposed to the CMS frontend.
Google credentials are not placed in AI prompts.
OAuth client secrets are not exposed to the browser.

Google OAuth Security

The Google connection uses a JPro Studio controlled OAuth service.

Google access and refresh tokens are stored server-side and encrypted at rest.

The CMS stores only the minimum information needed to identify the Google connection.

The AI agent receives access to specific Google tool operations rather than raw Google credentials.

The Google Tools gateway exposes a fixed set of supported operations and is not intended to be a generic Google API proxy.

History

JP Agent Tracking Bridge records meaningful administrative and agent activity in the History section.

History entries can include actions such as:

Remote tagging started
Remote tagging stopped
Agent session established
Tracking rule created
Tracking rule updated
Custom script created
Configuration updated

History is intended to provide a useful audit trail without storing sensitive credentials.

Raw Google OAuth tokens, Bridge session tokens and other secrets must never be written to the History log.

Reset and Clear Log

The Reset section provides administrative controls for Bridge-managed data.

Reset Tracking

Reset Tracking removes Bridge-managed tracking rules and scripts.

It does not automatically delete unrelated Google Tag Manager resources or modify unrelated Google Analytics settings.

Clear Log

Clear Log removes the Bridge activity/history log without changing the active tracking configuration.

Reset Tracking and Clear Log are intentionally separate operations.

Working With Existing Tracking

JP Agent Tracking Bridge is intended for existing websites as well as new installations.

Before creating tracking, the AI agent should inspect what is already configured.

This can help identify:

Existing GA4 tags
Existing Google Tag configuration
Existing Google Ads conversions
Existing phone or form tracking
Duplicate GA4 loading
Existing ecommerce tracking
Unrelated Meta, Pinterest or TikTok tags

The presence of existing tracking is not a reason to remove it automatically.

The agent should explain conflicts or duplicate risks and let the user decide how they should be handled.

Troubleshooting

The Agent Cannot Connect

Check that Start Tagging is active.
Generate a new Agent Connection if the previous session has been revoked.
Check that the AI agent is using the current connection information.
Check that the website REST/API endpoints are accessible.
Check firewall, security plugin and server rules if requests are blocked.

The Connection Returns 410

Current versions use a two-step bootstrap flow so normal link previews should not consume the connection credential.

If a 410 response still occurs:

Press Stop Tagging.
Press Start Tagging again.
Use the newly generated connection.
Make sure the plugin and agent tooling are up to date.

Google Connection Problems

Google Account Connected but GTM Is Not Found

Check the GTM Container ID entered in JP Agent Tracking Bridge.
Confirm that the signed-in Google account has access to that GTM container.
Do not select another container simply because it is available.

Google Account Connected but GA4 Is Not Found

Check the GA4 Measurement ID entered in JP Agent Tracking Bridge.
Confirm that the signed-in Google account has access to the correct Analytics property.
Reconnect Google if access was recently changed.

Google Authorization Was Revoked

Use Connect Google again and complete the Google authorization process.

Events Appear in dataLayer but Not GA4

If an event appears in the browser's dataLayer but does not appear in Google Analytics, the Bridge portion may already be working correctly.

Check:

Whether the GTM container version has been published
Whether the GTM Custom Event trigger matches the Bridge event name
Whether the corresponding GA4 Event tag fires
Whether Analytics consent has been granted
Whether the correct GA4 Measurement ID is being used
Whether the site has duplicate or conflicting GA4 installations
GA4 Realtime or DebugView

Form Tracking Does Not Fire

If a form is not being tracked:

Check whether the form submits normally or through AJAX.
Check whether a real success event or callback exists.
Do not assume that clicking the Submit button means the form succeeded.
For YOOtheme Essentials, verify that the yooessentials-form:submitted event is available.
Check the browser console for JavaScript errors.
Check consent settings if the Bridge event fires but GA4 does not receive it.

WooCommerce Troubleshooting

WooCommerce Tracking Cannot Be Enabled

Check that WooCommerce is installed.
Check that WooCommerce is active.
Reload the JP Agent Tracking Bridge settings page.

Ecommerce Events Do Not Reach GA4

Check that WooCommerce tracking is enabled in JP Agent Tracking Bridge.
Inspect the browser dataLayer.
Check that the ecommerce GTM trigger includes the required ecommerce events.
Check that the GA4 ecommerce tag uses the event name dynamically.
Check that ecommerce data is sent with the GA4 event.
Check consent status.

Purchase Does Not Fire

Check the WooCommerce order status.
Check the configured Purchase statuses in JP Agent Tracking Bridge.
Check whether the purchase was already emitted for the order.
Remember that duplicate purchase protection intentionally prevents repeat emission.

Frontend Layout Problems

JP Agent Tracking Bridge should not change the appearance of the frontend.

The Bridge does not require public layout CSS and should not modify:

Viewport metadata
Theme widths
UIkit layout classes
YOOtheme responsive breakpoints
Body or HTML styles

If activating the plugin appears to change the public layout:

Check the server/PHP error log for fatal errors.
Check the browser console.
Make sure the latest plugin version is installed.
Temporarily disable the Bridge and compare the result.

A PHP fatal near the end of a page request can prevent theme footer scripts from loading and may look like a visual or responsive-layout problem even when no CSS has been changed.

Recommended First Tracking Job

For a normal business website, a good first task is:

Inspect the website and existing tracking. I want to track successful contact forms, email clicks and phone clicks. Tell me what you recommend before changing anything.

A typical result may use:

generate_lead - successful lead/contact form
contact_email_click - email links
contact_phone_click - telephone links

The agent should inspect the actual website before assuming that every form, email address or phone number represents the same business intent.

Recommended WooCommerce Setup

For a WooCommerce website:

Install and activate JP Agent Tracking Bridge.
Enter the GA4 Measurement ID.
Enter the GTM Container ID.
Enable WooCommerce tracking.
Connect Google.
Start Tagging.
Ask the agent to inspect existing ecommerce tracking before adding anything.

During verification, test real ecommerce actions such as:

Opening a product
Adding a product to cart
Viewing the cart
Opening checkout

A full purchase test can be performed separately when practical.

Developer and Agency Notes

JP Agent Tracking Bridge is intentionally designed as a controlled tracking bridge rather than a general remote administration interface.

The Bridge does not provide the AI agent with:

PHP execution
SQL execution
Filesystem access
Shell access
WordPress administrator credentials
Joomla administrator credentials

The API exposes specific tracking-related capabilities.

This makes JP Agent Tracking Bridge suitable for agency workflows where an AI agent should be able to configure tracking without receiving unrestricted website administration access.

Agent API Concepts

The Bridge exposes controlled capabilities for concepts such as:

Bridge status
Site information
Tracking configuration
Tracking rules
Custom scripts
History
Google connection status
Temporary Agent Sessions

The stable product interface is based on authenticated APIs and controlled tool operations rather than arbitrary code execution.

Google Tools MCP

The JP Agent Tracking Bridge Google Tools MCP provides a single customer-facing AI tool integration for both Google Tag Manager and Google Analytics.

Conceptually:

AI Agent
↓
JP Agent Tracking Bridge Google Tools
↓
JPro Studio secure gateway
↓
Customer Google OAuth connection
├── Google Tag Manager API
└── Google Analytics API

The MCP client does not contain the customer's Google OAuth refresh token.

The server-side gateway resolves the customer's connection and performs only supported Google operations.

Privacy and Google Data

JP Agent Tracking Bridge accesses Google data only to provide the tracking configuration and verification functionality requested by the user.

Google Analytics access is used to inspect Analytics account/property information and verify tracking results.

Google Tag Manager access is used to inspect and manage tracking resources required for the approved tracking configuration.

Google credentials are not sold and are not provided directly to the AI model.

Users can disconnect their Google account to revoke the JP Agent Tracking Bridge Google connection.

For complete information about data handling, see the current JPro Studio Privacy Policy and Terms of Service.

Before Finishing a Tagging Session

Before pressing Stop Tagging, confirm:

The intended Bridge rules/scripts are present.
Real browser interactions have been tested where practical.
The correct GTM container was used.
The correct GA4 property was used.
Existing unrelated GTM resources remain intact.
Any required GTM version has been reviewed.
Publishing has been explicitly approved if applicable.
GA4 verification has been performed where practical.

Then click Stop Tagging to revoke temporary remote agent access.

Quick Start

For most customers, the complete workflow is:

Install JP Agent Tracking Bridge for WordPress or Joomla.
Enter your GA4 Measurement ID.
Enter your GTM Container ID.
Enable WooCommerce tracking if applicable.
Click Connect Google.
Sign in with your normal Google account.
Install/register the JP Agent Tracking Bridge Google Tools integration in your AI environment.
Click Start Tagging.
Copy the Agent Connection to your AI agent.
Explain what you want to track.
Review the agent's recommendation.
Approve the tracking plan.
Let the agent implement and verify the configuration.
Approve GTM publishing if required.
Click Stop Tagging when finished.

Example Agent Request

You do not need to know Google Tag Manager terminology to use JP Agent Tracking Bridge.

For example:

Connect to my website and inspect the current tracking. I want to measure leads and important contact actions. Please tell me what you recommend before making any changes.

For a webshop:

Inspect my existing tracking and WooCommerce setup. I want GA4 ecommerce tracking and tracking for successful forms, email clicks and phone clicks. Keep my existing advertising tags and tell me what you recommend before changing anything.

The AI agent should handle the technical inspection and translate your business request into an appropriate tracking plan.

Extension list

yootheme

ecommerce

joomla

Support Tickets

Documentation

Changelogs