Fehlerbehebung bei benutzerdefinierten API-Integrationen

Dieser Leitfaden beschreibt häufige Probleme und Lösungen bei der manuellen Umsetzung einer API-basierten Integration. Sie müssen diese Empfehlungen an Ihre jeweilige Anwendung und Ihre Frameworks anpassen.

Wir können über die üblichen Supportkanäle keinen Support für benutzerdefinierte Integrationen anbieten, da es dabei so viele Faktoren gibt, die außerhalb unserer Kontrolle liegen. Das Erstellen einer benutzerdefinierten Integration ist relativ unkompliziert – allerdings müssen Sie ein erfahrener Entwickler sein, der die Grundlagen von HTTP gut beherrscht.

Beispiele für praxiserprobte Integrationen, die alle unten beschriebenen Probleme lösen, finden Sie auf GitHub:

• https://github.com/Crowdhandler/crowdhandler-cloudflare-integration
• https://github.com/Crowdhandler/crowdhandler-php-sdk

Probleme beim Ausschluss von URLs#

Wenn Ihre Anwendung über einen Front-Controller verfügt, leiten Sie möglicherweise alle Anfragen an Ihre Anwendung über eine Integration weiter, die sich beim CrowdHandler anmeldet, um einzelne URL-Anfragen zuzulassen oder abzulehnen. Dies kann zu den beiden folgenden Problemen führen:

1. Überprüfung unnötiger URLs#

Wenn ein Benutzer eine Seite lädt, lädt der Browser alle zugehörigen Seitenelemente auf Ihrer Domain, und es ist möglich, dass diese Anfragen über Ihren Front-Controller geleitet werden. Dies kann dazu führen, dass unnötige Überprüfungen durchgeführt werden, was die Ladezeit verlängert und letztendlich die Serverauslastung Ihrer Anwendung erhöht. Sie sollten zumindest diese gängigen Dateiendungen ausschließen, bevor Sie eine URL überprüfen:

.css, .gif, .ico, .jpg, .jpeg, .js, .json, .mov, .mp4, .mpeg, .mpg, .png, .svg, .ttf, .otf, .eot, .woff, .woff2

Sie sollten außerdem alle anderen Pfade in Ihren Anwendungen ausschließen, die sich auf Inhalte beziehen, für die kein „Waiting Room“-Schutz erforderlich ist. Wenn Sie beispielsweise alle statischen Ressourcen in einem Unterverzeichnis namens /static speichern, können Sie diesen Pfad von den Prüfungen ausschließen.

2. Blockieren von Diensten von Drittanbietern in der Warteschlange#

Wenn Sie einen Front-Controller wie oben beschrieben verwenden und Dienste von Drittanbietern nutzen, die APIs auf Ihrer geschützten Domain aufrufen, werden diese Dienste wahrscheinlich in der Warteschlange hängen bleiben und nicht weiterbearbeitet, da sie Cookies wahrscheinlich nicht akzeptieren. Zu den gängigen Diensten von Drittanbietern, die möglicherweise blockiert werden, gehören:

1. Dienste, Plugins oder Anwendungen, die APIs auf Ihrer Domain nutzen (RPC, REST)
2. Zahlungsdienste, die serverseitige Callbacks an Ihre Domain senden, um Transaktionen zu bestätigen.

Wenn die Dienste einen genau definierten IP-Bereich nutzen, können Sie diese möglicherweise zulassen, indem Sie den IP-Bereich über eine Bypass-Regel hinzufügen. In der Regel ist es jedoch besser, diese URLs von vornherein aus Ihren Prüfungen auszuschließen.

3. Blockieren Ihrer Admin-URLs#

Wenn Sie sich über URLs wie /admin bei Ihrer Backend-Anwendung oder Ihrem CMS anmelden, möchten Sie diese URLs möglicherweise ebenfalls ausschließen. Ebenso effektiv kann es sein, die IP-Adressen Ihres Büros oder Ihres VPNs als Ausnahmen festzulegen.

