1. Introduction

A long, long time ago, when the seats were square-shaped and each seat was numbered, UX and conversion rate terms were something vague for the ticketing. Ticketing giants like TM invested a lot of money using all their experience to create impressive seating plans for the users.

Nowadays, with thousands of competitors, it takes all the running you can do to stay at the same place. As well as Alice, you can run twice as fast as now, and you need the right partner.

If you are good at marketing, sales, and ticketing operation and want to compete with the best on the market – you need a perfect, nice looking, informative, convenient seating plans to sell your venues.

Seatmap.pro is the platform for seating plans creation, management, and efficient seating charts rendering for the ticketing companies. The most powerful feature of Seatmap.pro is the possibility of integration with any ticketing system regardless of seating plan supportability.

Let’s go.

2. Overview

Seatmap.pro allows you to use the cutting-edge technologies for the seating plans management and the best user experience approaches and practices for the interaction with the End User. Embed reserved ticketing with a modern seating plan software, html5 seat system, leveraging full stack of technologies for visualization: SVG, HTML canvas and WebGL. Designed as a SaaS solution, Seatmap.pro aimed at leveraging the conversion rate for the ticketing sales.

Seatmap.pro operates with two general types of tickets:

  1. Unique Seats with numbered names (Seat)

  2. General admission tickets, when you have only a section specified on your ticket (GA)

2.1. Components

Seatmap.pro contains the following components and services:

Seatmap Editor

Seating maps editor. Allows to create, edit and manage your seating plans.

Seatmap Booking

Events and price management tool. This component is a bridge between schemas and specific seats on the event available for booking.

Seatmap Renderer

JavaScript component embedded into the Sales page. Renderer responsible for all visualization routines on the client side.

components
Figure 1. Components. Green – Seatmap stack, Blue – Your ticketing system
All the components are designed as a seamless SaaS solution and should be delivered as one product. Unfortunately, we can’t deliver the only Renderer due to complex and constantly changing protocols between Renderer and Booking components.

2.2. Security Concerns

How to separate the seating chart’s visual representation from the complete assignments/booking/sales ticketing cycle?

Seatmap.pro is the platform only for manipulation with seating plans.

We are not:

  1. A ticketing company neither a ticketing service.

  2. Getting the money from the users. Checkout process is operated completely on your side.

  3. Counting how many tickets did you sell. We can see only the seat locks.

  4. Getting your prices information. The prices can be abstracted like – 'Price 1', 'Price 2', etc.

3. Getting Started

To understand how to integrate Seatmap.pro into your ticketing system lets review and match overall simplified lifecycle of tickets during a reserved ticketing event.

In this document, we assume that you already have some ticketing system.

In a common scenario, we need to accomplish the following steps:

  1. Create a schema for a venue.

  2. Create an Event.

  3. Assign prices to the seats (bind the event and schema).

  4. Show the sales page to customers, and allow them to interact with the seating chart.

  5. Add selected seats to the cart.

  6. Check them out.

lifecycle
Figure 2. Lifecycle

3.1. Composite Key

To address any attributes to specific seats on a chart (price, state and so on), Seatmap.pro uses natural language composite keys. For example, if you have a seat named: Section B, Row 5, Seat 14 – composite key will be "Section B;;5;;14".

So, to assign a price to a seat, lock, unlock and do any operation composite keys shall be considered as the main option.

General admission "Seats" shall be addressed by the section name

3.2. Creating a Schema

Please refer to Seatmap.pro editor documentation to learn how to create and manage seating plans.

When a schema is created and published, it is ready to be exposed by API. Please see the Venues section to get more details.

3.3. Create an Event

The event is an entity that binds prices and seats for a single show. In Seatmap.pro you can assign more than one event to the schema. For example, if you have several events of one artist with the same show at the same venue you probably want to have the same seating chart for all events.

Be advised that in your terminology Event might be Instance or Show.

Event creation should be a synchronized operation between your Event storage and Seatmap.pro. For example, if you want to create an event named "Test event" you should perform two simple requests:

event creation
Figure 3. Event creation
  1. Retrieve schemas and venues list

  2. Create an Event linked to the selected schema

The created Event ID should be saved on your side to specify it during Renderer’s initialization on the Sales page.

Now, when the event contains a linked schema, let’s assign prices to the event.

3.4. Assign Prices

To assign a price to the seats you should use Composite keys.

To retrieve all composite keys for a schema, please use the corresponding method getMeta from the Venues section.
assign prices
Figure 4. Assign prices
  1. It is an optional step, just to validate your namespace.

  2. The assign price command sends an Array of key/values like composite key/price.

3.5. Show Seating Plan to User

The user opens the sales page in a browser. Without Seatmap.pro integration, you just show theEvent description and your approach to seat selection to the User.

To integrate the Renderer component into your sales page, you need to initialize the JS component and transfer the following values to it:

  1. The public key (Security).

  2. Event id (Saved on step 2 during Event creation).

  3. Callbacks for the handling of mouse/touch events.

renderer init
Figure 5. Renderer initialization
  1. The Sales page should be rendered or filled with a data from the Ticketing System Backend.

  2. Event ID created on the step 2 shall be returned to the Sales page.

  3. The Sales page initializes the Renderer with Event ID.

  4. The Renderer fetches all information by Event ID and initializes a seating chart.

After the initialization phase, the Renderer retrieves all the data including the seating chart and prices by Event ID from Booking API. Now it is ready to interact.

3.6. Operations with Seats

The renderer has callbacks for the basic events like:

  1. Seat selection.

  2. Seat deselection.

  3. onHover, onBlur, etc.

Here, for the getting started purposes we are interested in how to integrate the ticket selection process and convert it into a successful purchase.

Your sales page handles callbacks including onSeatSelect. After catching this event you have two options:

  1. Collect all the seats is a cart without any interactions with server-side, or.

  2. On each select/deselect event do preliminary locks on objects.

Let’s consider the most complicated scenario – lock per click.

lock
Figure 6. Seat locking
  1. User clicks on a seat.

  2. The renderer component runs callback function to notify the Sales page about en event.

  3. The Sales page trying to lock a seat and sending the locking request to the Ticketing Backend.

  4. The Ticketing Backend checks the seat’s state in accordance with internal logic.

  5. In case if lock operation is available the Ticketing Backend sends lock request to the Booking service.

