Location hierarchy
City, region and country layers are always eligible when HI has hostels there.
Member Association integration guide
Search the world,
from your site.
One hosted HI search component for cities, regions, countries and hostels—with a mobile interface designed for the software keyboard.
10minutes for a typical installation
2standard interface languages
1centrally maintained widget
A small integration, maintained by HI
The widget downloads HI’s public location index, searches it in the visitor’s browser and hands a chosen place to Hostel Explorer. It supports city, region and country results as well as hostel-name matching.
HI hosts the component and location data centrally. Member Associations do not need an API key, a software package or a locally hosted copy of the JavaScript.
On mobile, focusing the field opens a full-page search interface. Its results area scrolls independently and remains usable while the software keyboard is visible.
The old widget remains supported during migration. An MA can stage and approve the replacement normally, then roll back to its saved legacy embed if its own CMS or security policy causes a problem.
Full-page takeover
A focused interface with its own results scrolling above the keyboard.
One hosted version
Updates and current location data arrive without an MA reinstalling the widget.
Section 02 · Install
Copy, identify, test
Replace YOUR_MA_CODE with the code supplied by HI. Keep the fallback link inside the component.
Confirm settings
Get the MA partner code, language and tab behaviour from HI.
Add the embed
Place the component in normal page flow and include the module script once.
Test and publish
Complete the staging checklist, publish, then repeat the mobile smoke test.
<hi-hostel-search
index-url="https://widgets.hihostels.com/v1/locations.json"
search-url="https://widgets.hihostels.com/go/hostels"
locale="en-GB"
partner="YOUR_MA_CODE"
target="_blank">
<a href="https://www.hihostels.com/discover/explore">Search HI hostels</a>
</hi-hostel-search>
<script type="module" src="https://widgets.hihostels.com/v1/widget.js"></script>If the widget appears more than once on a page, include the script only once. Do not download, proxy or self-host the component.
Section 03 · Configure
Three decisions per MA
partner
The non-personal attribution code supplied by HI. Use lowercase letters, numbers and hyphens—for example djh.
locale
Use en-GB for English or de-DE for German. Standard copy follows this setting.
target
Use _blank to open Explorer in a new tab, recommended for an external MA site, or _self for the same tab.
Optional copy
Use the defaults where possible
placeholder and button-label can override standard interface text by agreement with HI. Overrides are not automatically translated.
Section 04 · Test
Try the production widget
This is the same hosted component and live location index an MA will embed. Search for Paris, a country, or a region you know.
Suggestions and hand-off
- Search
Paris. - Confirm city and country suggestions.
- Open the city and confirm Explorer shows Paris.
Keyboard and scrolling
- Test near 390px on a real phone.
- Open the software keyboard.
- Confirm the panel fills the usable screen and results scroll.
Destination contract
- Confirm
source=ma-widget. - Confirm the agreed partner code.
- Confirm the chosen place and language.
Section 05 · Migrate
No emergency deadline
The unchanged legacy widget is currently supported by HI’s compatibility service. MAs can schedule and test the replacement normally.
HI intends to maintain the legacy compatibility endpoints for at least 12 months after cutover and until measured use is negligible. HI will communicate before withdrawing support.
- 01
Save the current page
Keep a CMS revision or exact copy of the old embed.
- 02
Stage the new widget
Do not show both search interfaces in the same location.
- 03
Complete desktop and mobile QA
Include a real phone with the keyboard open.
- 04
Publish and smoke-test
Check the public page in a private browser window.
- 05
Roll back if required
Restore the saved legacy embed, publish it, then send HI the evidence below.
Section 06 · Technical
Security, privacy and hosting
Content Security Policy
Add the widget host to existing directives; do not replace the MA’s current sources or nonces.
script-src https://widgets.hihostels.com
connect-src https://widgets.hihostels.comThe browser must also be allowed to navigate to widgets.hihostels.com and www.hihostels.com. The widget does not require unsafe-eval.
Data behaviour
Suggestions are filtered locally after the public index downloads. The submitted location, language, source=ma-widget and non-personal partner code appear in the destination query string.
Do not put names, email addresses, customer IDs or other personal data in widget attributes.
Browser support
The widget targets current evergreen desktop and mobile browsers, including current Safari on iOS and Chrome on Android. Each MA should still test its own supported matrix.
The fallback link remains available if JavaScript cannot run.
Layout boundary
Place the component in normal flow in a container that can use the available width. Do not clip it or give its outer container a fixed height.
Shadow DOM isolates internal styling from the host site.
Section 07 · Support
Send evidence, not personal data
First compare the MA page with the hosted test above. If the hosted test works but the MA embed does not, include the MA page’s console or CSP error.
Download the complete MA pack
Embed file, installation guide, QA, rollback, technical notes and support template.
↘Include with a support request
- MA name, partner code and affected page URL
- Staging or production environment
- Date, time, device, operating system and browser
- Search entered, expected result and actual result
- Screenshot or short recording
- Widget-related console or CSP error
- Recent CMS, consent-manager, CSP or firewall change