Исчерпывающий справочник по API

Эта страница содержит абсолютный источник истины для API конфигурации Tracelet. Здесь перечислены все параметры, которые можно передать Tracelet.ready(Config).

Чтобы просмотреть реальные архитектурные сценарии, объясняющие почему вам следует использовать эти параметры, нажмите ссылку «Просмотреть историю 📖» рядом с ними.

🌍 GeoConfig (config.geo)

Управляет физическим местоположением, точностью и логикой выборки. См. Geo Story 📖

• desiredAccuracy: DesiredAccuracy (по умолчанию: DesiredAccuracy.high) Целевая аппаратная точность. Используйте high для GPS, low для сотовой связи/Wi-Fi, чтобы сэкономить заряд батареи.
• distanceFilter: double (по умолчанию: 10.0) Минимальное количество метров по горизонтали, которое необходимо пройти перед записью точки.

ℹ️ Изменение desiredAccuracy или distanceFilter через setConfig() сохраняет значения и перезапускает конвейер отслеживания. Для временного переопределения во время отслеживания (например, отключения GPS в течение подтвержденного стационарного периода) используйте updateLocationProviderOptions() — он обновляет работающего поставщика в реальном времени, без перезапуска и никогда не затрагивает сохраненную конфигурацию.

• stationaryRadius: double (по умолчанию: 25.0) Радиус вокруг пользователя считается стационарным (препятствует утечке GPS).
• locationTimeout: int (по умолчанию: 60) Максимальное количество секунд ожидания блокировки GPS, прежде чем сдаваться.
• disableElasticity: bool (по умолчанию: false) Если это правда, отключает динамическое масштабирование расстояния на основе скорости.
• elasticityMultiplier: double (по умолчанию: 1.0) Множитель для динамического фильтра расстояния при движении на высоких скоростях.
• stopAfterElapsedMinutes: int (по умолчанию: -1) Автоматически останавливает двигатель через X минут. -1 означает работать вечно.
• maxMonitoredGeofences: int (по умолчанию: -1) Максимальное количество геозон для одновременного мониторинга.
• enableTimestampMeta: bool (по умолчанию: false) Прикрепляет точные наносекундные аппаратные метки времени.
• enableAdaptiveMode: bool (по умолчанию: false) Автоматическое переключение настроек в зависимости от уровня заряда батареи.
• periodicLocationInterval: int (по умолчанию: 900) Секунды между периодическими обновлениями в неподвижном состоянии.
• periodicDesiredAccuracy: DesiredAccuracy (по умолчанию: DesiredAccuracy.medium) Точность, используемая во время периодических фоновых пробуждений.
• enableSparseUpdates: bool (по умолчанию: false) Использует исключительно триангуляцию вышки сотовой связи с низким энергопотреблением.
• sparseDistanceThreshold: double (по умолчанию: 50.0) Метров двигаться в разреженном режиме.
• sparseMaxIdleSeconds: int (по умолчанию: 300) Максимальное время без редких обновлений.
• enableDeadReckoning: bool (по умолчанию: false) Использует акселерометр/гироскоп для определения местоположения при потере GPS (например, в туннелях).
• deadReckoningActivationDelay: int (по умолчанию: 0) Секунды потери GPS, прежде чем сработает точный расчет.
• deadReckoningMaxDuration: int (по умолчанию: 0) Максимальное количество секунд, необходимое для точного расчета перед остановкой.
• resolveAddress: bool (по умолчанию: false) Автоматически обратное геокодирование координат в строку адреса.

🧹 Фильтр местоположения (config.geo.filter)

Очищает неверные данные GPS до того, как они попадут в SQLite/Sync. См. историю фильтров 📖

