Documentation

Adbot Guides

Choose a guide below to get started.

WordPress Plugin

Installation & Setup Guide

Install the Adbot plugin on your WordPress site to manage Google Tag Manager, run tracking audits, and apply automated fixes — all without leaving WordPress.

Requires WordPress 6.0+ and PHP 8.0+ · Last updated May 2026

1. Overview

The Adbot WordPress plugin is a thin client — it provides a WordPress admin interface for Adbot features, but all sensitive operations (Google OAuth, Paystack payments, database storage) are handled by the Adbot backend. The plugin itself never holds any API secrets.

Feature	Description
Site registration	One-time automatic activation — no manual configuration needed
Google OAuth	Connect your Google account to access GTM containers via a secure popup flow
GTM snippet injection	Automatically adds your GTM container snippet to your WordPress theme
Tracking audit	Scans your GTM container for gaps and produces a scored report
Apply fixes	Lets Adbot automatically publish the correct tag setup to your GTM container
Onboarding payment	One-time Paystack payment flow for setup fees (ZAR currency)
Plugin updates	Automatic update checks against the Adbot backend

The plugin communicates exclusively with the Adbot backend at https://api.adbot.co.za/wp/v1. No other third-party services are contacted directly from the plugin.

2. Prerequisites

WordPress 6.0 or later
PHP 8.0 or later on your web server
An active Adbot account (your agency or account manager will provide this)
Your WordPress site must be publicly accessible on the internet — not behind a login wall, maintenance mode, or firewall that blocks outbound HTTP
Administrator access to your WordPress dashboard
A Google account with access to your GTM container (for Google connection)

No API keys, .env files, or manual configuration are required. The plugin configures itself automatically on activation.

3. Downloading the Plugin

Navigate to Settings → WordPress Plugin

Click Download Plugin ZIP

The ZIP file is named adbot.zip and contains the full plugin ready for upload. Do not unzip it — WordPress accepts the ZIP directly.

The ZIP URL and current version are managed by the Adbot backend. Always download from the Dashboard to ensure you get the latest release.

4. Installing in WordPress

Upload method (recommended)

Go to Plugins → Add New Plugin

Click Upload Plugin at the top of the page

Click Choose File and select the adbot.zip file you downloaded

Click Install Now

Once installation completes, click Activate Plugin

FTP / cPanel method (alternative)

Unzip adbot.zip on your computer

Upload the resulting adbot/ folder to wp-content/plugins/ on your server

In your WordPress admin, go to Plugins → Installed Plugins, find Adbot, and click Activate

5. Activation & Site Registration

When you activate the plugin, it automatically registers your site with the Adbot backend. This process takes a few seconds and requires no input from you.

What happens during registration

Step	What happens
1. Plugin sends site info	Adbot receives your site URL, site name, admin email, WordPress version, and plugin version
2. Backend issues a challenge	Adbot generates a unique verification challenge and sends back a verification URL
3. Ownership verified	Adbot calls your site's REST API to confirm you control the domain — this proves ownership
4. Site token minted	Adbot returns a secure site_token that the plugin stores encrypted in your WordPress database

The site_token is encrypted at rest in wp_options using AES-256-GCM with a key derived from your WordPress security salts. It is never stored in plain text.

After registration

A new Adbot menu appears in your WordPress sidebar. You will see a confirmation that your site is registered and ready. No further setup is required to complete activation.

If registration fails with “Site could not be verified”, your site is likely not publicly accessible. Disable maintenance mode, remove any “coming soon” plugins, and ensure your server allows outbound HTTP requests, then deactivate and reactivate the Adbot plugin.

6. Connecting Your Google Account

To access GTM containers and run audits, you need to connect a Google account that has access to your GTM workspace.

In the WordPress sidebar, click Adbot → Google Connection

Click Connect Google Account

A pop-up window opens for Google sign-in — select your Google account

Review the permissions Adbot is requesting and click Allow

The pop-up closes and the Adbot panel shows your connected account name and email

Permissions requested

Permission	Why
View email and basic profile	Required to identify your account
View GTM containers	To list accounts and containers for the audit
Manage GTM containers	To write tags, triggers, and variables when applying fixes
Publish GTM containers	To push the corrected setup live

Disconnecting your Google account

Go to Adbot → Google Connection and click Disconnect. This revokes access tokens on the Adbot backend and clears the connection. Your audit history is not deleted.

7. Installing the GTM Snippet

Adbot can automatically inject your GTM container snippet into your WordPress theme — no code editing required.

Go to Adbot → Tag Manager in the WordPress sidebar

Adbot lists all GTM accounts and containers your Google account can access — select the correct container

Enter your GA4 Measurement ID in the format G-XXXXXXXXXX

