Testing and debugging guides

Testing guides is essential to ensure they work correctly for your users before going live. This page covers how to test guides during development and troubleshoot issues that may arise during testing.

You can preview guides directly in the Knock dashboard using the preview pane, which is powered by your message type's template preview:

1. Navigate to your guide in the dashboard and open the guide editor.
2. Use the preview pane on the right side to see how your guide content will render.
3. Edit your guide content and see the preview update in real-time.
4. Test different variants and content to refine your guide.

The guides toolbar is a floating panel that enables you to inspect and debug guides on any page of your application. Use it to understand why a guide is or isn't showing in a given context, force guides to display for testing, and inspect the targeting parameters being evaluated for the current user.

1. In the Knock dashboard, click the Preview option above your list of guides, or at the top of the guide editor's preview pane.
2. Provide or confirm the URL for your environment and click Open preview. The URL should point to a page where the guide's target element exists and the guide provider is initialized.
3. After clicking Open preview, the toolbar appears as a floating panel that you can expand or collapse.

You can also reopen the toolbar at any time by appending ?knock_guides_toolbar=true to any URL in your application.

The toolbar provides three views, toggled from options at the top of the panel:

• All guides. Every guide in your environment.
• Eligible. Guides that pass all eligibility checks for the current user.
• On this page. Guides whose target element exists on the current page.

Each guide row shows a status badge indicating its current state:

Status	Description
Inactive	The guide has not been published or is currently inactive.
Archived	The current user has already dismissed this guide.
Not targeted	The current user doesn't meet the guide's targeting conditions.
Not found	No component that can render this guide was found on the page.
Not activated	The guide cannot be activated in the current location.
Queued	The guide is queried but is not yet ready to display.
Throttled	The guide is ready to display but is currently throttled.
Display	The guide is available and ready to display.

Each guide row displays three eligibility ("Elig.") indicators. A filled dot means the condition passes; an X means it fails. All three must pass for a guide to display.

1. Active. The guide is published and active.
2. Not archived. The guide has not been dismissed for the current user.
3. Targeted. The current user matches the guide's targeting conditions.

Two visibility ("Vis.") indicators show the guide's display state:

1. Activated. The guide's trigger condition has been met in the current location.
2. Selectable. The availability and readiness of the target component on the current page. Possible values:
   • Ready. A component found the guide and is actively returning it for display.
   • Throttled. A component found the guide, but throttling rules are holding it back.
   • Queued. The guide is available but not yet ready to display because another guide is ahead of it in the display sequence.
   • Not found. No component on the page can render this guide.

Click Focus on a guide row to force that guide to display, bypassing eligibility checks, throttling, and query order. Click it again to unfocus. The focus button is disabled if no component on the page can render the guide.

• Drag handle. Drag to reposition the toolbar anywhere within the viewport. The toolbar stays within viewport bounds and re-clamps automatically on window resize.
• Sandbox. Prevents engagement API calls (seen, interacted, dismissed) from being sent to Knock. Local state still updates so the UI reflects changes, but nothing is recorded in Knock. Use this to test continuously without needing to reset engagement.
• Ignore throttle. Bypasses the display interval throttle window so guides can display immediately, regardless of when the last guide was dismissed.
• Inspect target params. Opens a panel showing the tenant and data params being used to evaluate guide targeting for the current user.
• Exit. Closes the toolbar and clears its session state. To reopen it, click Preview in the dashboard or append ?knock_guides_toolbar=true to the URL.
• Minimize. Collapses the toolbar to a small icon. Click the icon to expand it again.
• Expand details. Click any guide row to expand its details.

Before launching your guides to users, test them thoroughly to ensure they work as expected. Focus on these key areas:

• Page targeting. Verify that guides appear on the correct pages by testing different URLs and path patterns in your activation rules.
• User targeting. Confirm that targeting conditions work correctly by testing with users who should and shouldn't see the guide based on your eligibility criteria.
• Engagement tracking events. Interact with your guides and verify that engagement status updates appear as expected in the dashboard (seen, interacted, archived).
• User interactions. Click all links, buttons, and interactive elements to ensure they work as expected and navigate to the correct destinations.

While testing, take advantage of the "unarchive" option in the dashboard to reset guide messages, allowing you to test the same user/guide combination multiple times.

When guides aren't working as expected, use these debugging approaches to identify and resolve issues.

The easiest way to confirm if a user is eligible for a guide is to call the Guides API directly for that user and check if your guide appears in the response.

If your guide is missing from the response:

• Confirm the guide is activated. Verify the guide is committed and active in the environment you're testing.
• Check if the guide is archived. Verify the guide hasn't been archived for that user by checking the message status in the dashboard.
• Review targeting conditions. Check that user properties match your targeting rules.
• Verify audience membership. Ensure the user belongs to any required audiences.
• Check activation rules. Confirm the current page matches your path-based activation rules.
• Validate data types. Ensure string vs. number comparisons in conditions are correct.
• Test runtime data. Verify any data passed to the guides API matches your targeting conditions.

If you've confirmed user eligibility for the guide, you may need to debug an issue within the guide provider.

Common implementation issues:

• Your implementation is attempting to reference an incorrect part of the guides response.
• The key or type filter is set incorrectly.
• The fetched guide is not being rendered correctly by your component.
• The message type schema for the guide is formatted differently than expected.
• Guide websocket is not established and realtime updates are unavailable.

The expected results of engagment status updates may vary based on your own implementation decisions. While Knock's pre-built guide components provide out-of-the-box engagement tracking, your team will own the UI of other guide components completely. This includes making decisions about and implementing engagement tracking.

Common engagement tracking issues:

• Engagement status updates have not been implemented for the component.
• Engagement status requests fail because required parameters are missing or incorrect:
  • channel_id (string, required): The unique identifier for the channel.
  • guide_id (string, required): The unique identifier for the guide.
  • guide_key (string, required): The key of the guide.
  • guide_step_ref (string, required): The step reference of the guide.
• Engagement status requests fail because the guide_id is used in the endpoint instead of message_id.

API reference ->