Skip to content
Ecotic Ecotic Game SDK

Cómo funciona el SDK

Antes de escribir código de juego, es útil entender qué ocurre entre bastidores. Esta página explica el flujo completo, desde que el estudiante abre tu juego hasta que recibe su recompensa.

El modelo iframe + token

Ecotic muestra los juegos dentro de un iframe. El componente que controla ese iframe se llama GameCenter. Cuando el estudiante abre tu juego, ocurre esto:

 Ecotic (GameCenter)                  Tu juego (iframe)
 ─────────────────────                ──────────────────────────
 1. Crea un token de sesión (10 min)
 2. Carga tu URL en el iframe
 3. ──── postMessage(ECOTIC_GAME_TOKEN) ────►  SDK lo recibe en _onMessage()
                                               llama a onReady(token, apiBase)
 4.                               ◄──── POST /games/events (started) ────
 5.                               ◄──── POST /games/events (checkpoint) ─
 6.                               ◄──── POST /games/events (completed) ──
    Otorga XP + monedas al estudiante
    Actualiza misiones activas
 7. ◄──── postMessage(ECOTIC_GAME_EXIT) ────  sdk.exit() cierra el iframe

El token nunca viaja en la URL de tu juego — solo por postMessage. Esto evita que quede en logs del servidor o en el historial del navegador.

Ciclo de vida de una sesión

  1. Token llega — El GameCenter envía ECOTIC_GAME_TOKEN con el token y la URL base de la API. El SDK lo guarda internamente y llama a onReady().

  2. El jugador inicia — Tu código llama a sdk.start() cuando el jugador hace su primer gesto real (clic en “Jugar”). Esto registra la sesión como activa.

  3. Progreso — Durante la partida, llama a sdk.checkpoint() con datos de progreso. El GameCenter actualiza los indicadores de misión en tiempo real.

  4. Fin de partida — Llama a sdk.complete(score). El backend:

    • Valida el token.
    • Verifica que hayan pasado al menos 15 segundos desde que se creó la sesión.
    • Calcula la recompensa (XP + monedas) según los límites configurados.
    • Acredita la recompensa al estudiante.
    • Responde con { reward: { xp, coins }, wallet_balance }.

  5. Salida — sdk.exit() envía ECOTIC_GAME_EXIT al GameCenter para cerrar el iframe.

Renovación de token

El token dura 10 minutos. Si el jugador lleva más tiempo en una partida y el token expira, el servidor responderá con 401. El SDK lo maneja automáticamente:

  1. Guarda el evento que falló en _pendingRetry.
  2. Envía ECOTIC_GAME_REQUEST_TOKEN al GameCenter por postMessage.
  3. El GameCenter genera un nuevo token y lo envía de vuelta como ECOTIC_GAME_TOKEN.
  4. El SDK reintenta el evento guardado.

Tu código no necesita hacer nada — la renovación es transparente.

Fallback CORS

Si fetch falla (por ejemplo, CORS mal configurado en desarrollo), el SDK envía el evento como postMessage al GameCenter. El GameCenter actualiza la UI pero no llama al backend — el evento se pierde. Esto es solo un mecanismo de emergencia para que la UI no se congele.

Idempotencia

Dos métodos son idempotentes — solo se ejecutan una vez por sesión aunque los llames varias veces:

  • sdk.start() — la segunda llamada devuelve { skipped: true }.
  • sdk.complete() — la segunda llamada devuelve { skipped: true }.

Esto protege contra bugs donde el jugador podría terminar la partida dos veces.

Límites de recompensa por sesión

El backend aplica límites duros para evitar abusos:

RecursoLímite por sesiónLímite diario
XP60240
Monedas1560

Aunque tu puntuación sea alta, la recompensa nunca superará estos valores. Son configurables por el equipo admin de Ecotic.