Website Integratie

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

It is possible to use direct links to the production, event or subscription sales pages and place these in your website by hand. Of Course this depends on the cms how this is done.

Some examples:

Link to a production:

https://tix.theaterexample.com/nl/buyingflow/tickets/1290/

Link to an event in this production

https://tix.theaterexample.com/nl/buyingflow/tickets/1290/18417/

Link to an subscription:

https://tix.se/sv/oslo/buyingflow/subscription/15/ 

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

These links can be found in the Box Office sales screens in Tixly and also on the Internet tab of the event edit screens

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:

1. The website periodically imports all future events into their database with help of the Tix Event APIThis 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. 

2. The more information is used the better, the PurchaseURL's, OnlineSaleStart,OnlineSaleEnd and SaleStatus are proably needed.

3. The cms is used to add more information, videos, reviews etc to the event groups (productions) or to individual events.

4. 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. The user can buy tickets.

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 has only salestatus. You can use this to more frequently sync the status, and build a lighter script the does not need to check of 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.

Tix 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.  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, you 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 if logged in Tixly and if he has 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 can be hidden on the venue webpage. The event/postmessage framework is used to communicate between the opener page and the iframe.

The post messaging is limited by the “skin” where you can set which websites are able to post messages and receive them. (see  Skin settings) Multiple domains can be configured to allow development and staging servers of the venue site to use the same skin as the production website.

The url of the Integration TIX (itix) file is defined as:

{skin url}/{language}/itix

example:

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

This url has 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. The simple javascript in the example site can help to understand this.

Example of the json structure of the postmessage response shows the order 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/"
}

In the above example we have a user with an ongoing order.

Details of the object 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.
      Note that Subscription is a ticket that is part of a subscription package.

4. order->items->name

   1. Name of the item these are different 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 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 user is not logged in on this session

10. user-> id

    1. Id of the webuser. Note: this is not the customer id In the CRM API there is a endpoint to get the customer Id from the webuser Id
       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

13. user ->hash

    1. With this hash the website can validate if the webuser id is valid.  A secret can be added in the skin settings. The hash is computed as a SHA256 over the webuser Id + skin secret

       Example
       webuser id: 544803
       secret: uXL9aHWX3pumEEZsjU!U
       The hash will be SHA256(544803uXL9aHWX3pumEEZsjU!U) Which gives 2ac9f3a26521d0194530daf3e68c88589d4490617059793dd2eba1b14b786b84

14. user->tags

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

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, this is not guaranteed to be unique it can be chosen by the venue admins

18. profile

    1. A url that takes you to users profile page, or to the login page if you are not logged in.

Delivery fees are not to be seen in the session information.

Personalized information

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

For example if a VIP customer is logged in he can see his 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.

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

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.

A possible approach to use this data

The webpage loads with the prices visible in the template, and the "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 can be evaluated using that date.

Example of what normal, or not logged-in users see and what friends see sometime on Jun 10th after 13:00.

Default info / state	Friends benefit had an different date
"OnlineSaleStart": "2021-06-26T13:00:00"	"OnlineSaleStart": "2021-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. 

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

Bijlagen (3)

4791560180765.jpeg
33.9 KB

360018573157.png
42 KB

360018573137.png
30.8 KB