Skip to Content
Referencia de API

Referencia API exhaustiva

Esta página contiene la fuente absoluta de la verdad sobre la API de configuración de Tracelet. Todos los parámetros que se pueden pasar a Tracelet.ready(Config) se enumeran aquí.

Para escenarios arquitectónicos del mundo real que expliquen por qué usaría estos parámetros, haga clic en los enlaces “Ver historia 📖” junto a ellos.

🌍 GeoConfig (config.geo)

Controla la ubicación física, la precisión y la lógica de muestreo. Ver historia geográfica 📖

  • desiredAccuracy: DesiredAccuracy (Predeterminado: DesiredAccuracy.high) La precisión del hardware de destino. Utilice high para GPS, low para celular/Wi-Fi para ahorrar batería.
  • distanceFilter: double (Predeterminado: 10.0) Metros horizontales mínimos a recorrer antes de que se registre un punto.

ℹ️ Al cambiar desiredAccuracy o distanceFilter a través de setConfig() se mantienen los valores y se reinicia el proceso de seguimiento. Para una anulación temporal durante el seguimiento (por ejemplo, desactivar el GPS durante un período estacionario confirmado), use updateLocationProviderOptions(): actualiza el proveedor en ejecución en vivo, sin reiniciar y nunca toca la configuración persistente.

  • stationaryRadius: double (Predeterminado: 25.0) El radio alrededor del usuario se considerará estacionario (detiene el drenaje del GPS).
  • locationTimeout: int (Predeterminado: 60) Máximo de segundos para esperar un bloqueo del GPS antes de darse por vencido.
  • disableElasticity: bool (Predeterminado: false) Si es verdadero, deshabilita la escala dinámica de distancia basada en la velocidad.
  • elasticityMultiplier: double (Predeterminado: 1.0) Multiplicador para el filtro dinámico de distancia cuando se viaja a altas velocidades.
  • stopAfterElapsedMinutes: int (Predeterminado: -1) Detiene automáticamente el motor después de X minutos. -1 significa ejecutar para siempre.
  • maxMonitoredGeofences: int (Predeterminado: -1) Máximo de geocercas para monitorear simultáneamente.
  • enableTimestampMeta: bool (Predeterminado: false) Adjunta marcas de tiempo exactas del hardware en nanosegundos.
  • enableAdaptiveMode: bool (Predeterminado: false) Alterna automáticamente la configuración según el nivel de la batería.
  • periodicLocationInterval: int (Predeterminado: 900) Segundos entre actualizaciones periódicas cuando está parado.
  • periodicDesiredAccuracy: DesiredAccuracy (Predeterminado: DesiredAccuracy.medium) Precisión utilizada durante despertares de fondo periódicos.
  • enableSparseUpdates: bool (Predeterminado: false) Utiliza exclusivamente triangulación de torres de telefonía móvil de bajo consumo.
  • sparseDistanceThreshold: double (Predeterminado: 50.0) Metros para moverse en modo disperso.
  • sparseMaxIdleSeconds: int (Predeterminado: 300) Tiempo máximo sin una actualización escasa.
  • enableDeadReckoning: bool (Predeterminado: false) Utiliza acelerómetro/giroscopio para adivinar la ubicación cuando se pierde el GPS (por ejemplo, túneles).
  • deadReckoningActivationDelay: int (Predeterminado: 0) Segundos de pérdida del GPS antes de que entre en acción la navegación a estima.
  • deadReckoningMaxDuration: int (Predeterminado: 0) Máximo de segundos para permitir la navegación a estima antes de detenerse.
  • resolveAddress: bool (Predeterminado: false) Geocodifica automáticamente las coordenadas en una cadena de dirección de calle.

🧹 Filtro de ubicación (config.geo.filter)

Limpia los datos GPS incorrectos antes de que lleguen a SQLite/Sync. Ver historia filtrada 📖

  • trackingAccuracyThreshold: int (Predeterminado: 100) Se eliminan los puntos con una precisión peor que la de los medidores X.
  • maxImpliedSpeed: int (Predeterminado: 80) Rechaza saltos de ubicación que impliquen velocidad > X m/s (80 m/s = 288 km/h).
  • odometerAccuracyThreshold: int (Predeterminado: 50) Los puntos con una precisión peor que los medidores X no se suman a la distancia total del viaje.
  • policy: LocationFilterPolicy (Predeterminado: LocationFilterPolicy.adjust) Cómo manejar los puntos negativos (drop o adjust).
  • rejectMockLocations: bool (Predeterminado: false) Elimina inmediatamente ubicaciones generadas por aplicaciones de suplantación de GPS.
  • mockDetectionLevel: int (Predeterminado: 1) Agresividad de las heurísticas de detección de GPS falsas.
  • useKalmanFilter: bool (Predeterminado: false) Aplica un complejo suavizado de Kalman a la trayectoria GPS sin procesar.

