Notificaciones in-app

Obtener notificaciones in-app para un cliente.

GET/api/v1/notifications/in-app

Retorna notificaciones activas que coinciden con las segment rules del cliente.

Query params

Parametro	Tipo	Descripcion
clientId*	string	ID del cliente en SouthGames

Ejemplo

curl "https://southgames.ai/api/v1/notifications/in-app?clientId=abc123" \
  -H "Authorization: Bearer sg_live_xxx" \
  -H "X-Org-Id: mi-empresa"

Respuesta

{
  "notifications": [
    {
      "id": "notif_123",
      "name": "Bienvenida",
      "contentType": "standard",
      "type": "banner",
      "position": "top",
      "title": "Bienvenido!",
      "body": "Juega tu primera campana y gana puntos.",
      "imageUrl": null,
      "bgColor": "#1a1a2e",
      "textColor": "#ffffff",
      "cta": {
        "label": "Jugar ahora",
        "action": "app://campaigns"
      },
      "dismissible": true,
      "htmlContent": null,
      "modalSize": null,
      "blocks": null,
      "priority": 0,
      "startsAt": null,
      "expiresAt": null,
      "trigger": {
        "type": "always"
      }
    }
  ]
}

Tipos de notificacion

type	Descripcion
`banner`	Banner horizontal (top/bottom)
`modal`	Modal centrado
`toast`	Notificacion flotante

Mini-juegos

En Firestore y en el editor del dashboard, una notificacion de mini-juego (por ejemplo, la ruleta de premios) se guarda con contentType: "game". Pero en este endpoint (el wire hacia el SDK) ese valor nunca se expone: por diseno, toda notificacion con htmlContent compilado llega como contentType: "html", indistinguible de una notificacion HTML normal — el campo interno gameId tampoco se incluye en la respuesta:

{
  "id": "notif_456",
  "name": "Ruleta de premios",
  "contentType": "html",
  "type": "modal",
  "position": "center",
  "htmlContent": "<html>...</html>",
  "modalSize": null,
  "dismissible": true,
  "priority": 0
}

El SDK no necesita saber que es un mini-juego; renderiza el HTML igual que cualquier otra notificacion "html", sin logica especial. Esa es justamente la garantia de compatibilidad: mini-juegos nuevos funcionan en SDKs ya deployados sin ningun cambio ni release. Ver la guia de mini-juegos in-app para el detalle de configuracion.

Para el sorteo de premios, el HTML embebido llama a un endpoint aparte:

POST/api/v1/notifications/in-app/spin

Sortea (o repite, si el cliente ya jugo) el premio de un mini-juego in-app.

Request body

Parametro	Tipo	Descripcion
clientId*	string	ID del cliente en SouthGames
notificationId*	string	ID de la notificacion de mini-juego

Respuesta

{
  "segmentId": "seg_1",
  "label": "20% de descuento",
  "alreadyPlayed": false,
  "isPrize": true,
  "awardId": "2026-07_abc123"
}

alreadyPlayed: true indica que el cliente ya habia jugado en el periodo vigente: el resultado es el mismo que se le entrego la primera vez (idempotente), no un giro nuevo.

isPrize y awardId son campos aditivos (la forma base {segmentId, label, alreadyPlayed} esta congelada para siempre, ver guia de mini-juegos): isPrize indica si el gajo ganador esta marcado como "Es premio" en el editor; awardId ("{spinPeriod}_{clientId}") identifica de forma unica el premio de ese cliente en ese periodo de giro y sirve como clave de idempotencia. Un HTML de mini-juego ya compilado (viejo) los ignora sin romperse.

Errores: 404 si la notificacion no existe, no esta activa o no es de tipo mini-juego; 409 (NO_ELIGIBLE_SEGMENTS) si todos los gajos con cupo estan agotados y no queda ninguno ilimitado.