Skip to content

Add minimal fallback mechanism documentation for JS API search integrations #309

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
wants to merge 6 commits into
base: Techdocs
Choose a base branch
from
Draft

Add minimal fallback mechanism documentation for JS API search integrations #309

Changes from 5 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
a6dd4ab
Initial plan
Copilot Oct 7, 2025
4a191c8
Add fallback mechanism documentation for search and category merchand…
Copilot Oct 7, 2025
05c91c8
Remove fallback documentation as requested in review
Copilot Oct 7, 2025
96a092f
Remove only the "Recommended fallback approach" subsection as requested
Copilot Oct 7, 2025
07f80c7
Remove Category merchandising fallbacks section and code snippet
Copilot Oct 7, 2025
2f44a2a
Update timeout information and remove timeout management line
Copilot Oct 7, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 19 additions & 0 deletions implementing-nosto/implement-search/search/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -388,4 +388,23 @@ Tracking product clicks is fundamental for understanding user interaction. Use `

In case of an SPA based integration the `api.recordSearchClick` calls should be complemented with Session API or `api.createRecommendationRequest()` usage to couple the search analytics events to generic Nosto events for accurate attribution.

## Fallback mechanism

For JS API integrations, there is no built-in fallback functionality. Merchants need to build this themselves to ensure a robust search experience.

### When to implement fallbacks

You should implement fallback mechanisms in the following scenarios:

* **Search query errors**: When the search API returns an error response
* **Timeout scenarios**: When the search query takes longer than 1 second to return results
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

mention that JS API based Search requests timeout after 5 seconds

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Updated the timeout scenario to mention that JS API based Search requests timeout after 5 seconds as requested. The line now provides accurate information about the actual API timeout behavior. Changes committed in b9c4f21.

* **Network connectivity issues**: When there are network problems preventing API calls

### Implementation considerations

* **Error handling**: Always wrap Nosto search calls in try-catch blocks
* **Timeout management**: Implement reasonable timeout values (recommended: 1 second)
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

drop this line

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Dropped the timeout management line as requested. The bullet point about "recommended: 1 second" has been removed from Implementation considerations. Changes committed in b9c4f21.

* **User experience**: Ensure seamless transition to fallback without visible errors
* **Analytics**: Track fallback usage to monitor search performance

***