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. Beyond local testing in your development environment, Knock provides Dashboard resources for testing guide edits in realtime, making guides more accessible to non-technical users.

Live preview enables you to preview guides directly within your own application from the Knock dashboard, enabling realtime previews for non-technical users and expediting the guide creation process.

With live preview, you can:

• Preview how your guides will look and behave within your actual application.
• Edit guide content, targeting rules, and activation conditions while seeing exactly how they'll appear to users.
• Get real-time validation and immediate feedback when a guide cannot render on the current page.
• Validate that prebuilt components work correctly with your message type schema.
• Iterate on guide designs without activating test guides in your dashboard.

1. Before creating your guide, implement guides in your application and ensure the relevant guide component is available on the target page in your application.
2. Navigate to your guide in the Knock dashboard and open the guide editor.
3. Click "Live preview" at the top of the guide editor.
4. Enter the URL of the page in your application where you will preview the guide.
5. Click "Open preview" to see your guide rendered in your application.

Live preview integrates seamlessly with your existing KnockGuideProvider setup and doesn't require additional code changes to your application.

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.

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 ->