Transistorsoft Background Geolocation 替代方案

如果你在寻找适用于 Capacitor 的 Transistorsoft 后台地理位置替代方案，最接近的免费选项是 @capgo/background-geolocation。它采用 MIT 许可证，支持 Capacitor 8，可在 iOS 和 Android 上后台追踪位置，支持原生地理围栏，并能从原生 code 向你的服务器 POST 位置数据。它并未复制 Transistorsoft 的所有功能，因此本指南将介绍你能获得什么、会失去什么，以及如何迁移。

为什么团队在寻找 Transistorsoft 的替代方案

Transistorsoft SDK 是一款成熟的产品，多年来为车队、配送和健身类应用提供支持。人们很少因为产品损坏而弃用它。他们离开的原因通常如下：

发布构建现在需要在两个平台上配置密钥

根据 Transistorsoft 的更新日志，版本 9.0.0 转向基于 JWT 的许可证密钥，并开始要求在 iOS 上也配置密钥。在 v9 之前，只有 Android 的发布构建受到锁定。v8 及更早版本的密钥在 v9 中无法使用，因此升级插件也意味着需要从他们的 dashboard 生成新密钥。

他们的商店按应用标识符销售永久许可证，从 1 个密钥到 100 个密钥不等，包含一年的更新。多边形地理围栏等附加功能现在也编码在同一个密钥中。对于单个应用来说，这个价格还算合理。但对于拥有 20 个白标应用的代理机构，或需要为独立的 staging 和 production bundle ID 发布应用的公司来说，许可证就成了每年都需要有人去管理的一项开支。

核心引擎是一个二进制文件

Capacitor 封装层是开源的，但定位引擎以预构建的 iOS framework 和来自 Maven 的 Android 库形式提供。当某个特定 Android OEM 上出现异常时，你无法阅读或修补决定何时记录定位的 code。有些团队能接受这一点。但那些有严格审计要求，或者只想在 Xcode 中单步调试 code 的团队，通常无法接受。

配置项

该插件暴露了一个非常大的配置对象：运动检测、调度、里程计、SQLite 持久化、HTTP 同步模板、headless tasks 等等。如果你需要所有这些功能，那很好。但如果你只需要“在司机上班期间每 30 秒发送一次位置”，那就有很多设置需要理解。

@capgo/background-geolocation 的功能

Capgo 插件源于 Cordova 后台地理定位分支的悠久历史以及轻量级的社区 Capacitor 插件。其目标是实现精准定位、可靠的后台运行和原生地理围栏，且无需许可证。

8.x 版本系列的当前功能：

• 通过单次调用获取前台和后台位置更新， start() 并附带回调函数。
• distanceFilter 以及 minIntervalMs 以控制位置点到达的频率。
• 将每个位置通过原生 HTTP POST 发送到 url 您配置的端点，并支持自定义 headers 以及 updateHeaders() 用于令牌轮换。
• 原生圆形地理围栏，支持进入和退出事件，并提供用于状态变化通知的原生 webhook。
• checkPermissions() 以及 requestPermissions() 可区分 iOS 的“使用 App 期间”与“始终”权限。
• openSettings() 面向拒绝授权的用户。
• setPlannedRoute() 在用户偏离规划路线时播放提示音。
• Android 可选功能 networkFallback 用网络定位填补 GPS 信号盲区。
• 用于开发和浏览器测试的 Web 实现。

功能对比

实话实说：如果应用需要自行决定何时追踪、在重启后继续运行，并能离线缓存数周的定位点，Transistorsoft 更合适。如果追踪由用户或你的应用显式启动，且你想要无需 license、code 可读的精准定位，那么 Capgo 插件更合适。

安装与配置

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，可以在当前的 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，因此在 Android 限制 WebView 或 iOS 挂起 JavaScript 时，数据仍能持续流动。在 Android 上，设置 url 还能让服务保持常驻（sticky），因此即使应用被划掉，点位仍能持续发送到你的服务器。要实现可靠的后台追踪，这两个选项都需要开启。

当 access token 过期时，无需重启会话即可轮换：

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. 通过 feature flag 或单独的 build，用 Capgo 插件实现该服务。
3. 让后端接受插件的位置 JSON。请求 body 与 Location 类型（latitude, longitude, accuracy, speed, bearing, time 等等），再加上 source.
4. 移除 Transistorsoft 插件、它的 license key、额外的 Gradle 变量，以及不再需要的 background modes。
5. 在真机上锁屏测试至少 30 分钟，至少覆盖一台 Pixel、一台 Samsung 和一台 iPhone。

原生插件变更需要新的商店构建。该构建上线后，你可以继续通过 Live Update 向追踪 UI 发布 JavaScript 修复。 Capgo 实时更新 无需再走一轮审核。

当 Capgo 插件无法满足需求时

切换前请先确认这几点：

• 没有持久化队列。 Native POST 采用尽力而为模式。如果设备离线，失败的点位会被记录后丢弃。如果你一个点位都不能丢，还要在回调中把点位存到本地（例如用 SQLite），再由 App 同步，或者继续使用 Transistorsoft。
• 重启后不会自动恢复。 用户下次打开 App 时，追踪会恢复。
• 不支持自动运动检测。 何时开始和停止由 App 决定。
• iOS 终止机制。 如果用户在 iOS 上强制退出，标准定位更新就会停止。这是系统规则，不是插件限制。

想进一步了解 Capacitor 在 App 进入后台时能运行哪些内容，请参阅 后台任务在 Capacitor 中如何工作.

故障排除

在 Android 上，更新几分钟后就会停止。 查看 useLegacyBridge: true，确认前台服务通知可见，并在激进的 OEM 设备上测试时禁用应用的电池优化。使用 url 选项，让下发不依赖 WebView。

iOS 在后台无法进行更新。 确认 UIBackgroundModes 包含 location，你传入的 backgroundMessage，并且你调用了 start() 在应用处于前台时。我们关于 为什么 iOS 会停止后台位置更新 逐一讲解每个原因。

NOT_AUTHORIZED 错误。 用户拒绝了定位权限。请调用 openSettings() 在解释应用为何需要定位之后。

室内定位点跳动。 提高 distanceFilter，忽略具有较大 accuracy 值的点，并在 Android 上考虑 networkFallback: true 仅当可接受粗略定位时。

外卖应用中的模拟定位。 每个 Location 有一个 simulated 标志。如需更严格的检查，请添加 @capgo/capacitor-mock-location-detector.

选择

如果需要基于运动的自动启动、重启后仍能运行、离线队列和多边形地理围栏，且许可证费用合适，就选 Transistorsoft。如果 @capgo/background-geolocation 你的追踪是基于会话的，希望 code 可读且无需按应用购买许可证，并愿意在应用内自行管理队列，请选择。如果你要一次性替换多个付费原生 SDK，那么 Ionic Enterprise 插件替代方案 页面列出了其他 Capgo 替代方案。