• trackingAccuracyThreshold: int (по умолчанию: 100) Точки с точностью хуже, чем X метров, отбрасываются.
• maxImpliedSpeed: int (по умолчанию: 80) Отклоняет скачки местоположения, которые подразумевают скорость > X м/с (80 м/с = 288 км/ч).
• odometerAccuracyThreshold: int (по умолчанию: 50) Точки с точностью хуже, чем метры X, не увеличивают общее расстояние поездки.
• policy: LocationFilterPolicy (по умолчанию: LocationFilterPolicy.adjust) Как обрабатывать плохие точки (drop или adjust).
• rejectMockLocations: bool (по умолчанию: false) Немедленно удаляет местоположения, созданные приложениями для подмены GPS.
• mockDetectionLevel: int (по умолчанию: 1) Агрессивность эвристики обнаружения поддельных GPS.
• useKalmanFilter: bool (по умолчанию: false) Применяет комплексное сглаживание Калмана к необработанной траектории GPS.

📱 Конфигурация приложения (config.app)

Управляет общим поведением жизненного цикла приложения.

• stopOnTerminate: bool (по умолчанию: true) Если true, отслеживание прекращается, когда пользователь смахивает приложение. Если false, он перезагружается в фоновом режиме. См. Завершить историю 📖
• startOnBoot: bool (по умолчанию: false) Если true, отслеживание начинается автоматически при перезагрузке телефона.
• heartbeatInterval: int (по умолчанию: 60) Вызывает событие «пульс» каждые X секунд, чтобы доказать, что движок жив.
• schedule: List<String> (по умолчанию: []) CRON-подобные строки для автоматического запуска/остановки отслеживания в определенное время.
• remoteConfigUrl: String? (по умолчанию: null) URL-адрес HTTPS, из которого SDK извлекает карту конфигурации JSON на ready(), применяя ее к локальной конфигурации и обновляя в фоновом режиме. Кэшируется на устройстве для мгновенного применения в автономном режиме. См. Удаленная настройка.
• remoteConfigHeaders: Map<String, String>? (по умолчанию: null) HTTP-заголовки для удаленной выборки конфигурации.
• remoteConfigTimeout: int (по умолчанию: 60000) Таймаут получения удаленной конфигурации в мс.
• remoteConfigRefreshInterval: int (по умолчанию: 1440) Несколько минут до повторного получения удаленной конфигурации.

🤖 Конфигурация Android (config.android)

Ограничения ОС Android. Смотрите историю Android 📖

• locationUpdateInterval: int (по умолчанию: 1000) Ms между пингами GPS.
• batteryBudgetPerHour: double (по умолчанию: 0.0) Целевой максимальный расход батареи в % в час. 0.0 отключает регулирование.
• releaseWakelockWhenStationary: bool (по умолчанию: false) При использовании MotionDetectionMode.smart блокировка отслеживания снимается, когда устройство полностью неподвижно, чтобы максимизировать экономию заряда батареи при глубоком сне.
• fastestLocationUpdateInterval: int (по умолчанию: 500) Самая быстрая мс между пингами GPS, если их запрашивает другое приложение.
• deferTime: int (по умолчанию: 0) Позволяет Android пакетно обновлять местоположение для X ms.
• allowIdenticalLocations: bool (по умолчанию: false) Если false, повторяющиеся точные координаты удаляются.
• geofenceModeHighAccuracy: bool (по умолчанию: false) — ⚠️ Устарело Включает GPS-чип для геозон (сильный разряд батареи). Используйте кроссплатформенность GeofenceConfig.geofenceModeHighAccuracy (см. раздел GeofenceConfig ниже) вместо этого — теперь он контролирует как iOS, так и Android. Этот флаг только для Android по-прежнему отмечен за обратную совместимость (если какой-либо из них имеет значение true, используется режим высокой точности). включен), но будет удален в будущей основной версии.
• periodicUseForegroundService: bool (по умолчанию: false) Вызывает постоянное уведомление во время периодических пробуждений.
• periodicUseExactAlarms: bool (по умолчанию: false) Использует AlarmManager для точного пробуждения (требуется разрешение манифеста SCHEDULE_EXACT_ALARM). См. точные сигналы тревоги 📖
• scheduleUseAlarmManager: bool (по умолчанию: false) Использует точные сигналы тревоги для планирования CRON.

ForegroundServiceConfig (config.android.foregroundService)

