Hjemmeside Integration

Tixlys billetsystem bliver brugt i kombination med en hjemmeside fra et spillested. Denne artikel beskriver mulighederne og best-practice for at integrere et spillesteds hjemmeside og Tixly. 

Der er mange måder at gøre dette på, fra simple manuelle links til en fuldautomatisk opsætning. 

• Manuelle links
• Automatisk Opsætning
  • Webhook
  • Brugerlogin status og kurveinformation
  • Data i session informationen
  • Brugen af personlig information til at give f.eks. pre-sale adgang og forskellige billettyper til nogle kunder.
• Skins

Manuelle links

Det er muligt at bruge direkte links til en produktion, et event eller et abonnements salgsside og indsætte linket manuelt i jeres CMS-system. Disse links kan findes i Boxoffice Salgsvinduet eller i Internet-fanen på det enkelte event/produktion eller abonnement. 

Eksempler på hvordan links kan se ud: 

1. Link til en produktion

   1. https://billet.detfiktiveteater.dk/dk/buyingflow/tickets/1290/

2. Link til et event indenfor en produktion

   1. https://billet.detfiktiveteater.dk/dk/buyingflow/tickets/1290/18417/

3. Link to an subscription

   1. https://tix.dk/dk/detfiktiveteater/buyingflow/subscription/15/

De første to er eksempler hvor der er brugt et underdomæne for spillestedet, mens den sidste er opsat på Tixlys domæne. 

Automatisk opsætning 

Hjemmeside 

Hjemmesidens database indeholder events eller abonnementer med al den information, som spillestedet ønsker at offentliggøre på deres hjemmeside. Det kan være en kalender side eller en side per produktion.

En almindelig tilgang er at have et setup, der gør følgende:

• Hjemmesiden importerer periodisk alle fremtidige events til deres database ved hjælp af Tixly Event API.
  Dette sikrer, at begivenhedsinformationen fra Tixly er til stede i hjemmeside-databasen.
  • Tilføj nye events til den lokale database.
  • Opdater eksisterende events.
  • Marker de lokale events, der ikke længere er i outputtet, som slettet.
• Jo mere information der bruges, desto bedre. PurchaseURL's, OnlineSaleStart, OnlineSaleEnd og SaleStatus er sandsynligvis nødvendige. 
• CMS'et bruges til at tilføje flere oplysninger, videoer, anmeldelser osv. til produktionerne eller til individuelle event datoer.
• Hjemmesiden offentliggør begivenheden. Fra nu af er den synlig for besøgende. En [køb billetter]-knap vises med Purchase URL, når den aktuelle dato er mellem OnlineSaleStart og OnlineSaleEnd.

Når brugeren klikker på [køb billetter], åbnes Tixly-flowet i samme browservindue. Et rimeligt interval for importen i trin 1 afhænger af situationen, én gang i timen er rimeligt.

Du kan tilføje minimized=true til event API-URL'en for at få en output med den minimale version, som kun indeholder SaleStatus. Dette kan bruges til at synkronisere status oftere og bygge et lettere script, der ikke behøver at tjekke, om andre egenskaber ved events er ændret.

Webhook

Det virker lidt som spild at importere meget ofte, når der ikke sker nogen ændringer det meste af tiden. Men på den anden side, vil du ikke vente 2 timer på, at en ændring i Tixly bliver synlig på din hjemmeside. Det er her, du kan bruge webhook-funktionen til at løse dette.

Tixly vil kalde en URL på din hjemmeside, webhook-URL'en, hver gang der er lavet en ændring af en begivenhed i Tixly. Som svar på webhook-anmodningen kan din hjemmeside starte et import-job.

Der er ingen information i webhook'en om, hvilken begivenhed der er blevet ændret, og Tixly gør ikke noget med de data, som webhook'en måtte returnere.

Eksempler på gyldige webhook-URL'er er:

https://www.theaterxyx.nl/import/trigger
https://username:password@examplevenue.dk/admin/tix-importer.php

Pro tip: Webhooken bliver kaldt hver gang noget ændres. Hvis spillestedets personale ændrer priser, kategorier etc. kan dette betyde at webhooken bliver kaldt flere gang i minuttet. Herefter kan der gå flere timer før den bliver kaldt igen.

I stedet for at køre din import hver gang webhooken bliver kaldt, er det bedre at vente et minut eller to, og hvis webhooken ikke er blevet kaldt igen i denne periode, kan du lave importen. 

For at sætte dette op, skal du kontakte Tixly Support og give dem din hjemmesides webhook-URL. 

