# 本地日志 (/zh-CN/realtime-media/whiteboard/fastboard-sdk/build/extend-whiteboard/local-log)

> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).

<_PlatformTabsGroup>
<_PlatformProcessedMarker groupMode="structured" canonicalPlatform="web" platform="android" />
适用于 **Fastboard Android SDK 1.8.2（内置 Whiteboard 2.16.131）**。

Android 已内嵌日志运行时，通过 Native 配置开启，无需业务部署 Web Worker。

## 创建 SDK 前开启 [#创建-sdk-前开启]

```java
LoggerOptions logger = new LoggerOptions();
logger.setLocalLog(new LocalLogOptions().setEnabled(true).setEnabledUpload(true));
roomOptions.getSdkConfiguration().setLoggerOptions(logger);
```

## 状态与按需上报 [#状态与按需上报]

```java
// FastRoom ready 后操作；不要重新创建内部 SDK。
fastRoom.getWhiteSdk().getLocalLogState(new Promise<JSONObject>() {
    @Override public void then(JSONObject state) { Log.i("Whiteboard", state.toString()); }
    @Override public void catchEx(SDKError error) { Log.e("Whiteboard", "状态查询失败", error); }
});
fastRoom.getWhiteSdk().uploadLocalLogs(new Promise<JSONObject>() {
    @Override public void then(JSONObject result) { Log.i("Whiteboard", result.toString()); }
    @Override public void catchEx(SDKError error) { Log.e("Whiteboard", "上传失败", error); }
});
```

状态查询用于确认运行时是否可用；配置 enabled=true 仍需结合状态确认，不能只据配置判断落盘成功。`collectLocalLogs` 收集导出结果，不等价于上传；`flushLocalLogs` 等待缓冲写入；`uploadLocalLogs` 触发上传，需要等待结果并处理失败。enabledUpload=false 时可以保留本地写入而关闭上传。

```java
fastRoom.setCommonCallback(new CommonCallback() {
    @Override public void onLocalLogStateChange(JSONObject state) {
        Log.i("Whiteboard", state.toString());
    }
});
```

将此方法合并到已有 CommonCallback，保持其他业务回调。Fastboard 通过 setCommonCallback 组合外部回调，不能覆盖内部 SDK 回调。

建议在错误反馈流程中按需收集/上传，记录结果并限制重复触发。自定义上传参数和返回字段以[客户端 /api-ref/fastboard/android/fastboard-api](/zh-CN/api-reference/whiteboard/fastboard/android)为准；不要把不同平台的回调对象当作相同模型解析。
<_PlatformProcessedMarker close="true" />

<_PlatformProcessedMarker groupMode="structured" canonicalPlatform="web" platform="ios" />
适用于 **Fastboard iOS SDK 1.4.6（依赖 Whiteboard 2.16.145）**。

iOS 已内嵌日志运行时，通过 Native 配置开启。

## 创建 SDK 前开启 [#创建-sdk-前开启-1]

```swift
let logs = WhiteLocalLogOptions()
logs.enabled = true
logs.enabledUpload = true
config.whiteSdkConfiguration.localLogOptions = logs
// config 为 FastRoomConfiguration，在创建 FastRoom 前设置。
```

## 状态与按需上报 [#状态与按需上报-1]

```swift
// FastRoom 的 whiteSDK 已创建且宿主有效时调用。
fastRoom.whiteSDK.getLocalLogState { result, error in
    print(result as Any, error as Any)
}
fastRoom.whiteSDK.uploadLocalLogs { result, error in
    print(result as Any, error as Any)
}
```

状态查询用于确认运行时是否可用；配置 enabled=true 仍需结合状态确认，不能只据配置判断落盘成功。`collectLocalLogsWithCompletionHandler:` 收集导出结果，不等价于上传；`flushLocalLogsWithCompletionHandler:` 等待缓冲写入；`uploadLocalLogsWithCompletionHandler:` 触发上传，需要等待结果并处理失败。enabledUpload=false 时可以保留本地写入而关闭上传。

