Website-Integration

Diese Seite ist das empfohlene Rezept, um die Website einer Crew mit Sway zu verbinden: Die Site behält ihr eigenes Design und Hosting, und Sway wird ihre Quelle für Roster, Veranstaltungen, Tickets, Formulare und das Ambassador-Programm.

1. Die API von deinem Server aus aufrufen

Behalt den geheimen Schlüssel auf deinem Server (API-Routen, serverseitiges Rendering, Edge Functions), nie in einer Seite.

• Speicher ihn als Secret (SWAY_API_KEY), nie im Repository oder im Client-Bundle.
• Gib deinen Seiten eigene Routen (/api/site-data), die Sway aufrufen und nur zurückgeben, was die Seite zeigt.
• Prüf den Schlüssel und seine Limits beim Start mit GET /v1/me.
• Limits, die pro Besucher zählen (Booking-Anfragen, Newsletter-Anmeldungen, Checkout, die Ambassador-Routen), zählen den Besucher, den dein Server im Body als client_ip nennt, und deinen Schlüssel als Ganzes mit zwanzigmal so viel Spielraum. Schick ihn mit: ohne ihn zählt nur der ganze Schlüssel, und ein Besucher, der nicht aufhört, kann den Spielraum deiner ganzen Site aufbrauchen.
• Eine ganz statische Site ohne Server kann stattdessen einen veröffentlichbaren Schlüssel (sway_pk_) aus dem Browser nutzen, nur für öffentliche Lesezugriffe, mit den Adressen der Site am Schlüssel hinterlegt. Siehe Zwei Schlüsselarten.

2. Lass Caching den Traffic tragen

Sway cacht jeden Lesezugriff pro Crew und liefert Wiederholungen gratis, damit der Traffic deiner Site nicht zu API-Traffic wird. Trag deinen Teil bei:

• Schick If-None-Match. Behalt das ETag jeder Antwort; eine unveränderte Ressource antwortet mit 304, ohne Body und ohne Kosten.
• Behalt deine eigene Kopie, so lange wie Sway es tut, und liefer sie aus, wenn die API langsam oder nicht erreichbar ist:

• Frag nach dem, was du zeigst. ?fields= kürzt Antworten, ?expand=venue,lineup,ticket_tiers im Feed eines Veranstalters ersetzt drei Anfragen pro Veranstaltung, ?ids= holt 50 bekannte Veranstaltungen auf einmal, und updated_since synchronisiert nur, was sich geändert hat.
• Hör zu, statt zu pollen. Aktualisier mit Webhooks eine Veranstaltung, sobald event.updated eintrifft, und füg sie bei event.published hinzu, statt jede Seite nach einem Timer neu zu lesen. Schick diese Aktualisierungen mit Cache-Control: no-cache, damit Sway sie frisch liest und nicht aus einer Kopie von vor der Änderung.

Eine so gebaute Site macht wenige API-Anfragen pro Minute, egal wie viel Traffic sie hat, und läuft durch einen kurzen Ausfall weiter.

3. Tickets verkaufen

Bezahlt wird immer auf der Checkout-Seite von Sway. Zwei Wege dorthin:

Ein Link. Jeder Tickettyp trägt eine checkout_url. Zeig deinen eigenen "Tickets holen"-Button, der darauf zeigt. Sonst gibt es nichts zu bauen.

Ein von deiner Site geöffneter Checkout. Mit write:checkout ruft dein Server POST /v1/checkout-sessions auf, mit den Tickettypen und Mengen, die der Besucher auf deiner Seite gewählt hat, und leitet auf die url weiter, die zurückkommt. Davor:

• prüf einen Gutschein oder einen Zugangscode mit POST /v1/coupons/validate oder POST /v1/access-codes/validate, um den Rabatt zu zeigen oder versteckte Tickettypen freizuschalten, bevor der Besucher zahlt;
• behalt die checkout_id aus der Antwort, um den Checkout zu verfolgen (GET /v1/checkout-sessions/{id}) oder ihn zu beenden (POST /v1/checkout-sessions/{id}/expire), wenn der Besucher geht.

