Preguntas frecuentes - Integración técnica
Arquitectura y Autenticación
P: ¿Cuáles son las dos pasarelas de API que necesito integrar y por qué existen ambas?
R: La Pasarela de API de Plataforma conecta tu backend para ingerir datos (por lotes + en tiempo real). La Pasarela de API Frontend autentica a los jugadores y alimenta los widgets/interfaz en tiempo real. Generalmente usarás Plataforma para ingestión/sincronización servidor→servidor y Frontend para lecturas/UI con alcance de jugador.
P: ¿Qué flujo de autenticación debe usar mi backend para llamadas a la API de Plataforma?
R: OAuth 2.0 Client Credentials para obtener un token de acceso JWT; usa la URL de token publicada e incluye el token al llamar a los endpoints REST/RX/Data Fetch de Plataforma.
P: ¿Cómo se autentican los jugadores en la Pasarela de API Frontend?
R: Tu FE llama a {PEP_FE}/api/auth/v1/player con tu clientId y tu identityToken (por ejemplo, tu ID de sesión del casino). PEP llama tu /api/auth/v1/player para validar, luego emite un JWT que usan los widgets/FE (vía x-authorization).
P: ¿Necesito construir un endpoint del Operador para la validación de jugadores?
R: Sí—implementa POST {operator}/api/auth/v1/player que valide el identityToken y devuelva playerId (+ opcional expiresAt). PEP depende de esto para emitir el JWT del jugador.
P: ¿Dónde coloco el JWT del jugador al llamar directamente a los endpoints PEP FE?
R: En el encabezado x-authorization (los widgets manejan esto por ti si los usas).
P: ¿Puedo omitir la autenticación Frontend si solo uso widgets?
R: No—todavía debes proporcionar un token de identidad para que PEP pueda validar al jugador y emitir su JWT; los widgets simplifican, pero no eliminan, el requisito de autenticación.
P: ¿Cuál es la diferencia entre las APIs de “ingestión” y las “reactivas”?
R: Ingestión es para sincronizaciones por lotes/periodicas (por ejemplo, cargas iniciales); reactiva son feeds de eventos en tiempo real que impulsan instantáneamente misiones/segmentos/disparadores. Necesitarás ambas para una integración completa.
P: ¿Hay un único token para todas las APIs de Plataforma?
R: Sí—obtén un token OAuth de Plataforma y reutilízalo en las llamadas Platform REST, RX (reactivo) y Data Fetch hasta su expiración.
P: ¿El flujo de autenticación de Plataforma devuelve un JWT?
R: Sí—el flujo Client Credentials produce un token de acceso JWT que incluyes en las llamadas posteriores a Plataforma.
P: ¿Necesito definir Clientes OAuth en PEP Admin?
R: Sí—crea Client Credentials en Admin para llamar a Platform/Data Fetch; también creas client IDs de FE allí.
SDK Frontend y Widgets
P: ¿Cómo cargo el paquete de widgets v2?
R: Incluye el script v2 desde el CDN de tu región, luego llama a GamanzaEngageClient.init(config, cb). Usa getInstance(cb) más tarde para acceder de forma segura a GamificationWidgets.
P: ¿Qué ocurre si llamo a getInstance antes de que init termine?
R: La callback recibe null; implementa un fallback para (re)llamar init o posponer el uso.
P: ¿Cómo renderizo widgets en rutas SPA que montan nodos DOM más tarde?
R: Usa GamificationWidgets.reload() (o reloadOne(id)) después de que aparezcan nuevos nodos para que la librería escanee y adjunte los widgets.
P: ¿Qué estructura DOM esperan los widgets?
R: Elementos con la clase gamification_widget y un data-type como avatar, reward-shop, active-boosters, etc.
P: ¿Cómo puedo obtener los datos básicos del jugador actual (p. ej., opt-in) desde el SDK?
R: Usa GamificationWidgets.getPlayer(cb) (expuesto vía getInstance) y escucha el evento GamanzaEngage_Client_Initialized para saber que la obtención inicial terminó.
P: ¿Cuál es el gancho de limpieza al cerrar sesión?
R: Llama a GamificationWidgets.destroyWidgets() para limpiar Redux/almacenamiento local/socket y desmontar la instancia.
P: ¿Todavía se soporta la v1 del cliente?
R: v1 está obsoleta; usa el paquete y las APIs v2.
P: ¿Los widgets proporcionan actualizaciones en tiempo real?
R: Sí—la pasarela FE + widgets aprovechan SocketIO para actualizaciones de progreso/notificaciones del jugador una vez autenticado.
P: ¿Puedo localizar las etiquetas de los widgets dinámicamente?
R: Sí—vuelve a renderizar con reload(newLocale) o reloadOne(id, newLocale) después de actualizar la configuración regional en el estado de tu app.
P: ¿Cuál es el marcado mínimo para mostrar active boosters?
R: <div class="gamification_widget" data-type="active-boosters"></div> (después de init).
Recompensas, XP, Tokens y Paquetes
P: ¿Cuál es la API para acreditar XP a muchos jugadores a la vez?
R: POST /v1/platform-api/xp-bulk/credit (XP masivo). Planifica el manejo de 202/4xx/5xx.
P: ¿Puedo acreditar monedas de moneda virtual también?
R: Sí—usa las APIs de Acreditar Moneda Virtual bajo “Acreditar Puntos de Experiencia y Tokens”.
P: ¿Puedo asignar múltiples tipos de recompensa en una sola solicitud?
R: Sí—configura un paquete de recompensas (por ejemplo, booster de XP + tokens + XP) en una sola asignación.
P: ¿Hay límites de velocidad al acreditar recompensas?
R: Sí—100 req/min para las APIs de acreditación (throttling por ventana deslizante).
P: ¿Buenas prácticas al asignar recompensas?
R: Proporciona cadenas de motivo/fuente significativas para auditoría; implementa manejo robusto de errores; máximo 1000 asignaciones por solicitud.
P: ¿Las asignaciones de recompensas se reflejan en la UI de Admin y en los Widgets?
R: Sí—las asignaciones aparecen en “Mis Recompensas”/Admin y en widgets FE cuando están configurados.
Canales CRM y Push Móvil
P: ¿Cómo habilito push nativo iOS/Android vía CRM?
R: Configura OneSignal (App ID/API Key) en Admin; asegúrate de que el External ID de OneSignal = Player ID y registra la suscripción con CRM.
P: Envolvemos el sitio web en una capa nativa con Median—¿algún atajo?
R: Sí—si usas Median.co con Widgets configurados, PEP puede auto-registrar suscripciones de OneSignal.
P: ¿De dónde provienen las notificaciones en sitio/web?
R: De la pasarela Frontend + stack de widgets (SocketIO + características del canal CRM) una vez que el jugador está autenticado.
P: ¿Los jugadores “con riesgo” aún pueden recibir push?
R: El riesgo bloquea envíos de marketing CRM (respecta las reglas jurisdiccionales). Los mensajes operativos/obligatorios son decisión de cumplimiento; el módulo de Riesgo de PEP está diseñado para suprimir específicamente el marketing.
Webhooks y APIs de Operador
P: ¿PEP puede enviar eventos a mis sistemas en lugar de que yo haga polling?
R: Sí—configura Event Webhooks (nombre, URL de callback, selecciona tipos de eventos) en Admin; PEP hará POST de payloads a tu endpoint.
P: ¿Cómo aseguran los webhooks?
R: PEP implementa características de seguridad para webhooks (p. ej., patrones de firma/validación)—verifica la autenticidad del payload antes de procesarlo.
P: ¿Necesito exponer alguna API de operador además de la validación de jugadores?
R: Recomendado: Assign Bonus y Get Bonuses para que PEP/CRM puedan auto-poblar opciones de bonus y ejecutar adjudicaciones de bonus sin IDs manuales; considera también una API de Reconciliación para la integridad de datos del jugador.
P: ¿Por qué una API de Reconciliación si ya envío CRUD/eventos?
R: Es un recurso de seguridad para que PEP pueda pedir a tu plataforma que rellene campos faltantes (cumplimiento regulatorio, integridad de segmentación), con registros de auditoría.
Metadatos de juegos, Riesgo y Varios
P: ¿Cómo hago para que mi catálogo de juegos se muestre bien en torneos/widgets?
R: Publica Metadatos de Juegos para que PEP pueda mapear IDs de juego a imágenes/información de lanzamiento e integrarse profundamente con torneos/UX.
P: ¿Existe una API para establecer/restablecer banderas de riesgo?
R: Sí—la API REST de Riesgo incluye endpoints para establecer/eliminar riesgo de jugador y listar riesgos activos (OAuth de Plataforma). Úsala para bloquear/desbloquear programáticamente la elegibilidad de marketing CRM.
Última actualización
¿Te fue útil?