Brugeres login status og kurveinformation 

Vigtigt: Grundet restriktioner i de fleste browsere, er det påkrævet at din Tixly instance er på et underdomæne til dit spillesteds hjemmeside, f.eks. billet.detfiktiveteater.dk. Det betyder, at denne session-sharing feature kun virker på det vi kalder hosted skins. 

Det er muligt at vise på et spillesteds hjemmeside at en bruger er logget in i Tixly og hvis de har noget i kurven. Det er også muligt at vise kurvens indhold. Et eksempel kan være dette: 

Dette opnås ved at dele sessiondata fra Tixly til hjemmesiden. Hjemmesiden bruger derefter disse data til at vise dem i det design, de ønsker. Delingen fungerer ved at åbne et iframe til Tixly-webstedet med integrations-URL'en på det korrekte skin. Dette iframe skal være skjult på venue-hjemmesiden og viser ikke noget. Det bruges kun til at lade JavaScript fra event/postmessage framework til at kommunikere mellem åbningssiden på spillestedets side og iframen fra Tixly.Flere websider kan konfigureres, hvilket gør det muligt for udviklings- og staging-servere på spillesteds-sitet at bruge det samme skin som produktionswebsiden

URL'en til iframe-URL'en, itix (kort for integration tix) filen er:

{skin url}/{language}/itix

Eksempel:

https://billet.detfiktiveteater.dk/dk/itix

Denne URL bør anmodes om i et iframe.

PostMessage 'GetSession' bør udsendes til iframe'et.

En EventListener bruges til at reagere på den returnerede besked med sessioninformationen. At kigge på implementeringer fra andre Tixly-kunder kan hjælpe med at forstå dette. Det Bruxelles-baserede spillested La Monnaie / De Munt har et setup der er nemt at forstå. 

Data i sessions informationen

Nedenfor er et eksempel på json strukturen af postmessage svaret. Dette viser en ordrer med to billetter og en bruger. 

{
    "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": "JamesBond@Example.com",
        "hash": "2ac9f3a26521d0194530daf3e68c88589d4490617059793dd2eba1b14b786b84"
        "tags": [{
            "id": 7,
            "name": "Premium",
            "abbr": "PP"
        }]
    },
    "profile": "https://tix.theaterexample.nl/nl/profile/"
}

Detaljerne for elementerne i objektet der sendes er som følger: 

1. order

   1. Objektet er null, hvis der ikke er nogen ordre i brugerens session i øjeblikket. 

2. order > items

   1. En liste med alle delene i en ordre.

3. order > items > type

   1. Typen af varen. Dette kan være Ticket, Subscription, GiftCard, Membership, Donation eller Product. 
   2. Obs: Subscription er en billet der er en del af en abonnementspakke. 

4. order > items > name

   1. Varens navn, der varierer for hver type:
      • Ticket > Eventets navn
      • Subscription > Abonnementets navn
      • GiftCard > Gavekortgruppens navn
      • Product > Produktets navn

5. order > items > details

   1. Detaljer for hver type:
      • Ticket > Eventets starttidspunkt
      • Subscription > Eventets navn og starttidspunkt 
      • GiftCard > Værdien af gavekortet formateret som en invariant string “20.00”
      • Product > Der gives ingen detaljer for produktet. 

6. order > items > price

   1. Prisen for varen er en invariant decimal (0.00)

7. order > expires

   1. Decimal sekunder og millisekunder indtil ordren udløber fra øjeblikket sessionens info blev anmodet. 

8. order > url

   1. En URL der tager dig til købssiden for ordren.

9. user

   1. Objektet er null hvis brugeren ikke er logget in i denne session 

10. user > id

    1. Webbrugerens ID. OBS: Dette er IKKE kunde-ID'et.
    2. I CRM Api'et er der et endpoint for at få kunde-ID'et ud fra Webbruger-ID'et.
    3. CRM API: POST /WebUser/{webUserId}/customer

11. user > name

    1. Det fulde navn på brugeren der er logget ind (kan være tomt) 

12. user > email

    1. Email på webprofilen der er logget ind (i sjældne tilfælde kan dette være en anden end Kundens e-mail.)

13. user > hash

    1. Med dette hash, kan hjemmesiden validere om webprofilens ID er gyldigt. 
    2. En secret skal tilføjes til skin indstillingerne af en Tixly Admin. Hashen beregnes som en SHA256 over webprofilens ID + skin secret.
    3. Eksempel:
       • web user id: 544803
       • secret: uXL9aHWX3pumEEZsjU!U
       • The hash vil blive SHA256(544803uXL9aHWX3pumEEZsjU!U) der resulterer i: 2ac9f3a26521d0194530daf3e68c88589d4490617059793dd2eba1b14b786b84

