Referencia de API de configuración

Tracelet se configura completamente utilizando un único objeto Config pasado a Tracelet.ready(Config). Este objeto contiene todas las subconfiguraciones anidadas.

Para ayudarlo a crear la configuración perfecta para su caso de uso, aquí no solo enumeramos parámetros. Explicamos por qué existen y cuándo debes usarlos en el mundo real.

El objeto GeoConfig (config.geo)

Maneja toda la ubicación física, la precisión y la lógica de muestreo.

NO TRADUCIR

• Predeterminado: DesiredAccuracy.high (GPS)
• Qué: La precisión objetivo para el hardware de ubicación.
• Cuándo anular: Si está creando una aplicación meteorológica que solo necesita saber en qué ciudad se encuentra el usuario, anule esto a DesiredAccuracy.low (Celular/Wi-Fi). El uso de high requiere el chip GPS físico, lo que agota la batería 10 veces más rápido.

NO TRADUCIR

• Predeterminado: 10.0 (metros)
• Qué: La distancia horizontal mínima que debe moverse el dispositivo antes de que se registre un nuevo punto.
• Cuándo anular: Si está rastreando un buque de carga marítimo a través del Atlántico, configúrelo en 1000.0 (1 km). Un barco no hace giros repentinos de 10 metros y guardar puntos cada 10 metros creará miles de millones de filas inútiles en su base de datos.

NO TRADUCIR

• Predeterminado: 25.0 (metros)
• Qué: El radio alrededor del último punto conocido del usuario donde se considera “estacionario”.
• Cuándo anularlo: En entornos urbanos densos, el GPS “rebota” en los rascacielos. Si un usuario está sentado en una cafetería, su GPS podría rebotar 40 metros calle abajo. Si stationaryRadius es demasiado pequeño, Tracelet pensará que el usuario está caminando y encenderá el GPS, agotando la batería. Establezca esto en 50.0 en ciudades como Nueva York o Tokio.

NO TRADUCIR

• Predeterminado: false
• Qué: Llama automáticamente al geocodificador del sistema operativo nativo (Apple Maps/Servicios de Google Play) para codificar geográficamente las coordenadas en una dirección legible por humanos.
• Cuándo anular: Si su aplicación es un rastreador de kilometraje que necesita mostrar a los usuarios exactamente en qué calle comenzaron y terminaron un viaje, configúrelo en true. Sin embargo, tenga cuidado: la geocodificación inversa requiere una conexión a Internet activa y agrega latencia HTTP al canal de ubicación. No use esto si registra puntos cada 5 segundos, ya que el sistema operativo limitará la velocidad.

disableElasticity Y elasticityMultiplier

• Valores predeterminados: false, 1.0
• Qué: Amplía dinámicamente distanceFilter según la velocidad del usuario.
• Cuándo anularlo: Si estás siguiendo un tren de alta velocidad que va a 300 km/h, el dispositivo recorre 10 metros en una fracción de segundo. Tracelet naturalmente multiplicará el filtro de distancia por la velocidad. Si desea aún menos puntos a altas velocidades, aumente elasticityMultiplier a 2.0. Si debe tener un rastro de puntos exacto de 10 metros independientemente de la velocidad (por ejemplo, al dibujar imágenes de la calle), configure disableElasticity: true.

NO TRADUCIR

• Predeterminado: 0.0 (Desactivado)
• Qué: El porcentaje máximo objetivo de consumo de batería por hora.
• Cuándo anular: Si los clientes de su empresa se quejan de que su aplicación apaga los teléfonos de sus conductores a la hora del almuerzo, configúrelo en 1.5 (1,5 % de drenaje por hora). Tracelet monitoreará automáticamente la API de la batería. Si el drenaje supera el 1,5%, degrada desiredAccuracy y aumenta distanceFilter dinámicamente para ahorrar energía.

El objeto AndroidConfig (config.android)

Restricciones y optimizaciones específicas del sistema operativo Android.

NO TRADUCIR

• Predeterminado: false
• Qué: Elimina el Wakelock OEM cuando el dispositivo entra en un estado completamente estacionario (solo se aplica cuando se usa MotionDetectionMode.smart).
• Cuándo anular: Si su aplicación es utilizada por repartidores que pasan 30 minutos dentro de un restaurante esperando comida. Liberar el wakelock permite que la CPU del teléfono entre en suspensión profunda, ahorrando enormes cantidades de batería, mientras sigue dependiendo del acelerómetro de hardware para activar la CPU instantáneamente en el momento en que el conductor comienza a caminar de regreso a su automóvil.

