Skip to Content
Справочник по API

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

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

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

Обновление конфигурации во время выполнения — ready() против setConfig()

Есть два способа, которыми конфигурация достигает плагина, и они означают разные вещи.

Tracelet.ready(config) устанавливает полный базовый уровень. Каждое поле отправлено, решено до его фактического значения. Вызовите его один раз при запуске — или еще раз, когда вы хотите заменить всю конфигурацию. Tracelet.reset(config) ведет себя таким же образом.

Tracelet.setConfig(config) — это частичное обновление. Только поля ты фактически установленные данные передаются; все остальное сохраняет все, что есть на платформе упорствовал. Это то, что вам нужно в середине сессии, когда нужно что-то изменить:

// Changes one flag. The notification title from ready(), the HTTP URL,
// distanceFilter, stopOnTerminate — all keep their configured values.
await Tracelet.setConfig(const Config(
  android: AndroidConfig(
    foregroundService: ForegroundServiceConfig(
      showNotificationOnPauseOnly: true,
    ),
  ),
));
 
// Changes nothing at all.
await Tracelet.setConfig(const Config());

⚠️ Изменено в версии 3.8.0. setConfig() ранее заменял весь конфигурация, поэтому любое поле, которое вы не упомянули, молча возвращается к своему по умолчанию — setConfig(const Config()) сбросить все, включая stopOnTerminate, настройки HTTP, уведомление службы переднего плана и флаги активности iOS. Если вы полагались на это для сброса состояния, позвоните Tracelet.reset() или вместо этого ready() (#320 , #321 ).

Возврат значения к значению по умолчанию по-прежнему работает. «Не установлено» означает, что вы этого не сделали. указывайте поле, никогда значение равно значению по умолчанию — так ForegroundServiceConfig(showNotificationOnPauseOnly: false) включает флаг выключенный. Только поле, которое вы полностью опускаете, остается нетронутым.

Tracelet.activeConfig применяет одно и то же слияние локально, поэтому оно всегда отражает что на самом деле содержит платформа, а не значения по умолчанию, оставшиеся после последнего звонка не установлен.

Для изменений, которые не должны сохраняться или перезапускать конвейер, используйте метод вместо этого целевые API среды выполнения: updateLocationProviderOptions() для точности/расстояния и updateNotification() чтобы сделать репост живого уведомления.

🌍 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) Скрывает уведомление, пока приложение отображается на экране. Игнорируется, пока app.stopOnTerminate имеет значение false — его скрытие понижает статус службы переднего плана, а пролистывание по недавним событиям в этом окне завершает процесс (#378 ). Переопределение регистрируется один раз для start(). См. Скрытие уведомления 📖
  • actions: List<String> (по умолчанию: [])
  • notificationStartedAt: int? (по умолчанию: null) Эпоха миллисекунд (настенные часы), от которой отсчитывает прошедшее время. Отображается только тогда, когда notificationShowTimer имеет значение true. Значение в будущем привязывается к текущему времени каждый раз при публикации уведомления, поэтому коррекция часов устройства самовосстанавливается. См. Таймер прошедшего времени 📖
  • notificationShowTimer: bool (по умолчанию: false) Показывает автоматически тикающие часы от notificationStartedAt. Android продвигает его без репостов из вашего приложения. Таймер не отображается, если notificationStartedAt отсутствует.
  • notificationOnlyAlertOnce: bool (по умолчанию: false) Оповещает устройство только при первом сообщении уведомления, поэтому последующие обновления контента остаются без звука. Полезно для любых уведомлений, текст которых меняется во время отслеживания, а не только для таймеров. См. Тихое обновление текста 📖

🔔 Чтобы применить изменение уведомления во время отслеживания уже запущено, вызовите 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+).

LiveActivityConfig (config.ios.liveActivityConfig)

  • title: String (Обязательно) Статический заголовок. Атрибуты ActivityKit неизменяемы во время выполнения действия, поэтому изменения применяются при следующем запуске.

  • body: String (Обязательно) Динамическая строка состояния, обновленная updateNotification().

  • startedAt: int? (по умолчанию: null) Эпоха миллисекунд (настенные часы), от которой отсчитывает прошедшее время. Отображается только тогда, когда showTimer имеет значение true. См. Таймер прошедшего времени 📖

  • showTimer: bool (по умолчанию: false) Отрисовывает автоматически тикающие часы из startedAt с помощью Text(timerInterval:). iOS продвигает его без обновлений вашего приложения. Таймер не отображается, если startedAt отсутствует.

    Пользовательское расширение виджета отображает таймер только в том случае, если его собственная копия TraceletActivityAttributes.ContentState объявляет startedAt и showTimer. Расширения, написанные до появления этих полей, продолжают работать — дополнительные значения просто игнорируются — но не показывают часы, пока вы не обновите структуру. Смотрите обновленный фрагмент 📖

📍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).

  • geofenceExitAccuracyMax: int (по умолчанию: -1) Настраивает ворота EXIT с учетом точности в режиме высокой точности (в стандартном режиме эффекта нет). Круговая геозона ВЫХОДИТ только после того, как весь круг ошибок GPS пересекает ограждение (distance - accuracy > radius + buffer), что предотвращает срабатывание ложного ВЫХОДа одним фиксом с большим дрейфом, пока устройство неподвижно находится внутри небольшого забора - за счет задержки истинного выхода примерно из-за неопределенности GPS.

    • -1 (по умолчанию) — полное стробирование; наиболее устойчив к ложным выходам.
    • 0 — стробирование отключено; самый быстрый выход, но склонен к заносу (поведение до исправления).
    • N > 0 — точность фиксации до метров N; поглощает дрейф до N, ограничивая при этом задержку на выход в худшем случае ~N метров. См. дрейф GPS и ложный ВЫХОД 📖

📡 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)
  • syncTelematics: bool (по умолчанию: false) Загружает сохраненные события вождения/удара рядом с вашими местоположениями. По умолчанию отключено, поэтому существующая полезная нагрузка никогда не меняется под вами. См. синхронизацию телематики 📖
  • telematicsUrl: String? (по умолчанию: null) Отправляет телематические данные в собственную конечную точку как {"telematics": [...]} вместо того, чтобы прикреплять их к полезной нагрузке местоположения. Требуется syncTelematics. Передайте пустую строку (не null), чтобы вернуться к прикрепленному пути — конфигурация объединяется, а не заменяется.

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

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

  • enabled: bool (по умолчанию: false) Создает криптографический защищенный от несанкционированного доступа блокчейн хэшей местоположений.
  • hashAlgorithm: HashAlgorithm (по умолчанию: HashAlgorithm.sha256) В настоящее время сеть всегда использует SHA-256; выбор другого алгоритма пока не применяется.
  • includeExtrasInHash: bool (по умолчанию: false) — ⚠️ Устарело: не реализовано. Цепочка всегда хэширует только основные поля местоположения, поэтому этот флаг ничего не меняет. Его подключение сделает недействительной каждую ранее вычисленную цепочку, поэтому требуется версионирование. цепная миграция, а не молчаливое изменение поведения.

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

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

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

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

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