📱 AppConfig (config.app)

Controla el comportamiento general del ciclo de vida de la aplicación.

  • stopOnTerminate: bool (Predeterminado: true) Si true, el seguimiento se detiene cuando el usuario desliza la aplicación. Si false, se reinicia en segundo plano. Ver Terminar Historia 📖
  • startOnBoot: bool (Predeterminado: false) Si true, el seguimiento comienza automáticamente cuando se reinicia el teléfono.
  • heartbeatInterval: int (Predeterminado: 60) Dispara un evento de “latido” cada X segundos para demostrar que el motor está activo.
  • schedule: List<String> (Predeterminado: []) Cadenas tipo CRON para iniciar/detener automáticamente el seguimiento en momentos específicos.
  • remoteConfigUrl: String? (Predeterminado: null) URL HTTPS donde el SDK obtiene un mapa de configuración JSON en ready(), lo aplica sobre la configuración local y lo actualiza en segundo plano. Almacenado en caché en el dispositivo para una aplicación instantánea sin conexión. Consulte Configuración remota.
  • remoteConfigHeaders: Map<String, String>? (Predeterminado: null) Encabezados HTTP para la recuperación de configuración remota.
  • remoteConfigTimeout: int (Predeterminado: 60000) Tiempo de espera para recuperar la configuración remota en ms.
  • remoteConfigRefreshInterval: int (Predeterminado: 1440) Minutos antes de recuperar la configuración remota.

🤖 Configuración de Android (config.android)

Restricciones específicas del sistema operativo Android. Ver historia de Android 📖

  • locationUpdateInterval: int (Predeterminado: 1000) Ms entre pings de GPS.
  • batteryBudgetPerHour: double (Predeterminado: 0.0) Objetivo de consumo máximo de batería % por hora. 0.0 desactiva la limitación.
  • releaseWakelockWhenStationary: bool (Predeterminado: false) Cuando se usa MotionDetectionMode.smart, libera el bloqueo de seguimiento cuando el dispositivo está completamente estacionario para maximizar el ahorro de batería en modo de suspensión profunda.
  • fastestLocationUpdateInterval: int (Predeterminado: 500) Ms más rápido entre pings de GPS si otra aplicación los solicita.
  • deferTime: int (Predeterminado: 0) Permite que Android realice actualizaciones de ubicación por lotes para X ms.
  • allowIdenticalLocations: bool (Predeterminado: false) Si es falso, se eliminan las coordenadas exactas duplicadas.
  • geofenceModeHighAccuracy: bool (Predeterminado: false) — ⚠️ Obsoleto Fuerza el chip GPS para geocercas (consumo elevado de batería). Utilice la multiplataforma GeofenceConfig.geofenceModeHighAccuracy (consulte la sección GeofenceConfig a continuación) en cambio, ahora controla tanto iOS como Android. Esta bandera solo para Android todavía está honrado por la compatibilidad con versiones anteriores (si alguno es true, el modo de alta precisión es habilitado) pero se eliminará en una versión principal futura.
  • periodicUseForegroundService: bool (Predeterminado: false) Fuerza una notificación persistente durante las reactivaciones periódicas.
  • periodicUseExactAlarms: bool (Predeterminado: false) Utiliza AlarmManager para reactivaciones exactas (requiere permiso de manifiesto SCHEDULE_EXACT_ALARM). Ver Alarmas Exactas 📖
  • scheduleUseAlarmManager: bool (Predeterminado: false) Utiliza alarmas exactas para la programación CRON.

