Website-Integrationen

Dieser Artikel erläutert die Möglichkeiten und die optimale Vorgehensweise zur Integration Ihrer Website mit Tixly.

Dabei stehen verschiedene Methoden zur Verfügung – von einfachen manuellen Verlinkungen bis hin zu einer vollständig automatisierten Lösung.

• Manuelle Verknüpfungen
• Automatische Verknüpfungen
  • Webhook
  • Status der Nutzer:innen-Anmeldung und Warenkorbinformationen
  • Daten der Sitzungsinformationen
  • Verwendung personalisierter Informationen zu Vorteilen für bestimmte Kund:innen
• Skins

Manuelle Verknüpfungen

Es ist möglich, direkte Links zu den Verkaufsseiten für Produktionen, Veranstaltungen oder Abonnements zu nutzen und diese manuell auf Ihrer Website zu platzieren. Diese Links finden Sie in den BoxOffice-Verkaufsbildschirmen in Tixly sowie in der Veranstaltungsanlage unter dem Reiter Internet. Wie diese Links eingebunden werden, hängt jedoch vom verwendeten CMS ab.

1. Link zu einer Produktion

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

2. Link zu einer Veranstaltung in dieser Produktion

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

3. Link zu einem Abonnement

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

Die ersten beiden Beispiele zeigen eine Tixly-Einrichtung auf der Subdomain des Veranstaltungsortes, das letzte Beispiel verwendet die Tixly-Domain.

Automatische Verknüpfungen

Die Website-Datenbank enthält alle Veranstaltungen oder Abonnements mit den Informationen, die die Veranstaltungsstätte auf ihrer Website veröffentlichen möchte. Dies kann eine Kalenderseite oder eine eigene Seite pro Produktion umfassen.

Eine gängige Vorgehensweise ist eine Einrichtung, die Folgendes ermöglicht:

• Die Website importiert in regelmäßigen Abständen alle zukünftigen Veranstaltungen mit Hilfe der Tixly Event APIin ihre Datenbank. Dadurch wird sichergestellt, dass die Veranstaltungsinformationen von Tixly in der Datenbank der Website vorhanden sind.
  • Neue Veranstaltungen in die lokale Datenbank aufnehmen
  • Bestehende Veranstaltungen aktualisieren
  • Markiert die lokalen Veranstaltungen, die nicht mehr im Output enthalten sind, als gelöscht. 
• Je mehr Informationen verwendet werden, desto besser. Die PurchaseURLs, OnlineSaleStart, OnlineSaleEnd und SaleStatus werden wahrscheinlich benötigt.
• Das CMS dient dazu, den Produktionen oder einzelnen Veranstaltungsterminen weitere Informationen, Videos, Rezensionen usw. hinzuzufügen.
• Die Veranstaltung wird auf der Webseite veröffentlicht. Von nun an ist sie für die Besucher:innen sichtbar. Der Button [Tickets kaufen] wird mit der Kauf-URL angezeigt, wenn das aktuelle Datum zwischen OnlineSaleStart und OnlineSaleEnd liegt.

Wenn der:die Käufer:in auf [Tickets kaufen] klickt, wird der Tixly-Webshop im selben Browserfenster geöffnet. Ein angemessenes Intervall für den Import in Schritt 1 hängt von der Situation ab, einmal pro Stunde ist angemessen.

Sie können minimized= true zur event api url hinzufügen, um eine Ausgabe mit der Minimalversion zu erhalten, die nur SaleStatus enthält. Sie können dies verwenden, um den Status häufiger zu synchronisieren und ein einfacheres Skript zu erstellen, das nicht prüfen muss, ob andere Eigenschaften von Veranstaltungen geändert werden.

Webhook

Es wäre ineffizient, den Import sehr häufig durchzuführen, wenn sich in den meisten Fällen nichts geändert hat. Andererseits möchte man auch nicht zwei Stunden warten, bis eine Änderung in Tixly auf der Website sichtbar wird. Genau hier kommt die Webhook-Funktionalität ins Spiel.

Tixly ruft bei jeder Änderung einer Veranstaltung eine Webhook-URL auf Ihrer Website auf. Als Reaktion auf diese Anfrage kann Ihre Website dann einen Importvorgang starten.