4. Renderer Component

The Renderer component is a JavaScript library for a seating plan visualization. The component allows us to display any available seating chart from Seatmap.pro and provides all functionality to interact with it. A renderer may be embedded into a sales page.

As a developer, from a JS perspective, you can interact with a component with in the following ways:

  • Component’s initial configuration

  • Subscribe on events

  • Direct component’s methods call

4.1. Initialization

For the component’s initialization you need to assign two basic parameters:

  1. DOM element that will be a host element for the Renderer

  2. Renderer settings

var el = document.getElementById('root');
var settings = {
  publicKey: 'bd780a2f-9b9d-48a8-ad05-34dc5154fb9a',
  onSectorClick: handleSectorClick
};
var renderer = new SeatmapBookingRenderer(el, settings);

Settings object may include the following properties:

var settings = {
    publicKey: 'bd780a2f-9b9d-48a8-ad05-34dc5154fb9a',(1)
    onSeatMouseEnter: function(seat) { (2)
      console.log('seat mouse enter', seat);
    },
    onSeatMouseLeave: function() { (3)
      console.log('seat mouse leave');
    },
    onSeatSelect: seat =>(4)
      function(seat) {
        console.log('seat select', seat);
      },
    onSeatDeselect: function(seat) {(5)
      console.log('seat deselect', seat);
    },
    onCartChange: function(cart) {(6)
      console.log('cart change ', cart);
    },
    onSectorMouseEnter: function(sector) {(7)
      console.log('sector mouse enter', sector);
    },
    onSectorMouseLeave: function() {(8)
      console.log('sector mouse leave');
    },
    onSectorClick: function(sector) {(9)
      console.log('sector click', sector);
    },
    onZoomStart: function(to, from) {(10)
      console.log('before zoom', to, from);
    },
    onZoomEnd: function(to, from) {(11)
      console.log('after zoom', to, from);
    },
    onPan: function(delta, isEnd) {(12)
      console.log('pan', delta, isEnd);
    }
  };
1 Public key shall be used for each request
2 onSeatMouseEnter rises when the mouse pointer moves above a seat
3 onSeatMouseLeave fires when the mouse pointer leaves a seat
4 onSeatSelect fires when the user mark a seat as selected
5 onSeatDeselect fires when the user deselect a seat
6 onCartChange fires when the cart is modified
7 onSectorMouseEnter fires when the mouse pointer moves above a section
8 onSectorMouseLeave fires when the mouse pointer leaves a section
9 onSectorClick fires when the user click on a section
10 onZoomStart fires before the zoom operation
11 onZoomEnd fires after the zoom operation
12 onPan fires while panning

4.2. Renderer Methods

4.2.1. Load Event’s Schema

loadEvent(eventId: string) => Promise

Loads event’s schema with prices and GA. As a parameter, you shall specify the Event ID. Method loadEvent is asynchronous, returns a Promise object.

Load event
var eventId = 'a4a75361-7823-4847-bf22-336843022e80';
renderer.loadEvent(eventId).then(function() {
  renderer.initCart(cart);
});

4.2.2. Retrieve Internal Cart State

getCart() => ICart

Seatmap.pro does not support any session mechanisms. Cart is always should be stored on the ticketing system side. For the state management reasons, the Renderer has internal selected seat representation.

Returns selected seats.

Cart container
var cart = {
  seats: [
    { id: 1389563, key: 'Section 1;;5;;14', price: 100 },
    { key: 'Table 3;;1;;1', price: 500 },
    { key: 'Section 2;;5;;1', price: 200 }
  ],
  ga: [
    {
        id: 100500, (1)
        key: 'Table 2', (2)
        price: 200, (3)
        count: 1 },(4)
    { key: 'Section 5', price: 100, count: 2 }
  ]
};
1 Internal seat or section id
2 Composite Key used for the global seats addressing
3 Price value
4 For GA section – quantity of tickets

4.2.3. Clear Cart

clearCart()

Eliminate all the elements from the cart.

4.2.4. Cart Initialization

initCart(cart: ICart)

In a case of page reload you should initialize the saved state with this method.

Cart initialization is available right after component initialization.

Cart initialization
var cart = {
  seats: [
    {
        id: 1389563,
        key: 'Section 1;;5;;14',
        price: 100 },
    { key: 'Table 3;;1;;1', price: 500 },
    { key: 'Section 2;;5;;1', price: 200 }
  ],
  ga: [
    {
        id: 100500,
        key: 'Table 2',
        price: 200,
        count: 1 },
    { key: 'Section 5', price: 100, count: 2 }
  ]
};
renderer.initCart(cart);
Sales page must save the cart state in the given format to support the page reload feature

4.2.5. Retrieve Prices

getPrices() => IColoredPrice[]

Returns array of available prices.

var prices = renderer.getPrices();
 [
   { id: 63, name: '100', color: '#9C27B0' },
   { id: 64, name: '200', color: '#2196F3' }
 ];

4.2.6. Manually Add Seats to Cart

addSeatsToCart(seats: ICartSeat[])

Adds seat to cart programmatically. This method is optional. In a common scenario, the User adds available seats by clicking them.

renderer.addSeatsToCart([
    {
        id: 803, (1)
        key: 'Section 3;;3;;1', (2)
        price: 500 (3)
    }
    ]);
1 Internal seat identifier
2 Composite Key used for the global seats addressing
3 Price value

4.2.7. Manually Add GA Seats to Cart

addGaToCart(ga: ICartGa)

Adds GA seats to the cart.

This method can be used when onSectorClick fired and developer wants to handle custom add/remove GA seats control. Then the selection in a custom control complete – you can just add desired quantity of GA tickets in the cart.

renderer.addGaToCart({
  id: 100500,(1)
  key: 'Table 2',(2)
  price: 200,(3)
  count: 3(4)
});
1 Internal seat or section id
2 Composite Key used for the global seats addressing
3 Price value
4 For GA section – quantity of tickets

