Setup guide
Install and verify the Portaviq WordPress plugin
Use this guide when connecting a WordPress client site to Portaviq during the private beta.
Before you start
Add the WordPress site in Portaviq first. The site detail page gives you the SaaS base URL, site public ID, and one-time verification token needed by the plugin.
Tracking disclosure
Before enabling tracking, confirm you have permission from the site owner or client and that the site privacy notice covers lightweight pageview collection. Portaviq sends page URL/path, page title, referrer, and basic technical request metadata. It does not set tracking cookies.
1. Download the Portaviq plugin ZIP
Use the download button in Portaviq. If the download is unavailable, the latest plugin package has not been built yet.
Complete this step before moving on.
2. Open WordPress admin
Sign in to the WordPress site you added in Portaviq. Use an admin account that can install plugins.
Complete this step before moving on.
3. Upload and activate the plugin
Go to Plugins > Add New > Upload Plugin, choose the ZIP file, install it, then activate the plugin.
Complete this step before moving on.
4. Open the plugin settings
In wp-admin, open Settings > Portaviq.
Complete this step before moving on.
5. Paste the setup values
Copy the SaaS base URL, site public ID, and one-time verification token from the Portaviq site detail page.
- SaaS base URL: the Portaviq app URL shown on the site page.
- Site public ID: the external site identifier for the plugin.
- Verification token: shown only when the site is created or when you regenerate a token.
6. Verify the connection
Save the plugin settings, then click Verify Connection. A successful verification clears the one-time token.
If verification fails, check that the WordPress site URL matches the Portaviq site URL and that the token has not expired.
7. Enable tracking when ready
After verification succeeds, enable frontend tracking in the plugin settings if this site should send pageview activity.
Complete this step before moving on.
8. Visit the site once
Open the public WordPress frontend once to confirm the first pageview can reach Portaviq.
Complete this step before moving on.
9. Return to Portaviq
Check the site detail page for plugin status, heartbeat, pageview activity, and the client report.
The client report becomes useful after verification, heartbeat, and at least one pageview have arrived.
After setup
What a successful plugin connection unlocks.
If the token is gone
Verification tokens are intentionally one-time values.
Return to the Portaviq site detail page and create a new verification token. The new raw token is shown once and should be pasted into the plugin immediately.
If the download is unavailable
The plugin ZIP is served from the local build artifact.
In local development, run pnpm plugin:build from the repository root, then retry the download route.
Related guides
Understand where plugin setup fits in the product.
Agency dashboard
See how verified sites roll up into the agency operating dashboard.
Multi-site monitoring
See how heartbeat and recent activity help identify sites needing attention.
Free portfolio audit
Not ready to install yet? Request a review of your current workflow first.
FAQ
Plugin setup questions.
Can I verify without a one-time token?
No. The one-time token connects the WordPress plugin to the correct Portaviq site record. If it is gone or expired, generate a new token from the site detail page.
Does the plugin start tracking immediately?
No. Tracking is enabled from the plugin settings after verification. Confirm you have permission before enabling it.
What if WordPress cron is disabled?
The dashboard may show heartbeat as unknown or stale. Verification can still succeed, and the site page will show the next setup state clearly.