Der Webhook selbst enthält keine Informationen darüber, welche Veranstaltung geändert wurde, und Tixly verarbeitet keine Daten, die als Antwort auf den Webhook zurückgesendet werden.

Gültige Beispiele für Webhook-URLs sind:

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

Profi-Tipp: Der Webhook wird jedes Mal aufgerufen, wenn eine Änderung vorgenommen wird. Wenn das Personal der Veranstaltungsstätte beispielsweise Preise oder Genres bearbeitet, kann dies dazu führen, dass der Webhook mehrmals pro Minute ausgelöst wird. In Phasen ohne jegliche Änderungen hingegen wird er stundenlang gar nicht aufgerufen. 
Anstatt den Importvorgang bei jedem Webhook-Aufruf sofort auszuführen, ist es sinnvoller, ein bis zwei Minuten zu warten. Falls in diesem Zeitraum keine weiteren Webhook-Aufrufe erfolgen, kann der Import gestartet werden. 

Um dies zu nutzen, kontaktieren Sie bitte den Tixly-Support. Wir brauchen hierfür die Webhook-Url Ihrer Website.

Status der Nutzer:innen-Anmeldung und Warenkorbinformationen

Wichtig: Aufgrund von Einschränkungen der meisten Browser muss Ihre Tixly-Instanz auf einer Subdomain Ihrer Veranstaltungsort-Website liegen, z.B. tixly.venuewebsite.de. Das bedeutet, dass diese Sitzungsfreigabe-Funktion nur mit sogenannten Hosted Skins funktioniert.

Es ist möglich, auf der Website der Veranstaltungsstätte anzuzeigen, ob ein:e Käufer:in in Tixly eingeloggt ist und ob er einen Warenkorb hat. Auch der Inhalt des Warenkorbs kann auf der Website angezeigt werden. Ein Beispiel dafür wäre:

Dies wird erreicht, indem Sitzungsdaten von Tixly an die Website übermittelt werden. Die Website nutzt diese Daten, um sie im gewünschten Design anzuzeigen. Die Übertragung erfolgt durch das Öffnen eines Iframes zur Tixly-Website mit der Integrations-URL auf dem entsprechenden Skin. Dieses Iframe sollte auf der Veranstaltungsseite verborgen bleiben und keine sichtbaren Inhalte anzeigen. Es dient lediglich dazu, JavaScript aus dem event/postmessage framework zu verwenden, um eine Kommunikation zwischen der geöffneten Seite auf der Veranstaltungswebsite und dem Iframe von Tixly zu ermöglichen.

Die Postnachrichten-Funktion wird durch die Einstellungen der Skins begrenzt, sodass nur bestimmte Websites Nachrichten senden und Daten empfangen dürfen (siehe Skin-Einstellungen). Es können mehrere Websites konfiguriert werden, sodass Entwicklungs- und Staging-Server der Veranstaltungswebsite derselben Skin wie die Produktionswebsite verwenden können.

Die URL des Iframe-URLs, der Itix (kurz für Integration Tix) Datei, lautet:

{skin url}/{language}/itix

Beispiel:

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

Diese URL sollte am besten in einem Iframe angefordert werden.

Die postMessage ‘GetSession’ sollte an das Iframe gesendet werden.

Ein EventListener wird verwendet, um auf die Rückgabemeldung mit den Sitzungsinformationen zu reagieren. Ein Blick auf die Implementierungen anderer Tixly-Kunden kann dabei helfen, dies besser zu verstehen. Die in Brüssel ansässige Veranstaltungsstätte La Monnaie / De Munt hat ein einfach zu verstehendes Setup.

Daten der Sitzungsinformationen

Unten finden Sie ein Beispiel für die JSON-Struktur der PostMessage-Antwort. Diese zeigt einen Auftrag mit zwei Tickets und dem Käufer.

{
    "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/"
}

Die Details der Eigenschaften im gesendeten Objekt sind wie folgt:

1. order

   1. Ein Objekt, das null ist, wenn keine Bestellung derzeit in der Benutzersitzung vorhanden ist.

2. order > items

   1. Eine Liste aller Positionen im Auftrag