4.2.8. Disable Seats by IDs

disableSeatsByIds(seatIds: number[])

Marks seats as unavailable using internal identifiers

4.2.9. Disable Seats by Keys

disableSeatsByKeys(keys: string[])

Marks seats as unavailable using Composite Key

4.2.10. Zooming

zoomIn() / zoomOut() / zoomToFit()

Zoom operations

4.2.11. Getting Zoom level

getZoom() => number

Returns the current zoom level

5. Endpoints

5.1. Booking

5.1.1. lock

POST /api/private/v1.0/booking/lock

Lock a seat or GA

Description

Seat should be available

Parameters
Body Parameter
Name Description Required Default Pattern

Selection

Selection

X

Query Parameters
Name Description Required Default Pattern

id

X

null

Return Type

array[Selection]

Content Type
  • application/json

Responses
Table 1. http response codes
Code Message Datatype

400

Input data is not valid

List[Selection]

403

Forbidden. Please use correct private key.

List[Selection]

200

Returns unsuccessful attempts

List[Selection]

Samples

5.1.2. sale

POST /api/private/v1.0/booking/sale

Transfer seat or GA to the state sold

Description

This feature applicable only in a sales control mode

Parameters
Body Parameter
Name Description Required Default Pattern

Selection

Selection

X

Query Parameters
Name Description Required Default Pattern

id

X

null

Return Type

array[Selection]

Content Type
  • application/json

Responses
Table 2. http response codes
Code Message Datatype

400

Input data is not valid

List[Selection]

403

Forbidden. Please use correct private key.

List[Selection]

200

Returns unsuccessful attempts

List[Selection]

Samples

5.1.3. unlock

POST /api/private/v1.0/booking/unlock

Unlock a seat or GA

Description

For GA unlocking capacity counter shall be specified

Parameters
Body Parameter
Name Description Required Default Pattern

Selection

Selection

X

Query Parameters
Name Description Required Default Pattern

id

X

null

Return Type

array[Selection]

Content Type
  • application/json

Responses
Table 3. http response codes
Code Message Datatype

400

Input data is not valid

List[Selection]

403

Forbidden. Please use correct private key.

List[Selection]

200

Returns unsuccessful attempts

List[Selection]

Samples

5.2. Events

5.2.1. eventAll

GET /api/private/v1.0/events/

Retrieve list of all events

Description

Getting all the events with paging

Parameters
Query Parameters
Name Description Required Default Pattern

limit

Quantity of requested items

-

50

offset

Offset for the pager

-

0

Return Type

array[Event]

Content Type
  • application/json

Responses
Table 4. http response codes
Code Message Datatype

400

Input data is not valid

List[Event]

200

Returns list of objects

List[Event]

403

Forbidden. Please use correct private key.

List[Event]

Samples

5.2.2. eventCreate

POST /api/private/v1.0/events/

Create an Event

Description

Before you start to create an Event you need to create a schema with venue.

Parameters
Body Parameter
Name Description Required Default Pattern

Event

Event

X

Return Type
Content Type
  • application/json

Responses
Table 5. http response codes
Code Message Datatype

400

Input data is not valid

Event

403

Forbidden. Please use correct private key.

Event

200

Returns created object

Event

Samples

5.2.3. eventDelete

DELETE /api/private/v1.0/events/{id}

Delete an Event

Description

Deleted event shall contains valid id.

Parameters
Path Parameters
Name Description Required Default Pattern

id

Valid event identifier

X

null

Return Type
Content Type
  • application/json

Responses
Table 6. http response codes
Code Message Datatype

200

Returns result of the delete operation

[Boolean]

400

Input data is not valid

[Boolean]

403

Forbidden. Please use correct private key.

[Boolean]

Samples

5.2.4. eventUpdate

PUT /api/private/v1.0/events/

Update an Event

Description

Updated event shall contains valid id.

Parameters
Body Parameter
Name Description Required Default Pattern

Event

Event

X

Return Type
Content Type
  • application/json

Responses
Table 7. http response codes
Code Message Datatype

200

Returns updated object

Event

400

Input data is not valid

Event

403

Forbidden. Please use correct private key.

Event

Samples

5.3. PriceAssignments

5.3.1. assignPrice

POST /api/private/v1.0/assignments/

Assign prices to event

Description

Price assignments assume using of plain representation of price. For GA sections you need to specify capacity

Parameters
Body Parameter
Name Description Required Default Pattern

PriceAssignment

PriceAssignment

X

Query Parameters
Name Description Required Default Pattern

id

Corresponding event id

X

null

clean

Clean before assign is used when you need completely renew the price assignment. It also could be cleaned with clean method

-

false

Return Type
Content Type
  • application/json

Responses
Table 8. http response codes
Code Message Datatype

400

Input data is not valid

List[PriceAssignment]

403

Forbidden. Please use correct private key.

List[PriceAssignment]

200

Returns unsuccessful assignments

List[PriceAssignment]

Samples

5.3.2. cleanAssignment

POST /api/private/v1.0/assignments/clean

Remove all price assignments from event

Description

All states including locked seats, will be cleaned up during this operation

Parameters
Query Parameters
Name Description Required Default Pattern

id

Corresponding event id

X

null

Return Type
Content Type
  • application/json

Responses
Table 9. http response codes
Code Message Datatype

400

Input data is not valid

[Boolean]

403

Forbidden. Please use correct private key.

[Boolean]

200

Returns true if everything is ok

[Boolean]

Samples

5.3.3. removeAssignment

DELETE /api/private/v1.0/assignments/

Remove specified assignments from event

Description

To remove assignments from event we are using simplified object Selection. For GA sections use capacity field as well

Parameters
Body Parameter
Name Description Required Default Pattern

Selection

Selection

X

Query Parameters
Name Description Required Default Pattern

id

Corresponding event id

X

null

Return Type

array[Selection]

Content Type
  • application/json

Responses
Table 10. http response codes
Code Message Datatype

200

Returns unsuccessful attempts to remove assignment

List[Selection]

400

Input data is not valid

List[Selection]

403

Forbidden. Please use correct private key.

List[Selection]

Samples

5.4. Prices

5.4.1. priceAll

