Developer Guide: Reachu SDK Configuration System

¿Qué es el Sistema de Configuración?

El sistema de configuración centralizado de Reachu SDK permite configurar una sola veztodos los aspectos del SDK (API key, colores, posición del cart, configuraciones de red, etc.) y que todos los módulos(Core, UI, LiveShow) funcionen automáticamente sin configuración adicional.

Problema que Resuelve

Antes necesitabas configurar cada módulo por separado:

// Antes: Configuración repetitiva
ReachuCore.configure(apiKey: "key")
ReachuUI.configure(theme: .custom, cartPosition: .bottomRight)
LiveShow.configure(apiKey: "key", chatEnabled: true)
ProductCard.configure(colors: customColors)

Ahora es súper simple:

// Ahora: Una configuración para todo
ReachuConfiguration.configure(apiKey: "your-key")
// Todo funciona automáticamente

Archivos del Sistema de Configuración

1. ReachuConfiguration.swift - Configuración Principal

**Qué hace:**Es el cerebro del sistema. Maneja la configuración global del SDK.

Componentes principales: - ReachuConfiguration - Singleton que guarda toda la configuración

• ReachuEnvironment - Enum para sandbox/production
• ConfigurationError - Errores de configuración

**Cuándo usarlo:**Para configurar el SDK inicialmente o cambiar configuraciones en runtime.

// Configuración básica
ReachuConfiguration.configure(apiKey: "tu-key")

// Configuración avanzada
ReachuConfiguration.configure(
 apiKey: "tu-key",
 environment: .production,
 theme: .dark,
 cartConfig: CartConfiguration(floatingCartPosition: .bottomRight)
)

2. ReachuTheme.swift - Sistema de Temas

**Qué hace:**Define todos los aspectos visuales del SDK (colores, tipografías, espaciados).

Componentes principales: - ReachuTheme - Contenedor del tema completo

• ColorScheme - Paleta de colores (primary, secondary, success, error, etc.)
• TypographyScheme - Tipos de letra (títulos, body, captions)
• SpacingScheme - Espaciados estándar (xs, sm, md, lg, xl)
• BorderRadiusScheme - Radios de bordes

**Cuándo usarlo:**Para personalizar la apariencia visual del SDK.

// Tema predefinido
ReachuConfiguration.configure(
 apiKey: "key",
 theme: .dark // .default, .light, .dark, .minimal
)

// Tema personalizado
let customTheme = ReachuTheme(
 name: "Mi Marca",
 colors: ColorScheme(
 primary: Color.blue,
 secondary: Color.purple
 )
)
ReachuConfiguration.configure(apiKey: "key", theme: customTheme)

3. ModuleConfigurations.swift - Configuraciones Específicas

**Qué hace:**Define configuraciones específicas para cada módulo del SDK.

Configuraciones incluidas:#### CartConfiguration - Comportamiento del Carrito

CartConfiguration(
 floatingCartPosition: .bottomRight, // Posición del cart flotante
 floatingCartDisplayMode: .full, // Modo de visualización
 floatingCartSize: .medium, // Tamaño
 autoSaveCart: true, // Auto-guardar en dispositivo
 showCartNotifications: true, // Mostrar notificaciones
 enableGuestCheckout: true, // Permitir checkout sin cuenta
 supportedPaymentMethods: ["stripe", "klarna"]
)

UIConfiguration - Configuración de Interfaz

