Especificación de un Check In

Un Check In representa el ingreso de un Player a alguna sucursal de Arena. En términos del sistema, esto quiere decir que un jugador se identificará ante el servidor onsite para que este le permita hacer uso del servicio.

Descripción general

El proceso de Check In involucra a la aplicación cliente de Kiosk, al servidor onsite y al servidor offsite.

Identificación de usuario

El primer paso consiste en obtener un check in token del servidor offsite.

_images/kiosk_identification_overview.svg
  1. La aplicación cliente Kiosk envía las credenciales del jugador al servidor offsite.
  2. El servidor offsite genera un checkin_token que envía en la respuesta a la aplicación cliente Kiosk.

Check In

Un check in se crea crea una vez que el usuario ha completado el proceso en la aplicación cliente: tiempo, categoría y juego. Esto es debido a que no hay manera de garantizar que habrá una mesa disponible al finalizar el proceso.

_images/kiosk_check_in_overview.svg

Flujo de Check In en Kiosk

El flujo, identificarse y seleccionar uno de los productos, se repite por cada uno de los jugadores que deseen entrar en la sesión.

Identificación

El proceso de identificación se realiza ante el servidor offsite. Y se realiza por cada jugador que desee hacer check in.

_images/kiosk_identification_sequence.svg

Se requieren dos endpoints:

Offsite: POST /players/check_in/with_[credentials|card]

Autorización: Kiosk

Identificación mediante nick y contraseña o tarjeta QR. Es en este momento donde Kiosk obtiene la información del jugador, que debe incluir la cantidad de coins.

Debe verificarse que la fecha de la última transacción del jugador que hace Check In sea menor a tres meses. En caso contrario, debe crearse una transacción negativa con el monto igual al saldo del jugador; esto con el objetivo de expirar sus monedas. Esta transacción no será reportada al sistema Vista.

Es posible que ocurra un conflicto en el cliente que no permita continuar con el Check In en Onsite, imposibilitando la redención del check_in_token generado en Offsite. Para prevenir la generación de múltiples tokens, Offsite realizará una comprobación de los Check Ins del jugador al momento de recibir esta petición. En caso de que este cuente con un Check In no usado, este será devuelto como resultado de la operación. Como consecuencia de devolver un token para su reuso, el registro en Offsite del Kiosk al que se otorga el Check In es ajustado.

En caso de contar con un Check In abierto para el lugar al que pertenece el Kiosk que lleva a cabo la petición, Offsite devolverá al cliente este último Check In. De esta manera, Offsite permite el reingreso a un local a lo largo del día sin registrar un nuevo token.

Nota

El check_in_token es generado de la forma SHA1(nick + time), donde nick corresponde al nick del usuario, y time es la fecha UNIX en milisegundos registrada al momento de computar el token.

Validaciones

  • En caso de que no exista el usuario con las credenciales especificadas, la contraseña esté mal o la tarjeta ya no esté vigente, los endpoints deben regresar el estado HTTP 401 y el mensaje de error debe ser algo ambiguo como Credenciales inválidas.
  • En caso de que el jugador cuente con un check in abierto en otro establecimiento, los endpoints deben regresar el estado HTTP 409.
  • En caso de que la cuenta haya sido desactivada, los endpoints deben regresar el estado HTTP 403.

Consulta de Check In activo

En caso de que el jugador esté haciendo uso de un Check In abierto, debe seguirse este flujo para comprobar el estado en Onsite. Un objeto Check In proveniente de Offsite con el campo usedAt no nulo indica que el usuario ya ha ingresado al local a lo largo del día, por lo que se hace uso de la siguiente ruta:

Onsite: GET /check_ins/{token}

Autorización: Kiosk

Mediante esta ruta se consulta el estado del token de Check In de un jugador, obteniendo así la información del producto de tiempo que se esté redimiendo actualmente (en caso de existir e independientemente del valor del tiempo restante o categoría), así como las reservaciones pendientes por redimir del jugador. Este proceso debe realizarse por Kiosk inmediatamente después de llevar a cabo el proceso de identificación.

Se devuelve la información del Check In de un jugador de la siguiente manera:

id: 3
createdAt: 1475709580
redeemableTimeProductId: 4
activeMatch:
  id: 47
  gameSystemId: 3
  joiningStationId: 6
  stationId: 4
  categoryId: 3
  zoneId: 3
  createdAt: 1479862013
  attendedAt: 1479862013
  closedAt: 1479862013
  players:
    - nick: Donnie Darko
      timeProductId: 2
    - nick: Mr Nobody
      timeProductId: 5
reservations:
  - id: 23
    number: 3
    paidCoins: 100
    timeProductId: 2
    categoryId: 2
    reservationAt: 1475699580
    redeemedAt: undefined
  - id: 67
    number: 1
    paidCoins: 300
    timeProductId: 3
    categoryId: Pl2
    reservationAt: 1475690978
    redeemedAt: undefined
id
El identificador del Check In.
createdAt
La fecha de creación del Check In en Onsite, que corresponde al momento en que un jugador efectuó el proceso en Kiosk.
redeemableTimeProductId
Identificador del producto de tiempo vigente que aún puede redimir el jugador. La recepción de este campo es opcional y su ausencia indica que el jugador no cuenta con un producto de tiempo vigente. Si el identificador no corresponde a un producto de 24 horas, el jugador no puede llevar a cabo la compra de tiempo.
activeMatch
Información de la partida actual del check in, en caso de existir.

Si no se encuentra un Check In activo que coincida con el token proporcionado, se responde con el estado 404 Not Found.

La manera de interpretar las reservaciones obtenidas es la misma que en Onsite: GET /reservations.

Consulta de reservación

El proceso de consulta de reservación se lleva a cabo ante el servidor Onsite del lugar donde se presenta el jugador. Este proceso es efectuado en caso de ser la primera vez en el día que el jugador hace Check In en un local específico. Lo anterior se valida con el campo usedAt proveniente de Offsite en el Check In.

_images/kiosk_verify_reservation_sequence.svg

Onsite: GET /reservations

Autorización: Kiosk, Assistant, Player