Configuración de servicio en primer plano (config.android.foregroundService)

  • enabled: bool (Predeterminado: true) Requiere permiso POST_NOTIFICATIONS en Android 13+. Ver Notificación 📖
  • channelId: String (Predeterminado: 'tracelet_channel')
  • channelName: String (Predeterminado: 'Tracelet')
  • notificationTitle: String (Predeterminado: 'Tracelet')
  • notificationText: String (Predeterminado: 'Tracking location in background')
  • notificationColor: String? (Predeterminado: null) Color hexadecimal para el fondo del icono pequeño.
  • notificationSmallIcon: String? (Predeterminado: null) Nombre del PNG solo en blanco en su carpeta res/drawable.
  • notificationLargeIcon: String? (Predeterminado: null)
  • notificationPriority: NotificationPriority (Predeterminado: NotificationPriority.defaultPriority)
  • notificationOngoing: bool (Predeterminado: true)
  • showNotificationOnPauseOnly: bool (Predeterminado: false)
  • actions: List<String> (Predeterminado: [])

🔔 Para aplicar un cambio de notificación mientras el seguimiento ya se está ejecutando, llame a Tracelet.updateNotification() después de setConfig(). Vuelve a publicar la notificación en vivo sin reiniciar la canalización (v3.6.8+). En iOS, en su lugar, actualiza la actividad en vivo en ejecución; En la web no es posible.

🍎IosConfig (config.ios)

Restricciones específicas del sistema operativo iOS. Ver historia de iOS 📖

  • activityType: LocationActivityType (Predeterminado: LocationActivityType.other) Le dice a iOS lo que está haciendo (por ejemplo, fitness, navigation) para que sepa cuándo pausar el seguimiento.
  • useSignificantChangesOnly: bool (Predeterminado: false) Depende completamente de las transferencias de las torres de telefonía móvil. Consumo de batería casi nulo.
  • showsBackgroundLocationIndicator: bool (Predeterminado: false) Muestra el indicador de la píldora azul. Requiere capacidad location Xcode. Ver Pastilla Azul 📖
  • pausesLocationUpdatesAutomatically: bool (Predeterminado: false) Permite que iOS apague el chip GPS si el usuario no se ha movido por un tiempo.
  • locationAuthorizationRequest: LocationAuthorizationRequest (Predeterminado: always) Qué permiso solicitar.
  • disableLocationAuthorizationAlert: bool (Predeterminado: false) Evita que el sistema operativo solicite “Permitir siempre” si solo se solicita “Cuando esté en uso”.
  • preventSuspend: bool (Predeterminado: false) Reproduce audio silencioso para mantener activa la aplicación las 24 horas del día, los 7 días de la semana. Requiere capacidad audio Xcode. Ver Evitar suspensión 📖
  • useBackgroundActivitySession: bool (Predeterminado: false) Utiliza CLBackgroundActivitySession (iOS 17+) para mantener una sesión de ubicación en segundo plano con solo autorización “Cuando esté en uso”. Esto reemplaza la tradicional píldora azul con un indicador de isla dinámica. Nota: Las pautas de la App Store de Apple requieren que las aplicaciones que usan esto brinden una explicación clara a los usuarios de por qué es necesaria la ubicación en segundo plano.
  • liveActivityConfig: LiveActivityConfig? (Predeterminado: null) Opte por una pantalla de bloqueo/actividad dinámica de la isla en vivo mientras realiza el seguimiento (iOS 16.1+, requiere una extensión de widget). Toma title y body. Ver actividades en vivo 📖. Actualícelo en tiempo de ejecución con Tracelet.updateNotification() (v3.6.8+).

📍 GeofenceConfig (config.geofence)

Comportamiento de geofencing multiplataforma (iOS + Android).

  • geofenceModeHighAccuracy: bool (Predeterminado: false) Controla cómo se detectan las transiciones de geocerca:
    • false (predeterminado): utiliza el servicio de supervisión de la región del sistema operativo. Bajo consumo, sin indicador azul de iOS, pero el sistema operativo impone un radio mínimo práctico (~100 m) y las transiciones pequeñas o de SALIDA pueden no ser confiables.
    • true: evalúa las transiciones en la aplicación desde GPS continuo. Hace que los radios estrechos (por ejemplo, 5 a 50 m) y los eventos de SALIDA sean confiables, a costa de un mayor uso de la batería y, en iOS, el indicador de la barra de estado de “ubicación en uso” (azul) del sistema (el GPS continuo lo obliga). Ver Pastilla Azul 📖

