统计 API

统计 API

从 1.3.0 版本开始，更新系统支持发送统计数据！

默认情况下，所有统计数据都会发送到我们的服务器，用于了解使用情况并进行研究。

注意

统计数据不会发送任何隐私数据，仅包含随机 UUID、更新版本、原生应用版本、平台、操作和 App ID。

如果你想改为将这些数据发送到自己的服务器，请修改以下配置：

// capacitor.config.json
{
  "appId": "**.***.**",
  "appName": "Name",
  "plugins": {
    "CapacitorUpdater": {
      "statsUrl": "YOUR_URL"
    }
  }
}

数据结构

你的服务器会收到：

interface AppInfosStats {
  "action": "set", // can be set, delete, set_fail, reset, revert
  // Then it's the same info as update
  "app_id": "**.***.**", // app identifier in the store
  "device_id": "*******", // unique id per app install
  "platform": "ios", // or android, or electron
  "custom_id": "user_1", // represent your user
        "version_name": "1.2.3", // version of the web build
        "version_build": "1.2.0", // version of the native build
        "version_code": "120", // build number of the native build
  "version_os": "16", // OS version of the device
        "plugin_version": "4.0.0"// to make your api behave differently with different plugins
        "is_emulator": false,
      "is_prod": false,
}

你也可以用空字符串完全禁用它。请注意，统计数据是隐私友好的，能帮助我了解大家如何使用这个 plugin，从而解决问题并改进它。

预期的“无更新”行为

当你的更新 endpoint 处于 没有新版本的状态时，它应该返回如下错误 payload：

{ "error": "no_new_version_available", "message": "No new version available" }

本指南中介绍的 error code 必须精确为 no_new_version_available。该 message 可以是任何你想要的字符串（仅用于日志记录/调试）。这是预期行为，且仍会通过 HTTP 返回 200。如果你的更新端点返回的是 200 响应且不包含 url，插件将视其为下载失败，并发送一条 download_fail 统计数据。

实现示例

以下是在 JavaScript 中使用 code 来保存插件统计数据的示例：

interface AppInfos {
  version_name: string
  action: 'delete' |
          'reset' |
          'set' |
          'get' |
          'set_fail' |
          'update_fail' |
          'download_fail' |
          'windows_path_fail' |
          'canonical_path_fail' |
          'directory_path_fail' |
          'unzip_fail' |
          'low_mem_fail' |
          'download_10' |
          'download_20' |
          'download_30' |
          'download_40' |
          'download_50' |
          'download_60' |
          'download_70' |
          'download_80' |
          'download_90' |
          'download_complete' |
          'decrypt_fail' |
          'app_moved_to_foreground' |
          'app_moved_to_background' |
          'uninstall' |
          'needPlanUpgrade' |
          'missingBundle' |
          'noNew' |
          'disablePlatformIos' |
          'disablePlatformAndroid' |
          'disableAutoUpdateToMajor' |
          'cannotUpdateViaPrivateChannel' |
          'disableAutoUpdateToMinor' |
          'disableAutoUpdateToPatch' |
          'channelMisconfigured' |
          'disableAutoUpdateMetadata' |
          'disableAutoUpdateUnderNative' |
          'disableDevBuild' |
          'disableEmulator' |
          'disablePlatformElectron' |
          'disableProdBuild' |
          'disableDevice' |
          'customIdBlocked' |
          'cannotGetBundle' |
          'checksum_fail' |
          'checksum_required' |
          'NoChannelOrOverride' |
          'setChannel' |
          'getChannel' |
          'rateLimited' |
          'disableAutoUpdate' |
          'keyMismatch' |
          'ping' |
          'InvalidIp' |
          'blocked_by_server_url' |
          'download_manifest_start' |
          'download_manifest_complete' |
          'download_zip_start' |
          'download_zip_complete' |
          'download_manifest_file_fail' |
          'download_manifest_checksum_fail' |
          'download_manifest_brotli_fail' |
          'backend_refusal' |
          'app_crash' |
          'app_crash_native' |
          'app_anr' |
          'app_killed_low_memory' |
          'app_killed_excessive_resource_usage' |
          'app_initialization_failure' |
          'app_memory_warning' |
          'webview_javascript_error' |
          'webview_unhandled_rejection' |
          'webview_resource_error' |
          'webview_security_policy_violation' |
          'webview_unclean_restart' |
          'webview_render_process_gone' |
          'webview_content_process_terminated' |
          'os_version_changed' |
          'native_app_version_changed' |
          'download_0'
  version_build: string
  version_code: string
  version_os: string
  plugin_version: string
  platform: string
  app_id: string
  device_id: string
  custom_id?: string
  is_prod?: boolean
  is_emulator?: boolean
}

export const handler: Handler = async (event) => {
  const body = JSON.parse(event.body || '{}') as AppInfos
  const {
    platform,
    app_id,
    action,
    version_code,
    version_os,
    device_id,
    version_name,
    version_build,
    plugin_version,
  } = body
  console.log('update asked', platform,
    app_id,
    action,
    version_os,
    version_code,
    device_id,
    version_name,
    version_build,
    plugin_version)
  // Save it in your database
  return { status: 'ok' }
}

该端点应返回如下 JSON：

{ "status": "ok" }

操作

有关所有 action 代码及其含义的详细说明，请参阅调试文档：

• 从设备端发送的 Actions：请参阅 调试文档 - 从设备端发送 章节
• 从后端发送的 Actions：请参阅 调试文档 - 来自后端 章节

处理更新

继续阅读统计 API

如果你正在使用 统计 API 要规划 dashboard 和 API 操作，请将其连接到 使用 @capgo/capacitor-updater 用于“使用 @capgo/capacitor-updater”中的原生能力， API 概览 关于 API Overview 中的实现细节， 简介 关于 Introduction 中的实现细节， API 密钥 有关 API Keys 的实现细节，以及 设备 有关 Devices 的实现细节。