Esta ruta devolverá las reservaciones no canceladas a cargo del Player cuyo nombre de usuario se indique en el query nick. Las reservaciones de un jugador deben ser devueltas ordenadas de manera ascendente por el campo reservationAt, con el objetivo de que un Kiosk interprete la primera leída como la más antigua. Las reservaciones devueltas serán todas las del día en que se realiza la petición, con el objetivo de que el cliente pueda discernir si el jugador en cuestión cuenta con un bono de tiempo redimible.

Se devuelven las reservaciones de la siguiente manera:

reservations:
  - id: 23
    numberOfPlayers: 3
    paidCoins: 100
    timeProductId: 2
    categoryId: 1
    reservationAt: 1475699580
    redeemedAt: undefined
  - id: 67
    numberOfPlayers: 1
    paidCoins: 300
    timeProductId: 3
    categoryId: 2
    reservationAt: 1475690978
    redeemedAt: undefined
id
El identificador de la reservación.
numberOfPlayers
El número de personas anunciadas en la reservación.
paidCoins
La cantidad de monedas pagadas en la reservación.
timeProductId
El identificador del producto de tiempo que se adquirió para la reservación.
categoryId
El identificador de la categoría para la cual se reservó.
reservationAt
Fecha para la cual se agendó la reservación.
redeemedAt
Fecha en la que la reservación fue redimida.

Se cuenta con los siguientes parámetros de búsqueda para reservaciones, los cuales únicamente pueden ser usados por un Kiosk o un Assistant. En una consulta de reservaciones efectuada por un jugador, los criterios de búsqueda son ignorados.

Parámetro Tipo Función
nick string
Nick del jugador anfitrión de la
reservación.
include_redeemed boolean
Para solicitar incluir reservaciones
que ya han sido redimidas.
from integer
Fecha a partir de la cual desean
obtenerse reservaciones.
to integer
Fecha límite hasta la cual se
quiere obtener reservaciones.
limit integer
Limitar el resultado obtenido al
número de objetos especificado.

Si el jugador para el cual se desean obtener reservaciones tiene perfil Guest, la ruta responde con el estado 412 Precondition Failed. Si los parámetros de fecha no corresponden a valores de fecha válidos, se responde con el estado 422 Unprocessable Entity. Si Kiosk lleva a cabo la petición y no proporciona nick, se responde con el estado 400 Bad Request. Si no se encuentra al jugador, la respuesta es exitosa con un arreglo vacío de reservaciones.

Nota

Si la petición es llevada a cabo por un Player, no es necesario indicar el nick en la petición. Esto debido a que el dato puede conocerse a partir del token del jugador autenticado.

Consulta de categorías

El cliente define un periodo de tiempo para actualizar las categorías existentes en el local, obteniendo el nombre y su identificador para futuras referencias.

_images/kiosk_category_fetching_sequence.svg

La consulta de categorías se lleva a cabo como se indica en Consulta de categorías.

Consulta de los últimos juegos usados

Como parte de la funcionalidad de Kiosk, se consultan los últimos juegos usados por cada Player que efectúa un Check In. Como parte de la petición, se incluyen los nicks de los jugadores de los cuales se obtendrán los últimos 5 juegos (por jugador). Cabe señalar que la entidad Game System indica la disponibilidad de un juego para una consola específica, por lo que un juego en diferentes consolas se interpretará como juegos distintos.

_images/kiosk_last_played_sequence.svg

Onsite: PUT /games/recent

Autorización: Kiosk

Mediante la cual se obtienen los últimos juegos usados por uno o más jugadores, limitando la consulta a 5 por jugador. En caso de que un Player no cuente con más de 5 juegos en su historial, la ruta devuelve la mayor cantidad de referencias posibles.

Esta ruta responde con el estado 200 OK acompañado del gameSystemId de los juegos, debido a que deben encontrarse ya en la memoria del cliente. En caso de que uno de los nicks proporcionados no se encuentre en el sistema, no se responden juegos para dicho Player.

Elección del tiempo

Después de que un jugador se ha identificado debe escoger la cantidad de tiempo que desea adquirir. Esto requiere, primero, mostrar las modalidades (Productos) disponibles en el lugar.

_images/kiosk_products_sequence.svg

La consulta a realizar para obtener los productos de tiempo es Onsite: GET /time_products.

El cargo no se realiza sino hasta que el jugador tiene una mesa. Pero es necesario, por experiencia del usuario, detectar en este momento si el jugador tiene suficientes coins para realizar la compra. Esta validación se hará en Kiosk por lo que requiere tener la lista de precios.

Nótese que no es necesario consultar este endpoint cada que un usuario se ha identificado. Kiosk podría obtener la lista de productos al iniciar o antes de que todos los jugadores empiezen a identificarse.

Es necesario que Kiosk valide también que los productos escogidos por todos los jugadores realizando el proceso sean compatibles. Por ejemplo: todos deben seleccionar un producto de la misma categoría. Esto requiere que el modelo de productos maneje una categoría por la que pueda ser agrupada. De lo contrario el sistema no aceptará el check in.

Onsite: GET /games/by_system

Autorización: Kiosk, Timer, Assistant

_images/kiosk_games_sequence.svg

Este endpoint permite acceder a la lista de copias disponibles de juegos en el establecimiento. Es decir, si un juego está disponible para tres sistemas de entretenimiento, el título aparecerá tres veces en el listado de este endpoint. Es importante notar que en caso de que un juego sea destacado, se devuelve además la liga a una imagen con dimensiones especiales del mismo.

Ejemplo:

games:
  - gameSystemId: 1234
    name: Killing Floor 2
    system:
      id: 6
      name: PC
    pathToLauncher: /Games/KillingFloor2/kill2.exe
    isHighlight: false
    maxPlayers: 1
    esrb: M
    description: 6-player co-op Zed-slaughtering mayhem. And now, 12-player Versus Survival mode, too - now you can BE the Zeds!
    timesPlayed: 23
    tags:
      - multiplayer
      - gore
      - zombies
    cover: https://www.googleapis.com/storage/v1/b/arena-test-bucket/o/1475699580391_94721.jpg
    screenshots:
      - https://www.googleapis.com/storage/v1/b/arena-test-bucket/o/1475699580399_72512.jpg
      - https://www.googleapis.com/storage/v1/b/arena-test-bucket/o/1475699580408_99334.jpg
  - gameSystemId: 28
    name: FIFA 16
    system:
      id: 4
      name: XBOX One
    isHighlight: true
    maxPlayers: 4
    esrb: PG13
    description: Get ready for the biggest season yet! FUT Champions and Squad Building Challenges give players new ways to compete and earn rewards in FIFA's most popular mode.
    timesPlayed: 127
    tags:
      - multiplayer
      - sports
      - soccer
    cover: https://www.googleapis.com/storage/v1/b/arena-test-bucket/o/1475699580323_82345.jpg
    screenshots:
      - https://www.googleapis.com/storage/v1/b/arena-test-bucket/o/1475699580465_90123.jpg
    highlight: https://www.googleapis.com/storage/v1/b/arena-test-bucket/o/1475699580391_94721.jpg
  - gameSystemId: 29
    name: FIFA 16
    system:
      id: 5
      name: PS4
    isHighlight: false
    maxPlayers: 4
    esrb: PG13
    description: Get ready for the biggest season yet! FUT Champions and Squad Building Challenges give players new ways to compete and earn rewards in FIFA's most popular mode.
    timesPlayed: 86
    tags:
      - multiplayer
      - sports
      - soccer
    cover: https://www.googleapis.com/storage/v1/b/arena-test-bucket/o/1475699580576_17324.jpg
    screenshots:
      - []
gameSystemId
El identificador de la copia disponible para un sistema. En Onsite, este modelo es GameSystem.
name
El nombre del juego.
system.id
El identificador del sistema de entretenimiento.
system.name
El nombre del sistema de entretenimiento.
pathToLauncher
La ruta al ejecutable del juego en el sistema. Este campo es opcional y únicamente está presente para PCs.
isHighlight
Indica si el juego debe mostrarse como un destacado ante el cliente.
maxPlayers
El número máximo de jugadores que permite el juego.
esrb
La clasificación ESRB.
timesPlayed
El número de veces que se ha utilizado el juego.
description
La descripción del juego.
tags
La lista de tags del juego.
cover
La liga a la imagen de la portada del juego.
screenshots
Un arreglo con las capturas de pantalla del juego.
highlight
La liga a la imagen del juego como destacado.

La ruta responde con el estado 200 Ok acompañado de las copias de los juegos que cumplen con la petición. Esta consulta admite los parámetros system_name para buscar los juegos con una consola en específico; y exclude_system para excluir la consola con el nombre proporcionado de la respuesta.

Creación de Match

Después de la elección de tiempo, el grupo de jugadores confirma la operación y procede a la creación de un match, que corresponde a la representación de la partida en la que participarán los jugadores. Como consecuencia, Onsite valida los tokens proporcionados contra el servidor Offsite.

Onsite: POST /matches

Autorización: Kiosk

Este es el endpoint encargado de crear un check in en Onsite, cuya petición lleva por cuerpo lo siguiente:

kioskCheckIn:
  gameSystemId: 1234
  joiningStation: TV021
  categoryId: 2
  checkIns:
    - productId: 11
      token: j5JSetsgHnpEpQPAY2J5a4KfeDrWGzWdx7jGMx68wKezRyfW
    - reservationId: 624821
      token: f7CJU48YNsBevWNnRyBbvmb7WN3gYyz2y6RfKvDt36Mb999q
    - productId: 12
      token: CSnz6pKD8EXqHeWJyKDx4Lw4bmuRk9c2YKx7cUpxUFaFMDGg
gameSystemId
El identificador a la copia disponible elegida por el usuario. Este campo es opcional y su ausencia indica que el Match proviene de una división de jugadores o que se procederá a unir a una mesa.
joiningStation
Nombre de la estación a la cual desea unirse el grupo de jugadores que llevan a cabo el Check In. Este campo es opcional y aplica únicamente en el flujo de Unirse a estación.
categoryId
El identificador de la Categoría elegida para buscar mesa.
reservationId
El identificador de la reservación que se va a redimir. Este campo es opcional.
checkIns
Una lista de objetos que tienen dos elementos.
productId / reservationId
El id del producto elegido por el usuario, o el id de reservación a redimir. En caso de usar un Check In abierto previamente, este campo no es incluido en la solicitud.
token
La autorización de Check In proporcionada por Offsite.

Si el proceso es llevado a cabo de manera exitosa, se responde con el estado 201 Created acompañado del Match creado.

Es posible que un jugador acuda a Kiosk cuando ya cuenta con un Check In abierto. Si el Check In abierto presenta un producto de tiempo vigente, se tienen los siguientes escenarios:

  1. Si el producto de tiempo del jugador es de 24 horas, sólo se permite la creación del Match si el jugador desea adquirir un producto o redimir una reservación para una categoría superior. Si esto no se cumple, se responde con el estado 409 Conflict.
  2. Si el producto de tiempo del jugador no es de 24 horas, no es posible llevar a cabo este proceso desde Kiosk. Se responde con el estado 409 Conflict.
  • En caso de que alguno de los identificadores no sea válido, el sistema debe responder con el estado 400 Bad Request y el mensaje de error debe indicar qué campo es el inválido.
  • En caso de que los productos no sean compatibles (todos deben ser de la misma categoría), el sistema debe responder con el estado 400 Bad Request.
  • Si alguna de las autorizaciones de check in no es válida, el sistema debe responder con el estado 403 Forbidden y el mensaje de error debe indicar qué clave de autorización es la que está mal.
  • Una reservación únicamente puede redimirse si la fecha reservationAt difiere a lo más en 10 minutos con la fecha actual. En caso de que el tiempo sea mayor, se responderá con el estado 409 Conflict.
  • En caso de que alguno de los Player ya se encuentre jugando en un Match activo, la ruta devuelve el estado 409 Conflict.
  • Si el número de jugadores dentro del Match es mayor a ocho, se responde con el estado 422 Unprocessable Entity.
  • Si la cantidad de copias de un juego ocupadas en partidas no cerradas al momento de la petición es igual al stock, se responde con el estado 409 Conflict.
  • Si se solicita jugar en una PC y el campo gameSystemId o joiningStation está presente, se responde con el estado 422 Unprocesable Entity.
  • Si no existen estaciones de tipo PC para la categoría indicada, se responde con el estado 409 Conflict.
  • Si la estación a la que se desea unir no existe, se responde con el estado 404 Not Found.
  • Si la estación a unirse no se encuentra en uso al momento de efectuar la petición, se responde con el estado 422 Unprocessable Entity.
  • Si para alguno de los jugadores no se proporciona un producto de tiempo y no cuenta con un producto de 24 horas redimible, se responde con el estado 422 Unprocessable Entity.
  • Si los códigos de reservación no son compatibles entre sí o con los productos de tiempo se devuelve el estado 422 Unprocessable Entity.