Esto reemplaza al obsoleto AndroidConfig.geofenceModeHighAccuracy; si cualquiera de ellos es true, se habilita el modo de alta precisión.

  • geofenceInitialTrigger: bool (Predeterminado: true) Evalúe el estado de la geocerca al registrarse.
  • geofenceInitialTriggerEntry: bool (Predeterminado: true) Dispare un ENTER inmediatamente si el dispositivo ya está dentro de una geocerca cuando se registra.
  • geofenceProximityRadius: int (Predeterminado: 1000) Radio (metros) para carga basada en proximidad: solo las geocercas dentro de esta distancia se registran activamente en el sistema operativo (le permite administrar mucho más que el límite de región de iOS 20).

📡 HttpConfig (config.http)

Controla el motor de sincronización de red. Ver historia de sincronización 📖

  • url: String? (Predeterminado: null) Su punto final de backend.
  • method: HttpMethod (Predeterminado: HttpMethod.post)
  • headers: Map<String, String>? (Predeterminado: null) Encabezados de autenticación personalizados. Para rotación dinámica de JWT, Ver Devoluciones de llamada 📖
  • params: Map<String, Object?>? (Predeterminado: null)
  • extras: Map<String, Object?>? (Predeterminado: null) Datos JSON estáticos inyectados en cada carga útil de ubicación.
  • httpRootProperty: String? (Predeterminado: 'location') El nodo raíz JSON.
  • autoSync: bool (Predeterminado: true) Se carga automáticamente. Si es falso, debes llamar a Tracelet.sync().
  • batchSync: bool (Predeterminado: false) Carga matrices de ubicaciones en lugar de 1 por 1.
  • maxBatchSize: int (Predeterminado: 250)
  • autoSyncThreshold: int (Predeterminado: 0) Número de registros SQLite necesarios antes de activar una sincronización.
  • autoSyncDelay: int (Predeterminado: 10000) Ms debe esperar antes de sincronizar después de que llegue una ubicación.
  • syncInterval: int (Predeterminado: 0) Segundos entre vaciados repetidos y basados ​​en el tiempo de la cola fuera de línea. Cuando > 0, el SDK carga periódicamente cualquier ubicación pendiente en esta cadencia, independientemente del rebote de autoSyncDelay que se activa en nuevas inserciones. Útil para el vaciado controlado por tiempo, independientemente de cuántos registros se hayan acumulado. 0 desactiva el temporizador de intervalos.
  • httpTimeout: int (Predeterminado: 60000)
  • locationsOrderDirection: LocationOrderDirection (Predeterminado: LocationOrderDirection.ascending)
  • disableAutoSyncOnCellular: bool (Predeterminado: false) Solo se sincroniza cuando está conectado a Wi-Fi para guardar los planes de datos del usuario.
  • maxRetries: int (Predeterminado: 3)
  • retryBackoffBase: int (Predeterminado: 1000)
  • retryBackoffCap: int (Predeterminado: 60000)
  • enableDeltaCompression: bool (Predeterminado: false) Solo envía las coordenadas delta, lo que reduce el tamaño de la carga útil JSON en un 80 %.
  • deltaCoordinatePrecision: int (Predeterminado: 5)
  • sslPinningFingerprints: List<String>? (Predeterminado: null)
  • sslPinningCertificates: List<String>? (Predeterminado: null)

🏢 Configuraciones empresariales

AuditConfig (config.audit)

  • enabled: bool (Predeterminado: false) Crea una cadena de bloques criptográfica a prueba de manipulaciones de hashes de ubicación.
  • hashAlgorithm: HashAlgorithm (Predeterminado: HashAlgorithm.sha256)
  • includeExtrasInHash: bool (Predeterminado: false)

SecurityConfig (config.security)

  • encryptionKey: String? (Predeterminado: null) Cifra la base de datos SQLite usando SQLCipher. Ver Cifrado 📖

PrivacyZoneConfig (config.privacy)

  • zones: List<PolygonZone> (Predeterminado: []) Polígonos geográficos donde el seguimiento se desactiva automáticamente. Ver Zonas de Privacidad 📖

AttestationConfig (config.attestation)

  • enabled: bool (Predeterminado: false) Utiliza Play Integrity (Android) y App Attest (iOS) para demostrar criptográficamente que el dispositivo es real y no un emulador.
  • refreshInterval: int (Predeterminado: 86400)
  • verificationUrl: String? (Predeterminado: null)
Funciones empresarialesHerramientas de diagnóstico