Transistorsoft背景地理位置替代方案

如果您正在寻找一个Transistorsoft背景地理位置替代品，用于Capacitor，最接近的免费选项是 @capgo/background-geolocation. It is MIT licensed, ships for Capacitor 8, tracks location in the background on iOS and Android, supports native geofencing, and can POST locations to your server from native code. It does not copy every Transistorsoft feature, so this guide covers what you gain, what you give up, and how to migrate.

为什么团队寻找Transistorsoft替代品

TransistorsoftSDK是一个成熟的产品，已经为几年了。人们很少离开它，因为它是破裂的。他们离开的原因是

发布构建现在需要在两个平台上都有一个密钥

根据Transistorsoft的更改日志，版本9.0.0将基于JWT的许可密钥，开始要求在iOS上也有一个密钥。之前的v9，只有Android发布构建被锁定。从v8和之前的密钥不能与v9一起使用，所以升级插件也意味着从他们的控制台生成新的密钥

他们的商店出售每个应用标识符的永久许可证，从一个密钥到100个密钥，包含一年的更新。现在的附加功能，如多边形地理围栏，已经编码到同一个密钥中。对于一个应用来说，这是一个合理的价格。对于一个拥有20个白标应用的代理公司，或者一个公司，需要管理每年一个许可证的公司，许可证就变成了一个需要管理的项目

核心引擎是一个二进制

The Capacitor wrapper is open, but the location engine ships as a prebuilt iOS framework and an Android library from Maven. When something odd happens on a specific Android OEM, you cannot read or patch the code that decides when to record a fix. Some teams accept that. Teams with strict audit requirements, or who just want to step through the code in Xcode, often do not.

配置表面

插件暴露了一个非常大的配置对象：运动检测、调度、里程计、SQLite持久性、HTTP同步模板、无头任务等。如果您需要所有这些，那么很好。如果您需要“在驾驶员上班时每30秒发送我的位置”，那么这需要了解很多设置。

什么是@capgo/background-geolocation

The Capgo plugin started from the long history of the Cordova background geolocation forks and the lightweight community Capacitor plugin. The goal is accurate fixes, reliable background operation and native geofencing, without a license.

8.x线上的当前功能：

• 通过一个回调函数来实现前台和后台位置更新 start() 和
• distanceFilter 控制点的频率 minIntervalMs 原生HTTP POST每个位置到
• 一个 url 您可以自定义配置 headers 和 updateHeaders() 用于令牌轮换
• 原生圆形地理围栏，具有进入和退出事件，以及原生过渡 webhook。
• checkPermissions() 和 requestPermissions() 区分 iOS 的 When In Use 和 Always。
• openSettings() 对于拒绝权限的用户
• setPlannedRoute() 在用户离开计划路线时播放声音
• 可选的 Android networkFallback 填补 GPS 空白区域的网络位置
• 用于开发和浏览器测试的 Web 实现

功能比较

Transistorsoft 是更好的选择：当应用程序必须自己决定何时跟踪、在重启后存活并缓冲数周的点时。Capgo 插件是更好的选择：当用户或您的应用程序明确开始跟踪时，您希望准确的定位并无需许可且可读的code。

安装和配置

bun add @capgo/background-geolocation
bunx cap sync

iOS

添加使用字符串和位置背景模式到 ios/App/App/Info.plist:

<key>NSLocationWhenInUseUsageDescription</key>
<string>We use your location to show your route.</string>
<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>We use your location in the background to record your route while the phone is locked.</string>
<key>UIBackgroundModes</key>
<array>
  <string>location</string>
</array>

请记住，自 2026 年 4 月起，App Store 上传要求使用 Xcode 26。如果您的 CI 镜像较旧，上传将被拒绝，即使构建成功。 Capgo 构建 在不维护 Mac 的情况下，__CAPGO_KEEP_0__ 构建可以在当前的 Xcode 镜像上运行。

Android

该插件使用前台服务与持久通知在后台跟踪。从 Android 13 开始，它要求 POST_NOTIFICATIONS 在位置授权后显示通知。

设置 useLegacyBridge 在 capacitor.config.ts. 如果没有它，WebView中的位置回调在后台将在大约五分钟后停止：

import type { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  appId: 'com.example.tracker',
  appName: 'Tracker',
  webDir: 'dist',
  android: {
    useLegacyBridge: true,
  },
};

export default config;

您可以通过以下方式自定义通知频道名称、图标和颜色： strings.xml 请参阅 插件文档.

开始跟踪

import { BackgroundGeolocation } from '@capgo/background-geolocation';

export async function startShift(token: string) {
  await BackgroundGeolocation.start(
    {
      backgroundTitle: 'Shift in progress',
      backgroundMessage: 'Your location is shared with dispatch until you end the shift.',
      requestPermissions: true,
      stale: false,
      distanceFilter: 25,
      url: 'https://api.example.com/v1/locations',
      headers: { Authorization: `Bearer ${token}` },
      minIntervalMs: 30_000,
    },
    (location, error) => {
      if (error) {
        if (error.code === 'NOT_AUTHORIZED') {
          BackgroundGeolocation.openSettings();
        }
        console.error(error);
        return;
      }
      if (location) {
        // Update the UI while the WebView is alive
        console.log(location.latitude, location.longitude, location.accuracy);
      }
    },
  );
}

export async function endShift() {
  await BackgroundGeolocation.stop();
}