El objeto LocationFilter (config.geo.filter)

Limpia los datos GPS incorrectos antes de que lleguen a su base de datos.

NO TRADUCIR

• Predeterminado: 80 (m/s)
• Qué: Rechaza los saltos de ubicación que implican que el usuario viaja más rápido que esta velocidad.
• Cuándo anular: 80 m/s es aproximadamente 288 km/h (más rápido que la mayoría de los automóviles). Si estás siguiendo un vuelo de una aerolínea comercial, un avión viaja a 900 km/h. ¡DEBES aumentar esto a 300 m/s, o Tracelet pensará que cada punto de ubicación es un problema técnico y lo desechará!

NO TRADUCIR

• Predeterminado: 50 (metros)
• Qué: Los puntos con una precisión peor que este valor no se suman al odómetro de distancia total del viaje.
• Cuándo anular: Si paga a los conductores de economía de trabajo por milla, un mal rebote del GPS de 500 metros a través de un río inflará injustamente su sueldo. Mantener este umbral ajustado (por ejemplo, 30) garantiza que solo pagará por una distancia demostrable y de alta precisión.

NO TRADUCIR

• Predeterminado: false
• Qué: Detecta si el usuario está utilizando una aplicación falsa de falsificación de GPS.
• Cuándo anular: Si estás creando un clon de Pokémon GO o una aplicación de viaje compartido, los usuarios intentarán falsificar su ubicación para engañar al sistema. Establezca esto en true para descartar instantáneamente las coordenadas falsas.

El objeto AppConfig (config.app)

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

NO TRADUCIR

• Predeterminado: true
• Qué: ¿Debería detenerse el seguimiento cuando el usuario desliza la aplicación fuera de la lista de aplicaciones recientes?
• Cuándo anular: Para las aplicaciones sociales (Buscar a mis amigos), los usuarios esperan que el seguimiento se detenga cuando fuerzan la eliminación de la aplicación. Para el seguimiento de flotas empresariales, el conductor DEBE ser rastreado independientemente. Configure stopOnTerminate: false para el seguimiento de la flota y Tracelet se reiniciará instantáneamente en segundo plano cuando el usuario cierre por la fuerza la aplicación.

Configuraciones empresariales

NO TRADUCIR

• Qué: Cifra la base de datos SQLite local en reposo mediante SQLCipher.
• Cuándo usarlo: Si está manejando el seguimiento de pacientes que cumple con HIPAA o el seguimiento de personal militar, el acceso físico local al dispositivo podría comprometer sus rutas históricas. Proporcionar una clave de cifrado garantiza que la base de datos sea inútil si roban el dispositivo.
• Cómo solicitarlo/usarlo: Tracelet proporciona un asistente criptográfico. Llame a await tl.Tracelet.generateEncryptionKey() para generar una clave aleatoria segura de 256 bits en el primer inicio de la aplicación, guárdela de forma segura (por ejemplo, usando flutter_secure_storage) y pásela a Config en arranques posteriores:

  // 1. Generate & store on first run
  final secureKey = await tl.Tracelet.generateEncryptionKey();
  await secureStorage.write(key: 'db_key', value: secureKey);
   
  // 2. Pass to config
  final config = tl.Config(
    security: tl.SecurityConfig(encryptionKey: secureKey),
  );

NO TRADUCIR

• Qué: Defina polígonos geográficos donde el seguimiento se desactiva automáticamente.
• Cuándo usarlo: Las regulaciones sindicales en muchos países europeos prohíben a los empleadores rastrear a los repartidores cuando toman su hora de almuerzo en casa o en el local sindical. Defina el salón del sindicato como PolygonZone, y Tracelet bloqueará el seguimiento mientras estén dentro y lo reanudará solo cuando se vayan.
• Cómo crear uno: Pase una lista de objetos tl.PolygonZone al PrivacyConfig.

  final config = tl.Config(
    privacy: tl.PrivacyConfig(
      zones: [
        tl.PolygonZone(
          id: 'union_hall',
          points: [
            tl.LatLng(48.8566, 2.3522),
            tl.LatLng(48.8568, 2.3525),
            tl.LatLng(48.8563, 2.3530),
          ]
        )
      ]
    )
  );