Dépannage des intégrations d'API personnalisées

Ce guide décrit les problèmes courants et les solutions à adopter lors de la mise en place manuelle d'une intégration basée sur une API. Vous devrez adapter ces conseils à votre application et à vos frameworks spécifiques.

We are unable to provide support for custom integrations through normal support channels since there are so many factors outside our control. Writing a custom integration is relatively straightforward — but you do need to be an experienced developer with a good grasp of HTTP essentials.

Pour découvrir des exemples d'intégrations testées en conditions réelles qui répondent à tous les enjeux décrits ci-dessous, vous pouvez consulter nos intégrations sur GitHub :

URL Exclusion Issues

Si votre application dispose d'un contrôleur frontal, il se peut que vous acheminiez toutes les requêtes vers votre application via une intégration qui interroge CrowdHandler afin d'autoriser ou de refuser des requêtes URL spécifiques. Cela peut entraîner les deux problèmes suivants :

1. Checking unnecessary URLs

Lorsqu'un utilisateur charge une page, le navigateur charge tous les ressources associées à cette page hébergées sur votre domaine, et il est possible que ces requêtes transitent par votre contrôleur frontal. Cela peut entraîner des vérifications inutiles, ce qui allonge le temps de chargement et, au final, augmente la charge du serveur de votre application. Il est donc recommandé d'exclure au moins ces extensions de fichiers courantes avant de vérifier une URL :

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

Vous devez également exclure de vos applications tout autre chemin d'accès correspondant à du contenu ne nécessitant pas de protection par « salle d'attente ». Par exemple, si vous stockez toutes vos ressources statiques dans un sous-répertoire nommé /static, vous pouvez exclure ce chemin d'accès des vérifications.

2. Blocking Third Party Services in the queue

Si vous utilisez un contrôleur frontal comme indiqué ci-dessus et que vous disposez de services tiers qui appellent des API sur votre domaine protégé, ces services risquent d'être bloqués dans la file d'attente et ne pourront pas aboutir, car ils sont peu susceptibles d'accepter les cookies. Parmi les services tiers courants susceptibles d'être bloqués, on peut citer :

  1. Services, plugins ou applications qui utilisent les API de votre domaine (RPC, REST)
  2. Services de paiement qui effectuent des rappels côté serveur vers votre domaine afin de valider les transactions.

Si les services utilisent une plage d'adresses IP bien définie, vous pouvez éventuellement les autoriser en ajoutant cette plage à une règle de contournement. Cependant, il est généralement préférable d'exclure d'emblée ces URL de vos vérifications.

3. Blocking your admin URLs

If you log in to your backend application or CMS via URLs such as /admin you may wish to exclude these URLs too. It may be as effective to set your office or VPN IPs to bypass.

Cookie Issues

Le principal problème que nous constatons avec les intégrations personnalisées est peut-être l'impossibilité de définir correctement un cookie permettant de suivre le jeton CrowdHandler de l'utilisateur.

You may be using cookies, or you may be using another form of browser or server-side session storage. Here we use cookies as a catch-all term for whatever storage method you use for tracking the user's CrowdHandler token, but you must take care whatever medium you are using for tracking sessions.

1. Failing to set a readable Cookie

Votre intégration doit enregistrer le jeton CrowdHandler de l'utilisateur lors de sa première redirection vers votre site. Vous ne pouvez pas compter sur la présence du jeton dans l'URL après la première visite suivant la redirection depuis la salle d'attente. Vous devrez vous assurer que le cookie est bien défini. Veillez à définir un cookie que votre application pourra lire à partir des chemins d'accès suivants que l'utilisateur est susceptible de parcourir.

2. Failing to set Cookie because of an HTTP redirect

La raison la plus courante pour laquelle une intégration ne parvient pas à définir un cookie est qu’une redirection HTTP intercepte l’utilisateur avant même que votre intégration ne s’exécute, et le redirige vers une nouvelle route sans transmettre le jeton dans l’URL. Ces règles de redirection peuvent figurer dans la configuration de votre serveur web, ou être exécutées en début de votre chemin d’exécution pour gérer les redirections liées à la langue ou à la connexion. Si vous gérez un site multilingue ou si vous protégez un chemin impliquant la connexion de l’utilisateur, soyez donc particulièrement vigilant. La solution consiste à vous assurer que les redirections incluent la chaîne de requête contenant le jeton, ou à veiller à ne pas envoyer les utilisateurs directement depuis la salle d'attente vers une URL qui les redirigera immédiatement.

There is a dedicated Knowledge Base Article about this issue. Read it to understand it better. While this article is mostly directed at users of the JavaScript integration, you could re-create this issue in your own integration.

3. Failing to update the Cookie

Il existe des raisons légitimes pour lesquelles un utilisateur peut se retrouver à passer par la file d'attente plusieurs fois, ou voir sa session expirer et se voir attribuer un nouveau jeton. C'est pourquoi il est important, chaque fois que vous repérez un jeton « crowdhandler » dans l'URL, ou lorsqu'un nouveau jeton est renvoyé par l'API, de mettre à jour le cookie en conséquence. Sinon, votre intégration risque d'utiliser un jeton expiré, ce qui renverrait l'utilisateur dans la file d'attente.

Dans votre code d'intégration, recherchez donc un jeton dans l'URL. Si vous en trouvez un, effectuez l'appel en utilisant ce jeton dans l'URL plutôt que celui que vous pourriez trouver dans un cookie. Ensuite, dans les deux cas, faites confiance au jeton correctement formé renvoyé par l'API et définissez le cookie.