UIConfiguration(
 enableProductCardAnimations: true, // Animaciones en cards
 showProductBrands: true, // Mostrar marcas
 enableHapticFeedback: true, // Feedback táctil
 imageQuality: .medium, // Calidad de imágenes
 defaultProductCardVariant: .grid, // Estilo por defecto
 
 // NUEVAS CONFIGURACIONES AVANZADAS:
 typographyConfig: TypographyConfiguration(
 fontFamily: "SF Pro Display", // Fuente personalizada
 enableCustomFonts: true, // Cargar fuentes custom
 supportDynamicType: true, // Dynamic Type
 lineHeightMultiplier: 1.2, // Altura de línea
 letterSpacing: 0.5 // Espaciado de letras
 ),
 
 shadowConfig: ShadowConfiguration(
 cardShadowRadius: 6, // Radio de sombra
 cardShadowOpacity: 0.15, // Opacidad
 buttonShadowEnabled: true, // Sombras en botones
 enableBlurEffects: true, // Efectos blur
 blurStyle: .systemMaterial // Estilo blur iOS
 ),
 
 animationConfig: AnimationConfiguration(
 defaultDuration: 0.25, // Duración por defecto
 springResponse: 0.4, // Respuesta spring
 enableMicroInteractions: true, // Micro-interacciones
 respectReduceMotion: true, // Accesibilidad
 animationQuality: .high // Calidad animación
 ),
 
 layoutConfig: LayoutConfiguration(
 gridColumns: 3, // Columnas grid
 gridSpacing: 20, // Espaciado grid
 enableResponsiveLayout: true, // Layout responsivo
 screenMargins: 16, // Márgenes pantalla
 sectionSpacing: 32 // Espaciado secciones
 ),
 
 accessibilityConfig: AccessibilityConfiguration(
 enableVoiceOverOptimizations: true, // VoiceOver
 enableDynamicTypeSupport: true, // Dynamic Type
 respectHighContrastMode: true, // Alto contraste
 minimumTouchTargetSize: 48, // Target táctil
 hapticIntensity: .medium // Intensidad háptica
 )
)

NetworkConfiguration - Configuración de Red

NetworkConfiguration(
 timeout: 30.0, // Timeout de requests
 retryAttempts: 3, // Intentos de retry
 enableCaching: true, // Cache habilitado
 enableLogging: false, // Logging de red
 
 // NUEVAS CONFIGURACIONES AVANZADAS:
 maxConcurrentRequests: 8, // Requests concurrentes
 requestPriority: .high, // Prioridad requests
 enableCompression: true, // Compresión GZIP
 
 // Seguridad
 enableSSLPinning: true, // SSL Certificate Pinning
 trustedHosts: ["api.reachu.io"], // Hosts confiables
 enableCertificateValidation: true, // Validación SSL
 
 // Performance
 enableNetworkInspector: false, // Inspector debug
 
 // Offline Mode
 enableOfflineMode: true, // Modo offline
 offlineCacheDuration: 86400, // Cache offline (24h)
 syncStrategy: .background // Estrategia sync
)

LiveShowConfiguration - Configuración de LiveShow

LiveShowConfiguration(
 autoJoinChat: true, // Auto-unirse al chat
 enableShoppingDuringStream: true, // Shopping durante stream
 videoQuality: .auto, // Calidad de video
 enableAutoplay: false // Auto-reproducción
)

4. ConfigurationLoader.swift - Cargador de Configuraciones

**Qué hace:**Permite cargar configuraciones desde diferentes fuentes (JSON, Plist, variables de entorno, URLs remotas).

Métodos principales: - loadFromJSON() - Carga desde archivo JSON

• loadFromPlist() - Carga desde archivo Plist
• loadFromEnvironment() - Carga desde variables de entorno
• loadFromRemote() - Carga desde URL remota

**Cuándo usarlo:**Cuando quieres externalizar la configuración del código.

// Desde archivo JSON
try ConfigurationLoader.loadFromJSON(fileName: "reachu-config")

// Desde variables de entorno (CI/CD)
ConfigurationLoader.loadFromEnvironment()

// Desde URL remota
await ConfigurationLoader.loadFromRemote(url: configURL)

Cómo Usar el Sistema

Paso 1: Configuración Inicial

Elige una de estas opciones según tu caso de uso:

Opción A: Configuración Simple (Recomendada para empezar)

// En AppDelegate o App.swift
ReachuConfiguration.configure(apiKey: "tu-reachu-api-key")

Opción B: Configuración Personalizada

ReachuConfiguration.configure(
 apiKey: "tu-reachu-api-key",
 environment: .production,
 theme: .dark,
 cartConfig: CartConfiguration(
 floatingCartPosition: .bottomRight,
 showCartNotifications: true
 ),
 uiConfig: UIConfiguration(
 enableAnimations: true,
 showProductBrands: true
 )
)

