How to add guides and surveys to a WordPress site

A WordPress pricing page can show what visitors clicked without telling you what they needed. Guides and surveys let you ask a question during that visit.

In this tutorial, I'll attach the engagement plugin after analytics is ready, create a pricing survey, and check its response against the test visitor.

What you'll build

Prerequisites

• A staging WordPress site with permission to upload a custom plugin and edit wp-config.php. This tutorial uses a plugin you control. On managed hosting, confirm that your plan permits those changes.
• WordPress 6.3 or later and PHP 7.4 or later, plus a theme that calls wp_head() and wp_footer(). The executable example was tested on WordPress 6.9.10 and PHP 8.3.33.
• An Amplitude project API key: Settings > Projects > your project > General > Manage next to API Key. Managers and Admins can view it. The browser key is public and limited to the minimum scope needed for ingestion. Keep secret keys out of this plugin.
• The shared plugin, public Pricing page, and guides and surveys enabled for the project's web app.
• Permission to create, save, and preview a survey. Keep the product analytics footer for optional event-based triggers.

A free Amplitude account covers this example within its product limits. Sign up for free to get your project API key.

1. Add engagement after the existing initialization

Create engagement.php below. The shared bootstrap already loads it when present. WordPress's dependency handle places its script after amp-build-sdk and the inline analytics init. The Web SDK reference supports waiting for analytics initialization before adding the plugin when it cannot be registered first.

