小红书监测链接

application/admin/model/shopro/xhs/MonitorLog.php

+<?php
+
+namespace app\admin\model\shopro\xhs;
+
+use app\admin\model\shopro\Common;
+
+/**
+ * 小红书监测链接点击日志模型
+ *
+ * 用于接收并存储小红书广告投放系统下发的监测链接请求参数。
+ * 支持文档中列出的全部宏参数：__CLICK_ID__、__PLACEMENT__、__OAID_MD5__、
+ * __CAID_MD5__、__CAID__、__IDFA__、__IMEI__、__OS__、__TS__、__IP__、
+ * __IPV6__、__UA__、__UA1__、__ADVERTISER_ID__、__NOTE_ID__、
+ * __CREATIVITY_ID__、__UNIT_ID__、__CAMPAIGN_ID__、__PAID__。
+ */
+class MonitorLog extends Common
+{
+    protected $name = 'fa_xhs_monitor_log';
+
+    protected $updateTime = 'updatetime';
+    protected $createTime = 'createtime';
+    protected $autoWriteTimestamp = 'integer';
+
+    /**
+     * 参数映射表
+     *
+     * key    : 数据库字段名
+     * value  : 可能出现在请求中的参数名（按优先级从左到右匹配）
+     *
+     * 支持：小红书官方宏参数名、小写/驼峰写法、以及示例中的 a1~a13 别名。
+     * 在聚光后台配置监测链接时，参数名可自定义，只要对应宏能替换即可。
+     */
+    protected static $fieldMap = [
+        'click_id'      => ['__CLICK_ID__', 'click_id', 'a1', 'clickId', 'clickid'],
+        'placement'     => ['__PLACEMENT__', 'placement', 'a2'],
+        'oaid_md5'      => ['__OAID_MD5__', 'oaid_md5', 'oaidMd5', 'a3'],
+        'caid_md5'      => ['__CAID_MD5__', 'caid_md5', 'caidMd5'],
+        'caid'          => ['__CAID__', 'caid'],
+        'idfa'          => ['__IDFA__', 'idfa', 'a4'],
+        'imei'          => ['__IMEI__', 'imei', 'a5'],
+        'os'            => ['__OS__', 'os', 'a6'],
+        'ts'            => ['__TS__', 'ts', 'a7', 'timestamp'],
+        'ip'            => ['__IP__', 'ip', 'userIp', 'user_ip'],
+        'ipv6'          => ['__IPV6__', 'ipv6', 'ip_v6'],
+        'ua'            => ['__UA__', 'ua', 'userAgent', 'user_agent'],
+        'ua1'           => ['__UA1__', 'ua1', 'browserUa', 'browser_ua'],
+        'advertiser_id' => ['__ADVERTISER_ID__', 'advertiser_id', 'advertiserId', 'a8'],
+        'note_id'       => ['__NOTE_ID__', 'note_id', 'noteId', 'a9'],
+        'creativity_id' => ['__CREATIVITY_ID__', 'creativity_id', 'creativityId', 'a10'],
+        'unit_id'       => ['__UNIT_ID__', 'unit_id', 'unitId', 'a11'],
+        'campaign_id'   => ['__CAMPAIGN_ID__', 'campaign_id', 'campaignId', 'a12'],
+        'paid'          => ['__PAID__', 'paid', 'a13'],
+    ];
+
+    /**
+     * 从请求对象中解析并记录监测日志
+     *
+     * @param \think\Request $request
+     * @return MonitorLog|null
+     */
+    public static function recordFromRequest($request)
+    {
+        $params = $request->param();
+        $data = self::parseParams($params);
+
+        // 服务端补充信息
+        $data['ip']        = $data['ip'] ?: $request->ip();
+        $data['ua']        = $data['ua'] ?: $request->header('user-agent');
+        $data['server_ip'] = $request->server('REMOTE_ADDR');
+        $data['request_uri'] = $request->url(true);
+        $data['raw_data']  = json_encode($params, JSON_UNESCAPED_UNICODE);
+
+        // 可选：业务方自定义透传的 user_id
+        $data['user_id'] = isset($params['user_id']) && $params['user_id'] !== ''
+            ? intval($params['user_id'])
+            : 0;
+
+        // click_id 为空时不记录，避免垃圾请求入库
+        if (empty($data['click_id'])) {
+            return null;
+        }
+
+        return self::create($data);
+    }
+
+    /**
+     * 解析请求参数，映射到数据库字段
+     *
+     * @param array $params
+     * @return array
+     */
+    protected static function parseParams(array $params)
+    {
+        $data = [];
+        foreach (self::$fieldMap as $field => $aliases) {
+            foreach ($aliases as $alias) {
+                if (isset($params[$alias]) && $params[$alias] !== '' && $params[$alias] !== null) {
+                    $data[$field] = $params[$alias];
+                    break;
+                }
+            }
+            if (!isset($data[$field])) {
+                $data[$field] = '';
+            }
+        }
+        return $data;
+    }
+
+    /**
+     * 根据 click_id 获取单条监测日志
+     *
+     * @param string $clickId
+     * @return MonitorLog|null
+     */
+    public static function getByClickId($clickId)
+    {
+        return self::where('click_id', $clickId)->find();
+    }
+}

