Webbintegrationer

All vår dokumentation om API:er och integrationer hålls på engelska för att säkerställa korrekt innehåll och etablerad terminologi

The Tixly ticketing system is used in combination with a website from the venue. This article describes the possibilities and best approach to integrate the venue website and Tixly.

There are multiple methods to do this, from simple manual links to a fully automated setup.

• Manual links
• Automated setup
  • Webhook
  • User login status and basket information
  • Data in the session information
  • Using personalised information to give pre-sale access and different ticket types to some customers
• Skins

Manual links

It is possible to use direct links to the production, event or subscription sales pages and place these on your website by hand. These links can be found in the Box Office sales screens in Tixly and also on the Internet tab of the event edit screens. Of Course, this depends on the cms how this is done.

1. Link to a production

   1. https://tix.theatreexample.com/en/buyingflow/tickets/1290/

2. Link to an event in this production

   1. https://tix.theatreexample.com/en/buyingflow/tickets/1290/18417/

3. Link to an subscription

   1. https://tix.uk/en/theatreexample/buyingflow/subscription/15/

The first two examples show a Tixly setup on the subdomain of the venue, the last one uses the Tixly domain. 

Automated setup

The website database holds the events or subscriptions with all information that the venue wants to publish on their website. There can be a calendar page, a page per production.

A common approach is to have a setup that does the following:

• The website periodically imports all future events into their database with help of the Tixly Event API.
  This ensures that the event information from Tixly is present in the website database.
  • add new events to the local database
  • update existing events 
  • mark the local events the are not in the output anymore as deleted. 
• The more information is used the better, the PurchaseURL's, OnlineSaleStart, OnlineSaleEnd and SaleStatus are probably needed.
• The CMS is used to add more information, videos, reviews etc to the event groups (productions) or to individual event dates.
• The website publishes the event. From now it is visible to the visitors. A [buy tickets] button is shown with the Purchase url when the current date is between OnlineSaleStart and OnlineSaleEnd

When the user clicks on [buy tickets] the Tixly flow is opened in the same browser window. A reasonable interval for the import in step 1 depends on the situation, once every hour is reasonable.

You can add minimized=  true to the event api url to get an output with the minimal version, this only has SaleStatus. You can use this to sync the status more frequently, and build a lighter script the does not need to check if other properties of events are changed. 

Webhook

It seems a bit of a waste to do the import very often, when most of the time nothing has changed. But on the other hand, you don't want to wait 2 hours for a change in Tixly to be visible on your website. This is when you can use the webhook functionality to solve this.

Tixly will call a url on your website, the webhook url, every time in Tixly a change to an event has been made. As a response to the webhook request your website can start an import job.

There is no information in the webhook on what event has been changed and Tixly does no do anything with the data the webhook may return.

Valid webhook url examples are:

https://www.theaterxyx.nl/import/trigger
https://username:[email protected]/admin/tix-importer.php

Pro tip: The webhook is called whenever something changes. If the venue staff is editing prices, genres etc. this can result in your webhook being called several times a minute. And then for hours, when nothing changes it is not called at all.

Instead of running your import routine every time the webhook is called, it is better to wait a minute or two, and if no more webhook calls have been made during this period, then do the import.

To start using this, contact Tixly support and give them your website webhook url and we configure this to be used.

User login status and basket information

Important: Due to restrictions of most browsers, your Tixly instance needs to be on a subdomain of your venue website. e.g. tix.venuewebsite.se  That means this session sharing feature only works on what we call hosted skins.

It is possible to show on the venue website that a user is logged into Tixly and if they have a basket. Also the basket contents can be shown on the website. Like this example:

This is achieved by sharing session data from Tixly to the website. The website then uses this data to show it in the design they want. The sharing works by opening an iframe to the Tixly website with the integration url on the correct skin. This iframe should be hidden on the venue webpage and does not show anything. It is just used to have javascript from the event/postmessage framework to communicate between the opener page on the venue site and the iframe from Tixly.

The post messaging is limited by the settings on the skin, to only allow some websites to post messages and receive data from (see Skin settings). Multiple websites can be configured, this allows development and staging servers of the venue site to use the same skin as the production website.