```swift
fastRoom.commonDelegate = self // 宿主实现 WhiteCommonCallbackDelegate。
func localLogStateChange(_ state: [AnyHashable: Any]) {
    print(state)
}
```

使用 commonDelegate 代理接收事件，保持宿主存活并避免覆盖内部 WhiteSDK delegate。

建议在错误反馈流程中按需收集/上传，记录结果并限制重复触发。自定义上传参数和返回字段以[客户端 /api-ref/fastboard/ios/fastboard-api](/zh-CN/api-reference/whiteboard/fastboard/ios)为准；不要把不同平台的回调对象当作相同模型解析。

iOS 12 及以下版本会强制关闭本地日志写入与上传，以规避 WKWebView Worker IndexedDB 的兼容问题；应读取状态确认可用性。
<_PlatformProcessedMarker close="true" />

<_PlatformProcessedMarker groupMode="structured" canonicalPlatform="web" platform="web" />
适用于 **Fastboard Web SDK 1.1.10**。

本地日志用于定位白板运行问题。Web 接入需要把日志依赖引入项目；只设置 loggerOptions 并不能补齐日志运行时。

## 安装日志依赖 [#安装日志依赖]

```shell
npm install agora-foundation@3.11.1
```

安装 white-web-sdk 的同时安装上述日志包，确保构建输出包含依赖。SDK 自动探测 `agora-foundation/lib/logger`，通常无需业务另行 import 或直接调用该模块。缺少依赖或 Worker 不可用时会降级，应读取本地日志状态确认。

## 配置 SDK [#配置-sdk]

```typescript
const app = await createFastboard({
  sdkConfig: { appIdentifier, region: "cn-hz",
    loggerOptions: {
  localLog: { enabled: true, enabledUpload: true }
} },
  joinRoom: { uuid, roomToken, uid }
});
```

Web 默认尝试启用本地日志与上传；设 enabled=false 关闭本地日志，enabledUpload=false 只关闭上传。

## 静态 Worker 资源（按构建环境选择） [#静态-worker-资源按构建环境选择]

若构建工具不能正确发布日志 Worker，可在构建阶段生成并部署与本项目实际 agora-foundation 版本一致的静态 Worker：

```shell
npm install -D esbuild @babel/core @babel/preset-env
npx white-web-sdk-sync-foundation-worker --out public/whiteboard/foundation-worker.js --manifest public/whiteboard/foundation-worker.manifest.json --required --target es5
```

将命令放到业务构建前，随站点发布生成的静态文件。SDK 配置的 `loggerOptions.localLog` 中可设置 `workerUrl: "/whiteboard/foundation-worker.js"`；或在需要自定义 Worker 创建时设置 `createWorker: () => new Worker("/whiteboard/foundation-worker.js")`，后者优先。URL 应按业务的部署前缀、CSP 与资源可访问性调整。

## 状态与按需上报 [#状态与按需上报-2]

```typescript
console.log(app.sdk.getLocalLogState());
try {
  await app.sdk.flushLocalLogs();
  const result = await app.sdk.uploadLocalLogs();
  console.log(result);
} catch (error) { console.warn("日志上传失败", error); }
```

状态查询用于确认运行时是否可用；配置 enabled=true 仍需结合状态确认，不能只据配置判断落盘成功。`collectLocalLogs` 收集导出结果，不等价于上传；`flushLocalLogs` 等待缓冲写入；`uploadLocalLogs` 触发上传，需要等待结果并处理失败。enabledUpload=false 时可以保留本地写入而关闭上传。

```typescript
const off = app.sdk.onLocalLogStateChange(state => console.log(state));
// 页面退出时清理监听：
off();
```

建议在错误反馈流程中按需收集/上传，记录结果并限制重复触发。自定义上传参数和返回字段以[客户端 /api-ref/fastboard/javascript/fastboard-api](/zh-CN/api-reference/whiteboard/fastboard/web)为准；不要把不同平台的回调对象当作相同模型解析。
<_PlatformProcessedMarker close="true" />
</_PlatformTabsGroup>