Como consecuencia del procesamiento exitoso de la petición, se notifica a los asistentes de la creación de un nuevo Match como se indica en Onsite broadcast: create_match. Si uno o más jugadores se encontraban en el pool de Check Ins, la salida de éste es notificada a los asistentes como se indica en Onsite broadcast: delete_checkin.

Offsite: PUT /players/check_ins

Autorización: Location

_images/kiosk_check_in_sequence.svg

Este endpoint recibe una lista de códigos de autorización existentes para marcarlos como usados. En caso de que un servidor Onsite proporcione un Check In usado, este únicamente será aceptado si proviene el local donde se creó, esto para garantizar el reingreso al mismo local a lo largo del día.

  • En caso de que el jugador cuente con un check abierto para un torneo en curso, se responde con el estado 403 Forbidden.
  • En caso de que Onsite no tenga ningún check in con el código de autenticación detectado, debe responder con un estado 404 Not Found.
  • En caso de proporcionar un código de Check In abierto que no corresponde al local que lleva a cabo la petición, se responde con el estado 409 Conflict.

Consejo

Al recibir respuesta de esta petición, Onsite actualiza el valor avatarUrl del jugador para que coincida con aquel devuelto por el servidor Offsite.

Unirse a estación en uso

Como opción a jugar en una estación, es posible que un Player o un grupo de Players se unan a una partida en curso, y por consiguiente, al grupo de jugadores que se encuentren participando en la misma.

Un Kiosk hace uso de la ruta Onsite: GET /stations/matches para buscar una estación proporcionando el nombre de la misma. A continuación, el servidor Onsite devuelve la información de la estación solicitada: el Match que actualmente está siendo jugado (en caso de existir), así como los Players que integran el mismo. En caso de no contar con un Match vigente, la estación requerida no es candidata a la opción Unirse a una mesa y, por lo tanto, debe retornarse un error desde el cliente Kiosk.

En caso de unirse a una mesa, el cliente Kiosk completa la información del flujo normal de Check In con los datos del Match que se encuentra siendo jugado en la estación deseada. Para finalizar, el Kiosk envía la información en la llamada Onsite: POST /matches sin incluir el campo gameSystemId, indicando así que el Check In actual no cuenta con juego seleccionado.

Las validaciones que deben suceder desde Kiosk al recibir la información de la estación son las siguientes:

  • La estación indicada en el parámetro name debe retornar un arreglo no vacío de estaciones (comprobando así que la estación exista).
  • El número de Players que se encuentren en el momento en la estación deseada (el número de Players devueltos), debe ser menor a ocho, garantizando así que la estación tenga cupo
  • La estación a unirse debe contar con capacidad para la cantidad de Players que deseen ingresar.
  • La estación debe estar siendo usada en el momento, es decir, debe verificarse que la estación obtenida cuente con un Match.

Creación de Check In

Si un jugador no reconoce ninguna de las opciones presentadas por el quiosco de identificación como aquella de su preferencia, le es permitida únicamente la creación de un Check In en Onsite. Mediante dicho Check In, el jugador se vuelve visible desde el listado de Check Ins en la aplicación de asistente. A continuación se indica la ruta que permite dicho comportamiento.

Onsite: POST /check_ins

Autorización: Kiosk

Solicita al servidor la generación de un Check In, proporcionando la autorización otorgada por el servidor Offsite. El cuerpo de la petición es el siguiente:

token: j5JSetsgHnpEpQPAY2J5a4KfeDrWGzWdx7jGMx68wKezRyfW
token
La autorización de Check In proporcionada por Offsite.

En consecuencia, se valida con el servidor Offsite el token de Check In como se indica en Offsite: PUT /players/check_ins, para posteriormente crear el Check In localmente.

La ruta responde con el estado 201 Created acompañado del Check In recién creado.

Si el token proporcionado no es válido, se responde con el estado 403 Forbidden. Si ya existe un Check In abierto en la sucursal para el jugador asociado al Check In proporcionado, se responde con el estado 412 Precondition Failed.

La creación exitosa del Check In se notifica a los asistentes como se indica en Onsite broadcast: create_checkin.

Observaciones sobre reservación

  • Un jugador puede redimir reservaciones 10 minutos antes o después de la fecha establecida en el campo reservationAt. Fuera de este intervalo, no es posible redimir una reservación.
  • En caso de que varios jugadores cuenten con reservación redimible al momento de hacer check in, se redimirá aquella que se incluya en el campo reservationId del objeto kioskCheckIn. Como lógica de Onsite, se verifica si alguno de los otros jugadores involucrados en el check in cuenta con reservación. De ser el caso, sus reservaciones se marcan como usadas si el producto de tiempo reservado es compatible con aquel de la reservación principal, ajustando el cobro de tiempo para el usuario. Por el contrario, si el producto del jugador adicional no es compatible, se cancela la reservación de dicho jugador, reteniendo el monto que fue pagado al hacer la reservación.

Flujo de Check In en Assistant

Notificación de un Match

_images/check_in_sequence.svg

Al momento de terminarse el proceso de check in desde un Kiosk en el local, la creación de la partida debe notificarse a todos los asistentes como se indica en Onsite broadcast: create_match.

Consulta de matches

_images/query_matches_sequence.svg