GET /api/private/v1.0/prices/

Retrieve all prices for event

Description

All prices

Parameters
Query Parameters
Name Description Required Default Pattern

id

X

null

Return Type

array[Price]

Content Type
  • application/json

Responses
Table 11. http response codes
Code Message Datatype

400

Input data is not valid

List[Price]

200

Returns list of objects

List[Price]

403

Forbidden. Please use correct private key.

List[Price]

Samples

5.4.2. priceCreate

POST /api/private/v1.0/prices/

Create a price for event

Description

Binds a price to event

Parameters
Body Parameter
Name Description Required Default Pattern

Price

Price

X

Return Type
Content Type
  • application/json

Responses
Table 12. http response codes
Code Message Datatype

400

Input data is not valid

Price

403

Forbidden. Please use correct private key.

Price

200

Returns created object

Price

Samples

5.4.3. priceDelete

DELETE /api/private/v1.0/prices/

Delete a price for event

Description

Binds a price to event

Parameters
Query Parameters
Name Description Required Default Pattern

id

X

null

Return Type
Content Type
  • application/json

Responses
Table 13. http response codes
Code Message Datatype

400

Input data is not valid

[Boolean]

200

Returns true if everything is okt

[Boolean]

403

Forbidden. Please use correct private key.

[Boolean]

Samples

5.4.4. priceUpdate

PUT /api/private/v1.0/prices/

Update a price for event

Description

Binds a price to event

Parameters
Body Parameter
Name Description Required Default Pattern

Price

Price

X

Return Type
Content Type
  • application/json

Responses
Table 14. http response codes
Code Message Datatype

200

Returns updated object

Price

400

Input data is not valid

Price

403

Forbidden. Please use correct private key.

Price

Samples

5.5. PublicEventController

5.5.1. getEventPrices

GET /api/public/v1.0/event/prices/

Description
Parameters
Query Parameters
Name Description Required Default Pattern

id

X

null

publicKey

X

null

Return Type
Content Type
  • /

Responses
Table 15. http response codes
Code Message Datatype

200

OK

PriceList

Samples

5.5.2. getEventSeatmap

GET /api/public/v1.0/event/

Description
Parameters
Query Parameters
Name Description Required Default Pattern

id

X

null

publicKey

X

null

Return Type
Content Type
  • /

Responses
Table 16. http response codes
Code Message Datatype

200

OK

Seatmap

Samples

5.5.3. getSchemaSeatmap1

GET /api/public/v1.0/event/schema/

Description
Parameters
Query Parameters
Name Description Required Default Pattern

id

X

null

publicKey

X

null

Return Type
Content Type
  • /

Responses
Table 17. http response codes
Code Message Datatype

200

OK

Seatmap

Samples

5.6. PublicVenueController

5.6.1. getSchemaSeatmap

GET /api/public/v1.0/venue/schema/

Description
Parameters
Query Parameters
Name Description Required Default Pattern

id

X

null

publicKey

X

null

Return Type
Content Type
  • /

Responses
Table 18. http response codes
Code Message Datatype

200

OK

VenueForWidget

Samples

5.6.2. getSchemaSeatmapList

GET /api/public/v1.0/venue/

Description
Parameters
Query Parameters
Name Description Required Default Pattern

publicKey

X

null

Return Type
Content Type
  • /

Responses
Table 19. http response codes
Code Message Datatype

200

OK

List[VenueForWidget]

Samples

5.7. Venues

5.7.1. schemaAll

GET /api/private/v1.0/venues/schemas/

Retrieve list of all schemas

Description

Getting all the schemas with paging

Parameters
Query Parameters
Name Description Required Default Pattern

limit

Quantity of requested items

-

50

offset

Offset for the pager

-

0

venueId

Venue id

-

null

lastUpdated

Schemas updated after this date will be retrieved.

-

null

Return Type

array[Schema]

Content Type
  • /

Responses
Table 20. http response codes
Code Message Datatype

400

Input data is not valid

List[Schema]

200

Returns list of schemas

List[Schema]

403

Forbidden. Please use correct private key.

List[Schema]

Samples

5.7.2. schemaDetails

GET /api/private/v1.0/venues/schemas/{schemaId}/details/

Retrieve schema’s details

Description

Getting schema’s details

Parameters
Path Parameters
Name Description Required Default Pattern

schemaId

X

null

Return Type
Content Type
  • /

Responses
Table 21. http response codes
Code Message Datatype

400

Input data is not valid

Schema

403

Forbidden. Please use correct private key.

Schema

200

Returns schema's details

Schema

Samples

5.7.5. venueAll

GET /api/private/v1.0/venues/

Retrieve list of all venues

Description

Getting all the venues with paging

Parameters
Query Parameters
Name Description Required Default Pattern

limit

Quantity of requested items

-

50

offset

Offset for the pager

-

0

Return Type

array[Venue]

Content Type
  • /

Responses
Table 24. http response codes
Code Message Datatype

400

Input data is not valid

List[Venue]

200

Returns list of objects

List[Venue]

403

Forbidden. Please use correct private key.

List[Venue]

Samples

5.7.6. venueById

GET /api/private/v1.0/venues/{venueId}

Retrieves a specific venue by id

Description

Getting venue by Id

Parameters
Path Parameters
Name Description Required Default Pattern

venueId

X

null

Return Type
Content Type
  • /

Responses
Table 25. http response codes
Code Message Datatype

400

Input data is not valid

Venue

200

Returns list of objects

Venue

403

Forbidden. Please use correct private key.

Venue

Samples

6. Models

6.1. Event

Valid event object without id field

Field Name Required Type Description Format

id

UUID

uuid

start

X

Date

date-time

killAfter

Date

date-time

name

X

String

schemaId

X

Long

int64

6.2. EventMetadata

Contains list of sections

6.3. PlainSeats

Field Name Required Type Description Format

names

List of [string]

ids

List of [long]

int64

x

List of [integer]

int32

y

List of [integer]

int32

rowIds

List of [long]

int64

sectorIds

List of [long]

int64

6.4. Price

Field Name Required Type Description Format

id

Long

int64

name

X

String

eventId

X

UUID