application/admin/sql/xhs_monitor_log.sql

+-- --------------------------------------------------------
+-- 小红书监测链接点击日志表
+-- 用于存储聚光平台通过监测链接回传的宏参数
+-- --------------------------------------------------------
+
+CREATE TABLE IF NOT EXISTS `fa_xhs_monitor_log` (
+  `id` int(10) unsigned NOT NULL AUTO_INCREMENT,
+  `click_id` varchar(255) NOT NULL DEFAULT '' COMMENT '小红书 click_id（URL Encode 后的值）',
+  `placement` varchar(20) NOT NULL DEFAULT '' COMMENT '场域：1信息流 2搜索 4全站智投 7视频内流',
+  `oaid_md5` varchar(64) NOT NULL DEFAULT '' COMMENT 'OAID 的 MD5 值',
+  `caid_md5` text COMMENT 'CAID 的 MD5 值，URL Encode 后，多个以英文逗号分隔',
+  `caid` text COMMENT 'CAID 原值，URL Encode 后，多个以英文逗号分隔',
+  `idfa` varchar(64) NOT NULL DEFAULT '' COMMENT 'IDFA 的 MD5 值',
+  `imei` varchar(64) NOT NULL DEFAULT '' COMMENT 'IMEI 的 MD5 值',
+  `os` varchar(10) NOT NULL DEFAULT '' COMMENT '系统：0 android 1 ios 2 鸿蒙',
+  `ts` varchar(32) NOT NULL DEFAULT '' COMMENT '时间戳（秒）',
+  `ip` varchar(64) NOT NULL DEFAULT '' COMMENT '客户端 IPV4 地址',
+  `ipv6` varchar(255) NOT NULL DEFAULT '' COMMENT '客户端 IPV6 地址',
+  `ua` text COMMENT '小红书客户端 UA（已 URL Decode）',
+  `ua1` text COMMENT '浏览器 UA（已 URL Decode）',
+  `advertiser_id` varchar(64) NOT NULL DEFAULT '' COMMENT '广告主 ID',
+  `note_id` varchar(64) NOT NULL DEFAULT '' COMMENT '笔记 ID',
+  `creativity_id` varchar(64) NOT NULL DEFAULT '' COMMENT '创意 ID',
+  `unit_id` varchar(64) NOT NULL DEFAULT '' COMMENT '单元 ID',
+  `campaign_id` varchar(64) NOT NULL DEFAULT '' COMMENT '计划 ID',
+  `paid` varchar(255) NOT NULL DEFAULT '' COMMENT 'paid 值',
+  `server_ip` varchar(64) NOT NULL DEFAULT '' COMMENT '服务端获取的远程 IP',
+  `request_uri` text COMMENT '完整请求 URI',
+  `raw_data` text COMMENT '原始请求参数 JSON',
+  `user_id` int(10) unsigned NOT NULL DEFAULT '0' COMMENT '关联用户 ID（如有透传）',
+  `createtime` int(10) unsigned NOT NULL DEFAULT '0',
+  `updatetime` int(10) unsigned NOT NULL DEFAULT '0',
+  PRIMARY KEY (`id`),
+  KEY `idx_click_id` (`click_id`),
+  KEY `idx_oaid_md5` (`oaid_md5`),
+  KEY `idx_idfa` (`idfa`),
+  KEY `idx_imei` (`imei`),
+  KEY `idx_caid_md5` (`caid_md5`(64)),
+  KEY `idx_caid` (`caid`(64)),
+  KEY `idx_createtime` (`createtime`),
+  KEY `idx_user_id` (`user_id`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='小红书监测链接点击日志';

application/api/controller/Xhstrack.php

+<?php
+
+namespace app\api\controller;
+
+use app\admin\model\shopro\xhs\MonitorLog;
+use app\common\controller\Api;
+use think\Log;
+
+/**
+ * 小红书监测链接接收接口
+ *
+ * 小红书聚光平台在广告曝光/点击时，会向配置的 HTTPS 监测链接发起 GET 请求。
+ * 本接口负责接收并存储回传的宏参数，用于后续归因与转化回传。
+ *
+ * 访问地址：
+ *   - 默认路由：/api/xhstrack/index
+ *   - 自定义路由（如已配置）：/xhs/track
+ *
+ * 监测链接配置示例：
+ *   https://your-domain.com/api/xhstrack/index?a1=__CLICK_ID__&a2=__PLACEMENT__&a3=__OAID_MD5__&a4=__IDFA__&a5=__IMEI__&a6=__OS__&a7=__TS__&a8=__ADVERTISER_ID__&a9=__NOTE_ID__&a10=__CREATIVITY_ID__&a11=__UNIT_ID__&a12=__CAMPAIGN_ID__&a13=__PAID__
+ *
+ * 也支持使用宏参数原名直接作为 key，例如：
+ *   ?__CLICK_ID__=xxx&__PLACEMENT__=1&...
+ *
+ * 响应：
+ *   - 默认返回 1x1 透明 GIF 像素，适合 img src 方式调用
+ *   - 传参 format=json 返回 JSON：{"code":1,"msg":"ok"}
+ */
+class Xhstrack extends Api
+{
+    /**
+     * 小红书监测入口
+     *
+     * @return \think\Response
+     */
+    public function index()
+    {
+        try {
+            MonitorLog::recordFromRequest($this->request);
+        } catch (\Exception $e) {
+            // 监测接口必须保证任何异常都不影响小红书广告投放，仅记录日志
+            Log::record('Xhstrack error: ' . $e->getMessage(), Log::ERROR);
+        }
+
+        // 支持 JSON 调试输出，默认返回像素图
+        $format = $this->request->param('format', 'gif');
+        if ($format === 'json') {
+            return json(['code' => 1, 'msg' => 'ok']);
+        }
+
+        // 1x1 透明 GIF 像素
+        $pixel = base64_decode('R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7');
+        return response($pixel, 200, [
+            'Content-Type'   => 'image/gif',
+            'Content-Length' => strlen($pixel),
+            'Cache-Control'  => 'no-store, no-cache, must-revalidate',
+            'Pragma'         => 'no-cache',
+        ]);
+    }
+}

application/route.php

@@ -17,6 +17,8 @@ return [
     //变量规则
     '__pattern__' => [
     ],
+    // 小红书监测链接（聚光后台配置时使用此地址更简洁）
+    'xhs/track' => 'api/xhstrack/index',
 //        域名绑定到模块
 //        '__domain__'  => [
 //            'admin' => 'admin',