Puede ocurrir que, debido a un error de conexión o a un nuevo inicio de sesión, un asistente no reciba las notificaciones de match. Por esto, debe contemplarse una ruta para obtener las notificaciones de nuevos Match de manera manual.

Onsite: GET /matches

Autorización: Assistant

Mediante esta ruta pueden consultarse los Match existentes en el local. Para conocer aquellos que no han sido atendidos aún, puede hacerse una consulta usando el parámetro attended.

La ruta responde con el estado 200 OK con una respuesta como la siguiente

match:
  id: 47
  gameSystemId: 3
  joiningStationId: 4
  categoryId: 3
  zoneId: 3
  createdAt: 1479862013
  players
    - nick: Donnie Darko
      avatarUrl: https://www.googleapis.com/storage/v1/b/arena-onsite-bucket/o/1475281865163-0.9304038190748543
      timeProductId: 2
      expiresAt : 1480642412
    - nick: Mr Nobody
      avatarUrl: https://www.googleapis.com/storage/v1/b/arena-onsite-bucket/o/1475281865163-0.9304038190748543
      timeProductId: 5
      expiresAt : 1480642412
  stationId: 23

División de jugadores

_images/update_match_sequence.svg

En caso de que un grupo de jugadores desee dividirse, es posible expulsar del Match actual a dichos jugadores. Esto se hace con el fin de que los jugadores expulsados sean visibles en un pool de Check Ins y puedan ser atendidos de manera adecuada.

Onsite: PUT /matches/{id}/players

Autorización: Assistant

Mediante esta ruta se actualizará la información de la partida indicada en la ruta por el parámetro ìd. Deben proporcionarse los nicks de los jugadores que permanecen en la partida mediante el siguiente cuerpo de petición:

nicks:
  aleeexkj
  susuhml

ocasionando así que los jugadores no incluidos en el mensaje sean removidos de la partida. Al ser removidos, dichos jugadores se añadirán a un nuevo Match, por lo que se encontrarán disponibles para ser agregados a una estación distinta.

Si la partida en la que se dividen jugadores cuenta con reservación, esta se asigna al Match que sobrevive a la división en caso de que el jugador responsable se encuentre en la partida. Si uno de los jugadores expulsados cuenta con reservación redimible, esta debe persistir.

La ruta responde con el estado 200 OK si los usuarios pudieron ser separados exitosamente. De manera adicional, tanto el Match creado con los nuevos jugadores como el actualizado deben notificarse a los asistentes.

Si uno o más de los jugadores a los que se quiere separar no se encuentran en la partida actual, o si el match referenciado no existe, esta ruta responde con el estado 404 Not Found.

Si se recibe un arreglo de jugadores vacío, o si se proporcionan todos los jugadores (indicando así que todos permanecen en la partida), la ruta responde con el estado 422 Unprocessable Entity.

El propósito de esta ruta es dividir un Match previo a su asignación a una estación. Si el Match se encuentra asignado a una estación, se responde con el estado 403 Forbidden.

Dado que la invocación a esta ruta genera un nuevo Match, la remoción de la partida original debe notificarse como se indica en Onsite broadcast: delete_match. El par de Matches que contienen a los jugadores separados se notifica como se indica en Onsite broadcast: create_match.

Borrado de la partida

_images/delete_match_sequence.svg

Es posible que al momento de ser atendidos por un asistente, un grupo de jugadores ya no desee llevar a término el proceso de asignación a una estación, por lo que el asistente debe ser capaz de eliminar el Match en cuestión. Lo anterior se logra mediante la invocación a la siguiente ruta:

Onsite: DELETE /matches/{id}

Autorización: Assistant

Mediante la cual se elimina del sistema la partida cuyo identificador se incluye como parámetro en la ruta.

Esta ruta responde con el esta 200 OK acompañada de la partida eliminada del sistema. Si la partida indicada no fue encontrada, se responde con el estado 404 Not Found. Si el match que se desea eliminar ya dio inicio, es decir, el campo attended_at es no nulo, se responde con 403 Forbidden.

Si un jugador en el Match eliminado no cuenta con un producto de tiempo activo, el Check In es cerrado en Offsite y en la sucursal. En otro caso, se envía al jugador al pool de Check Ins con el tiempo pausado. Si un jugador cuenta con un producto de tiempo no pagado, éste es eliminado del sistema.

La eliminación de un Match del sistema se notifica a los asistentes como se indica en Onsite broadcast: delete_match, y la salida de los jugadores del Match se notifica a los asistentes como se indica en Notificación de un Check In en el pool.

Asignación de jugadores a estación

_images/match_station_sequence.svg

Un asistente tiene la opción de atender un Match creado en Kiosk, asignando a los jugadores a una estación compatible con los productos de tiempo que se adquirieron o se reservaron.

Onsite: PUT /stations/{id}/matches

Autorización: Assistant

Mediante esta ruta se asignan una partida o un jugador a la estación referenciada en el parámetro id, tomando en cuenta si la estación donde se jugará está siendo ocupada o está disponible. El cuerpo de la petición es el siguiente:

{
  "matchId" : 3,
  "checkInId": 5,
  "gameSystemId" : 45
}

Donde matchId corresponde al identificador de la partida que se asignará a la estación indicada en la ruta, checkInId corresponde al identificador del Check In que se unirá a la estación (en caso de aplicar), y gameSystemId corresponde al ejemplar de juego que se usará. Si se asigna un Match a una estación libre y se proporciona el campo gameSystemId, dicho campo se actualizará en el Match sin necesidad de crear uno nuevo.

A continuación se describe el comportamiento de la ruta en función de los campos presentes.

Unir un Match a una estación

A continuación se ilustra el proceso de agregar un Match a una estación. Se contempla cuando la estación a la que se agregarán los jugadores está libre y cuando ya existen jugadores en la misma. Este flujo es llevado a cabo si el campo matchId está presente en el cuerpo de la petición.

Se tienen dos objetos Match a lo largo del proceso:

  • Match 1. Aquel que está siendo jugado en la estación a la que se agregarán jugadores. Este Match no existe en caso de que la estación esté libre.
  • Match 2. Aquel que tiene a los jugadores que se unirán a alguna estación, la cual debe contar con la consola compatible con el juego elegido en el Match.