3. order > items > type

   1. Art der Position. Kann Ticket, Abonnement, Gutschein, Mitgliedschaft, Spende oder Artikel sein.
   2. Hinweis: Ein Abonnement ist ein Ticket, das Teil eines Abonnement-Pakets ist.

4. order > items > name

   1. Name der Position, variiert je nach Typ:
      • Ticket > Name der Veranstaltung
      • Subscription > Name des Abonnement-Pakets
      • GiftCard > Name  der Gutscheingruppe
      • Product > Name des Artikels

5. order > items > details

   1. Details für jeden Typ:
      • Ticket > Startdatum der Veranstaltung
      • Subscription > Name und Startdatum der Veranstaltung
      • GiftCard > Betrag des Gutscheins, formatiert als unveränderliches string „20.00“
      • Product > Keine Details zu Artikel angegeben

6. order > items > price

   1. Preis des Artikels als invariant Dezimalzahl (0,00).

7. order > expires

   1. Dezimalsekunden und Millisekunden bis zum Ablauf des Auftrags, ab dem Moment, in dem die Sitzungsinformationen angefordert wurden.

8. order > url

   1. Eine URL, die Sie zur Kaufseite des Auftrags führt.

9. user

   1. Das Objekt ist null, wenn der:die Web-Benutzer:in in dieser Sitzung nicht eingeloggt ist.

10. user > id

    1. Die ID des:der Web-Benutzer:in. Hinweis: Dies ist nicht die Kund:innen-ID.
    2. In der CRM-API gibt es einen Endpunkt, um die Kund:innen-ID anhand der Web-Benutzer:innen-ID abzurufen.
    3. CRM API: POST /WebUser/{webUserId}/customer

11. user > name

    1. Vollständiger Name des:der eingeloggten Web-Benutzer:in (kann leer sein).

12. user > email

    1. E-Mail-Adresse des:der eingeloggten Web-Benutzer:in (in seltenen Fällen kann diese von der E-Mail-Adresse des:der Kund:in abweichen).

13. user > hash

    1. Mit diesem Hash kann die Website überprüfen, ob die Web-Benutzer:in-ID gültig ist.
    2. Ein secret muss in den Skin-Einstellungen von einem Tixly-Administrator hinzugefügt werden. Der Hash wird als SHA256-Hash über die Web-Benutzer-ID + Skin-secret berechnet.
    3. Beispiel:
       • web user id: 544803
       • secret: uXL9aHWX3pumEEZsjU!U
       • The hash will be SHA256(544803uXL9aHWX3pumEEZsjU!U) resulting in: 2ac9f3a26521d0194530daf3e68c88589d4490617059793dd2eba1b14b786b84

14. user > tags

    1. Eine Liste der Kund:innentags, mit denen der:die Web-Benutzer:in verknüpft ist, die mit Tags in Veranstaltungen abgeglichen werden können, um zu sehen, auf welche Vorteile der:die eingeloggte Web-Benutzer:in zugreifen kann.

15. user > tags > id

    1. ID des Tags

16. user > tags > name

    1. Name des Tags

17. user > tags > abbr

    1. Abkürzung des Tags (es ist nicht garantiert, dass dieser einmalig ist, und kann von den Veranstaltungsadministratoren ausgewählt werden.)

18. profile

    1. Eine URL, die Sie zur Profilseite des:der Web-Benutzer:in führt oder zur Login-Seite, wenn der:die Web-Benutzer:in nicht eingeloggt ist.

Beachten Sie: Liefergebühren sind nicht in den Sitzungsinformationen enthalten.

Verwendung personalisierter Informationen zu Vorteilen für bestimmte Kund:innen

Mit den Sitzungsinformationen des:der Kund:in und den Vorteilen aus der Tixly Event API ist die Website in der Lage, den Kund:innen personalisierte Extra-Informationen anzuzeigen.

Zum Beispiel, wenn ein:e VIP-Kund:in eingeloggt ist, kann er:sie VIP-Preise sehen, während normale Kund:innen diese nicht sehen. Oder Sie können den [Tickets kaufen]-Button früher für Ihre Freundeskreis-Mitglieder anzeigen, sodass diese vor dem regulären Verkaufsstart Tickets erwerben können.

