Javascript setup

This guide will help you setup the SeatCurve javascript application ready for use on your website, this guide assumes you have completed the Server Setup guide and have a working middleware application ready for use.

Javascript Installation

SeatCurve Javascript Library

SeatCurve is a Javascript application, in order to use SeatCurve on a web page you must first load the SeatCurve Javascript library, to do so add the following code to your webpage:

<script src="/syos-bundle.js"></script>

SeatCurve Root element

Next you will need to define where to load SeatCurve, to do this you will need to create a HTML element with a unique id that will act as the SeatCurve root element, for this example we will use the id syos-root add the following code to your webpage:

<div id="syos-root"></div>

Initialization

SeatCurve needs to be initialized before it can be used, as a minimum SeatCurve needs the following information:

The SeatCurve Javascript library we loaded earlier gives us access To a new SYOS class, To initialize SeatCurve with the above information we create a new instance of this SYOS class passing in a configuration object with the above information. See below for an example:

<script>
  var syosApp = new SYOS({
      initialPerfNo: 1620,
      initialFacilityNo: 12,
      endpoint: 'https://example.seatcurve.api/rest-proxy',
      onComplete: function() {
          window.location.href = '/booking/basket';
      }
  });
</script>

Lets run through each line to explain what is happening:

var syosApp = new SYOS({

Creates a new variable syosApp and passes in a new instance of the SeatCurve SYOS object

initialPerfNo: 1620,

Tells SeatCurve what performance ID to load.

initialFacilityNo: 12,

Tells SeatCurve what Facility/Venue ID to load.

endpoint: 'https://example.seatcurve.api/rest-proxy',

Tells SeatCurve the URL of the SeatCurve API.

onComplete: function() {
    window.location.href = '/booking/basket';
}

onComplete is a function that runs once SeatCurve has finished adding tickets to the basket, in this example we are redirecting the user to a '/booking/basket' page once the tickets are added to the basket.

Running SeatCurve

Now that we have the SeatCurve Javascript library loaded, A element with a unique ID for SeatCurve and SeatCurve initialized all we need to do now is tell SeatCurve to run:

var rootEl = document.getElementById('syos-root');
syosApp.run(rootEl);

Notice that we used the syos-root ID above, this is the ID of the element we created earlier and is how SeatCurve knows where on the page to render.

Putting it all together

Putting the above steps together the HTML needed to run SeatCurve should now look like this:

<script src="/syos-bundle.js"></script>

<div id="syos-root"></div>

<script id="script-syos-run">
  var syosApp = new SYOS({
        initialPerfNo: 1620,
        initialFacilityNo: 12,
        endpoint: 'https://example.seatcurve.api/rest-proxy',
        onComplete: function() {
            window.location.href = '/booking/basket';
        }
    });

  var rootEl = document.getElementById('syos-root');
  syosApp.run(rootEl);
</script>

SeatCurve Configuration

There are two main points of configuration. Essential configuration is passed into the SYOS constructor when initialising the app. All other config is defined via a global SYOSConfig object.

Essential Configuration Options

Name Description Required?
endpoint URL to proxy endpoint. (required)
onComplete On-complete callback. Called after successfully adding or updating seats. Use this to redirect on to your cart page. (required)
initialSessionKey Customer Session key to use (optional)
initialPerfNo Performance number to use (required if loading a performance)
initialPkgNo Package number to use (required if loading a package)
initialFacilityNo Facility number for the performance or package. Used to determine which seat-map graphic to use. (required if using a custom seat-map graphic)
initialMos Current mode-of-sale. If provided alongside the initialPromoCode option we can avoid making a call to loginInfo. If omitted we’ll explicitly call loginInfo (optional)
initialPromoCode Current promo source-code. If provided alongside the initialMos option we can avoid making a call to loginInfo. Of omitted we’ll explicitly call loginInfo (optional)

Global Configuration Options

The following documents the available configuration options that can be configured through the global SYOSConfig object.

Name Description Required?
currencyCode Currency for display. Supports GBP or USD. (optional, defaults to USD)
dateTimeFormat Date format used for performance dates. Uses date-fns/format (optional, defaults to MMMM D, YYYY [at] h:mma)
returnUrl If defined a UI back button will be displayed and this URL will be used as a return location (optional)
maxTicketsMessage Message to be displayed when hitting the max-tickets limit (optional, defaults to “You cannot select any more seats.”)
customMaxTicketsLimit Provide a custom max-tickets limit. Will use the value from GetMaxTicketAmount if not set (optional)
facilityMapping Configures seat-map and level-selector graphics for individual facilities (optional, but required if using a custom seat-map graphic)
basket Provides the following options for configuring messaging for the mini-basket: totalLabel, submitLabel, successLabel, updateLabel, processingLabel, extraMessages[] (optional, defaults to US-centric wording)
seatTypes Configure seat types. Mostly used to configure custom seat icons like ADA seating or restricted view. Custom seat icons can be associated with either hold-codes or seat-type IDs. (optional)
seatMessages Custom seat messages. An Array of possible messages to show for a seat, messages can be associated with one or more seat type or hold codes. (optional)

Feature Flags

As part of the global SYOSConfig object, there is a subobject of this global config used for feature flags. Feature flags are used to configure optional functionality. They allow us to keep the core functionality lean yet provide configurable additional functionality, The basic format looks something like this:

window.SYOSConfig = {
    features: {
        promoCode: {
            // Boolean flag to enable/disable feature
            enabled: true,
            // Additional custom properties to configure the feature
            myCustomOption: null
        }
    },
    // top-level config here
};

Available feature flags are as follows:

Name Description
metrics Log usage metrics to Google Analytics. Enabled by default.
bestAvailableLink If enabled a choose best available button will be shown on both the level-selector screen (if enabled) and in the seat-map controls.
promoCode Display a promo-code form on the level-selector and seat-map
levelSelector If enabled renders an additional level-selector screen before the main seat-map. Useful for quick navigation in large venues and to introduce the venue using imagery.
panZoom Pan zoom behaviour. It would be weird to disable this one but the options provided allow you to adjust min/max zoom threshold and zoom sensitivity. Enabled by default.
customSeatDescription If enabled allows you to customise the format used for seat descriptions. Accepts a customiser function which passes through the full seat data object for you to use to determine to construct your own set description.
details Performance details. Allows a web content field ID to be provided to override the standard title returned by GetPerformanceDetailWithDiscountingEx
performanceSelector If enabled displays a performance switcher in the seat-map controls allowing you to switch between performances within the app.
cacheableGetSeats Enables a calls to the custom GetSeatsBriefWithMOS method described in the API intergration section. Enabled by default.
preferredPriceType If enabled then the application will select the same price type for subsequent seats as long as it has the same hold code, zone, and seat type. Enabled by default.
priceFilters If enabled displays a price key allowing people to filter seats on the seat-map by price. Enabled by default.
seatKey If enabled displays a seat key showing icons for each of the available types of seat. Enabled by default.
viewFromSeat If enabled displays inline view from seat imagery. Full implementation details are described later in the document.

Note: imageBackground, imageForeground, and imageMask are all paths to the location of each graphic. zoomLevel determines how far to zoom in when selecting a hit-area. hitAreaLabels let’s you provide a mapping between the hit-area layer names and a meaningful label.

View From Seat Imagery

SeatCurve has a feature which allows you to provide a mapping of seat images for a facility, the application will use a nearest neighbor algorithm to determine the best seat to show.

This allows you to supply a relatively small number of images and still fill the venue. Whilst we encourage you to provide as many high-quality seat images as you can, you do not need to provide an image for every single seat.

JSON Feed Specification

In order to show view from seat images you must generate a JSON feed in the following format. How this feed is implemented is up to you but it is typically a static JSON file hosted on your website.

{
  "facilities": [{
    "facility_no": "10",
    "seat_images": [
      "https://static.example.com/path/to/images/seat-1-A-2.png",
      "https://static.example.com/path/to/images/seat-2-A-2.png",
      "https://static.example.com/path/to/images/seat-3-A-2.png"
    ]
  }]
}

The image file-name needs to be in the format seat-{number}-{row}-{screen}, e.g. seat-42-A-2. This is the same format as the seat id's used in the seatmap graphic.

To tell the application to use this feed you need to configure the viewFromSeat feature flag as follows:

window.SYOSConfig = {
  features: {
    viewFromSeat: {
      enabled: false,
      endpoint: 'https://static.example.com/path/to/images/seat-images.json',
      // If enabled shows a caption describing the real location of the seat image.
      showCaption: true
    }
    …
  }
}

Analytics Data

Analytics

SeatCurve has built-in support for Google Analytics Custom Events and tracks a number of metrics out of the box. The full list of metrics are as follows:

Name Description
Seat Selected Tracked when adding a seat to the mini-cart, includes a description of the seat that was selected.
Seat Removed Tracked when removing a seat from the mini-cart, includes a description of the seat that was removed.
Refresh Seat Availability Tracked when a seat-collision occurs and users are prompted to refresh the seat availability.
Filter Prices Tracked when using the price filters, includes which price was selected.
Selected Level Tracked when switching between levels using the control-panel for multi-level venues. Includes which level was selected.
Toggle Cart Tracked when toggling the cart open or closed
Toggle Control-Panel Tracked when toggling the controls open or closed

This data has been very useful and helped inform future development and guide technical decisions on support tickets. The more we can track the better.