for Developers

简体中文

English

简体中文

English

Appearance

H5嵌入指南 ​

概述 ​

当需要引入我们的页面时（例如识图报告页面），需正确实现基于签名的鉴权验证机制，确保接口调用的安全性。请仔细阅读以下章节，了解引入流程。

适用场景 ​

  • 使用 React Native、Flutter 等混合开发框架，通过 WebView 组件集成我们的 H5 页面（适用于跨平台应用开发）
  • 使用原生 Android 或 iOS 开发，通过系统 WebView 加载我们的 H5 页面（适用于原生应用开发）
  • 自有 H5 页面通过 <iframe> 或 <script> 动态引入我们的 H5 页面（适用于纯 Web 应用）

整体流程 ​

以 App 内嵌 H5 为例： report embed flow

请求参数说明 ​

参数名类型是否必填说明
signstring是使用 APPID 和 APPSECRET 对请求进行对称加密的签名计算
appIdstring是调用者调用 API 所用的 APPID 的值
timestamplong是请求时间秒级时间戳，时区必须设置为 UTC
其他业务参数...否根据具体业务场景添加的其他参数

注意：

  • timestamp 为请求当时的时间戳，请勿随意修改 timestamp 的值，服务端会根据 timestamp 的值离当前时间是否超过 60s 来判断请求是否过期，这有助于防止潜在的重复攻击。
  • sign 请由服务端生成，确保密钥不会暴露在客户端。
  • 参数的值都应该是经过 URL 编码后的字符串，例如 https://google.com 被编码后变为 https%3A%2F%2Fgoogle.com

签名计算 ​

签名的计算公式如下：

Signature = Base64(HMAC-SHA256(APPSECRET, StringToSign))

其中 StringToSign 是需要构造的待签名字符串，格式如下：

  • 将所有请求参数拆分为 key=value 的形式，
  • 将 key 按照字典序（a-z）升序排列，再以 & 进行连接成字符串，例如 appId=85206f97-2f4f-4b6e-8830-f3f4ec6fd6ae&language=zh_CN&taskId=8127919&timestamp=1745923427

注意：

参数中的 value 应该是经过 URL 编码后的字符串，例如 https://google.com 被编码后变为 https%3A%2F%2Fgoogle.com。

示例 ​

假设我们有一个 APPID 和 APPSECRET 对：

{
    "app_id": "85206f97-2f4f-4b6e-8830-f3f4ec6fd6ae",
    "app_secret": "c6ae8924a68a5d839947a7885894dfe4"
}

请求示例 ​

H5 的 URL 为 http://127.0.0.1:8080/report?language=zh_CN&taskId=8127919&timestamp=1745923427&appId=85206f97-2f4f-4b6e-8830-f3f4ec6fd6ae

  1. 请求的业务参数为：
language=zh_CN&taskId=8127919
  1. 得到 StringToSign：
appId=85206f97-2f4f-4b6e-8830-f3f4ec6fd6ae&language=zh_CN&taskId=8127919&timestamp=1745923427
  1. 计算 Signature：
通过 Base64(HMAC-SHA256(APPSECRET, StringToSign)) 计算
Signature = vuINPfgYzMKuR4C8oIvWchE0cJjIWSUN38nKEXU7ico=
  1. 最终得到 URL 为：
http://127.0.0.1:8080/report?language=zh_CN&taskId=8127919&timestamp=1745923427&appId=85206f97-2f4f-4b6e-8830-f3f4ec6fd6ae&sign=vuINPfgYzMKuR4C8oIvWchE0cJjIWSUN38nKEXU7ico=