Testing

Amplitude provides 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 more thorough live test with specific users to be extra certain before launch.

Preview mode

Preview mode helps make sure that your guides and surveys are set up as you want them. You can always see how a guide or survey looks just by opening it in Amplitude, but if you want to ensure that it behaves as expected, test it in preview mode.

Preview mode is accessible from the builder:

1. Open a guide or survey.
2. Click Test & Preview.
3. Enter the URL of the page with the Guides and Surveys SDK installed.
4. Amplitude verifies that the SDK is available on the URL, and opens it in a new tab with the preview bar visible.

Conditions checked in preview mode

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

• Trigger
• Limit
• Throttle

Condition status

These conditions have three 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 (approximately 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 this 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. When this happens, and the instrumentation is correct, check the following:

• That the user you're previewing as hasn't already seen the guide or survey you're trying to test. If this is the case, the preview bar shows a yellow (warning) status for the Limit condition. If this happens, hover over the condition, and click Reset User History.
• That the throttle limit isn't reached. In this case, the Throttle condition shows yellow (warning) status. If this happens, hover over the condition, and toggle Ignore Throttle Limits.
• If you're using On event tracked as the trigger condition, ensure that the corresponding event fires. If the event hasn't fired, the Trigger condition has a blue status. Hover over the Trigger condition, and click Manually trigger event.

No error message but preview doesn't appear

If the Amplitude dashboard doesn't show an error but your preview doesn't appear, this indicates that:

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

To troubleshoot this scenario:

• 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 approximately 10 seconds, the dashboard didn't receive a message from the SDK. This indicates that:

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

To troubleshoot this scenario:

• 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
• Check that 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, it prevents message passing between the Amplitude dashboard and your application. This blocks preview mode from working.

To resolve this issue, either:

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

For more information about the COOP header, review the MDN documentation.

Testing status function

While preview mode provides a close approximation of how your guide or survey appears to users, sometimes you want to test in a live environment. In these cases, 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.
• Limits are automatically ignored 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 .