Opción C: Configuración desde Archivo JSON

do {
 try ConfigurationLoader.loadFromJSON(fileName: "reachu-config")
} catch {
 // Fallback a configuración manual
 ReachuConfiguration.configure(apiKey: "tu-api-key")
}

Paso 2: Usar los Componentes

Después de la configuración inicial, todos los componentes funcionan automáticamente:

import ReachuUI

struct ContentView: View {
 var body: some View {
 VStack {
 // Todos usan la configuración global automáticamente
 RProductCard(product: producto)
 RProductSlider(products: productos)
 RFloatingCartIndicator() // Posición configurada globalmente
 }
 .sheet(isPresented: $showCheckout) {
 RCheckoutOverlay() // Tema y configuración globales
 }
 }
}

Paso 3: Cambios en Runtime (Opcional)

// Cambiar tema dinámicamente
ReachuConfiguration.updateTheme(.light)

// Cambiar configuración del cart
ReachuConfiguration.updateCartConfiguration(
 CartConfiguration(floatingCartPosition: .topRight)
)

Casos de Uso Comunes

Desarrollo Multi-Ambiente

#if DEBUG
ReachuConfiguration.configure(
 apiKey: "sandbox-key",
 environment: .sandbox,
 networkConfig: NetworkConfiguration(enableLogging: true)
)
#else
ReachuConfiguration.configure(
 apiKey: "production-key",
 environment: .production
)
#endif

White-Label / Multi-Marca

let brandTheme = ReachuTheme(
 name: "Mi Marca",
 colors: ColorScheme(
 primary: Color(red: 0.2, green: 0.4, blue: 0.8),
 secondary: Color(red: 0.8, green: 0.2, blue: 0.4)
 )
)

ReachuConfiguration.configure(
 apiKey: "key",
 theme: brandTheme
)

Configuración Externa (JSON)

Crea reachu-config.json en tu bundle:

{
 "apiKey": "tu-api-key",
 "environment": "production",
 "theme": {
 "name": "Brand Theme",
 "colors": {
 "primary": "#007AFF",
 "secondary": "#5856D6"
 }
 },
 "cart": {
 "floatingCartPosition": "bottomRight",
 "showCartNotifications": true
 }
}

CI/CD con Variables de Entorno

# Variables de entorno
export REACHU_API_KEY="production-key"
export REACHU_ENVIRONMENT="production"

// En tu app
ConfigurationLoader.loadFromEnvironment()

Beneficios del Sistema

Para Desarrolladores: - Setup una vez → Todo funciona

• Menos código → Sin configuración repetitiva
• Type-safe → Errores en compile-time
• Flexible → Múltiples formas de configurar
• Testeable → Fácil cambiar configs para tests

Para Equipos: - Consistencia → Mismo tema en toda la app

• Mantenible → Cambios centralizados
• Escalable → Fácil añadir nuevas configuraciones
• Multi-ambiente → Dev/Staging/Production

Para Empresas: - White-label ready → Personalización completa

• Configuración remota → Updates sin deploy
• Compliance → Control total de configuraciones
• CI/CD friendly → Variables de entorno

Resumen

El sistema de configuración de Reachu SDK es como el centro de controlde tu integración ecommerce:

1. Configuras una vez → Todo funciona
2. Personalizas fácilmente → Temas, colores, comportamiento
3. Escalas sin problemas → Multi-ambiente, white-label
4. Mantienes con facilidad → Configuración centralizada

¡Es la base que hace que el SDK sea verdaderamente plug-and-play!

Configuraciones Avanzadas Añadidas

Typography Configuration - Tipografías Personalizadas#### ¿Qué incluye? - Fuentes personalizadascon mapeo de pesos

• Dynamic Typepara accesibilidad
• Espaciado de letrasy altura de línea
• Escalado de fuentescon límites min/max

Casos de uso:

// White-label con fuente corporativa
TypographyConfiguration(
 fontFamily: "MiBrand-Display",
 enableCustomFonts: true,
 fontWeightMapping: FontWeightMapping(
 light: "MiBrand-Light",
 regular: "MiBrand-Regular",
 bold: "MiBrand-Bold"
 )
)

