Solución de problemas en las integraciones de API personalizadas

Esta guía describe los problemas más habituales y sus soluciones a la hora de desarrollar manualmente una integración basada en una API. Deberás adaptar estos consejos a tu aplicación y a tus marcos de trabajo concretos.

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.

Para ver ejemplos de integraciones probadas en la práctica que abordan todas las cuestiones que se describen a continuación, puedes consultar nuestras integraciones en GitHub:

URL Exclusion Issues

Si tu aplicación cuenta con un controlador principal, es posible que estés redirigiendo todas las solicitudes a tu aplicación a través de una integración que consulta con CrowdHandler para permitir o denegar solicitudes de URL concretas. Esto puede dar lugar a los dos problemas siguientes:

1. Checking unnecessary URLs

Cuando un usuario carga una página, el navegador carga todos los recursos asociados a la página que se encuentran en tu dominio, y es posible que estas solicitudes se redirijan a través de tu controlador principal. Esto puede provocar que se realicen comprobaciones innecesarias, lo que aumentará el tiempo de carga y, en última instancia, la carga del servidor de tu aplicación. Te conviene excluir al menos estas extensiones de archivo habituales antes de comprobar una URL:

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

También debes excluir cualquier otra ruta de tus aplicaciones que esté relacionada con contenido que no requiera protección mediante la sala de espera. Por ejemplo, si almacenas todos los recursos estáticos en un subdirectorio llamado /static, puedes excluir esa ruta de las comprobaciones.

2. Blocking Third Party Services in the queue

Si utilizas un controlador frontal como el descrito anteriormente y dispones de servicios de terceros que realizan llamadas a las API de tu dominio protegido, es probable que estos servicios queden retenidos en la cola y no puedan continuar, ya que es poco probable que acepten cookies. Entre los servicios de terceros más habituales que pueden verse bloqueados se incluyen:

Servicios, complementos o aplicaciones que utilizan las API de tu dominio (RPC, REST)
Servicios de pago que realizan llamadas de retorno del lado del servidor a tu dominio para confirmar las transacciones.

Si los servicios utilizan un rango de direcciones IP bien definido, es posible que puedas permitir su acceso añadiendo dicho rango mediante una regla de excepción. Sin embargo, por lo general es preferible excluir estas URL de tus comprobaciones desde el principio.

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

Quizás el mayor problema que observamos con las integraciones personalizadas es la imposibilidad de establecer correctamente una cookie para realizar un seguimiento del token de CrowdHandler del usuario.

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

Tu integración debe almacenar el token CrowdHandler del usuario la primera vez que este sea redirigido a tu sitio web. No puedes dar por hecho que el token vaya a aparecer en la URL tras la primera visita tras la redirección desde la sala de espera. Deberás asegurarte de que la cookie esté configurada. Asegúrate de configurar una cookie que tu aplicación pueda leer desde las rutas posteriores que el usuario pueda visitar.

2. Failing to set Cookie because of an HTTP redirect

La razón más habitual por la que una integración no consigue establecer una cookie es que una redirección HTTP intercepta al usuario antes incluso de que se ejecute la integración y lo redirige a una nueva ruta sin pasar el token en la URL. Estas reglas de redirección pueden estar en la configuración de tu servidor web o ejecutarse al principio de la ruta de tu código para gestionar redirecciones de idioma o de inicio de sesión. Por lo tanto, si trabajas con un sitio web multilingüe o proteges una ruta que implica el inicio de sesión del usuario, presta especial atención. La solución consiste en asegurarte de que las redirecciones incluyan la cadena de consulta con el token, o de que no envíes a los usuarios directamente desde la sala de espera a una URL que los redirija de inmediato.

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

Existen motivos legítimos por los que un usuario puede verse obligado a pasar por la cola más de una vez, o puede que su sesión caduque y se le asigne un nuevo token. Por este motivo, es importante que, cada vez que veas un token de Crowdhandler en la URL, o cuando la API te devuelva un nuevo token, actualices la cookie para que coincida. De lo contrario, tu integración podría utilizar un token caducado, lo que haría que el usuario volviera a la cola.

