> For AI agents: the complete documentation index is available at /apps-plugin/docs/llms.txt, the full documentation bundle is available at /apps-plugin/docs/llms-full.txt.

# startLocationUpdate

开始接收位置更新。

## 使用限制

> \[!WARNING]
> **iOS**：省略 type 时调用失败；iOS 调用方必须显式传入 type。

## 支持版本

前端库版本不低于 `0.0.32`。

## 支持平台

<table>
<thead>
<tr><th>平台</th><th>支持情况</th></tr>
</thead>
<tbody>
<tr><td>Android</td><td>支持</td></tr>
<tr><td>iOS</td><td>支持</td></tr>
<tr><td>PC</td><td>不支持</td></tr>
<tr><td>HarmonyOS</td><td>不支持</td></tr>
</tbody>
</table>

## 支持场景

<table>
<thead>
<tr><th>场景</th><th>支持情况</th></tr>
</thead>
<tbody>
<tr><td>页面</td><td>支持</td></tr>
<tr><td>卡片</td><td>不支持</td></tr>
</tbody>
</table>

## 接入准备

### 权限要求

<table>
<thead>
<tr><th>类型</th><th>标识</th><th>是否必须</th><th>平台</th><th>说明</th></tr>
</thead>
<tbody>
<tr><td>应用权限</td><td><code>scope.userLocation</code></td><td>必须</td><td>Android、iOS</td><td>需要获取位置信息授权</td></tr>
<tr><td>应用权限</td><td><code>scope.userLocationBackground</code></td><td>按条件</td><td>Android、iOS</td><td>实现会尝试申请后台定位授权，申请失败不阻断本次启动</td></tr>
<tr><td>系统权限</td><td>地理位置权限</td><td>必须</td><td>Android、iOS</td><td>需要开启系统定位服务并授予位置权限</td></tr>
</tbody>
</table>

### 授权行为

- **Android**：调用会主动申请应用位置授权和系统定位权限，并以尽力而为方式申请后台定位授权。拒绝、取消或撤销应用授权后，再次调用直接失败；可通过 `authorize({ scope: 'scope.userLocation' })` 重新发起。后台定位授权失败不阻断启动。
- **iOS**：调用会主动申请应用位置授权和系统定位权限，并继续尝试后台定位授权。已拒绝或撤销后再次调用直接失败；可通过 `authorize({ scope: 'scope.userLocation' })` 重新发起。后台定位授权失败不阻断启动。

### 前置条件

- 在应用权限声明中配置 `scope.userLocation`，并确保系统定位服务已开启

## 使用说明

需配对调用 stopLocationUpdate。

- 建议在启动前注册 `onLocationChange` 和 `onLocationChangeError`；不再需要更新时及时调用 `stopLocationUpdate`
- **iOS**：调用时必须显式传入 type
- `scope.userLocationBackground` 为后台定位授权；豆包会尝试申请，申请失败不阻断本次启动
- 定位信息属于敏感数据，仅在业务确有需要时持续获取和使用；事件回调频率不固定

## 调用方式

### 异步 API

```typescript
startLocationUpdate(params?: StartLocationUpdateParams): Promise<LocationOperationResult>
```

## 入参

<table>
<thead>
<tr><th>名称</th><th>类型</th><th>必填</th><th>默认值</th><th>约束</th><th>说明</th></tr>
</thead>
<tbody>
<tr><td><code>type</code></td><td><code>&quot;wgs84&quot; | &quot;gcj02&quot;</code></td><td>否</td><td><code>gcj02</code></td><td>wgs84 表示 WGS-84 坐标系，gcj02 表示 GCJ-02 坐标系</td><td>坐标系类型，支持 wgs84 或 gcj02。iOS：省略 type 时调用失败。</td></tr>
</tbody>
</table>

## 调用示例

```typescript
import { startLocationUpdate } from '@doubao-dev/framework/api';

await startLocationUpdate({ type: 'gcj02' });
```

## 成功返回

无返回字段。

### 返回示例

```json
{}
```

## 错误处理

错误对象和通用错误码见 [通用错误处理](/apps-plugin/docs/js-api/common-errors.md#错误返回)。

### 失败示例

```json
{
  "errNo": 1700001,
  "errMsg": "location permission denied"
}
```

### 错误码

<table>
<thead>
<tr><th>errNo</th><th>errMsg</th><th>平台</th><th>触发条件</th><th>处理建议</th></tr>
</thead>
<tbody>
<tr><td><code>103</code></td><td><code>feature not support</code></td><td>Android、iOS</td><td>当前豆包客户端未提供持续定位能力（location service 不可用）</td><td>请在支持持续定位的豆包版本中调用</td></tr>
<tr><td><code>114</code></td><td><code>operation cancelled</code></td><td>Android、iOS</td><td>启动过程中被取消（用户取消授权，或授权返回前已调用 stopLocationUpdate）</td><td>需要时重新调用 startLocationUpdate</td></tr>
<tr><td><code>118</code></td><td><code>already exists</code></td><td>Android、iOS</td><td>持续定位已启动，重复调用 startLocationUpdate</td><td>先调用 stopLocationUpdate 再重新启动</td></tr>
<tr><td><code>1700001</code></td><td><code>location permission denied</code></td><td>Android、iOS</td><td>用户拒绝应用位置授权或系统定位权限被拒</td><td>调用 authorize 重新发起授权并在系统设置中开启定位权限后重试</td></tr>
<tr><td><code>1700002</code></td><td><code>location network error</code></td><td>Android、iOS</td><td>位置授权过程中发生网络错误</td><td>检查网络连接后重试</td></tr>
<tr><td><code>104</code></td><td><code>invalid parameter</code></td><td>iOS</td><td>位置授权 scope 非法</td><td>检查应用权限声明中配置的 scope 后重试</td></tr>
</tbody>
</table>

#### 通用错误码

<table>
<thead>
<tr><th>errNo</th><th>errMsg</th><th>说明</th><th>平台</th></tr>
</thead>
<tbody>
<tr><td><code>102</code></td><td><code>internal error</code></td><td>内部错误</td><td>Android、iOS</td></tr>
</tbody>
</table>

## 平台差异

- **Android**：用户拒绝授权返回 1700001、取消返回 114、授权网络失败返回 1700002；当前豆包客户端不支持持续定位时返回 103；其他失败统一返回 102。
- **iOS**：用户拒绝授权返回 1700001、取消返回 114、授权网络失败返回 1700002、非法 scope 返回 104；当前豆包客户端不支持持续定位时返回 103；其他失败统一返回 102。
