Configuration

You can customize your widget by adding attributes to the widget container div element.

Attribute list

The table below lists all available attributes:

Attribute	Required	Purpose	Example value
`data-whitelabel-domain`	Yes	Fetch partner white label configuration	`your-whitelabel-address.com`
`data-city-slug`	Yes*	Fetch activities in a specific destination	`New York`
`data-coords-latitude`	Yes*	Fetch activities near a specific latitude	`45.466667`
`data-coords-longitude`	Yes*	Fetch activities near a specific longitude	`9.183333`
`data-coords-distance`	No	Fetch activities located within the specified search radius	`5KM`
`data-coords-search-mode`	No	Fetch activities based strictly on coordinates or the nearest destination	`nearest` OR `distance`
`data-products`	Yes*	Fetch specific activities by their UUID	`a312c09e-14cf-400a-b511-8a070c93f4d7,c4149554-9f9d-49ac-acf4-eaf2c4262337`
`data-date-from`	No	Fetch activities available from the specified date	`2022-01-01`
`data-date-to`	No	Fetch activities available before the specified date	`2022-01-15`
`data-market-prefix`	No	Use a specific market	`it`
`data-number-of-elements`	No	The maximum number of activities to display at a time	`10`
`data-pass-through-params`	No	Add query parameters to the white label or musement.com URL	`{"aid":"example-id-123"}`
`data-cid`	No	Tag traffic with a channel ID	`widget_cid`
`data-utm-source`	No	Tag traffic source	`your-site.com`
`data-utm-medium`	No	Tag traffic device	`web-widget`
`data-utm-campaign`	No	Tag traffic campaign	`summer-promo`

* A widget must be set for a single destination or specific products. See the Products selection for more info.

White label domain

The white label domain is required for the widget configuration. It fetches your white label configuration: activity card styles, default market, language and currency. It also handles redirections to the correct white label page when a user selects an activity in the widget.

To pass the white label domain, add the data-whitelabel-domain attribute to the widget container.Affiliate partners who do not have their own white label domain can use a value of www.musement.com, together with their affiliate ID in the data-pass-through-params attribute.

Products selection

The widget configuration must contain either a specific destination to show activities in the area or a list of activities. There are two ways to define the location:

By City Slug
By Coordinates

As an alternative you can pass comma-separated list of activities. See Specific products for more details.

City

If you provide the widget with the name of city via the data-city-slug attribute, it will display activities which belong to the city in our database which best matches the attribute value.

Coordinates

Using a city name can be inaccurate. Giving the widget a set of coordinates instead allows it to display activities within 100 km of the specified location. When specifying a location via coordinates, both the data-coords-latitude and data-coords-longitude attributes are required. Omitting either attribute, or using invalid decimal values, will result in an error.

Distance

When searching for activities by coordinates, results are located within a 100 km radius by default. You can override this default using the data-coords-distance attribute. The attribute must contain a positive integer value plus and of the following units of measure:

KM: kilometers
M: miles

For example, to search for activities located 5 km within the coordinates, set the data-coords-distance attribute to 5KM.

Search mode

Note

Partners should consider using nearest as the preferred parameter because they will take advantage of our automatic sorting system to display popular activities. This will improve conversion rate.

The data-coords-search-mode attribute allows you to refine how activities are fetched based on coordinates. You can choose between two modes:

nearest: The nearest destination is retrieved based on the provided coordinates. Products are loaded from this destination and sorted by a ranking algorithm optimized for destination pages. data-coords-distance must not be specified with this mode. Doing so will trigger a warning in the console.
distance: Products are loaded based on the specified coordinates.

When omitted, the widget defaults to the nearest mode.

Specific products

Note

The Musement catalog can be retrieved from the Partner Hub for your convenience.

The widget allows you to fetch specific activities by their unique identifiers (UUIDs). This is helpful when you want to display a predefined selection of activities rather than relying on location or coordinates. The attribute accepts a comma-separated list of UUIDs. It may be used in combination with other optional attributes, except for data-city-slug or data-coords-latitude / data-coords-longitude.

Market prefix

While the white label solution allows partners to specify translations, the market prefix determines the widget's entire market. The market determines the currency and catalog of activities to display as well as translations. You can specify the market prefix with the data-market-prefix attribute.

The market prefix is optional. Your white label's default market prefix is used whenever the attribute is absent, contains an invalid value or uses a value that has not been enabled for you.

Number of elements

The data-number-of-elements attribute affects the maximum number of activities displayed in the widget. This attribute is optional and will use a value of 3 by default when absent. It accepts values from 1 to 15.

Date range

Similar to the date filters for our white label solution, you can limit activities in the widget to those with availability between a specified date range by using the data-date-from and data-date-to attributes. These attributes must contain values in the yyyy-mm-dd format and they must be used together. It is currently not possible to use only one of the date range attributes.

Query parameters

The optional data-pass-through-params attribute allows you to add query parameters to the resulting white label URL.

The attribute value must be a serialized JSON object with key-value pairs. Parameters in the attribute which are already present in the white label configuration will be omitted in the resulting URL. Due to the nature of the serialized data, partners are encouraged to take appropriate steps to properly encode the attribute value. In the example below, the value is encased in single quotes:

Copy

Copied

data-pass-through-params=" '{"aid":"example-id-123"}' "

Affiliate partners who do not have their own white label domain must include their affiliate ID as the aid query parameter via data-pass-through-params attribute. This ID is issued at the beginning of the development process.

Tagging traffic

Just as the white label solution gives partners the option to set up deep link tracking, the widget can help you better understand its performance by tagging traffic with different tracking parameters. Currently, the widget supports the following tracking parameters:

Attribute	Default value
`data-utm-source`	The site using the widget
`data-utm-medium`	`web-widget`
`data-utm-campaign`	The coordinates and position of the clicked element on the page
`data-cid`	`widget_cid`

These attributes are all optional. The widget will use the specified default values when these attributes are absent.