Click Install Snippet

The plugin automatically adds the required GTM code to your theme’s <head> and immediately after the opening <body>tag, matching Google’s recommended placement.

This installation is recorded in the Adbot backend. To remove the snippet later, go to Adbot → Tag Manager and click Remove Snippet.

Verifying the installation

After installing, visit your site in a browser and right-click → View Page Source. Search for your GTM container ID (e.g. GTM-XXXX) — it should appear near the top of the <head> and immediately after <body>.

8. Running a Tracking Audit

An audit scans your GTM container and produces a health score with a prioritised list of tracking gaps and recommended fixes.

Go to Adbot → Audit in the WordPress sidebar

Select the GTM container you want to audit (if not already selected from the Tag Manager screen)

Click Run Audit — this typically takes 10–30 seconds

Review the health score, tags inventory, and gap report

Reading your audit results

Score	Status	Meaning
80–100	Healthy	Minor gaps only — tracking is mostly correct
60–79	Warning	Moderate issues — some events may not be tracked
0–59	Critical	Significant gaps — key conversions are likely missing

Each gap in the report shows what is missing (e.g. “GA4 purchase event tag not found”), why it matters, and the recommended fix. Adbot can apply most fixes automatically — see the next section.

Audit results are stored on the Adbot backend. You can retrieve a previous audit from Adbot → Audit → History without re-running the scan.

9. Applying Fixes

Applying fixes publishes a new version to your live GTM container. Review the proposed changes carefully before confirming. GTM keeps a full version history so you can roll back at any time from the GTM interface.

After running an audit, click Apply Fixes in the results panel

Adbot displays a summary of the tags, triggers, and variables it will add or modify

Review the list and click Confirm & Publish

Adbot publishes a new GTM container version — a confirmation message shows which changes were made

Rolling back

If something goes wrong after applying fixes, open your GTM account at tagmanager.google.com, go to Versions, select the previous version, and click Publish. Adbot never deletes GTM versions.

10. Onboarding Payment

Some Adbot plans include a one-time onboarding fee in addition to your subscription. If a payment is required, you will be prompted inside the plugin.

In the Adbot panel, click Pay Now when prompted

You are redirected to a Paystack checkout page

Enter your card details and complete the payment (currency: ZAR)

You are redirected back to your WordPress admin — Adbot confirms payment and unlocks all features

Payment is processed entirely by Paystack. Adbot receives only a payment confirmation reference — your card details are never stored by Adbot or WordPress.

Payment verification

The Adbot backend verifies your payment directly with Paystack using a secure server-to-server call. If you are redirected back but features remain locked, click Verify Payment in the Adbot panel to trigger a manual check.

11. Plugin Updates

The plugin checks for updates automatically against the Adbot backend. When a new version is available, it appears in your WordPress Dashboard → Updates screen like any other plugin.

Go to Dashboard → Updates in your WordPress admin

If an Adbot update is listed, tick the checkbox next to Adbot

Click Update Plugins

Updates do not affect your site registration, Google connection, or GTM configuration. All settings are preserved across updates.

12. Security Model

The plugin is designed so that no sensitive credentials ever touch your WordPress server.

What	Where it lives	How it's protected
Google OAuth client secret	Adbot backend only	Never sent to the plugin
Paystack secret key	Adbot backend only	Never sent to the plugin
Database credentials	Adbot backend only	Never sent to the plugin
site_token	WordPress database (wp_options)	AES-256-GCM encrypted using WP security salts as the key
Google access tokens (WP)	Adbot backend only	Encrypted at rest; keyed by site_id

Site ownership verification

Before minting a site_token, the Adbot backend performs an HTTP challenge-response against your site’s public REST API (/wp-json/adbot/v1/verify). A token is only issued after ownership is confirmed. This prevents one site from impersonating another.

Inbound webhooks

When the Adbot backend pushes entitlement updates to your site (e.g. after a Paystack payment), the request is signed with an HMAC-SHA256 signature (X-Adbot-Signature header). The plugin verifies this signature before applying any changes.

13. Developer Reference

The following optional constants can be defined in wp-config.php. All are optional — the plugin works without any of them.

Constant	Default	Purpose
ADBOT_API_BASE	https://api.adbot.co.za/wp/v1	Point the plugin at a staging or local backend
ADBOT_DEBUG	(undefined)	Enable verbose logging when WP_DEBUG is also on

Example wp-config.php override

// Point Adbot plugin at a staging backend
define( 'ADBOT_API_BASE', 'https://staging.api.adbot.co.za/wp/v1' );

// Enable verbose debug logging (only when WP_DEBUG is true)
define( 'ADBOT_DEBUG', true );

Plugin REST endpoints (provided by the plugin)