Probleme mit Cookies#

Das vielleicht größte Problem, das wir bei benutzerdefinierten Integrationen beobachten, ist das Scheitern beim Setzen eines Cookies zur Nachverfolgung des CrowdHandler-Tokens des Benutzers.

Möglicherweise verwenden Sie Cookies oder eine andere Form der browser- oder serverseitigen Sitzungsspeicherung. Wir verwenden hier den Begriff „Cookies“ als Sammelbegriff für alle Speicherverfahren, die Sie zur Nachverfolgung des CrowdHandler-Tokens des Benutzers einsetzen; Sie müssen jedoch darauf achten, welches Medium Sie auch immer zur Nachverfolgung von Sitzungen verwenden.

1. Es wurde kein lesbares Cookie gesetzt#

Ihre Integration muss das CrowdHandler-Token des Benutzers speichern, wenn dieser zum ersten Mal auf Ihre Website weitergeleitet wird. Sie können sich nicht darauf verlassen, dass das Token nach dem ersten Aufruf nach der Weiterleitung aus dem Warteraum in der URL enthalten ist. Sie müssen sicherstellen, dass das Cookie gesetzt wird. Achten Sie darauf, ein Cookie zu setzen, das Ihre Anwendung auch auf nachfolgenden Seiten, die der Benutzer möglicherweise besucht, auslesen kann.

2. Cookie wird aufgrund einer HTTP-Weiterleitung nicht gesetzt#

Der häufigste Grund, warum eine Integration kein Cookie setzen kann, ist, dass eine HTTP-Weiterleitung den Nutzer abfängt, noch bevor Ihre Integration überhaupt ausgeführt wird, und den Nutzer zu einer neuen Route weiterleitet, ohne das Token in der URL zu übergeben. Diese Weiterleitungsregeln können in der Konfiguration Ihres Webservers enthalten sein oder früh in Ihrem Codepfad ausgeführt werden, um Sprach- oder Anmeldeweiterleitungen zu handhaben. Seien Sie daher besonders vorsichtig, wenn Sie es mit einer mehrsprachigen Website zu tun haben oder einen Pfad schützen, der eine Benutzeranmeldung erfordert. Die Lösung besteht darin, sicherzustellen, dass Weiterleitungen den Abfrage-String mit dem Token enthalten, oder darauf zu achten, dass Sie Nutzer nicht direkt aus dem Warteraum an eine URL weiterleiten, die sofort eine Weiterleitung auslöst.

Zu diesem Problem gibt es einen eigenen Knowledge-Base-Artikel. Lesen Sie ihn, um das Problem besser zu verstehen. Dieser Artikel richtet sich zwar in erster Linie an Nutzer der JavaScript-Integration, Sie können dieses Problem jedoch auch in Ihrer eigenen Integration nachstellen.

3. Das Cookie wurde nicht aktualisiert#

Es gibt berechtigte Gründe, warum ein Nutzer möglicherweise mehrmals die Warteschlange durchläuft oder warum seine Sitzung abläuft und ihm ein neues Token zugewiesen wird. Aus diesem Grund ist es wichtig, dass Sie das Cookie entsprechend aktualisieren, sobald Sie ein Crowdhandler-Token in der URL sehen oder wenn ein neues Token von der API zurückgegeben wird. Andernfalls verwendet Ihre Integration möglicherweise ein abgelaufenes Token, wodurch der Nutzer erneut in die Warteschlange geleitet wird.

Suchen Sie also in Ihrem Integrationscode nach einem Token in der URL. Wenn Sie eines finden, führen Sie den Aufruf mit dem Token in der URL durch, anstatt das Token zu verwenden, das Sie möglicherweise in einem Cookie finden. Vertrauen Sie dann in jedem Fall dem wohlgeformten Token, das von der API zurückgegeben wird, und setzen Sie das Cookie.

4. Löschen des Cookies oder Festlegen eines fehlerhaften Werts#