uuid

6.5. PriceAssignment

Field Name Required Type Description Format

capacity

Integer

int32

compositeKey

X

String

price

X

Integer

int32

properties

Object

6.6. PriceList

Field Name Required Type Description Format

seats

List of [array]

groupOfSeats

List of [array]

prices

List of Price

6.7. Row

Field Name Required Type Description Format

id

Long

int64

name

X

String

seatName

String

rowNumber

String

sectorId

Long

int64

6.8. RowMetadata List of rows

6.9. Schema

Field Name Required Type Description Format

id

Long

int64

capacity

Integer

int32

name

String

venueId

Long

int64

eventId

UUID

uuid

6.10. SeatMetadata Array of SeatMetadata

6.11. Seatmap

Field Name Required Type Description Format

rows

List of Row

sectors

List of Sector

plainSeats

PlainSeats

background

Object

6.12. Sector

Field Name Required Type Description Format

id

Long

int64

isGa

Boolean

name

X

String

x

BigDecimal

y

BigDecimal

guid

UUID

uuid

angle

Integer

int32

type

String

6.13. SectorMetadata List of sections metadata

6.14. SectorWithCoords

Field Name Required Type Description Format

id

Long

int64

isGa

Boolean

name

X

String

x

BigDecimal

y

BigDecimal

guid

UUID

uuid

left

BigDecimal

top

BigDecimal

angle

Integer

int32

width

BigDecimal

height

BigDecimal

6.15. Selection

Field Name Required Type Description Format

capacity

Integer

int32

compositeKey

X

String

6.16. Venue

Field Name Required Type Description Format

id

Long

int64

name

String

address

String

lat

Double

double

lng

Double

double

6.17. VenueForWidget

Field Name Required Type Description Format

guid

UUID

uuid

name

String

gaCapacity

Integer

int32

seatsCapacity

Integer

int32

seatmap

Seatmap

7. Renderer Resources

7.1. Class: SeatmapBookingRenderer

7.1.1. Hierarchy

  • Renderer

    SeatmapBookingRenderer

7.1.3. Constructors

constructor
  • new SeatmapBookingRenderer(element, settings?)

Creates the booking renderer.

Parameters
Name Type Description

element

HTMLElement

DOM element that will be a host element for the Renderer

settings?

IBookingRendererSettings

Renderer settings

Overrides

Renderer.constructor

7.1.4. Methods

addGaToCart

addGaToCart(ga): void

Adds GA seats to cart programmatically.

Parameters
Name Type Description

ga

ICartGa

GA cart item

Returns

void

Remarks

This method can be used when onSectorClick was fired and developer wants to handle custom add/remove GA seats control. You can add desired quantity of GA tickets to the cart.

Example

renderer.addGaToCart({
  id: 100500,
  key: 'Table 2',
  price: 200,
  // quantity of GA tickets
  count: 3
});
Inherited from

Renderer.addGaToCart


addSeatsToCart

addSeatsToCart(seats): void

Adds seats to cart programmatically.

Parameters
Name Type Description

seats

ICartSeat[]

Array of seats to add

Returns

void

Remarks

This method is optional. In a common scenario the user adds available seats by clicking on them.

Example

renderer.addSeatsToCart([
  {
    id: 803,
    key: 'Section 3;;3;;1',
    price: 500
  }
]);
Inherited from

Renderer.addSeatsToCart


clearCart

clearCart(): void

Clears the internal cart state.

Returns

void

Inherited from

Renderer.clearCart


destroy

destroy(): void

Returns

void

Inherited from

Renderer.destroy


disableSeatsByIds

disableSeatsByIds(ids): void

Marks seats as unavailable and removes them from cart.

Parameters
Name Type Description

ids

number[]

Array of internal seat IDs

Returns

void

Inherited from

Renderer.disableSeatsByIds


disableSeatsByKeys

disableSeatsByKeys(keys): void

Marks seats as unavailable and removes them from cart.

Parameters
Name Type Description

keys

string[]

Array of composite seat keys

Returns

void

Inherited from

Renderer.disableSeatsByKeys


getCart

getCart(): ICart

Retrieves the internal cart state.

Returns

ICart

Returns selected seats and GA ticket count

Remarks

Seatmap.pro doesn’t support any session mechanisms. Cart is always should be stored on the ticketing system side. For the state management reasons, the Renderer has internal selected seat representation.

Example

Example of cart object:

var cart = {
  seats: [
    { id: 1389563, key: 'Section 1;;5;;14', price: 100 },
    { key: 'Table 3;;1;;1', price: 500 },
    { key: 'Section 2;;5;;1', price: 200 }
  ],
  ga: [
    {
      id: 100500,
      key: 'Table 2',
      price: 200,
      count: 1
    },
    { key: 'Section 5', price: 100, count: 2 }
  ]
};
Inherited from

Renderer.getCart


getCategoryColor

getCategoryColor(category): undefined | string

Returns category’s color

Parameters
Name Type Description

category

number

Category number

Returns

undefined | string

Inherited from

Renderer.getCategoryColor


getHeight

getHeight(): number

Returns

number

Inherited from

Renderer.getHeight


getMaxZoom

getMaxZoom(): number

Returns the maximum zoom preset value.

Returns

number

Inherited from

Renderer.getMaxZoom


getMinZoom

getMinZoom(): number

Returns the minimal zoom preset value.

Returns

number

Inherited from

Renderer.getMinZoom


getMode

getMode(): undefined | string

Returns

undefined | string

Inherited from

Renderer.getMode


getPrices

getPrices(): IColoredPrice[]

Retrieves the available prices.

Returns

IColoredPrice[]

Array of available prices

Example

Example of return value:

[
  { id: 63, name: '100', color: '#9C27B0' },
  { id: 64, name: '200', color: '#2196F3' }
];
Inherited from

Renderer.getPrices


getSeatIds

getSeatIds(seats): number[]

Parameters
Name Type

seats

number[] | string[] | ISeat[]

Returns

number[]

Inherited from

Renderer.getSeatIds


getSeatSelection

getSeatSelection(): IExtendedSeat[]

Returns selected seats

Returns

IExtendedSeat[]

