Flutter内容分析插件contentsquare_cli的使用

contentsquare_cli 是一个用于与 Contentsquare 插件交互的命令行工具。它可以帮助你上传调试符号文件和映射文件到 Contentsquare 插件，从而更好地进行错误分析。

如果你在 flutter build 命令中使用了以下选项之一，则需要使用此工具：

1. --split-debug-info：你需要上传由 Flutter 编译生成的符号文件，以便能够读取堆栈跟踪。
2. --obfuscate：你需要上传混淆映射文件，以便清晰地展示错误信息。

安装

在项目的 pubspec.yaml 文件中添加 contentsquare_cli 作为开发依赖项：

dev_dependencies:
  contentsquare_cli: ^1.0.0

安装完成后，运行以下命令以确保依赖项已正确安装：

flutter pub get

配置

upload-debug-files 命令需要以下信息：

1. 目标平台
   可以是 ios 或 android。

2. 项目 ID

   • 登录到 Contentsquare 平台：https://app.contentsquare.com。
   • 确保你在正确的项目中。
   • 项目 ID 可以在 URL 的查询参数 project 中找到：https://app.contentsquare.com/#/{MODULE_NAME}?project={PROJECT_ID}&hash={HASH}。

3. 有效的 API 凭证
   请参阅帮助中心文档以获取客户端 ID 和客户端密钥：如何创建 API 凭证。

4. 调试信息目录
   在构建命令中通过 --split-debug-info 指定的路径。

5. 混淆映射文件路径（可选）
   如果在构建时使用了 --obfuscate，可以通过额外的构建选项提取混淆映射文件：--extra-gen-snapshot-options=--save-obfuscation-map=[YOUR DESIRED FILENAME]。

使用 YAML 文件配置

可以在项目的根目录下添加一个 contentsquare_cli.yaml 文件来存储这些信息：

contentsquare_cli:
  android:
    client_id: "[ANDROID CLIENT ID]"
    client_secret: "[ANDROID CLIENT SECRET]"
    project_id: "[ANDROID PROJECT ID]"
    debug_info_dir: "[PATH PROVIDED TO THE --split-debug-info option]"
    obfuscation_mapping_file: "[PATH TO THE OBFUSCATION MAP]"
  ios:
    client_id: "[IOS CLIENT ID]"
    client_secret: "[IOS CLIENT SECRET]"
    project_id: "[IOS PROJECT ID]"
    debug_info_dir: "[PATH PROVIDED TO THE --split-debug-info option]"
    obfuscation_mapping_file: "[PATH TO THE OBFUSCATION MAP]"

使用命令行参数配置

也可以直接通过命令行参数传递这些信息：

运行以下命令查看更多帮助信息：

dart run contentsquare_cli --help

如何使用

上传命令必须在每次构建命令之后执行。

示例 1：使用 YAML 文件配置

假设你的 contentsquare_cli.yaml 文件内容如下：

contentsquare_cli:
  android:
    client_id: "my-client-id-android"
    client_secret: "myClientSecretAndroid"
    project_id: "00000"
    debug_info_dir: "myDebugInfoDir"
    obfuscation_mapping_file: "app.android.map.json"
  ios:
    client_id: "my-client-id-ios"
    client_secret: "myClientSecretIos"
    project_id: "00001"
    debug_info_dir: "myDebugInfoDir"
    obfuscation_mapping_file: "app.ios.map.json"

执行以下命令：

### 构建 APK 并生成调试信息和混淆映射文件
flutter build apk --split-debug-info=myDebugInfoDir --obfuscate --extra-gen-snapshot-options=--save-obfuscation-map=app.android.map.json

### 上传生成的调试文件到 Contentsquare
dart run contentsquare_cli upload-debug-files --platform=android

或者使用 Flutter 替代 Dart：

flutter packages pub run contentsquare_cli upload-debug-files --platform=android

示例 2：不使用 YAML 文件配置

如果不想使用 YAML 文件，可以直接通过命令行参数传递所有信息：

dart run contentsquare_cli upload-debug-files \
  --platform=android \
  --client-id=my-client-id-android \
  --client-secret="myClientSecretAndroid" \
  --project-id=00000 \
  --debug-info-dir=./myDebugInfoDir \
  --obfuscation-mapping-file=./app.android.map.json