_images/join_station_diagram.svg

Donde para procesar cada Check In del Match 2 se debe:

  • Validar que la Categoría de cada Time Product adquirido sea compatible con la categoría de la nueva estación.

Adicionalmente, de existir un Match 1 se debe:

  • Pausar el tiempo de los jugadores que actualmente se encuentran redimiendo un producto en la estación.
  • Guardar los respectivos Check Ins de los jugadores que permanecen en la estación.
  • Asociar los Check Ins de los jugadores al Match 2

Posterior a las validaciones sobre la ocupación de la estación y compatibilidad de consolas en la estación con el juego del Match, se solicita autorización para procesar el descuento en moneda Arena de cada uno de los jugadores como se indica en Redención de un producto de tiempo; lo cual únicamente se lleva a cabo si los jugadores no tienen producto de tiempo adquirido. Si alguno de los jugadores cuenta con una reservación bonificable, se hace uso de la misma como se indica en Reglas para redención de reservación. Posteriormente, se confirma la asignación de los jugadores a la estación.

En caso de asignar correctamente la partida a una estación, se agregan los correspondientes registros de inicio de tiempo de cada jugador, y se establece el campo attended_at del Match como la fecha actual. Adicionalmente, se agenda el cambio a la señal “muerta” con fecha de aplicación igual al menor tiempo de juego de entre los jugadores participantes. Posteriormente, se responde con el estado 200 OK y se notifica al Timer de la nueva disposición de jugadores y tiempo como se indica en Onsite broadcast: update_match.

El Match previo a la adición de los jugadores adicionales se cierra, y su remoción debe ser notificada a los asistentes y al Timer asociado como se indica en Onsite broadcast: update_match.

Cuando este proceso es llevado a término de manera exitosa, debe notificarse a los asistentes en el local de la no disponibilidad del Match para ser asignado, por lo que debe enviarse un mensaje como se describe en Onsite broadcast: delete_match. El nuevo Match se notifica a los asistentes como se indica en Onsite broadcast: update_match.

Si el identificador de partida corresponde a un Match que ya ha sido atendido, esta ruta responde con el estado 403 Forbidden.

Si el identificador de estación proporcionado no corresponde a ninguna entidad conocida, se responde con el estado 404 Not Found.

Se responde con el estado 409 Conflict en cualquiera de los siguientes casos:

  • La categoría en que se encuentra la estación no es compatible con los productos de tiempo de los jugadores.
  • Se solicita asignar a la estación a algún jugador que no cuenta con tiempo disponible.
  • Uno o más jugadores no cuentan con la moneda Arena suficiente para efectuar la compra del producto de tiempo. En este caso se indica el nick de los usuarios con saldo insuficiente.
  • La copia del juego solicitada no se encuentra disponible.
  • La estación destino no cuenta con la consola para hacer uso del juego solicitado.

Si el match no cuenta con la información del juego que se usará en la partida y no se proporciona en la petición el identificador del mismo (a excepción de PC), la ruta responde con 422 Unprocessable Entity.

Si la estación no cuenta con un dispositivo Timer vinculado y aceptado, esta ruta responde con el estado 410 Gone.

En caso de se haya hecho uso de una o más reservaciones como bonificación para la partida, se notifican las reservaciones redimidas como en Onsite broadcast: update_reservation.

Unir un Check In a una estación

A continuación se describe el proceso para agregar el Check In de un jugador a una estación. Este flujo es llevado a cabo cuando el campo checkInId está presente en el cuerpo de la petición.

Se tienen los siguientes dos casos:

La estación a unir está libre.
De no existir jugadores haciendo uso de la estación, se crea un Match perteneciente al Check In indicado, para posteriormente ser asignado a la estación. El tiempo del jugador se reanuda e inmediatamente es pausado por un máximo de 7 minutos para representar el tiempo de configuración.
La estación a unir está ocupada.
De exisitr un Match haciendo uso de la estación a unir, se hace una verificación de capacidad de la misma. Si la capacidad de la estación alberga a un jugador adicional, se cierra el Match actual pausando los tiempos de los jugadores que pertenecen a este, se crea un nuevo Match que cuente con los jugadores de la partida original más el nuevo Check In, y posteriormente se activa el tiempo de los jugadores de la estación. La expiración de la partida se establece con el calendarizador como el momento de expiración del tiempo de los jugadores más próximo a vencer. El juego de esta partida será el que estaba siendo usado en el Match previo de la estación.

La ruta responde con el estado 200 OK acompañado del Match integrado por todos los jugadores.

Si el Check In a unir se encuentra actualmente jugando en una partida, se responde con el estado 403 Forbidden. Si el Check In no se encuentra, se responde con el estado 404 Not Found. Si se proporcionan en la ruta tanto matchId como checkInId se responde con el estado 400 Bad Request. Si el jugador a unir no cuenta con tiempo disponible, si la copia del juego no se encuentra disponible, o si la estación destino no cuenta con la consoola para hacer uso del juego indicado, se responde con el estado 409 Conflict.

Si la estación a unirse no permite a un jugador adicional o cuenta con un Match grupal en curso, o si se une a una estación libre y no se proporciona juego, se responde con el estado 422 Unprocessable Entity.

Si la estación no cuenta con un dispositivo Timer vinculado y aceptado, esta ruta responde con el estado 410 Gone.

El Match previo a la adición del jugador adicional se cierra, y su remoción debe ser notificada a los asistentes y al Timer asociado como se indica en Onsite broadcast: update_match.

Posteriormente, se notifica a los asistentes y al Timer asociado de la nueva disposición de jugadores y tiempo como se indica en Onsite broadcast: update_match. El jugador agregado a la partida es removido del pool de Check Ins mediante una notificación del estilo Onsite broadcast: delete_checkin.

Notificación de Match eliminado

_images/deleted_match_sequence.svg

Cuando un asistente atiende un check in, el Match asociado debe removerse del pool de notificaciones, por lo que el servidor Onsite debe notificar a los asistentes. Lo anterior se logra difundiendo el mensaje Onsite broadcast: delete_match.