The plugin registers the following public REST endpoints on your WordPress site. These are called by the Adbot backend during registration and verification — you do not call them directly.

Endpoint	Method	Purpose
/wp-json/adbot/v1/verify	GET	Ownership verification during registration — returns the challenge nonce
/wp-json/adbot/v1/entitlements	POST	Receives entitlement updates from the Adbot backend (HMAC-signed)

Backend API base URL

All plugin requests go to https://api.adbot.co.za/wp/v1 (or the value of ADBOT_API_BASE). Every request except registration carries an Authorization: Bearer <site_token> header. All responses use JSON.

14. Troubleshooting

Registration failed — 'Site could not be verified'

The Adbot backend could not reach your site’s public REST API. Check:

Your site is not in maintenance mode or behind a “coming soon” plugin
Your server does not block outbound HTTP requests
Your site URL is publicly accessible (try opening it in an incognito window)
The WordPress REST API is enabled — some security plugins disable it. Temporarily disable them and retry activation.

After fixing the issue, go to Plugins, click Deactivate on Adbot, then Activate again.

Adbot menu doesn't appear after activation

Check that PHP 8.0 or later is running on your server — go to Tools → Site Health → Info → Server and look at the PHP version.

Verify you are on WordPress 6.0 or later under Dashboard → Updates.

Check your PHP error log for any fatal errors. Add define( 'ADBOT_DEBUG', true ); and define( 'WP_DEBUG_LOG', true ); to wp-config.php and check wp-content/debug.log.

Google account connection pop-up closes without connecting

Make sure pop-ups are allowed for your WordPress admin domain in your browser settings.

Check that your WordPress admin URL uses HTTPS — Google OAuth requires a secure origin. If your admin is on HTTP, update your WordPress Address in Settings → General to use HTTPS.

Try the connection in an incognito window to rule out extension interference.

GTM snippet installed but not firing on the site

Open your site in a browser and view the page source — search for your GTM container ID (e.g. GTM-XXXX). If it is missing, your theme may be using a custom wp_head / wp_body_open implementation that skips standard WordPress hooks. Contact your theme developer to ensure these hooks are called.

Also check if a caching plugin is serving a stale page from before the snippet was installed — clear your cache and try again.

Audit failed or returned no results

Confirm your Google account is still connected — go to Adbot → Google Connection and look for the green indicator.

Ensure the connected Google account has access to the GTM container you are trying to audit — check in the GTM interface that the account has at least Read access.

Wait 60 seconds and retry — GTM API rate limits can occasionally cause temporary failures.

Payment completed but features are still locked

In the Adbot panel, click Verify Payment to trigger a manual verification check against Paystack.

If the issue persists, check your internet connection and confirm that your server can receive inbound POST requests on your /wp-json/adbot/v1/entitlements endpoint — some hosts block inbound webhooks by default.

Contact support with your Paystack payment reference (format: adbot_xxxx) so your account manager can manually confirm.

15. Frequently Asked Questions

Does the plugin store any API keys or secrets?

No. The plugin only stores a site_token — an opaque credential that identifies your site. It is encrypted at rest using your WordPress security salts. All Google, Paystack, and database credentials remain exclusively on the Adbot backend.

What happens if I deactivate the plugin?

Deactivating removes the Adbot admin menu and stops the GTM snippet from being injected. Your site registration and backend data are preserved. You can reactivate at any time to restore all functionality without re-registering.

What happens if I delete the plugin?

Deleting the plugin removes the plugin files and clears the stored site_token from your WordPress database. Your site registration on the Adbot backend is not automatically removed. If you reinstall the plugin, it will re-register and receive a new site token.

Can I use the plugin on a staging site?

Yes. Define ADBOT_API_BASE in wp-config.php to point at a staging backend. Each unique site URL registers as a separate site, so staging and production are tracked independently.

Is the plugin compatible with page builders and caching plugins?

Yes, for most setups. The GTM snippet is injected via standard WordPress hooks (wp_head and wp_body_open). If your theme or page builder bypasses these hooks, the snippet may not appear — contact your theme developer. After installing the snippet, clear your caching plugin’s cache to ensure visitors receive the updated page.

Do I need to use the WordPress plugin if I'm on Shopify?

No. The WordPress plugin is for WordPress-hosted sites. If your store runs entirely on Shopify, install the Shopify App instead.

What PHP and WordPress versions are supported?

The plugin requires PHP 8.0 or later and WordPress 6.0 or later. Older versions are not tested and may not work correctly.

How do I contact support?

Click Help in the Adbot Dashboard left navigation and use the support form, or contact your account manager using the email provided in your onboarding email. Include your site URL and a description of the issue.

← Back to Adbot·Last updated May 2026