14. user > tags

    1. En liste over Kundetags der er forbundet til brugeren, der kan matches med kundetags på events for at se hvilke fordele brugeren der er logget in kan få adgang til.

15. user > tags > id

    1. Kundetaggets ID 

16. user > tags > name

    1. Kundetaggets navn 

17. user > tags > abbr

    1. Forkortelsen for det tag. Det er ikke sikkert det er unikt og det kan vælges af en Admin fra spillestedet. 

18. profile

    1. En URL der fører til brugerens profilside eller til login siden hvis brugeren ikke er logget ind. A URL that takes you to the user's profile page, or to the login page if not logged in.

OBS: Leveringsgebyrer er ikke inkluderet i sessionsinformationen

Brug af personaliserede oplysninger til at give forsalgadgang og forskellige billettyper til nogle kunder.

Med sessioninformationerne om kunden, i kombination med fordelene i Tixly Event API, er hjemmesiden i stand til at vise personaliserede oplysninger til kunderne. 

For eksempel, hvis en VIP-kunde er logget ind, kan de se deres VIP-priser, mens normale kunder ikke kan se disse. Eller du kan vise [køb billetter]-knappen tidligere til dine medlemmer, så de kan købe billetter før den brede offentlighed (forsalg).

Metoden, der anvendes her, er Tixly Event API, som indeholder alle de normale salgsdatoer og priser, men også de mulige fordele, som kunder med bestemte kundetag kan udnytte.

Et eksempel på en objektliste af fordele:

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

Her kan du se, at kunder med tagget "Student" får lov til at købe billetter til billettypen "Student" for en pris på 8,5.

For kunder, der er "Friend", er der et alternativ: en tidligere "OnlineSaleStart" og en ekstra billettype "Friends", som kun er tilgængelig i en begrænset periode og for maksimalt 2 billetter.

Alle fordeldataene skal opbevares i databasen på hjemmesiden, så de er tilgængelige til brug i web front-end’en.

Hjemmesiden viser som standard et event med priser synlige i skabelonen, mens de andre fordel-priser er i skjulte elementer. Når hjemmesiden får et brugerobjekt i sessioninformationen fra Tixly, kan brugerens > tags > id bruges til at vise fordelpriserne, til de der har det tilsvarende CustomerTagId.

Det samme gælder for "Køb billetter"-knappen. Standardinformationen bruges til at vise knappens oprindelige tilstand. Men når brugeren har et CustomerTagId, der matcher en fordel med en tidligere dato, kan knaptilstanden re-evalueres ved hjælp af denne dato.

Eksempel på, hvad normale eller ikke-loggede brugere ser, og hvad venner ser, når OnlineSaleStart for vennerne er gået, men den normale OnlineSaleStart stadig er i fremtiden.

Standardinfo / tilstand: "OnlineSaleStart": "2024-06-26T13:00:00"

Kunder med tagget Friends har en anden dato "OnlineSaleStart": "2024-06-10T13:00:00"

Noter

Fordele kan tilføje billettyper til listen over tilgængelige billettyper. Fordele kan ikke ændre prisen på allerede tilgængelige billettyper, og de kan heller ikke fjerne billettyper.

• En kunde kan have flere kundetag. Hvert tag kan have en fordel. Alle fordelagtige billettyper er tilgængelige for sådan en kunde, og de bør derfor vises for ham.
• Når der er flere OnlineSaleStart-datoer for en fordel, skal den første OnlineSaleStart-dato anvendes.
• Et kundetag eller en fordel påvirker ikke OnlineSaleEnd, SoldOut eller SaleStatus – disse forbliver de samme for alle kunder.

Skins

Den del af Tixly, som kunderne ser, i onlineflowet og på Min Side. Denne kan styles og konfigureres på mange måder. Denne konfiguration kaldes et "skin" og styrer disse ting, og endnu mere:

• Design elementer, farver, logoer.

• Webtrackers.

• URLs på logoet, "fortsæt shopping"-knapper.

• Standardindstillinger for mange af e-mailerne.

• URL'en for skin'et, hvor det kan være på din egen domæne, for eksempel "https://billet.musikhuset.dk" eller på et Tix-domæne som dette "https://tix.no/nb/notteroy"

• Når man bruger organisationer, kan et skin være begrænset til kun at sælge fra den konfigurerede organisation.

• Definer hvilke sider der har lov til at læse sessioninformation.