Como consecuencia de la recepción de este mensaje, el cliente Assistant cambia localmente el estado de la estación indicada en el match de disponible a en uso. Adicionalmente, hace uso del valor expiresAt para calcular los tiempos de notificación al usuario sobre el próximo vencimiento del tiempo de la estación. También es posible obtener la información de los Match de todas las estaciones mediante la ruta Consulta de estaciones.

El usuario del cliente Assistant debe ser notificado 15 y 5 minutos previos a la expiración del tiempo de una partida.

Nota

El campo closedAt es devuelto únicamente en caso de que el Match haya llegado a su fin, marcando el tiempo en que el término de la partida es registrado en Onsite.

Grupo de matches

El siguiente comportamiento contempla la adquisición por parte de un jugador de múltiples productos de tiempo en distintas estaciones, donde no necesariamente la cantidad de productos adquiridos coincide con la cantidad de estaciones empleadas.

Onsite: POST /match_groups

Autorización: Assistant

Mediante esta ruta se solicita al sistema la creación de un grupo de matches asociados a un jugador. El cuerpo de la petición es el siguiente:

checkInId: 78439
stations:
  - id: 12
    timeProductId: 4
    quantity: 3
  - id: 67
    timeProductId: 8
    quantity: 2
checkInId
Identificador del Check In del jugador al cual se efectuará el cargo correspondiente a todas las compras de tiempo.
stations[].id
Identificador de la estación a reservar.
stations[].timeProductId
Identificador del producto de tiempo a adquirir sobre la estación.
stations[].quantity
Cantidad de ejemplares del producto de tiempo que se adquieren para la estación.

Como consecuencia de la recepción de la petición, se valida que todas las estaciones indicadas se encuentren sin partidas en uso, para posteriormente efectuar el cargo al jugador con el identificador de Check In proporcionado por el monto total de productos de tiempo adquiridos. El tiempo compartido de las estaciones es puesto en pausa con el objetivo de otorgar tiempo de configuración a todas las estaciones.

Si la operación es exitosa, se responde con el estado 201 Created acompañado de la siguiente información:

id: 56
nick: Zoomyzoomyzoom
avatarUrl: https://www.googleapis.com/storage/v1/b/arena-onsite-bucket/o/1475281865163-0.9304038190748543
isTimeRunning: true
createdAt: 1480641789
closedAt: null
expiresAt: 1480642412
stations:
  - id: 12
  - id: 67

Adicionalmente, se notifica a los asistentes y los Timers acerca de la creación de las partidas como se indica en Onsite broadcast: update_match_group.

Se responde con el estado 409 Conflict bajo cualquiera de los siguientes casos:

  • La categoría a la que pertenece alguna de las estaciones proporcionada es distinta con el producto de tiempo que se contrata para jugarse en dicha estación.
  • Al menos uno de los productos de tiempo contratados cuenta con una cantidad de minutos distinta a los demás.
  • Una o más estaciones no pudieron ser encontradas.
  • Para al menos una de las estaciones, se intenta adquirir una cantidad de productos de tiempo mayor a 8.
  • El jugador cuenta con un Match o un Match Group activo al momento de la petición.

Se responde con el estado 412 Precondition Failed bajo cualquiera de los siguientes escenarios:

  • Alguna de las estaciones está en uso al momento de la petición.
  • El check in al cual se efectuará el cargo no está activo o no existe.
  • El jugador dueño del check in no cuenta con la cantidad de ares suficientes para liquidar la transacción.
  • Alguna de las estaciones no cuenta con un Timer vinculado.

Onsite: GET /match_groups

Autorización: Assistant

Mediante esta ruta, se obtiene registro de todas las partidas grupales activas en la sucursal al momento de la petición. La ruta responde con el estado 200 OK acompañado de la siguiente información:

- id: 56
  nick: Zoomyzoomyzoom
  avatarUrl: https://www.googleapis.com/storage/v1/b/arena-onsite-bucket/o/1475281865163-0.9304038190748543
  isTimeRunning: true
  createdAt: 1480641789
  closedAt: null
  expiresAt: 1480642412
  stations:
    - id: 12
    - id: 67

Flujo de Check In en Timer

Notificación de nuevo Match

_images/start_match_sequence.svg

Cuando un match es atendido por un asistente, debe ser notificado al cliente Timer con el objetivo de activar la aplicación e iniciar el temporizador.. Esto se logra mediante el mensaje Onsite broadcast: update_match.

En consecuencia a la recepción de este mensaje, el cliente consulta en su base de datos local los minutos correspondientes a cada producto de tiempo y los muestra a los jugadores. Posteriormente, debe consultar el balance de monedas del jugador mediante la ruta:

Offsite: GET /players/coins

Autorización: Timer, Assistant

Mediante esta ruta se consulta la información de monedas de los jugadores solicitados. Si la operación es exitosa, se responde con el estado 200 OK acompañado de la siguiente información:

- nick: aleexj
  coinsPerCountry:
    - coinAmount: 450
      isoCode: USD
    - coinAmount: 200
      isoCode: MXN
- nick: susu
  coinsPerCountry:
    - coinAmount: 0
      isoCode: USD
    - coinAmount: 350
      isoCode: MXN

Se hace uso de los siguientes parámetros de consulta para filtar la búsqueda de monedas

Parámetro Tipo Función
iso_code string
Código de país para filtrar los
monederos de los jugadores.

Para cada jugador incluido en la respuesta, debe verificarse que la fecha de su última transacción sea menor a tres meses. En caso contrario, debe crearse una transacción negativa con el monto igual al saldo del jugador; esto con el objetivo de expirar sus monedas. Esta transacción no será reportada al sistema Vista.

Si uno o más jugadores solicitados en la petición no existen, se responde con el estado 404 Not Found.

En caso de ocurrir una desconexión del Timer hacia el servidor es necesario contar con una forma de obtener los Match aosciados a la entidad que los solicita. Esto se logra medianta la invocación a la ruta

Onsite: GET /timers/status

Autorización: Timer

Mediante esta ruta puede consultarse la información del Timer, así como la partida que se juega actualmente en la estación, en caso de existir. La ruta responde con el estado 200 OK con un cuerpo como el que sigue

