PHP调用穿山甲SDK回调验证方法

穿山甲广告SDK服务端回调验签失败，往往并非算法错误，而是踩中了其文档未明示的几大隐性规则：必须对所有POST参数（含空值）严格按字段名ASCII升序排序（ksort）、用原始字符串拼接（如price保持"12"而非转为1.23）、签名采用md5($params_string . $secret_key)而非HMAC且密钥顺序不可颠倒；同时需规避响应超时、BOM头、非空输出等导致重试的陷阱，并对callback_id做幂等校验以防重复计费——掌握这些细节，才能真正打通穿山甲回调验证的最后一公里。

穿山甲回调验签失败：sign 校验总不通过

根本原因不是算法写错了，而是穿山甲文档里没明说的「参数预处理规则」被跳过了。他们要求对所有回调参数（包括 callback_id、ad_type、price 等）先按字段名 ASCII 升序排序，再拼成 key1=value1&key2=value2 形式，最后用 md5 + 密钥计算签名——但很多人直接用 $_POST 原始顺序拼串，或漏掉空值字段。

实操建议：

• 必须用 ksort($_POST) 排序，不能依赖表单提交顺序
• 空字符串字段（如 click_id 可能为空）也要参与拼接，值为 ""，不能跳过
• 密钥是穿山甲后台「应用管理 → 应用详情 → 服务端回调密钥」里配的那个，不是 AppKey 或 SecretKey
• 拼接时字段名和等号间无空格，& 前后也无空格，例如：ad_type=reward&callback_id=xxx&price=0.12

PHP 验签代码里 md5() 和 hash_hmac() 该用哪个

穿山甲目前只支持 md5 签名方式（v2 版本回调），不是 HMAC。官方文档写的是「MD5(key+string)」，实际是 md5($string . $secret_key) —— 注意是「参数串在前、密钥在后」，不是反过来，也不是 hash_hmac('md5', $string, $secret_key)。

示例关键片段：

$params = $_POST;
unset($params['sign']); // 先剔除 sign 字段
ksort($params);
$string = http_build_query($params, '', '&', PHP_QUERY_RFC3986); // 保证编码一致
$expected_sign = md5($string . $secret_key); // 注意顺序！
if ($expected_sign !== $_POST['sign']) {
    http_response_code(400);
    exit('sign invalid');
}

回调接口被重复调用或收不到请求

穿山甲服务端回调有重试机制（失败时最多重试 3 次，间隔约 1s/3s/10s），且要求你的接口在 3 秒内返回 HTTP 200。超时、返回非 200、或响应体含非空内容（比如 echo 'ok'）都会触发重试。

常见踩坑点：

• PHP 脚本开头有 echo、var_dump 或 BOM 头，导致响应体非空
• 用了 sleep() 或数据库慢查询，响应时间超过 3 秒
• Nginx 配置了 fastcgi_read_timeout 小于 3s
• 没做幂等处理，同一 callback_id 多次入库，造成重复计费

建议：收到回调后立即记录原始 $_POST 到日志，再校验；校验通过后先查库确认 callback_id 是否已存在，存在则直接返回 200。

price 字段单位和精度问题

穿山甲回调里的 price 是字符串格式的「分」为单位的整数（例如展示一次广告收益 0.12 元，传的是 "12"），不是浮点数也不是元。很多开发者直接 (float)$_POST['price'] 当元来用，结果精度丢失或小数点错位。

正确做法：

• 始终把 price 当字符串处理，用 intval() 转成整数分
• 入库或结算时统一用「分」为单位存储，避免浮点运算
• 注意穿山甲可能传 "0"（未出价）或 "123"（1.23 元），不会传 "1.23"

验签时也必须用原始字符串拼接，不能先转数字再拼——否则 "007" 会变成 "7"，签名就崩了。

以上就是本文的全部内容了，是否有顺利帮助你解决问题？若是能给你带来学习上的帮助，请大家多多支持golang学习网！更多关于文章的相关知识，也可关注golang学习网公众号。