Inherited from

Renderer.getSeatSelection


getSections

getSections(): ISector[]

Returns sections info

Returns

ISector[]

Inherited from

Renderer.getSections


getSectionsWithCoords

getSectionsWithCoords(): { ga: boolean ; id?: number ; name: string ; price?: number ; rect: ISectionRect ; special?: ISpecialState ; type?: string ; x: number ; y: number }[]

Returns

{ ga: boolean ; id?: number ; name: string ; price?: number ; rect: ISectionRect ; special?: ISpecialState ; type?: string ; x: number ; y: number }[]

Inherited from

Renderer.getSectionsWithCoords


getSelectedGa

getSelectedGa(): undefined | ISector

Returns

undefined | ISector

Inherited from

Renderer.getSelectedGa


getVisibleSeats

getVisibleSeats(): ISeat[]

Returns only visible seats with coords relative to canvas

Returns

ISeat[]

Inherited from

Renderer.getVisibleSeats


getWidth

getWidth(): number

Returns

number

Inherited from

Renderer.getWidth


getZoom

getZoom(): number

Returns current zoom value.

Returns

number

Inherited from

Renderer.getZoom


initCart

initCart(cart): void

Initializes the internal cart state.

Parameters
Name Type Description

cart

ICart

Cart state

Returns

void

Remarks

In a case of page reload you should initialize the saved state with this method.

Cart initialization is available right after component initialization.

Sales page must save the cart state in the given format to support the page reload feature.

Example

var cart = {
  seats: [
    {
      id: 1389563,
      key: 'Section 1;;5;;14',
      price: 100
    },
    { key: 'Table 3;;1;;1', price: 500 },
    { key: 'Section 2;;5;;1', price: 200 }
  ],
  ga: [
    {
      id: 100500,
      key: 'Table 2',
      price: 200,
      count: 1
    },
    { key: 'Section 5', price: 100, count: 2 }
  ]
};

renderer.initCart(cart);
Inherited from

Renderer.initCart


loadEvent

loadEvent(eventId, sectorId?): Promise<void>

Loads event’s schema and prices.

Parameters
Name Type Description

eventId

string

Event GUID

sectorId?

number

You can specify sector ID to show only specific sector

Returns

Promise<void>

Resolves when the data fetching is completed

Example

var eventId = 'a4a75361-7823-4847-bf22-336843022e80';
renderer.loadEvent(eventId).then(function() {
  renderer.initCart(cart);
});

removeSeatsFromCartByIds

removeSeatsFromCartByIds(ids): void

Removes seats from internal cart.

Parameters
Name Type Description

ids

number[]

Array of internal seat IDs

Returns

void

Inherited from

Renderer.removeSeatsFromCartByIds


removeSeatsFromCartByKeys

removeSeatsFromCartByKeys(keys): void

Removes seats from internal cart.

Parameters
Name Type Description

keys

string[]

Array of composite seat keys

Returns

void

Inherited from

Renderer.removeSeatsFromCartByKeys


resetCategories

resetCategories(): void

Returns

void

Inherited from

Renderer.resetCategories


seatKeysToIds

seatKeysToIds(keys): number[]

Convert array of seat keys to array of seat ids

Parameters
Name Type Description

keys

string[]

Array of composite seat keys

Returns

number[]

Inherited from

Renderer.seatKeysToIds


seatToExtendedSeat

seatToExtendedSeat(seat): IExtendedSeat

Parameters
Name Type

seat

ISeat

Returns

IExtendedSeat

Inherited from

Renderer.seatToExtendedSeat


setGaCategory

setGaCategory(sectionId, category): void

Parameters
Name Type

sectionId

number

category

undefined | number

Returns

void

Inherited from

Renderer.setGaCategory


setGroupSize

setGroupSize(groupSize): void

Parameters
Name Type

groupSize

number

Returns

void

Inherited from

Renderer.setGroupSize


setHeight

setHeight(height): void

Parameters
Name Type

height

number

Returns

void

Inherited from

Renderer.setHeight


setMode

setMode(mode): void

Parameters
Name Type

mode

string

Returns

void

Inherited from

Renderer.setMode


setSeatSelection

setSeatSelection(seats): void

Parameters
Name Type

seats

number[] | string[] | ISeat[]

Returns

void

Inherited from

Renderer.setSeatSelection


setSeatsCategory

setSeatsCategory(seats, category): void

Parameters
Name Type

seats

number[] | string[] | ISeat[]

category

number

Returns

void

Inherited from

Renderer.setSeatsCategory


setSelectedGa

setSelectedGa(ga?): void

Parameters
Name Type

ga?

string | number

Returns

void

Inherited from

Renderer.setSelectedGa


updateSeatLocks

updateSeatLocks(filter): void

Updates seat lock states.

Parameters
Name Type Description

filter

SeatFilter

Function should return true for seats to lock

Returns

void

Example

For example, you can create handler to prevent selection of seats with different special state:

const handleCartChange = (cart, prevCart) => {
  if (!cart.seats.length) {
    // Unlock all the seats if the cart is empty
    renderer.updateSeatLocks(s => false);
  } else if (!prevCart || !prevCart.seats.length) {
    // Lock seats with different special state
    const seat = cart.seats[0];
    renderer.updateSeatLocks(
      s => (s.special && s.special.s1) !== (seat.special && seat.special.s1)
    );
  }
};
Inherited from

Renderer.updateSeatLocks


zoomIn

zoomIn(): void

Returns

void

Inherited from

Renderer.zoomIn


zoomOut

zoomOut(): void

Returns

void

Inherited from

Renderer.zoomOut


zoomToFit

zoomToFit(): void

Returns

void

Inherited from

Renderer.zoomToFit

7.2. Interface: IBookingRendererSettings

7.2.1. Hierarchy

  • IRendererSettings

    IBookingRendererSettings

7.2.3. Properties

debounceDelay
  • Optional debounceDelay: number

Inherited from

IRendererSettings.debounceDelay


env
  • Optional env: string

Environment (prod/stage)


groupSize
  • Optional groupSize: number

Inherited from

IRendererSettings.groupSize


height
  • Optional height: number

Inherited from