The url of the URL to Iframe, itix (short for integration tix) file is;

{skin url}/{language}/itix

Example:

https://tix.theateraandeparade.nl/nl/itix

This url is best to be requested in an iframe .

The postMessage 'GetSession' should be issued to the iframe.

An EventListener is used to act on the return message with the session information. Looking at implementations of other tixly customers can help to understand this. The Brussels based venue La Monnaie / De Munt has an easy to understand setup.

Data in the session information

Below is an example of the json structure of the postmessage response. This shows an order with two tickets and the user.

{
    "order": {
        "items": [{
                "type": "Ticket",
                "name": "An evening with Q on stage",
                "details": "13-3-2022 20:00:00",
                "price": 12.0000
            },
            {
                "type": "Ticket",
                "name": "An evening with Q on stage",
                "details": "13-3-2022 20:00:00",
                "price": 12.0000
            }
        ],
        "expires": 896.0954898,
        "url": "https://tix.theaterexample.nl/nl/buyingflow/purchase/"
    },
    "user": {
        "id": 544803,
        "name": "James Bond",
        "email": "[email protected]",
        "hash": "2ac9f3a26521d0194530daf3e68c88589d4490617059793dd2eba1b14b786b84"
        "tags": [{
            "id": 7,
            "name": "Premium",
            "abbr": "PP"
        }]
    },
    "profile": "https://tix.theaterexample.nl/nl/profile/"
}

Details of the properties in the object that is being sent are as follows:

1. order

   1. Object that is null if no order is currently in the user session

2. order->items

   1. A list of all items in the order

3. order->items->type

   1. Type of item. Can be Ticket, Subscription, GiftCard, Membership, Donation, or Product.
   2. Note: Subscription is a ticket that is part of a subscription package.

4. order->items->name

   1. Name of the item, varies for each type:
      • Ticket > Name of event
      • Subscription > Name of subscription package
      • GiftCard > Name of gift card group
      • Product > Name of product

5. order->items->details

   1. Details for each type:
      • Ticket > Event’s start date
      • Subscription > Event’s name and start date
      • GiftCard > Amount of the gift card formatted as an invariant string “20.00”
      • Product > No details given on products

6. order->items->price

   1. Price of the item as an invariant decimal (0.00)

7. order->expires

   1. Decimal seconds and milliseconds until the order expires from the moment the session info was requested.

8. order->url

   1. A URL that takes you to the purchase page for the order.

9. user

   1. Object is null if the user is not logged in on this session

10. user->id

    1. Id of the web user. Note: this is not the customer id.
    2. In the CRM API, there is an endpoint to get the customer Id from the web user Id.
    3. CRM API: POST /WebUser/{webUserId}/customer

11. user->name

    1. Full name of the logged-in user (can be empty)