• enabled: bool (по умолчанию: true) Требуется разрешение POST_NOTIFICATIONS на Android 13+. См. уведомление 📖
• channelId: String (по умолчанию: 'tracelet_channel')
• channelName: String (по умолчанию: 'Tracelet')
• notificationTitle: String (по умолчанию: 'Tracelet')
• notificationText: String (по умолчанию: 'Tracking location in background')
• notificationColor: String? (по умолчанию: null) Шестнадцатеричный цвет фона маленькой иконки.
• notificationSmallIcon: String? (по умолчанию: null) Имя PNG-файла только белого цвета в папке res/drawable.
• notificationLargeIcon: String? (по умолчанию: null)
• notificationPriority: NotificationPriority (по умолчанию: NotificationPriority.defaultPriority)
• notificationOngoing: bool (по умолчанию: true)
• showNotificationOnPauseOnly: bool (по умолчанию: false)
• actions: List<String> (по умолчанию: [])

🔔 Чтобы применить изменение уведомления во время отслеживания уже запущено, вызовите Tracelet.updateNotification() после setConfig(). Он повторно публикует живое уведомление без перезапуска конвейера (v3.6.8+). В iOS вместо этого обновляется текущая активность Live; в сети это не работает.

🍎 IosConfig (config.ios)

Ограничения ОС, специфичные для iOS. Смотрите историю iOS 📖

• activityType: LocationActivityType (по умолчанию: LocationActivityType.other) Сообщает iOS, что вы делаете (например, fitness, navigation), чтобы она знала, когда приостановить отслеживание.
• useSignificantChangesOnly: bool (по умолчанию: false) Полностью полагается на передачу обслуживания вышкой сотовой связи. Почти нулевой разряд батареи.
• showsBackgroundLocationIndicator: bool (по умолчанию: false) Показывает индикатор «Синяя таблетка». Требуется возможность location Xcode. См. Синюю таблетку 📖
• pausesLocationUpdatesAutomatically: bool (по умолчанию: false) Позволяет iOS отключать чип GPS, если пользователь некоторое время не двигался.
• locationAuthorizationRequest: LocationAuthorizationRequest (по умолчанию: always) Какое разрешение запрашивать.
• disableLocationAuthorizationAlert: bool (по умолчанию: false) Не позволяет ОС запрашивать «Всегда разрешать», если запрашивается только «При использовании».
• preventSuspend: bool (по умолчанию: false) Воспроизводит бесшумный звук, чтобы приложение работало круглосуточно и без выходных. Требуется возможность audio Xcode. См. Предотвращение приостановки 📖
• useBackgroundActivitySession: bool (по умолчанию: false) Использует CLBackgroundActivitySession (iOS 17+) для поддержания фонового сеанса определения местоположения только с авторизацией «При использовании». Он заменяет традиционную синюю таблетку индикатором Dynamic Island. Примечание. Рекомендации Apple App Store требуют, чтобы приложения, использующие это, четко объясняли пользователям, почему необходимо фоновое местоположение.
• liveActivityConfig: LiveActivityConfig? (по умолчанию: null) Включите экран блокировки/динамическую активность на острове во время отслеживания (iOS 16.1+, требуется расширение виджета). Принимает title и body. См. Живые мероприятия 📖. Обновите его во время выполнения с помощью Tracelet.updateNotification() (v3.6.8+).

📍GeofenceConfig (config.geofence)

Межплатформенное поведение геозон (iOS + Android).

• geofenceModeHighAccuracy: bool (по умолчанию: false) Управляет обнаружением переходов геозон:
  • false (по умолчанию) — использует службу мониторинга региона ОС. Низкое энергопотребление, отсутствие синего индикатора iOS, но ОС обеспечивает практический минимальный радиус (~ 100 м), поэтому небольшие переходы или переходы ВЫХОД могут быть ненадежными.
  • true — оценивает переходы в приложении от непрерывного GPS. Обеспечивает надежность малых радиусов (например, 5–50 м) и событий ВЫХОД за счет более высокого расхода заряда батареи и — на iOS — индикатора системного «местоположения использования» (синего) в строке состояния (постоянный GPS требует этого). См. Синюю таблетку 📖

Это заменяет устаревший AndroidConfig.geofenceModeHighAccuracy; если любой из них имеет значение true, включается режим высокой точности.

