# 本地日志 (/zh-CN/realtime-media/whiteboard/whiteboard-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" /> 适用于 **Whiteboard Android SDK 2.16.134**。 Android 已内嵌日志运行时,通过 Native 配置开启,无需业务部署 Web Worker。 ## 创建 SDK 前开启 [#创建-sdk-前开启] ```java LoggerOptions logger = new LoggerOptions(); logger.setLocalLog(new LocalLogOptions().setEnabled(true).setEnabledUpload(true)); config.setLoggerOptions(logger); ``` ## 状态与按需上报 [#状态与按需上报] ```java // SDK 初始化完成后操作。 whiteSdk.getLocalLogState(new Promise() { @Override public void then(JSONObject state) { Log.i("Whiteboard", state.toString()); } @Override public void catchEx(SDKError error) { Log.e("Whiteboard", "状态查询失败", error); } }); whiteSdk.uploadLocalLogs(new Promise() { @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 whiteSdk.setCommonCallbacks(new CommonCallback() { @Override public void onLocalLogStateChange(JSONObject state) { Log.i("Whiteboard", state.toString()); } }); ``` 将此方法合并到已有 CommonCallback,保持其他业务回调。 建议在错误反馈流程中按需收集/上传,记录结果并限制重复触发。自定义上传参数和返回字段以[客户端 /api-ref/whiteboard/android/overview](/zh-CN/api-reference/whiteboard/whiteboard-sdk/android/overview)为准;不要把不同平台的回调对象当作相同模型解析。 <_PlatformProcessedMarker close="true" /> <_PlatformProcessedMarker groupMode="structured" canonicalPlatform="web" platform="ios" /> 适用于 **Whiteboard iOS SDK 2.16.147**。 iOS 已内嵌日志运行时,通过 Native 配置开启。 ## 创建 SDK 前开启 [#创建-sdk-前开启-1] ```objc WhiteLocalLogOptions *logs = [WhiteLocalLogOptions new]; logs.enabled = @YES; logs.enabledUpload = @YES; config.localLogOptions = logs; ``` ## 状态与按需上报 [#状态与按需上报-1] ```objc [sdk getLocalLogStateWithCompletionHandler:^(NSDictionary *result, NSError *error) { NSLog(@"%@ %@", result, error); }]; [sdk uploadLocalLogsWithCompletionHandler:^(NSDictionary *result, NSError *error) { NSLog(@"%@ %@", result, error); }]; ``` 状态查询用于确认运行时是否可用;配置 enabled=true 仍需结合状态确认,不能只据配置判断落盘成功。`collectLocalLogsWithCompletionHandler:` 收集导出结果,不等价于上传;`flushLocalLogsWithCompletionHandler:` 等待缓冲写入;`uploadLocalLogsWithCompletionHandler:` 触发上传,需要等待结果并处理失败。enabledUpload=false 时可以保留本地写入而关闭上传。 ```objc // 在创建 WhiteSDK 时传入的 WhiteCommonCallbackDelegate 中实现: - (void)localLogStateChange:(NSDictionary *)state { NSLog(@"%@", state); } ``` 建议在错误反馈流程中按需收集/上传,记录结果并限制重复触发。自定义上传参数和返回字段以[客户端 /api-ref/whiteboard/ios/overview](/zh-CN/api-reference/whiteboard/whiteboard-sdk/ios/docs/headers/agora-interactive-whiteboard-objective-c-overview)为准;不要把不同平台的回调对象当作相同模型解析。 iOS 12 及以下版本会强制关闭本地日志写入与上传,以规避 WKWebView Worker IndexedDB 的兼容问题;应读取状态确认可用性。 <_PlatformProcessedMarker close="true" /> <_PlatformProcessedMarker groupMode="structured" canonicalPlatform="web" platform="web" /> 适用于 **Whiteboard Web SDK 2.16.59**。 本地日志用于定位白板运行问题。Web 接入需要把日志依赖引入项目;只设置 loggerOptions 并不能补齐日志运行时。 ## 安装日志依赖 [#安装日志依赖] ```shell npm install agora-foundation@3.11.1 ``` 安装 white-web-sdk 的同时安装上述日志包,确保构建输出包含依赖。SDK 自动探测 `agora-foundation/lib/logger`,通常无需业务另行 import 或直接调用该模块。缺少依赖或 Worker 不可用时会降级,应读取本地日志状态确认。 ## 配置 SDK [#配置-sdk] ```typescript const sdk = new WhiteWebSdk({ appIdentifier, region: "cn-hz", loggerOptions: { localLog: { enabled: true, enabledUpload: true } } }); ``` 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(sdk.getLocalLogState()); try { await sdk.flushLocalLogs(); const result = await sdk.uploadLocalLogs(); console.log(result); } catch (error) { console.warn("日志上传失败", error); } ``` 状态查询用于确认运行时是否可用;配置 enabled=true 仍需结合状态确认,不能只据配置判断落盘成功。`collectLocalLogs` 收集导出结果,不等价于上传;`flushLocalLogs` 等待缓冲写入;`uploadLocalLogs` 触发上传,需要等待结果并处理失败。enabledUpload=false 时可以保留本地写入而关闭上传。 ```typescript const off = sdk.onLocalLogStateChange(state => console.log(state)); // 页面退出时清理监听: off(); ``` 建议在错误反馈流程中按需收集/上传,记录结果并限制重复触发。自定义上传参数和返回字段以[客户端 /api-ref/whiteboard/javascript/overview](/zh-CN/api-reference/whiteboard/whiteboard-sdk/web/overview)为准;不要把不同平台的回调对象当作相同模型解析。 <_PlatformProcessedMarker close="true" /> <_PlatformProcessedMarker groupMode="structured" canonicalPlatform="web" platform="harmonyos" /> 适用于 **Whiteboard HarmonyOS SDK 0.2.11**。 HarmonyOS 已内嵌日志运行时,通过 WhiteboardOptions 配置开启。 ## 入房前开启 [#入房前开启] ```typescript const options: WhiteboardOptions = { appIdentifier: appIdentifier, roomUuid: roomUuid, roomToken: roomToken, uid: uid, region: Region.CN_HZ, localLogOptions: { enabled: true, enabledUpload: true } }; ``` ## 状态与按需上报 [#状态与按需上报-3] ```typescript try { console.info(JSON.stringify(await controller.getLocalLogState())); console.info(JSON.stringify(await controller.uploadLocalLogs())); } catch (error) { console.warn('本地日志操作失败'); } ``` 状态查询用于确认运行时是否可用;配置 enabled=true 仍需结合状态确认,不能只据配置判断落盘成功。`collectLocalLogs` 收集导出结果,不等价于上传;`flushLocalLogs` 等待缓冲写入;`uploadLocalLogs` 触发上传,需要等待结果并处理失败。enabledUpload=false 时可以保留本地写入而关闭上传。 ```typescript const callbacks = new WhiteboardCallbacks().setOnLocalLogStateChange(state => { console.info(JSON.stringify(state)); }); // 将 callbacks 放入本次 WhiteboardOptions。 ``` 建议在错误反馈流程中按需收集/上传,记录结果并限制重复触发。自定义上传参数和返回字段以[客户端 /api-ref/whiteboard/harmonyos/overview](/zh-CN/api-reference/whiteboard/whiteboard-sdk/harmonyos/overview)为准;不要把不同平台的回调对象当作相同模型解析。 <_PlatformProcessedMarker close="true" />