12. user->email

    1. Email of the logged-in web user (in rare cases, this can differ from the customer's email)

13. user->hash

    1. With this hash, the website can validate if the web user id is valid.
    2. A secret must be added in the skin settings by a Tixly admin. The hash is computed as a SHA256 over the web user Id + skin secret.
    3. Example:
       • web user id: 544803
       • secret: uXL9aHWX3pumEEZsjU!U
       • The hash will be SHA256(544803uXL9aHWX3pumEEZsjU!U) resulting in: 2ac9f3a26521d0194530daf3e68c88589d4490617059793dd2eba1b14b786b84

14. user->tags

    1. A list of “Customer Tags” that the user is connected to, which can be matched with “tags” on events to see which benefits the logged-in user can access.

15. user->tags->id

    1. Id of the tag

16. user->tags->name

    1. Name of the tag

17. user->tags->abbr

    1. Abbreviation of the tag, not guaranteed to be unique and can be chosen by venue admins

18. profile

    1. A URL that takes you to the user's profile page, or to the login page if not logged in.

Note: delivery fees are not in the session information.

Using personalised information to give pre-sale access and different ticket types to some customers

With the session information on the customer, in combination with the benefits in the Tixly Event API, the website is able to show personalised information to the customers.

For example if a VIP customer is logged in they can see their VIP prices, normal customers don't see these. Or you can show the [buy tickets] button earlier to your members, with this they can buy before the general public is able to do so (pre sale).

The method used here is the Tixly event API containing all the normal sales dates and prices, but also the possible benefits the customers with certain customer tags can utilise.

And example of an object list of benefits;

{
    "Benefits": [{
            "CustomerTag": {
                "CustomerTagId": 8,
                "Name": "Student",
                "Abbreviation": "ST"
            },
            "Prices": [{
                "TicketType": "Student",
                "Translations": [],
                "Prices": [{
                    "PriceZone": "1",
                    "Price": 8.5
                }]
            }]
        },
        {
            "CustomerTag": {
                "CustomerTagId": 16,
                "Name": "Friend",
                "Abbreviation": "FR"
            },
            "OnlineSaleStart": "2021-06-10T13:00:00",
            "OnlineSaleStartUTCUnix": 1620039600,
            "Prices": [{
                "TicketType": "Friends",
                "Translations": [],
                "Prices": [{"PriceZone": "Rang 1","Price": 15},
                           { "PriceZone": "Rang 2", "Price": 10}],
                "ActiveFrom": "2021-06-12T08:00:00+02:00",
                "ActiveFromUTCUnix": 1623477600,
                "ActiveTo": "2021-7-12T22:00:00+02:00",
                "ActiveToUTCUnix": 1626069600,
                "TicketCount": "0-2"
            }],
        },
    ]
}

Here you can see that Customers with the tag Student get to buy tickets for TicketType Student for a price of 8.5.

For customers who are Friend there is an alternative, earlier, OnlineSaleStart and also an extra TicketType Friends, that is only available during a limited time period and for a max of 2 tickets.

All the benefit data should be stored in the database of the website, so they are available to use in the web front-end.

The webpage by default shows an event with the prices visible in the template, the other Benefits prices are in hidden elements. Then when the website gets a user object in the session information from Tixly. The user > tags > id can be used to display the benefit prices, the ones with the corresponding CustomerTagId. 

The same goes for the buy tickets button. The default information is used to display the initial state of the button. But when the user has a CustomerTag Id that matches a benefit with an earlier date, the button state to show can be re-evaluated using that date.

Example of what normal, or not logged-in users see and what friends see when after the OnlineSaleStart of the friend has passed but the normal OnlineSaleStart is still in the future.

Default info / state: "OnlineSaleStart": "2024-06-26T13:00:00"

Friends benefit has a different date: "OnlineSaleStart": "2024-06-10T13:00:00

Notes

Benefits can add ticket types to the list of available ticket types. Benefits can not change the price of already available ticket types, nor can they remove ticket types.

• A customer can have multiple customer tags. Each tag can have a benefit. All beneficiary ticket types are available to such a customer, and as such should be shown to him. 
• When there are multiple beneficiary OnlineSaleStart dates, the first occurring OnlineSaleStart should be used.
• A customer tag or benefit does not influence the OnlineSaleEnd, SoldOut or SaleStatus, they remain the same for all customers.

Each tag can have a benefit. All beneficiary ticket types are available to such a customer, and as such should be shown to him. 

When there are multiple beneficiary OnlineSaleStart dates, the first occurring OnlineSaleStart should be used.

A customer tag or benefit does not influence the OnlineSaleEnd, SoldOut or SaleStatus, they remain the same for all customers.

Skins

The Tixly part that the customers see it the online flow and the account pages. This can be styled and configuered in many ways. That configuration is what we call a skin and controls these things, and even more:

• Design elements, colors, logos.
• Webtrackers.
• URLs on the logo, continue shopping buttons.
• Default settings for many of the emails.
• URL of the skin, where is can be on a your domain, for example "https://billet.musikhuset.dk" or on a tix domain like this "https://tix.no/nb/notteroy"
• When using organisations, a skin can be limited to sell only from the configuered organisation. 
• Define what sites are allowed to read session information.

Bilagor (3)

4791560180765.jpeg
33.9 KB

360018573157.png
42 KB

360018573137.png
30.8 KB