Configuración de marca blanca y empresarial
Configuración de marca blanca y empresarial
Algunos clubes utilizan DistantRace mediante un despliegue de marca blanca: un portal para participantes con su propia marca y dominio personalizado, conectado a la misma consola de organización y a los mismos datos de eventos de DistantRace.
La marca blanca es una oferta gestionada por la plataforma. DistantRace activa el indicador del club, las credenciales OAuth, las páginas de inicio de sesión personalizadas, el alojamiento en un dominio propio y los proveedores de identidad SAML. Los organizadores siguen creando eventos y gestionando participantes en la consola de gestión habitual.
Ponte en contacto con el equipo de soporte de DistantRace para hablar sobre la marca blanca para tu organización.
Qué permite la marca blanca #
| Función | Experiencia del participante | Organizador o plataforma |
|---|---|---|
| Dominio personalizado | Navegar e inscribirse en la URL de tu club (por ejemplo, events.yourcompany.com) |
DNS y TLS proporcionados por DistantRace; dominio verificado mediante Dominios insertados |
| Portal con marca | Nombre, logotipo y colores del club, e interfaz localizada | La marca de la SPA se configura durante el despliegue; el contenido de los eventos sigue procediendo de DistantRace |
| Inicio de sesión personalizado | Las páginas de inicio de sesión y cuenta coinciden con tu marca durante OAuth | Plantillas domain_theme en el host de autenticación de DistantRace |
| Inicio de sesión OAuth del participante | Iniciar sesión en tu portal y conservar la sesión en el navegador | Aplicación OAuth2 de código de autorización limitada a tu organización |
| Token de API de la organización | Listados públicos de eventos, desafíos y clasificaciones sin iniciar sesión | Token de lectura de larga duración para el backend del sitio con marca |
| API de imágenes principales | Banners de carrusel en la página de inicio del portal | Marca del club e imágenes principales, disponible cuando is_whitelabel está activado |
| SAML / SSO empresarial | Iniciar sesión con el correo de trabajo mediante Microsoft Entra ID u otro IdP | Asociación de IdP por dominio; descubrimiento en /saml2/discovery/. Consulta Inicio de sesión SAML empresarial y de marca blanca |
| Correo con marca | Códigos de inicio de sesión y correos transaccionales enviados desde tu remitente | Integración de SendGrid en el club |
| Códigos de acceso e invitaciones | Canjear códigos y enlaces de invitación por correo en el sitio con marca | Los mismos códigos de acceso que en distantrace.com; inscripción automática por enlace mágico mediante la API |
| Conexiones con aplicaciones deportivas | Conectar Garmin, Strava, fuentes de pasos, etc. | Los flujos de conexión OAuth se ejecutan en el host de autenticación canónico de DistantRace y después regresan a tu portal |
| API REST | Todas las acciones del participante después de iniciar sesión (unirse, sincronizar entrenamientos y perfil) | La misma interfaz /api/v1/ que la aplicación móvil: Descripción general de la API pública y API de resultados de desafíos |
| Consola de gestión | No aplicable; los organizadores utilizan distantrace.com | Sin cambios; sigue siendo obligatoria la autenticación de dos factores |
Alcance de la plataforma y del portal
Un portal de participantes de marca blanca es una interfaz específica sobre la API de DistantRace. Las pantallas disponibles —solo desafíos, competiciones con pago, clasificaciones por equipos, etc.— dependen del despliegue. Todos los tipos de evento y opciones subyacentes se configuran en la consola de gestión.
Cómo encajan los componentes #
flowchart LR
subgraph portal [Portal de participantes con marca]
SPA[SPA en dominio personalizado]
end
subgraph drace [Plataforma DistantRace]
API["/api/v1/"]
Auth[OAuth + inicio de sesión personalizado]
Console[Consola de gestión]
SAML[Descubrimiento SAML]
end
SPA -->|token de organización — datos públicos| API
SPA -->|token de usuario — tras iniciar sesión| API
SPA -->|redirección| Auth
Auth --> SAML
Console --> API
- Portal de participantes: aplicación web en tu dominio. Carga los datos públicos de eventos con un token de API limitado a la organización y envía a los participantes a DistantRace OAuth para iniciar sesión.
- Autenticación de DistantRace: gestiona códigos de inicio de sesión, OAuth, SAML y conexiones con aplicaciones deportivas. Las plantillas personalizadas se aplican cuando la solicitud OAuth incluye el contexto de tu organización.
- Consola de gestión: los organizadores crean desafíos, competiciones, entradas y campañas de marketing en distantrace.com. Los cambios aparecen en el portal con marca a través de la API.
Configuración gestionada por la plataforma #
Normalmente DistantRace se encarga de:
| Elemento | Detalles |
|---|---|
Indicador de club is_whitelabel |
Activa la gestión de imágenes principales y su API |
| Aplicaciones OAuth | Cliente de usuario (código de autorización) para el inicio de sesión de participantes y token de organización para listados públicos |
domain_theme |
Selecciona las plantillas de inicio de sesión y registro con marca en el host de autenticación |
| Alojamiento en dominio personalizado | Certificado TLS, ingreso y nombre de host de pruebas opcional *.wl.distantrace.com que coincide con el slug de domain_theme |
| Proveedores de identidad SAML | Registros SAMLIdentityProvider asociados a dominios de correo electrónico |
| Despliegue del portal | Compilación de la SPA con marca, proxy de caché y CI/CD en la infraestructura de marca blanca |
Qué configuran los organizadores #
| Tarea | Dónde |
|---|---|
| Eventos, entradas y códigos de acceso | Consola de gestión, igual que en cualquier club |
| Imágenes principales para el carrusel del portal | Marketing → Imágenes principales (solo clubes de marca blanca) |
| Dominios insertados o personalizados | Club → Dominios insertados. Consulta Dominios insertados para iframes |
| Remitente de correo con marca | Club → Integraciones → SendGrid |
| Logotipo del club | Club → Configuración |
| Desactivar correos de resumen diario | Configuración del club o de cada desafío (clubes de marca blanca) |
Flujos de inicio de sesión de participantes #
Los portales de marca blanca suelen utilizar el código de autorización OAuth:
- El participante hace clic en Iniciar sesión en el sitio con marca.
- El navegador redirige a
/oauth/authorize/de DistantRace con el UUID de tu organización. - DistantRace muestra una página de inicio de sesión personalizada (código por correo, clave de acceso o SAML, según la configuración del club).
- Después de la autenticación, el navegador vuelve al portal con un código que se intercambia por tokens de acceso y actualización.
- El portal llama a
/api/v1/con el token de usuario para acciones personales (unirse a un desafío, sincronizar entrenamientos o actualizar el perfil).
Los enlaces de invitación por correo electrónico pueden iniciar automáticamente la sesión del participante mediante el endpoint redeem-email-token de la API cuando el portal está configurado con un token de organización.
El SSO SAML está disponible para clubes empresariales. Los participantes introducen su correo de trabajo y DistantRace los dirige al IdP correcto según el dominio. Consulta Inicio de sesión SAML empresarial y de marca blanca.
Credenciales de API (resumen) #
Las integraciones de marca blanca utilizan dos tipos de credenciales:
| Credencial | Concesión o tipo | Uso habitual |
|---|---|---|
| Token de organización | Token bearer de larga duración (usuario administrador de la organización) | Listados públicos de desafíos y eventos, imágenes principales, validación de códigos de acceso y canje de tokens de correo |
| Cliente OAuth de usuario | Código de autorización (+ token de actualización) | Inicio de sesión de participantes, unirse a eventos, entrenamientos, perfil y pago |
DistantRace crea y rota ambos durante la incorporación. Los URI de redirección deben coincidir con la ruta /auth/callback de tu portal en cada entorno: pruebas *.wl.distantrace.com y dominio personalizado de producción.
URL de autorización OAuth #
El inicio de sesión del participante comienza en /oauth/authorize/ con:
client_id— tu aplicación OAuth de usuarioredirect_uri— callback registrado en tu portalresponse_type=codeorg=<club-uuid>— vincula la página de inicio de sesión a tu organización y selecciona la plantilla personalizada
Después de que el participante se autentique mediante código por correo, clave de acceso o SAML, DistantRace redirige a tu callback con un código de autorización. Intercámbialo en el servidor o en la SPA por tokens de acceso y actualización.
Códigos de acceso y correos de invitación #
| Paso | API |
|---|---|
| Validar un código antes de mostrar el pago | GET /api/v1/event/joincode/{code}/validate/ (token de organización) |
| Canjear el enlace mágico del correo | POST /api/v1/event/joincode/redeem-email-token/ con { "token": "…" } |
| Crear códigos desde tu sistema interno | POST /api/v1/event/joincode/ (token de usuario administrador, no el token público de organización) |
El canje del enlace mágico puede crear automáticamente una cuenta a partir de los datos precompletados del código de acceso, devolver tokens OAuth e inscribir automáticamente al participante en un desafío vinculado cuando esté configurado.
Mapa completo de endpoints: Descripción general de la API pública.
Pantallas de resultados de desafíos #
Los portales de marca blanca pueden crear clasificaciones y vistas detalladas de resultados de desafíos a partir de respuestas de la API adaptadas a quien realiza la solicitud. Empieza por result-settings/ para consultar las columnas configuradas y las vistas opcionales; después, carga según sea necesario el mapa de calor, las estadísticas de participantes, las cronologías de actividades y las analíticas de sensores permitidas.
Las API de resultados aplican la configuración de privacidad del organizador y devuelven formas de ruta normalizadas y sin ubicación para las miniaturas de actividades, en lugar de trazados GPS absolutos. Consulta API de resultados de desafíos para conocer la secuencia de endpoints, los parámetros de paginación, un resumen de los datos y las reglas de acceso.
Correo electrónico y notificaciones #
Cuando SendGrid está conectado:
- Los correos de código de inicio de sesión utilizan la plantilla transaccional y la dirección del remitente de tu organización.
- Las plantillas de inscripción y marketing siguen la misma integración.
Los clubes de marca blanca pueden suprimir el correo automático de Resumen diario de los desafíos de pasos a nivel de la organización (daily_email_disabled) o de cada desafío.
Aplicación móvil #
La aplicación móvil DistantRace estándar sigue disponible. Los participantes pueden conectar aplicaciones deportivas y sincronizar pasos mediante la aplicación aunque se inscriban en un portal web con marca. La aplicación no es de marca blanca; los datos de la cuenta se comparten entre distantrace.com, la aplicación móvil y el portal con marca.
Acceso de los organizadores #
Los organizadores y el personal siguen utilizando la consola de gestión en distantrace.com:
- Patrón de URL:
/console/<org-code>/ - Se requiere autenticación de dos factores
- SAML puede utilizarse para el inicio de sesión del personal en clubes empresariales, pero el acceso a la consola está separado del flujo OAuth del portal de participantes
Consulta Cómo acceder a la consola del organizador.