// Mejoras de legibilidad
TypographyConfiguration(
 lineHeightMultiplier: 1.4, // Más espacio entre líneas
 letterSpacing: 0.3, // Mejor espaciado
 supportDynamicType: true // Accesibilidad automática
)

Shadow Configuration - Sombras y Efectos

¿Qué incluye? - Sombras personalizablespara cards y botones

• Efectos blurcon materiales iOS
• Colores adaptativospara dark/light mode
• Performance optimizadapor plataforma

Casos de uso:

// Sombras sutiles para diseño minimal
ShadowConfiguration(
 cardShadowRadius: 2,
 cardShadowOpacity: 0.05,
 buttonShadowEnabled: false,
 enableBlurEffects: false
)

// Sombras dramáticas para diseño premium
ShadowConfiguration(
 cardShadowRadius: 12,
 cardShadowOpacity: 0.25,
 cardShadowOffset: CGSize(width: 0, height: 6),
 modalShadowRadius: 30,
 blurIntensity: 0.6
)

Animation Configuration - Animaciones Avanzadas

¿Qué incluye? - Spring animationscon timing personalizado

• Micro-interaccionespara feedback
• Easing curvespersonalizadas
• Optimizaciones de performance - Respeto a preferencias de accesibilidad#### Casos de uso:

// Animaciones rápidas y eficientes
AnimationConfiguration(
 defaultDuration: 0.2,
 springResponse: 0.3,
 springDamping: 0.9,
 animationQuality: .medium,
 enableHardwareAcceleration: true
)

// Animaciones premium con micro-interacciones
AnimationConfiguration(
 enableMicroInteractions: true,
 enableSharedElementTransitions: true,
 customTimingCurve: (0.25, 0.1, 0.25, 1.0),
 animationQuality: .ultra
)

Layout Configuration - Sistemas de Layout

¿Qué incluye? - Grid systemresponsivo

• Breakpointspara diferentes pantallas
• Safe areascustomizables
• Márgenes y espaciadoconsistentes

Casos de uso:

// Layout compacto para móviles
LayoutConfiguration(
 gridColumns: 2,
 gridSpacing: 12,
 screenMargins: 12,
 compactWidthThreshold: 600
)

// Layout expansivo para tablets
LayoutConfiguration(
 gridColumns: 4,
 gridSpacing: 24,
 gridMaxItemWidth: 200,
 enableResponsiveLayout: true,
 regularWidthThreshold: 1200
)

Accessibility Configuration - Accesibilidad Inclusiva

¿Qué incluye? - VoiceOveroptimizado

• Dynamic Typecon límites
• Alto contrasteautomático
• Touch targetsaccesibles
• Feedback hápticoconfigurable

Casos de uso:

// Máxima accesibilidad
AccessibilityConfiguration(
 enableVoiceOverOptimizations: true,
 maxDynamicTypeSize: .accessibility5,
 respectHighContrastMode: true,
 enableColorBlindnessSupport: true,
 minimumTouchTargetSize: 48,
 alternativeToAnimations: true
)

// Feedback háptico personalizado
AccessibilityConfiguration(
 enableHapticFeedback: true,
 hapticIntensity: .heavy,
 customVoiceOverLabels: [
 "add-to-cart": "Añadir producto al carrito",
 "checkout": "Proceder al pago"
 ]
)

Network Configuration - Red Avanzada

¿Qué incluye? - Performance: requests concurrentes, compresión

• Seguridad: SSL pinning, validación certificados
• Offline mode: cache persistente, sync strategies
• Debug tools: network inspector, logging avanzado

Casos de uso:

// Configuración enterprise con seguridad
NetworkConfiguration(
 enableSSLPinning: true,
 trustedHosts: ["api.reachu.io", "cdn.reachu.io"],
 enableCertificateValidation: true,
 maxConcurrentRequests: 4,
 enableCompression: true
)

