上个季度我们给一个短剧平台做广告联盟SDK对接后台管理系统用的PHP。听起来好像挺简单——不就是串一个SDK、接几个回调吗但真正把所有模块跑通之后我才发现最花时间的根本不是一行行调用代码而是后台里那堆跟广告位、订单、回调、对账相关的管理模块。这篇文章就把我这次从零搭建PHP后台管理系统的过程完整拆开讲一遍包括模块设计、核心接口对接逻辑、签名机制、和最容易踩的坑给后面要做APP广告变现的团队一个能直接落地的参考。1. 项目背景短剧APP为什么要接广告联盟后台到底要管什么先说清楚这个项目的商业模式不然后台模块容易设计跑偏。短剧类APP绝大多数是靠内容付费加广告变现两条腿走路其中广告联盟聚合了上游广告主的需求APP通过集成联盟SDK就能在自己的应用里展示激励视频、插屏、信息流广告按展示、点击、转化等维度获得分成收入。对APP方来说不用自己一家家对接广告主联盟作为中间方负责填充广告、竞价、展示逻辑和结算。对联盟来说要管控流量质量、审核素材、防止刷单和违规展示。对后台管理系统来说核心就是三件事配置管理、数据回收、结算对账。所以我在设计PHP后台时第一刀切的就是模块边界。整个后台分成六大块模块核心职能对应业务问题应用与广告位管理维护APP和广告位的上下架、类型、尺寸广告位开没开、用的什么场景广告主与素材管理记录联盟下有合作关系的广告主及其素材知道谁在投、投了什么请求与展示日志记录客户端广告请求、展示、点击明细排查请求量异常和素材问题回调接收中心接收广告联盟下发的转化回调并落库确定哪些展示产生了收益数据报表中心按时/日/广告位多维度汇总收入与消耗运营看数据做决策自动对账模块拉取联盟结算单与本地记录比对保证钱算得对、不扯皮这个划分在我实际开发中几乎够用了后面加需求也只是在这个骨架上加字段和子页面不需要推倒重来。关于技术栈多说一句为什么用PHP而不是Java或者Go团队熟悉度是第一位的另外这种后台管理系统偏CRUD加定时任务PHP配合ThinkPHP或Laravel这类框架开发效率最高环境部署也省心服务器上一套PHP-FPM加MySQL、Redis就齐了。你需要并发能力更强的大数据处理再说迁移或升级的事前期完全没必要给自己加负担。2. 后台管理系统核心模块设计从配置下发到数据落库的完整链路2.1 应用和广告位管理所有联调参数的源头应用和广告位是广告系统的最小粒度单元广告联盟在开发者后台会给你分配一个AppId和应用密钥AppKey然后在应用下面创建多个广告位ID每个广告位对应一种广告类型。后台里这张应用表我这样设计app_id联盟分配给应用的唯一标识app_key签名密钥前端APP不感知只存在服务端status1启用 0停用platformandroid / ios因为双端审核规则和广告填充有差异callback_url后台接收广告联盟转化回调的入口地址广告位表的关键字段ad_slot_id联盟分配的广告位IDscene_name广告场景名比如“开屏页”“激励视频-看广告解锁下一集”ad_type激励视频/插屏/信息流/开屏swidth、sheight素材尺寸要求ecpm_weight排序权重运营可以调节这个值影响广告位的优先级这里有个很重要的经验广告位ID的映射关系一定要单独做不要硬编码在代码里。客户端上报广告位IDPHP后台根据映射表把它翻译成语义化的场景名后续报表对接、问题排查都方便很多。2.2 广告主和素材管理流量方也要知道谁在花钱很多APP团队觉得广告主是联盟的事自己不用管其实大错特错。短剧平台最怕的就是同质竞品素材出现在自己用户面前投放把你的人拉走了。所以后台必须能管理广告主和素材的黑白名单。我在这个模块里做的是拉取联盟提供的素材列表按天同步到本地素材表。素材字段包括素材ID、所属广告主ID、类型图片/视频、尺寸、跳转链接落地页、审核状态。后台支持对广告主ID做黑名单设置命中后客户端拉取广告时直接过滤掉。别小看这功能短视频平台用户对广告素材非常敏感一个狗皮膏药式的素材挂三天用户留存会明显往下掉。设置黑名单之后可以做到小时级别屏蔽。2.3 请求与展示日志排查问题的第一现场广告系统的请求量级比普通后台业务大很多短剧APP日活十万的时候每天广告请求量可以到百万甚至千万级别。全部明细落MySQL会爆掉所以分冷热两套存储。热数据当天到三天的明细放Redis键用ad:log:{广告位ID}:{日期}:{小时}用LPUSH写入到期自动淘汰。冷数据三天前的历史明细每晚批量写MySQL分区表按天分区查询时按日期段裁剪分区。日志表主要字段log_idapp_id / ad_slot_id / device_id设备ID做脱敏处理request_time / show_time / click_timeip只存前三段避免隐私合规问题product_id / order_id和短剧内容关联的扩展参数status1正常 2超时 3被过滤设计这套日志最大的价值在于出现广告填充率下降、点击率异常突变时你能快速定位是某个素材、某个广告位还是某个机型的流量问题。没有明细数据就只能瞎猜。2.4 权限和操作日志多人协作不背锅后台不是一个人的工具。运营、财务、测试、超管都会用粗放式管理很容易出现误操作。所以加了RBAC权限控制和操作日志。权限按角色控制超管、运营、财务、客服。每个角色只给必要权限比如财务只能看对账和结算单不能改广告位状态运营可以改广告位素材和黑白名单看不到利润成本。操作日志记录每一次关键动作谁在什么时间改了广告位状态、改了素材黑名单、导出过哪些数据。后面出现线上事故追责不需要翻聊天记录后台日志就能还原。3. 广告联盟SDK对接核心流程签名、拉取、上报、回调一条链路3.1 通用对接协议为什么所有联盟流程都长得很像广告联盟SDK对接不管你是对接哪家流程都基本固定。客户端集成SDK后消息链路长这样客户端发起广告请求 - SDK带参数请求服务端广告接口 - 服务端校验签名和频控 - 返回广告素材和落地页 - 用户在客户端看到广告(展示) - 用户点击 - 联盟记录点击 - 用户完成转化(比如下载、注册、付费) - 联盟回调服务端 - 后台计费入账。这套链路里PHP后端的参与位置主要有两个一是提供服务端API供客户端SDK调用二是在回调中心接收联盟下发的数据。3.2 服务端接口签名把参数排序这件事做到极致客户端SDK请求后台广告接口时需要携带签名参数防止篡改。签名算法各家略有不同但通用逻辑都是参数名ASCII码排序 - urlencode - 拼接字符串 - 加上AppKey - 做MD5或HMAC。我这边用的签名逻辑是public function generateSign(array $params, string $appKey): string { // 1. 过滤掉sign本身和空值参数 unset($params[sign]); $params array_filter($params, function ($v) { return $v ! $v ! null; }); // 2. 按参数名ASCII码升序排列 ksort($params); // 3. 拼接 keyvaluekeyvalue $str ; foreach ($params as $k $v) { $str . $k . . urlencode($v) . ; } $str rtrim($str, ); // 4. 拼接AppKeyMD5后转大写 $str $str . app_key . $appKey; return strtoupper(md5($str)); }签名参数表如下参数名说明示例app_id应用标识100123timestamp当前时间戳1716180000nonce随机字符串防止重放5f4dcc3b5aa765d61d8327deb882cf99ad_slot_id广告位ID200456device_id设备标识demo_device_001sign最终签名上面算法的输出校验时我在PHP端做了三道防线时间戳防重放超过5分钟的直接拒绝。Redis SETNX nonce设置5分钟过期同一个nonce出现两次说明请求被重放。重新计算签名与服务端传来的sign比对不一致直接拒绝。这个签名逻辑看起来简单但它是整条链路的地基。后续你接任何联盟都能用同一套思路套过去。3.3 客户端广告拉取返回广告还是返回空背后的逻辑很重要客户端SDK调到服务端广告接口后PHP后端要决定返回什么内容。这一步除了查广告位配置还要做两件事频控同一个设备ID在10分钟内请求次数超过50次直接不返回广告防止恶意刷量。素材过滤读取素材黑名单命中广告主ID或素材ID的直接剔除。返回参数我固定为统一的JSON结构{ code: 0, msg: success, data: { ad_id: 素材ID, ad_type: reward_video, title: 素材标题, image_url: 素材封面图, video_url: 素材视频地址, click_url: 点击跳转地址, extension: { cp_id: 广告主ID, product_id: 关联短剧ID } } }3.4 展示和点击上报服务端需要校验上报的每一笔广告有没有被展示、被点击直接关系到广告主扣费和流量方收入这里必须做服务端校验不能完全信任客户端上报。我这边是在客户端SDK展示、点击成功后把上报请求转发到PHP后端再由后端转发到联盟运营后台同时本地记录一份日志。校验逻辑校验device_id在最近N分钟内是否有过成功的广告请求记录。校验ad_id是否为刚才下发过的素材。校验展示和点击的时间先后关系点击时间不能早于展示时间5秒以上。这个链路的价值是给后续对账留底联盟后台的数据是最终结算依据本地日志是对账判断的证据。3.5 回调接收中心这里是最容易出问题的地方联盟在用户发生转化后会主动请求我们配置的回调地址。比如用户看完激励视频后下载了某个APP并激活联盟会回调一个订单通知。回调中心处理不好后面对账必然一团糟。我的回调处理逻辑分四步验签回调请求里带联盟签名用约定的公共密钥验签。幂等判断以order_id event_type为唯一键查本地表已存在则直接返回成功。落库写入回调记录表记录联盟订单号、金额、转化类型、时间。业务处理更新对应对账汇总表的数据向财务模块推送一条待确认记录。用代码表示public function handleCallback(Request $request) { // 1. 验签 $verifyResult $this-adapter-verify($request-all()); if (!$verifyResult) { return response()-json([code 400, msg sign error]); } $orderId $request-input(order_id); $eventType $request-input(event_type); // 2. 幂等 $exists CallbackLog::where(order_id, $orderId) -where(event_type, $eventType) -exists(); if ($exists) { return response()-json([code 0, msg already exists]); } // 3. 落库 DB::transaction(function () use ($request, $orderId, $eventType) { $log CallbackLog::create([ order_id $orderId, event_type $eventType, amount $request-input(amount, 0), raw_data json_encode($request-all()), ]); $this-reporter-addRecord($log); }); // 4. 快速响应避免联盟超时重试 return response()-json([code 0, msg ok]); }注意回调接口收到请求后必须第一时间响应联盟不要在这个接口里做耗时的对账、推送、短信通知之类的操作。通常会先把记录落库返回成功然后异步把数据推到消息队列慢慢消化。原因很简单联盟回调一般有超时重试机制你处理超过5秒它就重复推结果幂等没做好就会重复入账。4. 对接过程中踩过的坑明明照着文档写怎么就是跑不通4.1 签名校验失败排序、编码、密钥都可能是凶手对接SDK第一天我就被签名校验卡了半天。文档写的是“参数按ASCII排序后拼接MD5加密”但实际操作时发现三家联盟的细节完全不同有的排完序之后要urlencode有的不用。有的拼接格式是a1b2有的却是a1b2连等号都不要。有的MD5是小写有的是大写。这个坑的排查方法很笨但有效先在服务端打印收到的原始参数和计算出来的签名然后在联盟开发者后台的调试工具里比对他们的genSign算法。当你发现两个签名就差大小写时基本上就是大小写的问题。建议把这部分封装成Adapter模式每家联盟一个类统一入口不同签名逻辑内部消化。4.2 nonce和时间戳同时出问题后来线上频控出现误杀排查发现是服务端和客户端服务器时间不同步客户端设备时间快了两分钟导致时间戳校验直接拒绝。很多设备的时间是用户自己改的不能依赖它。解决思路客户端在启动SDK时先调一次时间同步接口拿服务端时间校准。时间戳校验窗口从5分钟放宽到15分钟配合nonce去重足够安全了。对时间戳超时的请求返回特定code客户端SDK可以自动校准后重试。4.3 回调重复入账幂等设计不到位就是负数收入这个坑是最贵的。测试环境还好一上生产就发现财务对账单和联盟后台差了将近两千块钱。查了半天罪魁祸首是联盟回调在网络波动情况下重试了三次而我当时的回调处理里没有唯一索引。修复方案分两层数据库层给order_id event_type加唯一索引让数据库帮我们兜底防止并发情况下PHP判断和插入之间的间隙。应用层在落库之前先查一次缓存用Redis SETNX做分布式锁锁住同一个订单号避免同一毫秒两个请求同时查到不存在然后同时插入。两个一起用才开始稳定只靠任何一层都有漏网之鱼。4.4 测试环境和正式环境的隔离问题SDK集成最刺激的坑是在测试环境明明请求到了广告一上线就请求不到。原因通常有两个测试广告位ID和正式广告位ID分属不同应用后台只配置了测试环境的AppId。测试设备没有在联盟后台绑定为测试设备被正常的频控策略拦掉了。我的建议是后台把环境和设备管理显式做成配置用config/app_env区分dev/test/prod在数据库广告位表加一个is_test字段。客户端SDK在debug模式下会优先请求测试广告位正式包永远只会请求生产环境的广告位。这样两边物理隔离再也不会串。4.5 金额单位不统一广告联盟返回的金额有的是以分为单位有的是以元为单位甚至同一个联盟内不同接口有的返回分有的返回元。如果没统一直接落库报表会错得离谱。处理办法很暴力但有效业务层所有金额字段统一用“分”为单位所有接口在入口处做一层单位转换底层数据库只存整数。对账、结算、报表计算全部用分最后展示时候再除以100。这个约定要写进团队开发文档后面来新人也不会踩。5. 数据报表与自动对账别再把时间花在手工数钱上5.1 多维度报表设计让运营一眼看到问题出在哪广告变现运营最关心的报表有四个维度按广告位看哪个广告位收入最高、ecpm是多少。按素材看哪类素材点击率高要不要调展示权重。按小时看全天哪个时间段填充率高要不要做流量调度。按内容看哪部短剧的广告转化效果好可以加大买量。我的报表实现采用预聚合思路。Redis里维护小时级的汇总计数器键比如report:hour:ad_slot:1716180000:ad_slot_id按小时自动过期。每天凌晨2点定时任务把前一天的聚合结果刷入MySQL报表表。MySQL报表表设计成星型结构事实表只存维度和汇总值维度表存广告位、素材、内容的元信息。查询时JOIN维度表做筛选千万级数据量查询都在毫秒级。5.2 自动对账本地记录和联盟结算单的差异怎么处理对账是整个后台管理系统里我投入精力最多的模块。手工对账在广告量小的时候还凑合一天几百条记录还能用Excel筛量一上来就废了。自动对账逻辑每天早上定时任务调用联盟开放平台的结算单接口拉取前一天所有订单明细。把订单明细和本地回调记录表按order_id做全量比对。对账差异分成三类差异类型原因处理方式本地有联盟无联盟数据延迟或本地伪造先标记等28小时再比对还有差异转人工联盟有本地无回调丢失或没入库检查回调日志和MQ消费记录补录金额不一致单位换算或扣量调整以联盟为准记录差异原因备查这套对账跑了一个月之后财务基本就不用再打开两个平台手动比对数据了。5.3 定时任务框架从数据拉取到对账提醒的完整编排PHP后台我用的ThinkPHP框架自带命令行指令可以直接在Linux crontab里挂定时任务。定时任务编排如下0 2 * * * php think report:sync // 同步联盟结算单到本地 0 3 * * * php think report:aggregate // 聚合前一天报表数据 30 3 * * * php think report:compare // 执行对账比对 0 9 * * * php think report:push // 推送对账异常通知到企业微信每个任务独立执行任务执行状态写任务日志表开始时间、结束时间、成功失败、执行耗时、错误信息。如果对账差异超过设定阈值自动推送给财务和运营的群做到异常不过夜。5.4 给运营展示的关键指标后台首页我保留了一张“今日变现总览”卡片放六个指标今日广告收入今日请求数 / 填充率今日展示数 / 展示率今日点击数 / 点击率eCPM千次展示收入待处理对账异常数展示这些指标有一个前提统计逻辑必须和联盟后台对齐。刚开始我和联盟的数据总是差几个点后来才发现是我把重复请求算进去了联盟是按去重设备计费的两个口径自然对不上这个口径问题在报表设计阶段就要确认清楚。整个项目做下来我最大的感受是对接广告联盟最忌讳的一件事就是把整条链路想得太简单以为“SDK集成完就能数钱了”。真正花时间的其实是数据链路和稳定性设计。尤其是回调幂等、签名统一、对账自动化这三个点看起来不起眼但任何一个做不好到最后财务对账的时候都是在给自己埋雷。这套PHP后台管理系统跑了一个多月日处理请求过百万对账差异降到了千分之几基本稳定可控。如果你们团队也在做类似的广告变现项目可以按照我上面的模块拆解先搭骨架再根据实际联盟的文档适配细节能省掉不少弯路。
短剧APP广告联盟SDK对接：PHP后台管理系统设计与踩坑实践
上个季度我们给一个短剧平台做广告联盟SDK对接后台管理系统用的PHP。听起来好像挺简单——不就是串一个SDK、接几个回调吗但真正把所有模块跑通之后我才发现最花时间的根本不是一行行调用代码而是后台里那堆跟广告位、订单、回调、对账相关的管理模块。这篇文章就把我这次从零搭建PHP后台管理系统的过程完整拆开讲一遍包括模块设计、核心接口对接逻辑、签名机制、和最容易踩的坑给后面要做APP广告变现的团队一个能直接落地的参考。1. 项目背景短剧APP为什么要接广告联盟后台到底要管什么先说清楚这个项目的商业模式不然后台模块容易设计跑偏。短剧类APP绝大多数是靠内容付费加广告变现两条腿走路其中广告联盟聚合了上游广告主的需求APP通过集成联盟SDK就能在自己的应用里展示激励视频、插屏、信息流广告按展示、点击、转化等维度获得分成收入。对APP方来说不用自己一家家对接广告主联盟作为中间方负责填充广告、竞价、展示逻辑和结算。对联盟来说要管控流量质量、审核素材、防止刷单和违规展示。对后台管理系统来说核心就是三件事配置管理、数据回收、结算对账。所以我在设计PHP后台时第一刀切的就是模块边界。整个后台分成六大块模块核心职能对应业务问题应用与广告位管理维护APP和广告位的上下架、类型、尺寸广告位开没开、用的什么场景广告主与素材管理记录联盟下有合作关系的广告主及其素材知道谁在投、投了什么请求与展示日志记录客户端广告请求、展示、点击明细排查请求量异常和素材问题回调接收中心接收广告联盟下发的转化回调并落库确定哪些展示产生了收益数据报表中心按时/日/广告位多维度汇总收入与消耗运营看数据做决策自动对账模块拉取联盟结算单与本地记录比对保证钱算得对、不扯皮这个划分在我实际开发中几乎够用了后面加需求也只是在这个骨架上加字段和子页面不需要推倒重来。关于技术栈多说一句为什么用PHP而不是Java或者Go团队熟悉度是第一位的另外这种后台管理系统偏CRUD加定时任务PHP配合ThinkPHP或Laravel这类框架开发效率最高环境部署也省心服务器上一套PHP-FPM加MySQL、Redis就齐了。你需要并发能力更强的大数据处理再说迁移或升级的事前期完全没必要给自己加负担。2. 后台管理系统核心模块设计从配置下发到数据落库的完整链路2.1 应用和广告位管理所有联调参数的源头应用和广告位是广告系统的最小粒度单元广告联盟在开发者后台会给你分配一个AppId和应用密钥AppKey然后在应用下面创建多个广告位ID每个广告位对应一种广告类型。后台里这张应用表我这样设计app_id联盟分配给应用的唯一标识app_key签名密钥前端APP不感知只存在服务端status1启用 0停用platformandroid / ios因为双端审核规则和广告填充有差异callback_url后台接收广告联盟转化回调的入口地址广告位表的关键字段ad_slot_id联盟分配的广告位IDscene_name广告场景名比如“开屏页”“激励视频-看广告解锁下一集”ad_type激励视频/插屏/信息流/开屏swidth、sheight素材尺寸要求ecpm_weight排序权重运营可以调节这个值影响广告位的优先级这里有个很重要的经验广告位ID的映射关系一定要单独做不要硬编码在代码里。客户端上报广告位IDPHP后台根据映射表把它翻译成语义化的场景名后续报表对接、问题排查都方便很多。2.2 广告主和素材管理流量方也要知道谁在花钱很多APP团队觉得广告主是联盟的事自己不用管其实大错特错。短剧平台最怕的就是同质竞品素材出现在自己用户面前投放把你的人拉走了。所以后台必须能管理广告主和素材的黑白名单。我在这个模块里做的是拉取联盟提供的素材列表按天同步到本地素材表。素材字段包括素材ID、所属广告主ID、类型图片/视频、尺寸、跳转链接落地页、审核状态。后台支持对广告主ID做黑名单设置命中后客户端拉取广告时直接过滤掉。别小看这功能短视频平台用户对广告素材非常敏感一个狗皮膏药式的素材挂三天用户留存会明显往下掉。设置黑名单之后可以做到小时级别屏蔽。2.3 请求与展示日志排查问题的第一现场广告系统的请求量级比普通后台业务大很多短剧APP日活十万的时候每天广告请求量可以到百万甚至千万级别。全部明细落MySQL会爆掉所以分冷热两套存储。热数据当天到三天的明细放Redis键用ad:log:{广告位ID}:{日期}:{小时}用LPUSH写入到期自动淘汰。冷数据三天前的历史明细每晚批量写MySQL分区表按天分区查询时按日期段裁剪分区。日志表主要字段log_idapp_id / ad_slot_id / device_id设备ID做脱敏处理request_time / show_time / click_timeip只存前三段避免隐私合规问题product_id / order_id和短剧内容关联的扩展参数status1正常 2超时 3被过滤设计这套日志最大的价值在于出现广告填充率下降、点击率异常突变时你能快速定位是某个素材、某个广告位还是某个机型的流量问题。没有明细数据就只能瞎猜。2.4 权限和操作日志多人协作不背锅后台不是一个人的工具。运营、财务、测试、超管都会用粗放式管理很容易出现误操作。所以加了RBAC权限控制和操作日志。权限按角色控制超管、运营、财务、客服。每个角色只给必要权限比如财务只能看对账和结算单不能改广告位状态运营可以改广告位素材和黑白名单看不到利润成本。操作日志记录每一次关键动作谁在什么时间改了广告位状态、改了素材黑名单、导出过哪些数据。后面出现线上事故追责不需要翻聊天记录后台日志就能还原。3. 广告联盟SDK对接核心流程签名、拉取、上报、回调一条链路3.1 通用对接协议为什么所有联盟流程都长得很像广告联盟SDK对接不管你是对接哪家流程都基本固定。客户端集成SDK后消息链路长这样客户端发起广告请求 - SDK带参数请求服务端广告接口 - 服务端校验签名和频控 - 返回广告素材和落地页 - 用户在客户端看到广告(展示) - 用户点击 - 联盟记录点击 - 用户完成转化(比如下载、注册、付费) - 联盟回调服务端 - 后台计费入账。这套链路里PHP后端的参与位置主要有两个一是提供服务端API供客户端SDK调用二是在回调中心接收联盟下发的数据。3.2 服务端接口签名把参数排序这件事做到极致客户端SDK请求后台广告接口时需要携带签名参数防止篡改。签名算法各家略有不同但通用逻辑都是参数名ASCII码排序 - urlencode - 拼接字符串 - 加上AppKey - 做MD5或HMAC。我这边用的签名逻辑是public function generateSign(array $params, string $appKey): string { // 1. 过滤掉sign本身和空值参数 unset($params[sign]); $params array_filter($params, function ($v) { return $v ! $v ! null; }); // 2. 按参数名ASCII码升序排列 ksort($params); // 3. 拼接 keyvaluekeyvalue $str ; foreach ($params as $k $v) { $str . $k . . urlencode($v) . ; } $str rtrim($str, ); // 4. 拼接AppKeyMD5后转大写 $str $str . app_key . $appKey; return strtoupper(md5($str)); }签名参数表如下参数名说明示例app_id应用标识100123timestamp当前时间戳1716180000nonce随机字符串防止重放5f4dcc3b5aa765d61d8327deb882cf99ad_slot_id广告位ID200456device_id设备标识demo_device_001sign最终签名上面算法的输出校验时我在PHP端做了三道防线时间戳防重放超过5分钟的直接拒绝。Redis SETNX nonce设置5分钟过期同一个nonce出现两次说明请求被重放。重新计算签名与服务端传来的sign比对不一致直接拒绝。这个签名逻辑看起来简单但它是整条链路的地基。后续你接任何联盟都能用同一套思路套过去。3.3 客户端广告拉取返回广告还是返回空背后的逻辑很重要客户端SDK调到服务端广告接口后PHP后端要决定返回什么内容。这一步除了查广告位配置还要做两件事频控同一个设备ID在10分钟内请求次数超过50次直接不返回广告防止恶意刷量。素材过滤读取素材黑名单命中广告主ID或素材ID的直接剔除。返回参数我固定为统一的JSON结构{ code: 0, msg: success, data: { ad_id: 素材ID, ad_type: reward_video, title: 素材标题, image_url: 素材封面图, video_url: 素材视频地址, click_url: 点击跳转地址, extension: { cp_id: 广告主ID, product_id: 关联短剧ID } } }3.4 展示和点击上报服务端需要校验上报的每一笔广告有没有被展示、被点击直接关系到广告主扣费和流量方收入这里必须做服务端校验不能完全信任客户端上报。我这边是在客户端SDK展示、点击成功后把上报请求转发到PHP后端再由后端转发到联盟运营后台同时本地记录一份日志。校验逻辑校验device_id在最近N分钟内是否有过成功的广告请求记录。校验ad_id是否为刚才下发过的素材。校验展示和点击的时间先后关系点击时间不能早于展示时间5秒以上。这个链路的价值是给后续对账留底联盟后台的数据是最终结算依据本地日志是对账判断的证据。3.5 回调接收中心这里是最容易出问题的地方联盟在用户发生转化后会主动请求我们配置的回调地址。比如用户看完激励视频后下载了某个APP并激活联盟会回调一个订单通知。回调中心处理不好后面对账必然一团糟。我的回调处理逻辑分四步验签回调请求里带联盟签名用约定的公共密钥验签。幂等判断以order_id event_type为唯一键查本地表已存在则直接返回成功。落库写入回调记录表记录联盟订单号、金额、转化类型、时间。业务处理更新对应对账汇总表的数据向财务模块推送一条待确认记录。用代码表示public function handleCallback(Request $request) { // 1. 验签 $verifyResult $this-adapter-verify($request-all()); if (!$verifyResult) { return response()-json([code 400, msg sign error]); } $orderId $request-input(order_id); $eventType $request-input(event_type); // 2. 幂等 $exists CallbackLog::where(order_id, $orderId) -where(event_type, $eventType) -exists(); if ($exists) { return response()-json([code 0, msg already exists]); } // 3. 落库 DB::transaction(function () use ($request, $orderId, $eventType) { $log CallbackLog::create([ order_id $orderId, event_type $eventType, amount $request-input(amount, 0), raw_data json_encode($request-all()), ]); $this-reporter-addRecord($log); }); // 4. 快速响应避免联盟超时重试 return response()-json([code 0, msg ok]); }注意回调接口收到请求后必须第一时间响应联盟不要在这个接口里做耗时的对账、推送、短信通知之类的操作。通常会先把记录落库返回成功然后异步把数据推到消息队列慢慢消化。原因很简单联盟回调一般有超时重试机制你处理超过5秒它就重复推结果幂等没做好就会重复入账。4. 对接过程中踩过的坑明明照着文档写怎么就是跑不通4.1 签名校验失败排序、编码、密钥都可能是凶手对接SDK第一天我就被签名校验卡了半天。文档写的是“参数按ASCII排序后拼接MD5加密”但实际操作时发现三家联盟的细节完全不同有的排完序之后要urlencode有的不用。有的拼接格式是a1b2有的却是a1b2连等号都不要。有的MD5是小写有的是大写。这个坑的排查方法很笨但有效先在服务端打印收到的原始参数和计算出来的签名然后在联盟开发者后台的调试工具里比对他们的genSign算法。当你发现两个签名就差大小写时基本上就是大小写的问题。建议把这部分封装成Adapter模式每家联盟一个类统一入口不同签名逻辑内部消化。4.2 nonce和时间戳同时出问题后来线上频控出现误杀排查发现是服务端和客户端服务器时间不同步客户端设备时间快了两分钟导致时间戳校验直接拒绝。很多设备的时间是用户自己改的不能依赖它。解决思路客户端在启动SDK时先调一次时间同步接口拿服务端时间校准。时间戳校验窗口从5分钟放宽到15分钟配合nonce去重足够安全了。对时间戳超时的请求返回特定code客户端SDK可以自动校准后重试。4.3 回调重复入账幂等设计不到位就是负数收入这个坑是最贵的。测试环境还好一上生产就发现财务对账单和联盟后台差了将近两千块钱。查了半天罪魁祸首是联盟回调在网络波动情况下重试了三次而我当时的回调处理里没有唯一索引。修复方案分两层数据库层给order_id event_type加唯一索引让数据库帮我们兜底防止并发情况下PHP判断和插入之间的间隙。应用层在落库之前先查一次缓存用Redis SETNX做分布式锁锁住同一个订单号避免同一毫秒两个请求同时查到不存在然后同时插入。两个一起用才开始稳定只靠任何一层都有漏网之鱼。4.4 测试环境和正式环境的隔离问题SDK集成最刺激的坑是在测试环境明明请求到了广告一上线就请求不到。原因通常有两个测试广告位ID和正式广告位ID分属不同应用后台只配置了测试环境的AppId。测试设备没有在联盟后台绑定为测试设备被正常的频控策略拦掉了。我的建议是后台把环境和设备管理显式做成配置用config/app_env区分dev/test/prod在数据库广告位表加一个is_test字段。客户端SDK在debug模式下会优先请求测试广告位正式包永远只会请求生产环境的广告位。这样两边物理隔离再也不会串。4.5 金额单位不统一广告联盟返回的金额有的是以分为单位有的是以元为单位甚至同一个联盟内不同接口有的返回分有的返回元。如果没统一直接落库报表会错得离谱。处理办法很暴力但有效业务层所有金额字段统一用“分”为单位所有接口在入口处做一层单位转换底层数据库只存整数。对账、结算、报表计算全部用分最后展示时候再除以100。这个约定要写进团队开发文档后面来新人也不会踩。5. 数据报表与自动对账别再把时间花在手工数钱上5.1 多维度报表设计让运营一眼看到问题出在哪广告变现运营最关心的报表有四个维度按广告位看哪个广告位收入最高、ecpm是多少。按素材看哪类素材点击率高要不要调展示权重。按小时看全天哪个时间段填充率高要不要做流量调度。按内容看哪部短剧的广告转化效果好可以加大买量。我的报表实现采用预聚合思路。Redis里维护小时级的汇总计数器键比如report:hour:ad_slot:1716180000:ad_slot_id按小时自动过期。每天凌晨2点定时任务把前一天的聚合结果刷入MySQL报表表。MySQL报表表设计成星型结构事实表只存维度和汇总值维度表存广告位、素材、内容的元信息。查询时JOIN维度表做筛选千万级数据量查询都在毫秒级。5.2 自动对账本地记录和联盟结算单的差异怎么处理对账是整个后台管理系统里我投入精力最多的模块。手工对账在广告量小的时候还凑合一天几百条记录还能用Excel筛量一上来就废了。自动对账逻辑每天早上定时任务调用联盟开放平台的结算单接口拉取前一天所有订单明细。把订单明细和本地回调记录表按order_id做全量比对。对账差异分成三类差异类型原因处理方式本地有联盟无联盟数据延迟或本地伪造先标记等28小时再比对还有差异转人工联盟有本地无回调丢失或没入库检查回调日志和MQ消费记录补录金额不一致单位换算或扣量调整以联盟为准记录差异原因备查这套对账跑了一个月之后财务基本就不用再打开两个平台手动比对数据了。5.3 定时任务框架从数据拉取到对账提醒的完整编排PHP后台我用的ThinkPHP框架自带命令行指令可以直接在Linux crontab里挂定时任务。定时任务编排如下0 2 * * * php think report:sync // 同步联盟结算单到本地 0 3 * * * php think report:aggregate // 聚合前一天报表数据 30 3 * * * php think report:compare // 执行对账比对 0 9 * * * php think report:push // 推送对账异常通知到企业微信每个任务独立执行任务执行状态写任务日志表开始时间、结束时间、成功失败、执行耗时、错误信息。如果对账差异超过设定阈值自动推送给财务和运营的群做到异常不过夜。5.4 给运营展示的关键指标后台首页我保留了一张“今日变现总览”卡片放六个指标今日广告收入今日请求数 / 填充率今日展示数 / 展示率今日点击数 / 点击率eCPM千次展示收入待处理对账异常数展示这些指标有一个前提统计逻辑必须和联盟后台对齐。刚开始我和联盟的数据总是差几个点后来才发现是我把重复请求算进去了联盟是按去重设备计费的两个口径自然对不上这个口径问题在报表设计阶段就要确认清楚。整个项目做下来我最大的感受是对接广告联盟最忌讳的一件事就是把整条链路想得太简单以为“SDK集成完就能数钱了”。真正花时间的其实是数据链路和稳定性设计。尤其是回调幂等、签名统一、对账自动化这三个点看起来不起眼但任何一个做不好到最后财务对账的时候都是在给自己埋雷。这套PHP后台管理系统跑了一个多月日处理请求过百万对账差异降到了千分之几基本稳定可控。如果你们团队也在做类似的广告变现项目可以按照我上面的模块拆解先搭骨架再根据实际联盟的文档适配细节能省掉不少弯路。