4. Deleting the cookie or setting a malformed value

Lorsque vous examinez l'URL ou que vous analysez la réponse de l'API pour déterminer si vous devez mettre à jour le cookie de l'utilisateur, veillez à ce qu'un bug présent quelque part dans votre code ne provoque pas accidentellement l'attribution d'une valeur nulle, vide ou fausse. Certains frameworks interpréteront cela comme une suppression du cookie ; de toute façon, si l'utilisateur envoie un jeton non valide lors de sa prochaine requête, un nouveau jeton lui sera attribué, ce qui le renverra en fin de file d'attente.

5. Failing to set a cookie when you redirect the user to the waiting room.

À proprement parler, il n’est pas nécessaire de définir un cookie si vous comptez rediriger cet utilisateur vers la salle d’attente. Cependant, votre intégration sera bien plus robuste si vous définissez systématiquement un cookie. En effet, l’utilisateur pourrait se retrouver sur le site d’une manière ou d’une autre avant d’avoir terminé son parcours dans la salle d’attente. Si vous le reconnaissez toujours, il sera renvoyé vers la salle d'attente en conservant sa position initiale. Dans le cas contraire, il sera renvoyé vers la salle d'attente avec une nouvelle position, à la fin de la file d'attente. Lorsqu'un utilisateur reste longtemps dans une salle d'attente, il n'est pas rare qu'il tente à nouveau d'accéder au site, éventuellement dans un nouvel onglet. C'est particulièrement vrai s'il a reçu par e-mail un lien vers la page protégée.

6. Setting an inappropriate expiry date with your cookie, or relying on temporary session storage

Compte tenu du scénario décrit ci-dessus, le délai d'expiration standard de 20 minutes associé au stockage de session intégré fourni par des frameworks tels que .NET ou PHP pourrait ne pas être suffisamment fiable dans ce cas de figure. En cas de doute, définissez un cookie de session ou un cookie permanent.

API Issues

Prenez le temps de bien comprendre les paramètres que vous envoyez et les réponses que vous pourriez recevoir. Voici les principaux problèmes que nous constatons concernant les requêtes et les réponses API :

1. Sending the wrong IP to the API

Lorsque vous transmettez l’adresse IP à la ressource sollicitée, assurez-vous d’envoyer l’adresse IP de l’utilisateur, et non celle de votre serveur ni celle d’un serveur proxy intermédiaire. Si vous transmettez la même adresse IP à plusieurs reprises, celle-ci risque d’être identifiée et bloquée. Si vous rencontrez ce problème en production, vous pouvez configurer cette adresse IP ou cette plage d’adresses pour qu’elle soit « ignorée », ce qui empêchera le blocage automatique ; toutefois, vous devez tester et corriger votre intégration afin d’identifier la bonne adresse IP. En général, si votre serveur web est derrière un proxy, vous pouvez détecter l’adresse IP réelle à partir de l’en-tête HTTP X-Forwarded-For. Ce guide pourrait vous être utile.

2. Presuming the API will respond

CrowdHandler’s raison d’être is to be available when your site isn’t. However, there are many legitimate reasons why your server may be temporarily unable to connect to the CrowdHandler API, including general internet routing issues or data center problems. If your code presumes you will always receive a well-formed response, then you are likely to display an ugly error to the user if and when these situations occur. Solutions:

  • Lors de l'appel de l'API, spécifiez un délai d'expiration court (2 secondes est la durée optimale)
  • If the call times out, or the response is not well-formed, consider what you want to do. In the majority of cases you will want to trust this user and allow access to the URL, because this means if the outage occurs while you are not running a queue the user will not be disrupted. In low-trust scenarios, you may wish to send the user to the waiting room — the CrowdHandler waiting room will attempt to establish an API connection and do the best it can with the user until it receives a well-formed response from the API.

3. Presuming the response format

Dans la plupart des cas, vous recevrez une réponse détaillée, comprenant notamment des messages destinés à la salle d'attente, etc. En voici un exemple :

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

Cependant, certaines publications ne fournissent que peu d'informations.

Par exemple, si vous vérifiez une requête concernant une URL qui n'est protégée par aucune salle d'attente CrowdHandler.

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

Other responses you may see are if your key is invalid (a 401 HTTP error), if the room is full (Status: 5), or if the IP you are sending has been placed on the blocked list (Status: 4).

Solutions:

  • Prenez le temps de comprendre la signification des codes de réponse renvoyés. Voici quelques situations que vous devrez peut-être prendre en compte.
  • Pour déterminer si l'utilisateur doit se voir accorder l'accès ou être redirigé vers la salle d'attente, il vous suffit de vérifier l'attribut booléen « promoted », qui, sauf en cas d'erreur, sera toujours présent et prendra la valeur 0 ou 1. Si votre intégration est très simple et que vous vous contentez d'examiner cet attribut, vous n'avez pas vraiment besoin de comprendre les différentes réponses et états, car si « promoted » vaut 0, vous pouvez envoyer l'utilisateur dans la salle d'attente, et celle-ci saura quoi faire.
  • If you have built an application or use a framework that requires the response object to be consistent at all times for OO reasons, you should start with your own base object or class to represent the response, specifying sensible defaults, and then set only the values that come back from the API response.