id: 2
name: CUTi2012
match:
  id: 47
  stationName: TV003
  isTimeRunning: true
  players:
    - nick: Donnie Darko
      avatarUrl: https://www.googleapis.com/storage/v1/b/arena-onsite-bucket/o/1475281865163-0.9304038190748543
      timeProductId: 2
      expiresAt : 1480642412
    - nick: Mr Nobody
      avatarUrl: https://www.googleapis.com/storage/v1/b/arena-onsite-bucket/o/1475281865163-0.9304038190748543
      timeProductId: 5
      expiresAt : 1480642412
matchGroup:
  id: 45
  nick: Karen RoMa
  avatarUrl: https://www.googleapis.com/storage/v1/b/arena-onsite-bucket/o/1475281865163-0.9304038190748543
  isTimeRunning: true
  createdAt : 1480641673
  expiresAt : 1480642412
  closedAt : 1480642412
  stations:
    - id: 5
    - id: 7
tournamentMatch:
  tournamentXid: 3
  teamIds:
    - 2
    - 3

Advertencia

Cabe mencionar que la presencia de los campos match, matchGroup y tournamentMatch es excluyente. Se incluyen como ejemplo y con el fin de mostrar la respuesta obtenida en caso de que se esté jugando una partida normal, grupal, o de torneo en una estación.

Onsite: POST /stations/standby_status

Autorización: Scheduler

Mediante este ruta se notifica a Onsite del cambio en la señal de video efectuado a una estación, con el fin de que se tomen acciones sobre el tiempo de los jugadores. La petición lleva el siguiente cuerpo

{
  "stationName" : "TV004"
}

En consecuencia, se pausa el tiempo de los jugadores en el match que actualmente se encuentre activo en la estación indicada, cambiando la entrada de la pantalla de la estación a la señal muerta. Si el tiempo de alguno de los jugadores ha vencido al momento de recibir la petición, o difiere de la fecha de término en a lo más 5 segundos, se finaliza añadiendo el registro correspondiente al historial de tiempos del jugadores.

El Match cerrado, así como el Match recién creado con los jugadores que aún tienen tiempo, son notificados como se indica en Onsite broadcast: update_match. Los jugadores cuyo tiempo se agote son agregados al pool de Check Ins mediante una notificación como en Onsite broadcast: create_checkin.

La ruta responde con el estado 200 OK para confirmar la recepción del mensaje. Si la estación indicada no existe se responde con 404 Not Found. Si en la estación no se encuentran actualmente jugadores, se responde con el estado 409 Conflict. Ambos errores son indicados por protocolo; sin embargo, el obtener alguno de ellos sería un indicador de un estado inconsistente.

Onsite: POST /match_groups/stations/standby_status

Autorización: Scheduler

Mediante esta ruta se notifica a Onsite del cambio en la señal de video en un grupo de estaciones correspondientes a un grupo de Matches, con el fin de que Onsite tome acción sobre el tiempo en cada una de las estaciones. El cuerpo de la petición es el siguiente:

{
  "matchGroupId" : 38293
}

En consecuencia, se pausa el tiempo en cada una de las estaciones donde se juega el Match Group, cambiando la entrada de la pantalla de las estaciones a la señal muerta. Si el tiempo del jugador a quien se asocia el Match grupal ha vencido al momento de recibir la petición, o difiere de la fecha de término en a lo más 5 segundos, se agrega un registro de finalización a la partida grupal.

El Match cerrado es notificado como se indica en Onsite broadcast: update_match_group. El jugador cuyo tiempo se agota es agregado al pool de Check Ins mediante una notificación como en Onsite broadcast: create_checkin.

La ruta responde con el estado 204 No Content indicando que la recepción del mensaje fue exitosa. Si el Match Group no existe o no se encuentra activo al momento de la petición, se responde con el estado 404 Not Found. Dicho error es protocolario; sin embargo, el obtener alguno sería un indicador de un estado inconsistente.

Término del tiempo de un Match

Cuando Onsite es notificado del cambio de señal en una estación por la señal de bloqueo de pantalla, efectúa una comprobación del tiempo de los jugadores. En consecuencia, agrega los correspondientes registros end a aquellos jugadores cuyo tiempo haya finalizado, y un registro pause si aún se cuenta con tiempo redimible.

Para cada jugador cuyo tiempo llega a su fin, es necesario notificar a los Asistentes de las nuevas adiciones al pool de Check Ins como se indica en Notificación de un Check In en el pool.

Cierre de Check In

Assistant

Es posible que un asistente cierre un Check In de un jugador en el local. Como consecuencia de esta acción, el servidor Onsite solicita el cierre del Check In en Offsite como se describe a continuación.

Onsite: POST /players/check_out

Autorización: Assistant

Mediante esta ruta, un asistente solicita la remoción del Check In vigente de un grupo de jugadores ante Onsite. Este último cierra los Check In en Offsite para después removerlos localmente. Después de este procedimiento, cualquier tiempo contratado por los jugadores (distinto a una reservación) se vuelve inutilizable.

La ruta responde con el estado 200 Ok acompañado de los Check In recién cerrados. Si los jugadores cuentan con un Match activo al momento de realizar esta petición, o si los jugadores no cuentan con un Check In vigente en el local; sus correspondientes registros no son devueltos en la respuesta.

Onsite

A continuación se indica la ruta que es usada por el servidor Onsite para poner término a los Check Ins efectuados a lo largo del día en el local. Esta ruta debe invocarse de manera automática en intervalos de 24 horas.

Offsite: DELETE /players/check_ins

Autorización: Location

Mediante esta ruta, Offsite es notificado del cierre de los Check In contenidos en la petición. Como efecto de la recepción de esta petición, Offsite cierra los Check In abiertos proporcionados, mismos que hayan sido efectuados en el local que lleva a cabo la petición.

Si alguno de los Check Ins corresponde a un jugador invitado, es necesario eliminar las monedas que posee el jugador al momento de la petición. Para esto, se obtiene el balance del jugador y se crea una transacción negativa por dicho monto.

La ruta responde con el estado 200 Ok acompañada de todos los Check Ins que fueron recibidos en la petición.