<?php
// wp-content/plugins/amplitude-build/engagement.php
// Preserve the main plugin, analytics.js replay privacy, events.js, and consent.
defined('ABSPATH') || exit;
add_action('wp_enqueue_scripts', function () {
    if (!wp_script_is('amp-build-sdk', 'enqueued')) return;
    $zone = defined('AMP_BUILD_SERVER_ZONE') && AMP_BUILD_SERVER_ZONE === 'EU' ? 'EU' : 'US';
    $host = $zone === 'EU' ? 'https://cdn.eu.amplitude.com' : 'https://cdn.amplitude.com';
    wp_enqueue_script('amp-build-engagement', $host . '/script/' . rawurlencode(AMP_BUILD_API_KEY) . '.engagement.js', array('amp-build-sdk'), null, false);
    wp_add_inline_script('amp-build-engagement', "
if (window.ampBuildReady && window.engagement) {
  window.ampBuildEngagementReady = window.ampBuildReady
    .then(() => window.amplitude.add(window.engagement.plugin({ serverZone: window.ampBuildConfig.serverZone })).promise)
    .catch(error => console.warn('Guides and surveys did not initialize.', error));
}", 'after');
}, 20);

The plugin manages initialization and boot. Do not add standalone engagement.init() or boot() calls. Use the same key and region as analytics. For a custom proxy, follow the SDK's standalone proxy path instead of using this plugin unchanged.

This fallback does not forward events tracked before the plugin attaches. Use Immediately for the first survey. Before an optional Pricing CTA Clicked event-trigger test, wait for window.ampBuildEngagementReady. Preserve replay masking and any experiment consent configuration.

2. Preserve a stable guide anchor

Keep data-guide="pricing-help" on the existing CTA. The modal survey below needs no anchor, but an anchored guide can target it later. Test that guide at desktop and mobile widths before release.

<!-- Pricing page: Custom HTML block -->
<a href="#demo" data-analytics="pricing-cta" data-experiment="pricing-cta" data-guide="pricing-help">
  <span>Request a demo</span>
</a>

Deploy the plugin addition, clear relevant caches, and visit the public page. Confirm these globals exist:

// Browser Console on the public WordPress Pricing page
typeof window.amplitude;
typeof window.engagement;

3. Build and target the pricing survey

Open Guides and Surveys and create a web survey. Use a modal, a required List question, and a completion step. Save it before starting Preview.

# Survey builder
Title: WordPress pricing feedback QA
Question: What would help you choose a plan?
Options: Feature details; Pricing details; A product demo
Trigger: Immediately
Page: the public Pricing URL

In Setup and Targeting, inspect the page rule, audience, limits, and throttle. Use a dedicated test audience. For a later On event tracked trigger, keep the existing Pricing CTA Clicked handler; the plugin receives analytics events after attachment.

4. Preview and verify the answer

Choose Preview and enter the public Pricing URL. Keep the Amplitude preview tab open for cross-window messaging. Check the preview bar, complete the survey with a synthetic answer, and inspect Trigger, Limit, and Throttle if it fails to appear. Reset User History or ignore throttle limits in the test controls as appropriate. Multi-page preview has a documented issue, so start on one page.

// Browser Console after completing the synthetic survey
window.amplitude.flush();
window.amplitude.getDeviceId();

In the survey's Responses and Insights tabs, turn off Ignore test/preview data and include the test time in the date range. Confirm the answer, visitor, and timestamp. Restore the filter when reviewing production results. A loaded SDK or boot event alone does not verify a stored response.

MCP: Ask your coding agent to inspect the project's event taxonomy with the Amplitude MCP server before adding events. Reuse existing names when they describe the same action.

Verify it worked

1. WordPress output: Open the public staging page while logged out. Check that the project loader appears once and its inline initialization follows it. After deployment or configuration changes, purge the relevant page and CDN caches.
2. Network: Confirm an event POST receives HTTP 200 from api2.amplitude.com for US projects or api.eu.amplitude.com for EU projects. Large batches can be compressed; use this check for delivery status.
3. Instrumentation Explorer: Inspect event names, properties, counts, and device_id in the Chrome extension. Compare one action with one expected custom event.
4. User Profiles: Search that device ID in Amplitude and inspect its event stream. The docs describe a delay of ten seconds to one minute. Data > Sources > Ingestion Debugger shows request and event counts, rather than individual event payloads.

Confirm a saved synthetic answer in the survey views. Keep SDK load, eligible display, and stored response as separate checks.

Troubleshooting

The survey will not save

Record the error and resolve survey persistence before previewing. Without a saved survey, SDK boot does not complete this tutorial's response check.

The plugin is active but no SDK loads

Check that AMP_BUILD_API_KEY is defined before wp-settings.php, then inspect the public page source. This plugin uses the front-end enqueue hook, so its SDK is absent from the WordPress login and administration pages.

The script order differs from the example

Check caching and script-optimization exclusions for amp-build-sdk and amp-build-engagement. The project loader and inline initialization must remain together. Check for an earlier installation in a theme, tag manager, or snippet plugin.

Requests are blocked

Check the key, region, browser extensions, and Console. Follow the relevant SDK's CSP and endpoint guidance while preserving your site's security policy.

Autocapture settings differ from the file

Review Data > Settings > Autocapture. When remote configuration is enabled, remote values take precedence for the features they specify.

FAQ

Do I call boot after adding the plugin?

The Browser SDK plugin manages that lifecycle. Manual init and boot belong to the standalone installation path.

Why is my preview response missing from Insights?

Check the project, date range, and Ignore test/preview data filter. Then verify the answer in Responses; a boot event is not an answer record.

Full code reference

Unchanged from earlier pages; keep your versions: amplitude-build.php, analytics.js, demo.php, events.js, experiment-consent.js. Merge the changes into existing files; preserve sibling additions named in the comments.

<?php
// wp-content/plugins/amplitude-build/engagement.php
// Preserve the main plugin, analytics.js replay privacy, events.js, and consent.
defined('ABSPATH') || exit;
add_action('wp_enqueue_scripts', function () {
    if (!wp_script_is('amp-build-sdk', 'enqueued')) return;
    $zone = defined('AMP_BUILD_SERVER_ZONE') && AMP_BUILD_SERVER_ZONE === 'EU' ? 'EU' : 'US';
    $host = $zone === 'EU' ? 'https://cdn.eu.amplitude.com' : 'https://cdn.amplitude.com';
    wp_enqueue_script('amp-build-engagement', $host . '/script/' . rawurlencode(AMP_BUILD_API_KEY) . '.engagement.js', array('amp-build-sdk'), null, false);
    wp_add_inline_script('amp-build-engagement', "
if (window.ampBuildReady && window.engagement) {
  window.ampBuildEngagementReady = window.ampBuildReady
    .then(() => window.amplitude.add(window.engagement.plugin({ serverZone: window.ampBuildConfig.serverZone })).promise)
    .catch(error => console.warn('Guides and surveys did not initialize.', error));
}", 'after');
}, 20);

Hand it to your agent

Point your agent at https://amplitude.com/build/wordpress-guides-surveys.

Agent task: WordPress guides and surveys.
Add engagement.php without replacing any shared plugin files. Preserve analytics completion and engagement readiness promises, replay privacy, consent, and form handlers. Use one project and region, no manual boot, and disclose the early-event trigger limitation. Save a dedicated pricing survey, preview it on the public page, and confirm a synthetic answer in Responses with test data included. Report save, render, and response ingestion separately.

What this unlocks

Product analytics measures the accepted-form outcome when Demo Form Accepted is installed.

Session replay shows the interaction around the test form after capture and masking are verified.

Web Experiment can use Demo Form Accepted as a conversion metric.

Guides and surveys can ask a visitor what they need on Pricing after targeting is configured.

Next steps