Die verwendete Methode ist die Tixly Event API, die alle normalen Verkaufsdaten und Preise enthält, aber auch die möglichen Vorteile, die Kund:innen mit bestimmten Kund:innentags nutzen können.

Ein Beispiel für eine Liste von Vorteilen:

{
    "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"
            }],
        },
    ]
}

Hier sehen Sie, dass Kund:innen mit dem Tag Student Tickets zum Tickettyp „Student“ zu einem Preis von 8,50€ kaufen können. Für Kund:innen, die als Freund markiert sind, gibt es eine Alternative: Ein früherer Online-Vorverkaufsstart sowie ein zusätzlicher Tickettyp „Freunde“, der nur für einen begrenzten Zeitraum und für maximal 2 Tickets verfügbar ist. Alle Vorteile-Daten sollten in der Datenbank der Website gespeichert werden, damit sie im Web-Frontend verwendet werden können. Die Webseite zeigt standardmäßig eine Veranstaltung mit den in der Vorlage sichtbaren Preisen an, während die anderen Vorteilspreise in versteckten Elementen gespeichert sind. Wenn die Website dann ein Benutzerobjekt aus den Sitzungsinformationen von Tixly erhält, kann user > tags > id verwendet werden, um die Vorteilspreise anzuzeigen – die mit dem entsprechenden CustomerTagId.

Dasselbe gilt für den Tickets kaufen-Button. Die Standardinformationen werden verwendet, um den anfänglichen Status des Buttons anzuzeigen. Wenn jedoch der:die Web-Benutzer:in eine CustomerTagId hat, die mit einem Vorteil mit einem früheren Datum übereinstimmt, kann der Button-Status mithilfe dieses Datums neu bewertet werden.

Hier ein Beispiel, was normale oder nicht eingeloggte Web-Benutzer:innen sehen und was "Freunde" sehen, nachdem der OnlineSaleStart für Freunde vorbei ist, aber der normale Online-Verkaufsstart noch in der Zukunft liegt.

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

Der Freunde-Vorteil hat ein anderes Datum: „OnlineSaleStart“: „2024-06-10T13:00:00"

Anmerkungen

Vorteile können zusätzliche Tickettypen zur Liste der verfügbaren Tickettypen hinzufügen. Sie können jedoch weder den Preis bereits vorhandener Tickettypen ändern noch Tickettypen entfernen.

• Ein:e Kund:in kann mehrere Kund:innentags haben, wobei jeder Tag mit einem Vorteil verknüpft sein kann. Alle damit verbundenen Tickettypen stehen dem:der Kund:in zur Verfügung und sollten ihm:ihr entsprechend angezeigt werden.
• Gibt es mehrere Starttermine für den Online-Verkauf (OnlineSaleStart) für begünstigte Tickettypen, wird der früheste dieser Termine verwendet.
• Ein Kund:innentag oder Vorteil hat keinen Einfluss auf das Enddatum des Online-Verkaufs (OnlineSaleEnd), den Ausverkaufsstatus (SoldOut) oder den Verkaufsstatus (SaleStatus) – diese bleiben für alle Kund:innen unverändert.

Skins

Der Bereich von Tixly, den die Kund:innen sehen, umfasst den Webshop  sowie die Accountseiten der Kund:innen. Dieser kann auf vielfältige Weise gestaltet und konfiguriert werden. Diese Konfiguration wird als Skin bezeichnet und steuert unter anderem:

• Designelemente, Farben und Logos
• Web-Tracking-Tools
• URLs für das Logo sowie „Weiter einkaufen“-Buttons für den weiteren Kaufprozess
• Standard-Einstellungen für viele E-Mails
• Die URL des Skins, die entweder auf Ihrer eigenen Domain (z. B. https://billet.musikhuset.dk) oder auf einer Tix-Domain (https://tix.no/nb/notteroy) gehostet sein kann.
• Wenn Ihre Organisation mehrere Unterorganisationen hat, kann ein Skin so konfiguriert werden, dass er nur Verkäufe von der konfigurierten Organisation aus ermöglicht.
• Festlegung, welche Websites Sitzungsinformationen auslesen dürfen.