Así pues, en tu código de integración, busca un token en la URL. Si encuentras uno, realiza la llamada utilizando el token de la URL en lugar del token que puedas encontrar en una cookie. A continuación, en cualquier caso, confía en el token válido que devuelve la API y configura la cookie.

4. Deleting the cookie or setting a malformed value

Al examinar la URL o analizar la respuesta de la API para comprobar si debes actualizar la cookie del usuario, ten cuidado de no permitir que un error en algún punto de tu código establezca accidentalmente un valor nulo, vacío o falso. Algunos marcos de trabajo interpretarán esto como una eliminación de la cookie y, en cualquier caso, si el usuario envía un token no válido en su siguiente solicitud, se le asignará un nuevo token, lo que hará que pase al final de la cola.

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

En sentido estricto, no es necesario establecer una cookie si vas a redirigir a este usuario a la sala de espera. Sin embargo, tu integración será mucho más robusta si siempre estableces una cookie. Esto se debe a que el usuario podría volver al sitio web de alguna manera antes de completar su recorrido por la sala de espera. Si aún lo reconoces, se le redirigirá de nuevo a la sala de espera, manteniendo su posición original. Si no lo reconoces, se le redirigirá de nuevo a la sala de espera con una nueva posición al final de la cola. Si un usuario permanece en la sala de espera durante mucho tiempo, no es raro que vuelva a intentar acceder al sitio web, quizá en una nueva pestaña. Especialmente si ha recibido un enlace por correo electrónico a la página protegida.

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

Teniendo en cuenta el caso anterior, es posible que el tiempo de espera habitual de 20 minutos asociado al almacenamiento de sesiones integrado que ofrecen marcos de trabajo como .NET o PHP no sea lo suficientemente robusto para esta situación. En caso de duda, configura una cookie de sesión o una cookie permanente.

API Issues

Tómate tu tiempo para comprender los parámetros que estás enviando y las respuestas que puedes recibir. Estos son los principales problemas que observamos en las solicitudes y respuestas de las API:

1. Sending the wrong IP to the API

Cuando envíes la dirección IP al recurso solicitado, asegúrate de que estás enviando la dirección IP del usuario, y no la de tu servidor ni la de un servidor proxy intermediario. Si envías la misma dirección IP muchas veces, es probable que esa dirección sea identificada y bloqueada. Si te enfrentas a esta situación en un entorno de producción, puedes configurar esa dirección IP o rango para que se «ignore», lo que evitará el bloqueo automático; no obstante, deberías probar y corregir tu integración para identificar la dirección IP correcta. Normalmente, si tu servidor web está detrás de un proxy, puedes detectar la dirección IP real a partir del encabezado HTTP X-Forwarded-For. Quizás te resulte útil esta guía.

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:

Al realizar la llamada a la API, especifica un tiempo de espera breve (lo ideal son 2 segundos).
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

En la mayoría de los casos, recibirás una respuesta detallada, que incluirá mensajes de la sala de espera, etc. A continuación te mostramos un ejemplo:

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

Sin embargo, algunos estados ofrecen una pequeña cantidad de información.

Por ejemplo, si compruebas una solicitud para una URL que no está protegida por ninguna sala de espera de 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:

Tómate un momento para comprender el significado de los códigos de respuesta que se devuelven. Estas son situaciones que quizá debas tener en cuenta.
Para saber si se debe conceder acceso al usuario o enviarlo a la sala de espera, solo tienes que comprobar el atributo booleano «promoted», que, salvo que se produzca un error, siempre estará presente y tendrá el valor 0 o 1. Si tu integración es muy sencilla y solo tienes que fijarte en este atributo, en realidad no necesitas comprender las distintas respuestas y estados, ya que si «promoted» es 0, puedes enviar al usuario a la sala de espera, y la sala de espera sabrá qué hacer.
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.

URL Exclusion Issues#

1. Checking unnecessary URLs#

2. Blocking Third Party Services in the queue#

3. Blocking your admin URLs#

Cookie Issues#

1. Failing to set a readable Cookie#

2. Failing to set Cookie because of an HTTP redirect#

3. Failing to update the Cookie#

4. Deleting the cookie or setting a malformed value#

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

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

API Issues#

1. Sending the wrong IP to the API#

2. Presuming the API will respond#

3. Presuming the response format#

Solutions:#