// Configuración offline-first
NetworkConfiguration(
 enableOfflineMode: true,
 offlineCacheDuration: 604800, // 7 días
 syncStrategy: .automatic,
 enableCaching: true,
 cacheDuration: 3600 // 1 hora
)

Migración desde Configuración Básica

Antes (Configuración Simple):

ReachuConfiguration.configure(
 apiKey: "tu-key",
 theme: .default
)

Después (Configuración Avanzada):

ReachuConfiguration.configure(
 apiKey: "tu-key",
 theme: customTheme,
 uiConfig: UIConfiguration(
 typographyConfig: .custom,
 shadowConfig: .premium,
 animationConfig: .enhanced,
 accessibilityConfig: .maximum
 ),
 networkConfig: NetworkConfiguration(
 enableSSLPinning: true,
 enableOfflineMode: true
 )
)

Beneficios de las Configuraciones Avanzadas

Para Diseñadores: - Control granularsobre tipografías y sombras

• Consistencia visualcon design tokens
• Responsive designautomático
• Temas adaptativospara dark/light mode

Para Desarrolladores: - Type-safe configurationcon enums

• Hot-reloadingde configuraciones
• Debug toolsintegradas
• Performance optimizationsautomáticas

Para Usuarios Finales: - Mejor accesibilidadcon Dynamic Type

• Animaciones optimizadasque respetan preferencias
• Rendimiento superiorcon configuraciones optimizadas
• Experiencia offlinemejorada

Para Empresas: - Compliance automáticocon estándares de accesibilidad

• Seguridad enterprisecon SSL pinning
• White-labeling completocon tipografías custom
• Escalabilidadpara diferentes mercados

¡El sistema de configuración ahora es enterprise-gradey listo para cualquier caso de uso!

---

Dark/Light Mode Complete Guide

What is Dark/Light Mode Support?

Reachu SDK provides complete dark/light mode supportthat automatically adapts to system settings or can be manually controlled. All UI components respond to color scheme changes dynamically.

Features: - Automatic system following - Respects iOS dark/light mode

• Manual override - Force light or dark mode
• Complete color customization - Separate colors for light and dark
• Component adaptation - All UI components adapt automatically
• Professional appearance - iOS-standard dark mode colors

---

Theme Configuration Options

1. Automatic Mode (Recommended)

Follows system dark/light mode with custom colors:

{
 "theme": {
 "name": "My App Theme",
 "mode": "automatic",
 "lightColors": {
 "primary": "#007AFF",
 "secondary": "#5856D6",
 "surface": "#FFFFFF",
 "background": "#F2F2F7",
 "textPrimary": "#000000",
 "textSecondary": "#8E8E93"
 },
 "darkColors": {
 "primary": "#0A84FF",
 "secondary": "#5E5CE6", 
 "surface": "#1C1C1E",
 "background": "#000000",
 "textPrimary": "#FFFFFF",
 "textSecondary": "#8E8E93"
 }
 }
}

2. Force Light Mode

Always use light mode regardless of system setting:

{
 "theme": {
 "mode": "light",
 "lightColors": {
 "primary": "#FF6B6B",
 "surface": "#FFFFFF"
 }
 }
}

3. Force Dark Mode

Always use dark mode regardless of system setting:

{
 "theme": {
 "mode": "dark", 
 "darkColors": {
 "primary": "#00D4AA",
 "surface": "#1A1A1A"
 }
 }
}

---

Available Color Properties

Complete Color Scheme:

{
 "lightColors": {
 // Brand Colors
 "primary": "#007AFF",
 "secondary": "#5856D6",
 
 // Semantic Colors 
 "success": "#34C759",
 "warning": "#FF9500",
 "error": "#FF3B30",
 "info": "#007AFF",
 
 // Background Colors
 "background": "#F2F2F7",
 "surface": "#FFFFFF", 
 "surfaceSecondary": "#F9F9F9",
 
 // Text Colors
 "textPrimary": "#000000",
 "textSecondary": "#8E8E93",
 "textTertiary": "#C7C7CC",
 
 // Border Colors
 "border": "#E5E5EA",
 "borderSecondary": "#D1D1D6"
 },
 "darkColors": {
 // Same properties with dark mode values
 "primary": "#0A84FF",
 "secondary": "#5E5CE6",
 "surface": "#1C1C1E",
 "background": "#000000",
 "textPrimary": "#FFFFFF",
 // ... etc
 }
}