IRendererSettings.height


lockedSeatsFilter
  • Optional lockedSeatsFilter: (seat: ISeat) => boolean

Type declaration

▸ (seat): boolean

Parameters
Name Type

seat

ISeat

Returns

boolean

Inherited from

IRendererSettings.lockedSeatsFilter


onBeforeSeatDraw
  • Optional onBeforeSeatDraw: (event: IBeforeSeatDrawEvent) => ISeatStyle

Type declaration

▸ (event): ISeatStyle

You can control seats' styling by returning custom style for each seat

Parameters
Name Type

event

IBeforeSeatDrawEvent

Returns

ISeatStyle

Inherited from

IRendererSettings.onBeforeSeatDraw


onCartChange
  • Optional onCartChange: (cart: ICart, prevCart?: ICart) => void

Type declaration

▸ (cart, prevCart?): void

Fires when the cart was modified.

Parameters
Name Type

cart

ICart

prevCart?

ICart

Returns

void

Remarks

Cart state is passed as a param to the handler (see ICart).

Inherited from

IRendererSettings.onCartChange


onPan
  • Optional onPan: (delta: IPoint, isFinish?: boolean) => void

Type declaration

▸ (delta, isFinish?): void

Fires while panning.

Parameters
Name Type

delta

IPoint

isFinish?

boolean

Returns

void

Inherited from

IRendererSettings.onPan


onRedrawEnd
  • Optional onRedrawEnd: () => void

Type declaration

▸ (): void

Fires when component full redrawing ends.

Returns

void

Inherited from

IRendererSettings.onRedrawEnd


onRedrawStart
  • Optional onRedrawStart: () => void

Type declaration

▸ (): void

Fires when component full redrawing starts.

Returns

void

Inherited from

IRendererSettings.onRedrawStart


onSeatDebouncedEnter
  • Optional onSeatDebouncedEnter: (seat: IExtendedSeat) => void

Type declaration

▸ (seat): void

Same as onSeatMouseEnter but with debounce.

Parameters
Name Type

seat

IExtendedSeat

Returns

void

Remarks

Seat is passed as a param to the handler (see IExtendedSeat).

Inherited from

IRendererSettings.onSeatDebouncedEnter


onSeatDeselect
  • Optional onSeatDeselect: (seat: IExtendedSeat) => boolean | void | Promise<boolean | void>

Type declaration

▸ (seat): boolean | void | Promise<boolean | void>

Fires when the user deselects a seat.

Parameters
Name Type

seat

IExtendedSeat

Returns

boolean | void | Promise<boolean | void>

Remarks

Seat is passed as a param to the handler (see IExtendedSeat).

To cancel seat deselection you can return false or Promise resolving to false.

Inherited from

IRendererSettings.onSeatDeselect


onSeatMouseEnter
  • Optional onSeatMouseEnter: (seat: IExtendedSeat) => void

Type declaration

▸ (seat): void

Rises when the mouse pointer moves above a seat.

Parameters
Name Type

seat

IExtendedSeat

Returns

void

Remarks

Seat is passed as a param to the handler (see IExtendedSeat).

Inherited from

IRendererSettings.onSeatMouseEnter


onSeatMouseLeave
  • Optional onSeatMouseLeave: () => void

Type declaration

▸ (): void

Fires when the mouse pointer leaves a seat.

Returns

void

Inherited from

IRendererSettings.onSeatMouseLeave


onSeatSelect
  • Optional onSeatSelect: (seat: IExtendedSeat) => boolean | void | Promise<boolean | void>

Type declaration

▸ (seat): boolean | void | Promise<boolean | void>

Fires when the user marks a seat as selected.

Parameters
Name Type

seat

IExtendedSeat

Returns

boolean | void | Promise<boolean | void>

Remarks

Seat is passed as a param to the handler (see IExtendedSeat).

To cancel seat selection you can return false or Promise resolving to false.

Inherited from

IRendererSettings.onSeatSelect


onSeatSelectionChange
  • Optional onSeatSelectionChange: () => void

Type declaration

▸ (): void

Fires after seat selection was updated.

Returns

void

Inherited from

IRendererSettings.onSeatSelectionChange


onSectionClick
  • Optional onSectionClick: (section: ISection) => void

Type declaration

▸ (section): void

Fires when the user clicks on a section.

Parameters
Name Type

section

ISection

Returns

void

Remarks

Section is passed as a param to the handler (see ISection).

Inherited from

IRendererSettings.onSectionClick


onSectorClick
  • Optional onSectorClick: (section: ISection) => void

Type declaration

▸ (section): void

Fires when the user clicks on a section.

Parameters
Name Type

section

ISection

Returns

void

Deprecated

Use onSectionClick instead

Inherited from

IRendererSettings.onSectorClick


onSectorMouseEnter
  • Optional onSectorMouseEnter: (section: ISection) => void

Type declaration

▸ (section): void

Fires when the mouse pointer moves above a section.

Parameters
Name Type

section

ISection

Returns

void

Remarks

Section is passed as a param to the handler (see ISection).

Inherited from

IRendererSettings.onSectorMouseEnter


onSectorMouseLeave
  • Optional onSectorMouseLeave: () => void

Type declaration

▸ (): void

Fires when the mouse pointer leaves a section.

Returns

void

Inherited from

IRendererSettings.onSectorMouseLeave


onZoomEnd
  • Optional onZoomEnd: (newZoom: number, oldZoom?: number) => void

Type declaration

▸ (newZoom, oldZoom?): void

Fires after the zoom animation ended.

Parameters
Name Type

newZoom

number

oldZoom?

number

Returns

void

Inherited from

IRendererSettings.onZoomEnd


onZoomStart
  • Optional onZoomStart: (newZoom: number, oldZoom: number) => void

Type declaration

▸ (newZoom, oldZoom): void

Fires before the zoom animation started.

Parameters
Name Type

newZoom

number

oldZoom

number

Returns

void

Inherited from

IRendererSettings.onZoomStart


padding
  • Optional padding: number

Inherited from

IRendererSettings.padding


publicKey
  • Optional publicKey: string

Public API key