两个选项看似不重要，但实际上却很重要：

• backgroundMessage 是开启后台更新的关键，两者都需要。没有它，更新只在前台保证。 在 Android 上，它也是前台服务通知的文本。
• url 将每个点从本地 code 发送到服务器时，会在请求体中添加一个 "source": "native" 该路径不依赖于 WebView，WebView 是保持数据流动的关键。 当 Android 队列 WebView 或 iOS 暂停 JavaScript 时，WebView 就会保持数据流动。 在 Android 上，设置 url 也会使服务保持在内存中，使得点继续到达您的服务器，即使应用程序被滑动到后台。 需要同时设置这两个选项才能实现可靠的后台跟踪。

当访问令牌过期时，旋转令牌而不重新启动会话：

await BackgroundGeolocation.updateHeaders({
  headers: { Authorization: `Bearer ${newToken}` },
});

地理围栏

Transistorsoft用户经常依赖其地理围栏功能。Capgo插件使用两种平台的原生API来覆盖圆形区域:

import { BackgroundGeolocation } from '@capgo/background-geolocation';

await BackgroundGeolocation.setupGeofencing({
  url: 'https://api.example.com/v1/geofence-events',
  headers: { Authorization: 'Bearer <token>' },
  notifyOnEntry: true,
  notifyOnExit: true,
  payload: { driverId: 'd-381' },
  backgroundLocation: true, // Android only, needs ACCESS_BACKGROUND_LOCATION in your manifest
});

await BackgroundGeolocation.addGeofence({
  identifier: 'depot-north',
  latitude: 48.8584,
  longitude: 2.2945,
  radius: 200,
  payload: { depotId: 'north' },
});

await BackgroundGeolocation.addListener('geofenceTransition', (event) => {
  console.log(event.identifier, event.transition, event.payload);
});

iOS地理围栏需要始终授权。Android 10及以上版本的后台地理围栏需要 ACCESS_BACKGROUND_LOCATION,该插件不会为您添加此项。只有在您的应用获得了Google Play的背景位置批准时才会添加。如果您的地理围栏在iOS上表现异常，请阅读我们的指南 为什么地理围栏在iOS上不会触发.

从Transistorsoft迁移

API不同，因此您需要计划小规模地重写您的位置服务，而不是简单地替换。

实践中有效的步骤:

1. 在应用中包裹位置访问（startTracking, stopTracking, onPoint大多数应用已经有一个了。
2. 使用 Capgo 插件实现服务，后面带有一个特性标志或单独的构建。
3. 让后端接受插件的位置 JSON。请求体匹配类型（ Location 等等）加上latitude, longitude, accuracy, speed, bearing, time 移除 Transistorsoft 插件、许可证密钥、额外的 Gradle 变量和不再需要的后台模式。 source.
4. 移除 Transistorsoft 插件、许可证密钥、额外的 Gradle 变量和不再需要的后台模式。
5. 使用屏幕锁定状态的真实设备进行测试，至少30分钟，至少在一个Pixel、一个Samsung和一个iPhone上。

原生插件更改需要新建一个商店构建。一旦该构建上线，您就可以继续将JavaScript修复发送到您的跟踪UI中 Capgo实时更新 在__CAPGO_KEEP_0__插件不够的情况下

在Capgo插件不足的情况下

没有持久的队列。

• 原生POST请求最好努力。如果设备离线，失败的点会被记录并丢弃。如果您不能丢失一个点，也可以在回调中使用SQLite等存储点并从应用中同步它们，或者继续使用Transistorsoft。 没有重启后重启。
• 跟踪将在用户下一次打开应用时恢复。 没有自动运动检测。
• 应用决定何时启动和停止。 在切换之前，请明确以下几点:
• iOS终止。 如果用户在iOS上强制退出，标准位置更新将停止。 这是操作系统的规则，而不是插件限制。

有关Capacitor在后台时可以运行的更多上下文，请参见 如何在Capacitor中使用后台任务.

故障排除

在Android上，更新将在几分钟后停止。 检查 useLegacyBridge: true, 确认前台服务通知可见，并在aggressive OEMs上禁用应用程序的电池优化。 使用 url 选项以避免依赖WebView。

iOS中没有后台更新。 确认 UIBackgroundModes 包含 location, 你们都通过了 backgroundMessage, 你们都称为 start() 应用程序在前台时,我们的指南 iOS 为什么会停止后台位置更新 详细介绍了每种原因。

NOT_AUTHORIZED 错误。 用户拒绝了位置。请 openSettings() 解释为什么应用程序需要它。

Jumpy 点 indoor。 Raise distanceFilter, 忽略大值的点,并且在 Android 上考虑 accuracy values networkFallback: true 仅当粗略定位足够时。

模拟送货应用中的位置。 每个 Location 都有一个 simulated 标志。对于更严格的检查，添加 @capgo/capacitor-mock-location-detector.

选择

如果您需要基于运动的自动启动、重启持久性、离线队列和多边形地理围栏，并且许可证成本合适，请选择Transistorsoft。选择 @capgo/background-geolocation if your tracking is session based, you want readable code and no per app license, and you are fine owning queueing in your app. If you are replacing several paid native SDKs at once, the 并且不需要每个应用许可，并且您愿意在应用中拥有队列。 如果您一次替换多个付费原生 SDK，则 page lists the other Capgo replacements.