---

Implementation in Components

For SwiftUI Components:

import SwiftUI
import ReachuDesignSystem

struct MyComponent: View {
 @Environment(\.colorScheme) private var colorScheme
 
 // Get adaptive colors
 private var adaptiveColors: AdaptiveColors {
 ReachuColors.adaptive(for: colorScheme)
 }
 
 var body: some View {
 VStack {
 Text("Hello")
 .foregroundColor(adaptiveColors.textPrimary)
 .background(adaptiveColors.surface)
 
 Button("Action") { }
 .foregroundColor(adaptiveColors.primary)
 }
 .background(adaptiveColors.background)
 }
}

For Static Usage:

// Use static colors (fallback)
Text("Hello")
 .foregroundColor(ReachuColors.textPrimary)
 .background(ReachuColors.surface)

// Get colors for specific scheme
let lightColors = ReachuColors.colors(for: .light)
let darkColors = ReachuColors.colors(for: .dark)

---

Theme Mode Options| Mode | Behavior | Use Case |

|------|----------|----------| | "automatic" | Follows system dark/light | Recommended - Best UX | | "light" | Always light mode | Brand requirements, accessibility | | "dark" | Always dark mode | Gaming apps, developer tools |

---

Color Scheme Examples

Professional Blue Theme:

{
 "lightColors": {
 "primary": "#0066CC",
 "surface": "#FFFFFF",
 "background": "#F8F9FA"
 },
 "darkColors": {
 "primary": "#4A9EFF", 
 "surface": "#1E1E1E",
 "background": "#121212"
 }
}

Green E-commerce Theme:

{
 "lightColors": {
 "primary": "#00A86B",
 "secondary": "#FF6B35"
 },
 "darkColors": {
 "primary": "#00D084",
 "secondary": "#FF8A5B" 
 }
}

Minimal Monochrome Theme:

{
 "lightColors": {
 "primary": "#333333",
 "surface": "#FFFFFF"
 },
 "darkColors": {
 "primary": "#CCCCCC",
 "surface": "#222222"
 }
}

---

Advanced Configuration

Override Theme Mode Programmatically:

// Force dark mode
ReachuConfiguration.shared.updateTheme(
 ReachuTheme(
 name: "Override",
 mode: .dark,
 lightColors: .reachu,
 darkColors: .reachuDark
 )
)

Create Custom Theme:

let customTheme = ReachuTheme(
 name: "My Custom Theme",
 mode: .automatic,
 lightColors: ColorScheme(
 primary: Color(.sRGB, red: 1.0, green: 0.4, blue: 0.4),
 secondary: Color(.sRGB, red: 0.2, green: 0.6, blue: 1.0)
 ),
 darkColors: .autoDark(from: lightColors)
)

---

Best Practices

DO: - Use "automatic" mode for best user experience

• Provide both light and dark colors for complete themes
• Test your app in both light and dark modes
• Use semantic colors (success, warning, error) consistently
• Follow iOS Human Interface Guidelines for dark mode

DON'T: - Force light mode unless brand requirements demand it

• Use low contrast colors in dark mode
• Ignore system preferences without good reason
• Hardcode colors in components - use the theme system

---

Testing Dark/Light Mode

**iOS Simulator:**1. Settings > Developer > Dark Appearance

2. Or Device Settings > Display & Brightness > Appearance

Xcode Previews:

#Preview("Light Mode") {
 MyComponent()
 .preferredColorScheme(.light)
}

#Preview("Dark Mode") {
 MyComponent() 
 .preferredColorScheme(.dark)
}

---

Result

With this configuration system, your app will have:

• Professional dark modethat matches iOS standards
• Automatic adaptationto system settings
• Complete customizationof all colors
• Consistent themingacross all components
• Easy maintenancewith centralized configuration

**Your users will love the polished, professional appearance! **