Overview
When using the IBE on your website, you'll notice that your browser's URL shows parameters starting with nz-. This parameter type is attached to the URL by the TripBuilder IBE and provides two important features:
Support for Bookmarks and Page Refreshes
These IBE URL parameters represent state information for what the IBE loads. Maintaining it in the browser's URL makes it possible to bookmark a specific page loaded in the IBE or perform a page refresh without losing the context in the IBE.
API to Control what the IBE Loads
The reversed use case applies as well. By explicitly setting some IBE URL parameters, one can control what to load in the IBE.
This chapter gives an overview of supported IBE URL parameters.
Content (nz-url)
The URL parameter nz-url is the most important of all parameters and defines the TripBuilder path to be loaded into the IBE. It's automatically updated while a user browses TripBuilder pages in the IBE. The value of nz-url always needs to be URL-encoded.
Examples:
Load a list of templates:
www.your-domain.com/ibe?nz-url=%2Ftravel%2Froutes
(value of nz-url decoded is /travel/routes)
Load a specific template:
www.your-domain.com/ibe?nz-url=%2Ftravel%2Froutes%2Fthe-drive-of-your-life
(value of nz-url decoded is /travel/routes/the-drive-of-your-life)
Load a personalised itinerary:
www.your-domain.com/ibe?nz-url=%2Fitineraries%2Fozilf0xqcy3q
(value of nz-url decoded is /itineraries/ozilf0xqcy3q)
Please note:
Optionally, it's possible to define what value nz-url takes if not defined:
<div id="nz-planner" data-init-url="/travel/routes"></div>
Language (nz-lang)
nz-lang indicates the IBE to load the content in a specific language. Applicable languages have to be configured in Cockpit Settings first.
Example URL loading the list of itinerary templates in German:
www.your-domain.com/ibe?nz-lang=de&nz-url=%2Ftravel%2Froute
Currency Parameter (nz-currency)
nz-currency indicates the integration app to show prices in a specific currency. Applicable currencies must be configured for your TripBuilder instance first, otherwise, this parameter will be ignored. Also, make sure that any required foreign exchange rates have been added.
Example URL loading the list of itinerary templates with prices in EUR:
www.your-domain.com/tours?nz-currency=EUR&nz-url=%2Ftravel%2Froutes
External Customer ID (nz-ext-customer-id)
nz-ext-customer-id indicates the integration app to track interacting users in the scope of a customer. This parameter is used as part of the itinerary’s initialisation and can be retrieved via Booking API.
Example URL loading the list of itinerary templates in the scope of a customer with the ID cust1a2b3c
www.your-domain.com/tours?nz-ext-customer-id=cust1a2b3c&nz-url=%2Ftravel%2Froutes
Referral ID (referral-id)
The referral-id parameter is used to identify the integration app and specify which agency ID should be associated with bookings made through the IBE. The context of the agency making the bookings is particularly important for Tour Operators.
A possible setup using this parameter might involve an internal IBE tool where an agent logs in. Once authenticated, a parameter is passed to a standard TripBuilder IBE, with the "referral-id" parameter set to match the associated agency.
For example, to load a list of itinerary templates within the scope of an agency with the ID "TA1a2b3c," you would use a URL like this:
www.your-domain.com/tours?referral-id=TA1a2b3c&nz-url=%2Ftravel%2Froutes
Template Search (using TAGS)
While the full power of template search comes with the Discovery API, certain aspects of the API are available via URL parameters. The URL mentioned above /travel/routes that can be loaded by the IBE provides a search/filter API to only show specific templates.
The filtering of these templates is based on tags that can be assigned to any template in the Cockpit Inventory. For instance, tags can be based on countries, target customer groups (“family”, “honeymooners”, etc.) or any other category.
Tags are used in the filter API by the parameters listed below. A ranking algorithm evaluates all filter parameters and then sorts the list of itinerary templates accordingly.
Parameter | Description |
Required Tags | Optional. Comma-separated list of tags. Tags listed as required must be present on an itinerary template. Otherwise, the template is filtered out. If one or several tags are excluded, only the templates that include all the required tags will be returned. |
Preferred Tags | Optional. Comma-separated list of tags. Tags listed as preferred increase the importance of those itinerary templates containing one or several of the preferred tags. It is possible to mention the same tag several times, adding additional weight for templates with that tag when sorting. |
Disfavored Tags | Optional. Comma-separated list of tags. Tags listed as disfavored decrease the importance of those itinerary templates containing one or several of the disfavored tags. |
Example
The following example URL will only display the templates tagged USA, together with matching templates tagged mountain (both appearing on the upper part of the list). It will also include matching templates tagged city, which will show on the lower part of the list:
www.your-domain.com/tours?nz-url=%2Ftravel%2Froutes%3Frequired%3Dusa%26preferred%3Dmountain%26disfavoured%3Dcity
(decoded value of nz-url is /travel/routes?required=usa&preferred=mountain&disfavoured=city)
Note: By listing a tag several times, the tag's weight is increased.
Example
preferred=USA,USA,Canada
In this example, the USA templates would rank higher than the Canada templates.