Integration guide

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.

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)

Components

Seatmap.pro contains the following components and services:

Seatmap Editor

Seating maps editor. Allows creating, editing, and managing 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
Note
 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.

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.

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

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.

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

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.

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.

Note
 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

Important
 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.

Assign Prices

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

Note
 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.

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.

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.

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

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

Renderer Methods

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);
});

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

Clear Cart

clearCart()

Eliminate all the elements from the cart.

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);
Caution
 Sales page must save the cart state in the given format to support the page reload feature

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' }
 ];

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

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

Disable Seats by IDs

disableSeatsByIds(seatIds: number[])

Marks seats as unavailable using internal identifiers

Disable Seats by Keys

disableSeatsByKeys(keys: string[])

Marks seats as unavailable using Composite Key

Zooming

zoomIn() / zoomOut() / zoomToFit()

Zoom operations

Getting Zoom level

getZoom() => number

Returns the current zoom level

API

API V1.0

API V2.0

Renderer Resources

Unresolved directive in <stdin> - include::content/integration/renderer/booking-renderer.adoc[]

Unresolved directive in <stdin> - include::content/integrationicense.adoc[]

Contact us

For any questions please mail us hello@seatmap.pro