• geofenceInitialTrigger: bool (по умолчанию: true) Оцените состояние геозоны при регистрации.
• geofenceInitialTriggerEntry: bool (по умолчанию: true) Немедленно активируйте ENTER, если устройство уже находилось внутри геозоны на момент регистрации.
• geofenceProximityRadius: int (по умолчанию: 1000) Радиус (в метрах) для загрузки на основе близости — только геозоны на этом расстоянии активно регистрируются в ОС (позволяет управлять гораздо большим количеством регионов, чем лимит iOS 20).

📡 HttpConfig (config.http)

Управляет механизмом сетевой синхронизации. См. историю синхронизации 📖

• url: String? (по умолчанию: null) Ваша серверная конечная точка.
• method: HttpMethod (по умолчанию: HttpMethod.post)
• headers: Map<String, String>? (по умолчанию: null) Пользовательские заголовки аутентификации. Для динамической ротации JWT см. обратные вызовы 📖
• params: Map<String, Object?>? (по умолчанию: null)
• extras: Map<String, Object?>? (по умолчанию: null) Статические данные JSON, вводимые в полезную нагрузку каждого местоположения.
• httpRootProperty: String? (по умолчанию: 'location') Корневой узел JSON.
• autoSync: bool (по умолчанию: true) Загружается автоматически. Если false, вы должны вызвать Tracelet.sync().
• batchSync: bool (по умолчанию: false) Загружает массивы местоположений вместо 1 на 1.
• maxBatchSize: int (по умолчанию: 250)
• autoSyncThreshold: int (по умолчанию: 0) Количество записей SQLite, необходимых для запуска синхронизации.
• autoSyncDelay: int (по умолчанию: 10000) Необходимо подождать перед синхронизацией после прибытия местоположения.
• syncInterval: int (по умолчанию: 0) Секунды между повторяющимися, основанными на времени сбросами автономной очереди. Когда > 0, SDK периодически загружает любые ожидающие местоположения в этом ритме — независимо от устранения дребезга autoSyncDelay, который срабатывает при новых вставках. Полезно для очистки по времени, независимо от того, сколько записей накопилось. 0 отключает интервальный таймер.
• httpTimeout: int (по умолчанию: 60000)
• locationsOrderDirection: LocationOrderDirection (по умолчанию: LocationOrderDirection.ascending)
• disableAutoSyncOnCellular: bool (по умолчанию: false) Синхронизируется только при подключении к Wi-Fi для сохранения пользовательских планов передачи данных.
• maxRetries: int (по умолчанию: 3)
• retryBackoffBase: int (по умолчанию: 1000)
• retryBackoffCap: int (по умолчанию: 60000)
• enableDeltaCompression: bool (по умолчанию: false) Отправляет только дельта-координаты, уменьшая размер полезных данных JSON на 80 %.
• deltaCoordinatePrecision: int (по умолчанию: 5)
• sslPinningFingerprints: List<String>? (по умолчанию: null)
• sslPinningCertificates: List<String>? (по умолчанию: null)

🏢 Корпоративные конфигурации

AuditConfig (НОТРАНС1LATE)

• enabled: bool (по умолчанию: false) Создает криптографический защищенный от несанкционированного доступа блокчейн хэшей местоположений.
• hashAlgorithm: HashAlgorithm (по умолчанию: HashAlgorithm.sha256)
• includeExtrasInHash: bool (по умолчанию: false)

SecurityConfig (НОТРАНС1LATE)

• encryptionKey: String? (по умолчанию: null) Шифрует базу данных SQLite с помощью SQLCipher. См. Шифрование 📖

PrivacyZoneConfig (НОТРАНС1LATE)

• zones: List<PolygonZone> (по умолчанию: []) Географические полигоны, отслеживание которых автоматически отключается. См. Зоны конфиденциальности 📖

AttestationConfig (НОТРАНС1LATE)

• enabled: bool (по умолчанию: false) Использует Play Integrity (Android) и App Attest (iOS), чтобы криптографически доказать, что устройство реально, а не является эмулятором.
• refreshInterval: int (по умолчанию: 86400)
• verificationUrl: String? (по умолчанию: null)