seatSelectionMinZoom
  • Optional seatSelectionMinZoom: number

Inherited from

IRendererSettings.seatSelectionMinZoom


selectionLimit
  • Optional selectionLimit: number

Inherited from

IRendererSettings.selectionLimit


theme
  • Optional theme: IRendererTheme

Inherited from

IRendererSettings.theme


zoomAnimationDuration
  • Optional zoomAnimationDuration: number

Inherited from

IRendererSettings.zoomAnimationDuration

8. API Licensing Agreement

This Customer Agreement (hereinafter – the "Agreement") sets out the terms and conditions of using the Seatmap.pro website (hereinafter "Terms of Use"), accessible at https://seatmap.pro (hereinafter, the "Website"). Before using the Website, the natural person (hereinafter "Customer") must read, agree with and accept these Terms of Use. If the Customer doesn’t accept the terms of this Agreement and shall not accept to be bound by all the terms of this Agreement, they should stop using the Website immediately.

This API licensing agreement (hereinafter referred to as the "Agreement") defines the access rights of the Customer (hereinafter referred to as "Licensee") over APIs, data and documentation provided and licensed by Seatmap.pro. By using Seatmap.pro APIs, the Customer is under obligaton to comply with the terms of the Agreement. If the Customer does not agree with the terms of the Agreement, they can not use APIs.

APIs are protected by copyright and international copyright agreements, as well as other intellectual property laws.

8.1. General provisions

  1. An "application programming interface" or "API" is a set of libraries, tools, sample source codes, published specifications and documentation developed by Seatmap.pro. At its own discretion, Seatmap.pro may provide updates or API additions for Licensees.

  2. The documentation includes (but is not limited to) the programmer’s manual, materials and other information needed for the use of APIs.

8.2. Licensing

  1. Under the terms of this Agreement, Seatmap.pro grants the Licensee a limited, non-exclusive, non-transferable license (without the right to sublicense) to use APIs solely for the Licensee’s personal use (for the development of apps to work with Seatmap.pro products).
    The Licensee may not distribute, license, or otherwise transfer APIs to third parties.

8.3. Other Rights and Restrictions

  1. The Licensee may copy the APIs only for use under the terms of this Agreement.

  2. Reverse engineering. The Licensee has no rights over the API source code except for the rights expressly granted to the Licensee by this Agreement. The Licensee is not entitled to process, decompile, modify, or disassemble APIs, or otherwise bring the APIs to a generally accepted form of submission, in whole or in part, except as expressly permitted by this Agreement or applicable law.

  3. For the efficient use of API, additional development tools such as a compiler or other software (“Third-Party Software”) may be required. Licensee bears full responsibility for the purchase of this software and the necessary licenses. Seatmap.pro is not under any obligation and makes no warranties regarding the use of third-party software by the Licensee.

  4. The Licensee is not entitled to sublicense their rights under this Agreement, except for the cases expressly provided in this Agreement. The Licensee may not use Seatmap.pro trademarks or trade names. Seatmap.pro reserves all rights not expressly granted herein.

  5. The Licensee cannot obtain patent rights to APIs or applications developed using the Seatmap.pro API or APIs of other Seatmap.pro API licensees to create, use or sell any products or technologies.

8.4. Property

  1. Seatmap.pro shall reserve the property rights, including all rights to patents, copyrights, trade secrets, trademark and other intellectual property rights to APIs and any changes thereto. Seatmap.pro has exclusive right to register any patents and copyrights. The Licensee recognizes that under this Agreement the Licensee does not have property rights over APIs, only the right to limited use under the terms of this Agreement.

8.5. Support

  1. Seatmap.pro Customer Support does not provide technical support for the APIs under the terms of this Agreement and does not provide updates, bug fixes or API changes.

8.6. Confidentiality

  1. APIs contain valuable information about the company and commercial secrets belonging to Seatmap.pro. These remain the property of Seatmap.pro. Licensees are required to avoid disclosing this information and avoid unauthorized use of APIs.

  2. The Licensee shall not disclose, advertise or publish the terms of this Agreement without the prior written consent of Seatmap.pro. Any press release or publication relevant to this Agreement is subject to prior review and written approval by Seatmap.pro.

8.7. No warranty

  1. APIs and documentation are provided "as is" without warranty of any kind. Seatmap.pro does not warrant that APIs and documentation are suitable for use by Licensee and free of defects or errors. In addition, Seatmap.pro does not guarantee continuous and uninterrupted access to APIs and documentation and makes no warranties or representations regarding the results of their use.

8.8. Limitation of Liability

  1. The Licensee is fully liable for any damage to their computer system or loss of data resulting from the download or use of APIs. Seatmap.pro shall not be liable for any special, incidental, consequential damages (including, but not limited to, loss of profits, suspension or termination of work, failure or breakdown of the computer, loss of information or any other damages, including financial damages, arising from the use of or inability to use APIs or the provision or lack of provision of support services), even if Seatmap.pro has been notified of the possibility of such damage.

8.9. Indemnity

  1. Licensee shall not hold Seatmap.pro, its customers, suppliers or other partners and employees liable for any losses, claims or demands, reasonable legal fees arising from the use of APIs.

8.10. Term and Termination of the Agreement

  1. In the event that the Licensee fails to comply with any of the terms of this Agreement, they will be held liable to Seatmap.pro for any loss or damage arising from the breach of terms.

  2. Upon termination of this Agreement, the Licensee shall immediately terminate the use of APIs, delete all copies of APIs and documentation or return them to Seatmap.pro.

  3. Seatmap.pro shall be entitled to verify compliance of the Licensee with the terms of the Agreement. The Licensee, at the request of Seatmap.pro, is obliged to facilitate this.

8.11. Miscellaneous

  1. Violation or failure to comply with the terms of this Agreement shall result in its termination.

  2. Seatmap.pro shall be entitled to suspend (or terminate), at its own discretion and without notice, the Licensee’s access to the Service in the event that the terms of the Agreement are violated.

  3. By installing, copying or otherwise using Seatmap.pro APIs, the Licensee acknowledges that that they have read, understood and agree to the conditions specified above.

9. Contact us

For any questions please mail us hello@seatmap.pro