Testing and Publishing

Amplitude lets you test your guides and surveys before publishing them. Testing confirms the setup and the behavior match your expectations.

There are two ways to test your guides and surveys:

• Preview mode: a quick first check to see how your guide or survey looks and confirm your setup.
• Testing status: a live test with specific users before launch.

Preview mode

Preview mode confirms that your guides and surveys behave as expected. To check only the look of a guide or survey, open it in Amplitude. To confirm runtime behavior, test it in preview mode.

Amplitude recommends a thorough test before launch to confirm:

• Button actions behave as you intend.
• Multi-step guides and surveys have the right pace.
• Pins and tooltips appear where they should.

To open Preview mode from the builder:

1. Open a guide or survey.
2. Click Preview.
3. For web, enter the URL of the page with the Guides and Surveys SDK installed. For mobile, scan the QR code or open the preview URL.
4. Amplitude verifies that the SDK is available. For web, the URL opens in a new tab with the preview bar visible. For mobile, the preview opens in the app with the preview bar displayed.

Conditions checked in preview mode

The preview bar shows the status of the three conditions Amplitude uses to decide whether to show the guide or survey:

• Trigger
• Limit
• Throttle

Condition status

Each condition has three possible statuses:

How preview mode works

Preview mode uses browser messaging to communicate between the Amplitude dashboard and your application. When you start a preview:

1. The Amplitude dashboard opens your application URL in a new tab.
2. The dashboard waits about 10 seconds for a message from the Guides and Surveys SDK running on your page.
3. If the SDK sends a message, the dashboard responds with preview information, including the guide or survey ID.
4. The SDK receives the preview information and displays the preview.

This communication relies on the browser's window.postMessage API to pass messages between the dashboard and your application.

Troubleshooting preview mode

Sometimes the guide or survey doesn't appear in preview. If the instrumentation is correct, check the following:

• Confirm the preview user hasn't already seen the guide or survey. If the user has seen it, the preview bar shows a yellow (warning) status for the Limit condition. Hover over the condition and click Reset User History.
• Confirm the throttle limit isn't reached. If the limit is reached, the Throttle condition shows yellow (warning) status. Hover over the condition and toggle Ignore Throttle Limits.
• If the trigger condition is On event tracked, confirm the event fires. If the event hasn't fired, the Trigger condition shows blue status. Hover over the Trigger condition and click Manually trigger event.

No error message but preview doesn't appear

If the Amplitude dashboard shows no error but the preview doesn't appear:

• The dashboard received the initial message from your SDK.
• The SDK isn't receiving the response message from the dashboard.

To troubleshoot:

• Check your browser console for errors related to message passing.
• Verify that no browser extensions or security settings block cross-window messaging.
• Enable the Don't automatically close the preview window option in the preview modal to keep the window open for debugging.

Error message and preview doesn't appear

If the Amplitude dashboard displays an error after about 10 seconds, the dashboard didn't receive a message from the SDK. The cause is one of:

• The SDK isn't loading on your page.
• The SDK can't communicate with the dashboard.

To troubleshoot:

• Verify the SDK is installed correctly using window.engagement in your browser console.
• Enable the Don't automatically close the preview window option to extend the waiting time beyond 10 seconds.
• Confirm your application URL is correct and accessible.

Known issue: Cross-Origin-Opener-Policy header

If your application sets the Cross-Origin-Opener-Policy (COOP) header to same-origin, the COOP header prevents message passing between the Amplitude dashboard and your application, which blocks preview mode.

To resolve, either:

• Set the COOP header to same-origin-allow-popups instead of same-origin.
• Temporarily disable the COOP header for testing.

For more information about the COOP header, refer to the MDN documentation.

Testing status function

Preview mode approximates how your guide or survey appears to users. To test in a live environment, use the Testing status to test your guide or survey with specific users without affecting your broader audience.

When you set a guide or survey to Testing status:

• All specified test users (device IDs, user IDs, or cohorts) are eligible to see the guide or survey.
• Amplitude ignores limits to make testing easier.
• The guide or survey remains hidden from your production users.

To use the Testing status:

1. Open your guide or survey.
2. In the Test users section, specify your test users using device IDs, user IDs, or cohorts.
3. Change status to Testing.

Publishing

After you finish editing and testing your guide or survey, click Publish in the builder to release the guide or survey to your users.

After you publish a guide, you can still make changes. Amplitude saves the changes as "unpublished" until you click Publish to explicitly publish them.

The dashboard's preview pane and Preview mode both show your guide or survey, including any unpublished changes. Use the version history to see how many changes you made since you last published.