Wenn Sie die URL überprüfen oder die API-Antwort auswerten, um festzustellen, ob Sie das Cookie des Benutzers aktualisieren sollten, achten Sie darauf, dass nicht durch einen Fehler in Ihrem Code versehentlich ein Null-, leerer oder falscher Wert gesetzt wird. Einige Frameworks interpretieren dies als Löschung des Cookies, und in jedem Fall wird dem Benutzer bei der nächsten Anfrage, bei der er ein ungültiges Token übermittelt, ein neues Token zugewiesen, wodurch er an das Ende der Warteschlange verschoben wird.

5. Es wird kein Cookie gesetzt, wenn der Nutzer in den Warteraum weitergeleitet wird.#

Streng genommen ist es nicht notwendig, ein Cookie zu setzen, wenn Sie diesen Nutzer in den Warteraum weiterleiten. Ihre Integration wird jedoch wesentlich robuster, wenn Sie immer ein Cookie setzen. Der Grund dafür ist, dass der Nutzer möglicherweise auf irgendeine Weise wieder auf die Website gelangt, bevor er seinen Weg durch den Warteraum abgeschlossen hat. Wenn Sie ihn dann noch erkennen, wird er unter Beibehaltung seiner ursprünglichen Position zurück in den Warteraum geleitet. Ist dies nicht der Fall, wird er mit einer neuen Position am Ende der Warteschlange in den Warteraum zurückgeleitet. Befindet sich ein Nutzer längere Zeit im Warteraum, ist es nicht ungewöhnlich, dass er die Website erneut aufruft, möglicherweise in einem neuen Tab. Dies gilt insbesondere dann, wenn er einen E-Mail-Link zur geschützten Seite erhalten hat.

6. Festlegen eines ungeeigneten Ablaufdatums für Ihr Cookie oder Verlassen auf temporäre Speicherung während der Sitzung#

Angesichts des oben beschriebenen Szenarios ist die übliche Zeitüberschreitung von 20 Minuten, die mit dem integrierten Sitzungsspeicher von Frameworks wie .NET oder PHP verbunden ist, für dieses Szenario möglicherweise nicht robust genug. Setzen Sie im Zweifelsfall ein Sitzungs-Cookie oder ein permanentes Cookie.

Probleme mit der API#

Nehmen Sie sich Zeit, um die von Ihnen gesendeten Parameter und die möglichen Antworten zu verstehen. Dies sind die häufigsten Probleme, die wir bei API-Anfragen und -Antworten beobachten:

1. Übermittlung einer falschen IP-Adresse an die API#

Wenn Sie die IP-Adresse an die angeforderte Ressource senden, stellen Sie sicher, dass Sie die IP-Adresse des Benutzers und nicht die Ihres Servers oder die eines zwischengeschalteten Proxy-Servers übermitteln. Wenn Sie dieselbe IP-Adresse mehrfach senden, wird diese wahrscheinlich identifiziert und blockiert. Sollte dieses Problem in einer Produktionsumgebung auftreten, können Sie diese IP-Adresse oder diesen IP-Bereich als „zu ignorieren“ kennzeichnen, um eine automatische Sperrung zu verhindern. Sie sollten jedoch Ihre Integration testen und anpassen, um die korrekte IP-Adresse zu ermitteln. Befindet sich Ihr Webserver hinter einem Proxy, können Sie die echte IP-Adresse in der Regel anhand des HTTP-Headers „X-Forwarded-For“ ermitteln. Diese Anleitung könnte Ihnen dabei helfen.

2. Unter der Annahme, dass die API antwortet#

Der Sinn und Zweck von CrowdHandler besteht darin, verfügbar zu sein, wenn Ihre Website nicht erreichbar ist. Es gibt jedoch viele berechtigte Gründe, warum Ihr Server vorübergehend keine Verbindung zur CrowdHandler-API herstellen kann, darunter allgemeine Probleme mit dem Internet-Routing oder Störungen im Rechenzentrum. Wenn Ihr Code davon ausgeht, dass Sie immer eine wohlgeformte Antwort erhalten, wird dem Nutzer in solchen Situationen wahrscheinlich eine unschöne Fehlermeldung angezeigt. Lösungen:

• Geben Sie beim Aufruf der API ein kurzes Timeout an (2 Sekunden sind optimal).
• Sollte der Aufruf zeitlich ablaufen oder die Antwort nicht korrekt formatiert sein, überlegen Sie, wie Sie vorgehen möchten. In den meisten Fällen werden Sie diesem Nutzer vertrauen und den Zugriff auf die URL zulassen wollen, denn das bedeutet: Sollte der Ausfall auftreten, während Sie keine Warteschlange betreiben, wird der Nutzer nicht beeinträchtigt. In Szenarien mit geringem Vertrauen möchten Sie den Nutzer möglicherweise in den Warteraum leiten – der CrowdHandler-Warteraum versucht, eine API-Verbindung herzustellen, und bemüht sich nach besten Kräften, den Nutzer zu betreuen, bis er eine korrekt formatierte Antwort von der API erhält.

3. Annahme des Antwortformats#

In den meisten Fällen erhalten Sie eine ausführliche Antwort, einschließlich Informationen zum Wartezimmer usw. Hier ein Beispiel:

{
    "result": {
        "status": 1,
        "token": "tok_7pDi5dRB2nUi",
        "title": "The Herb Girls Reunited!",
        "position": 964,
        "promoted": 0,
        "urlRedirect": null,
        "onsale": "2021-12-06T12:20:00Z",
        "message": "Booking is very busy right now. We appreciate your patience and will forward you shortly.",
        "slug": "herb-girls",
        "priority": null,
        "priorityAvailable": 1,
        "logo": "https://crowdhandler-templates.s3.amazonaws.com/public/94ea09f553bf57af84c21427c68b3c89fc64e2044c347522ba4ca01363ffaf8b/Queen Victoria Hall-logo-2.png",
        "responseID": "e0abd8dbb8d2810fad16855622dcd45f",
        "captchaRequired": 0,
        "rate": 50,
        "hash": null,
        "ttl": 55
    }
}

Manche Statusmeldungen liefern jedoch nur wenige Informationen.

Wenn Sie beispielsweise eine Anfrage für eine URL prüfen, die nicht durch einen CrowdHandler-Warteraum geschützt ist.

{
    "result": {
        "status": 0,
        "token": null,
        "responseID": null,
        "promoted": 1
    }
}

Weitere mögliche Rückmeldungen sind: Ihr Schlüssel ist ungültig (HTTP-Fehler 401), der Raum ist voll (Status: 5) oder die IP-Adresse, von der aus Sie senden, wurde auf die Sperrliste gesetzt (Status: 4).

Lösungen:#

• Nehmen Sie sich etwas Zeit, um die Bedeutung der zurückgegebenen Antwortcodes zu verstehen. Dies sind Situationen, die Sie möglicherweise berücksichtigen müssen.
• Um festzustellen, ob dem Benutzer Zugriff gewährt oder er in den Warteraum weitergeleitet werden soll, müssen Sie lediglich das Boolean-Attribut „promoted“ überprüfen, das – sofern kein Fehler vorliegt – immer vorhanden ist und entweder den Wert 0 oder 1 annimmt. Wenn Ihre Integration sehr einfach ist und Sie lediglich dieses Attribut prüfen, müssen Sie die verschiedenen Antworten und Status nicht wirklich verstehen, denn wenn „promoted“ den Wert 0 hat, können Sie den Nutzer in den Warteraum leiten, und der Warteraum weiß dann, was zu tun ist.
• Wenn Sie eine Anwendung entwickelt haben oder ein Framework verwenden, bei dem das Antwortobjekt aus objektorientierten Gründen stets konsistent sein muss, sollten Sie zunächst ein eigenes Basisobjekt oder eine eigene Basisklasse zur Darstellung der Antwort erstellen, sinnvolle Standardwerte festlegen und anschließend nur die Werte setzen, die in der API-Antwort zurückgegeben werden.