Dann trifft order.paid an deinem Webhook ein, mit "via_your_site": true.

Zeig die Verfügbarkeit über den status des Tickettyps (on_sale, scheduled, sold_out, off_sale) und GET /v1/events/{id}/availability. Die API zeigt nie Bestandszahlen oder Käuferdaten.

4. Aus deinen Formularen sammeln

Validier zuerst auf deinem Server, und behalt deinen eigenen Bot-Schutz (ein Captcha, ein Honeypot) vor jedem Formular: Sway sieht deinen Server, nicht den Besucher. Gib die Adresse des Besuchers mit, wo der Endpunkt danach fragt (client_ip), damit die eigenen Limits von Sway pro Besucher gelten statt für deine ganze Site. Booking-Anfragen sind auf 10 pro Minute und Besucher und 300 pro Tag und Crew begrenzt.

Booking-Anfragen landen in Crew-Admin → API → Booking-Anfragen; Newsletter-Anmeldungen und Formularantworten im CRM des Veranstalters und bei den Antworten des Formulars. Schick Idempotency-Key bei jedem dieser Aufrufe mit, damit eine Wiederholung eine Einreichung nie doppelt erfasst.

5. Platzhalter als Rückfallebene behalten

Behalt den statischen Inhalt deiner Site (Beispielkünstler, Beispielveranstaltungen) als Rückfallebene, statt ihn zu löschen:

• Ist die API nicht erreichbar und dein Cache leer, zeig die Platzhalter statt einer leeren Seite.
• Liefert die API weniger Einträge, als das Design braucht, füll das Raster auf.
• Reihenfolge beim Zusammenführen: API-Daten, dann die eigene Auswahl deiner Site, dann Platzhalter.

So bleibt die Site jederzeit vorzeigbar, auch bevor der erste Schlüssel konfiguriert ist.

6. Das Ambassador-Portal auf dem Server betreiben

Schaltet der Veranstalter die Anmeldung über deine Website ein, sind die Beitrittsseite, die Anmeldeseite und die eigene Seite des Mitglieds deine, um zu rendern, und das Ranking, die Belohnungen und Quests des Programms sind deine, um zu zeigen (read:ambassadors). Eine Regel: Der Browser hält ein Cookie von dir, nie Sway-Zugangsdaten.

• Behalt die Mitglieds-Session (amb_st_...) auf deinem Server, in einem versiegelten First-Party-Cookie oder einem Session-Store. Sway lehnt diesen Header von einem Browser ohnehin ab.
• Setz deinen eigenen Bot-Schutz auf die Beitritts- und Anmeldeformulare. Sway rendert keines von beiden.
• Tausch das ?amb_token=... auf deiner Landingpage beim ersten Laden auf deinem Server gegen eine Session, und entfern es aus der URL.
• Setz nie eine discount_id in eine Seite. Erfass ?amb=CODE, behalt den Code für den Besuch, und lös ihn auf deinem Server auf, wenn du den Checkout öffnest.
• Die Mitgliederliste, Bewegungen und Statistiken (read:ambassador-members) sind personenbezogene Daten für die eigenen Werkzeuge des Veranstalters, nie für eine öffentliche Seite.

Checkliste

• SWAY_API_KEY als serverseitiges Secret gespeichert (oder ein veröffentlichbarer Schlüssel, begrenzt auf deine Websites)
• GET /v1/me als Start-up-Check genutzt
• If-None-Match gesendet, Antworten behalten, veraltete Kopie bei Fehlern ausgeliefert
• fields, expand, ids und updated_since genutzt, wo sie Anfragen sparen
• Ein Webhook für event.published und event.updated statt Polling
• Ticket-Buttons nutzen checkout_url, oder dein Server öffnet POST /v1/checkout-sessions
• Formulare werden von deinem Server gesendet, mit eigenem Bot-Schutz und einem Idempotency-Key
• Platzhalter-Inhalt als Rückfallebene behalten
• Ambassador-Sessions auf deinem Server behalten, ?amb=CODE beim Checkout aufgelöst