进阶 docs.writesonic.com 2026-10-09 08:02:29 · 0 阅读
第18章 集成自定义日志接收器
第18章：集成自定义日志接收器
本指南将带你了解如何通过自定义集成的方式实现 AI Bot Analytics。这种方法直接向 Writesonic 的分析接口发送 HTTP 请求，因此可以集成到任何平台或自定义应用中。
前提条件
一个有效的 Writesonic 账号
网站或应用的开发权限
服务器能够发起 HTTP POST 请求
可以访问请求头和元数据
阶段一：在 Writesonic 中开始
前往 Writesonic 的 AI Bot Analytics 页面，选择 "Custom" 作为提供方
点击 "Continue" 初始化集成
Writesonic 会为你的网站生成一个专属的 API key
阶段二：获取集成详情
步骤 1：复制接口地址（Endpoint URL）
复制以下接口地址，后续将用它来发送分析数据：
https://ingestion.writesonic.com/api/v1/analytics/ingest 步骤 2：记录认证请求头 你需要在所有请求中包含以下请求头： 请求头名称：x-api-key 请求头值：复制 Writesonic 提供的 API 密钥（每个项目都有唯一的密钥） 阶段 3：实施集成 请求格式 向该端点 URL 发送 POST 请求，JSON 请求体需包含以下字段： 字段类型描述示例 ip字符串客户端 IP 地址192.168.1.100 x_real_ip字符串X-Real-IP 请求头203.0.113.1 ua字符串请求中的 User-Agent 请求头Mozilla/5.0 (compatible; Googlebot/2.1) country_code字符串ISO 国家代码US referrer字符串Referer 请求头值https://chatgpt.com/ url字符串被请求的 URL 路径https://writesonic.com/about-us method字符串使用的 HTTP 方法POST x_forwarded_for字符串X-Forwarded-For 请求头链203.0.113.1, 198.51.100.1 response_status字符串HTTP 响应状态码200 Curl 示例 curl -X POST 'https://ingestion.writesonic.com/api/v1/analytics/ingest' \ -H "Content-Type: application/json" \ -H "x-api-key: YOUR_API_KEY_HERE" \ -d '[{ "ip": "192.168.1.1", "x_real_ip": "203.0.113.1", "ua": "Mozilla/5.0 (compatible; Googlebot/2.1)", "referrer" : "https://chatgpt.com/", "country_code": "US", "url": "https://writesonic.com/about-us", "method": "GET", "response_status": "200", "x_forwarded_for" : "203.0.113.1,198.51.100.1" }]' 阶段 4：测试与验证 测试你的集成 在你的应用程序中实现代码 向你的网站发送几个测试请求 确认请求已发送至 Writesonic 端点 监控应用程序日志，查看是否有错误发生 在 Writesonic 中验证安装 前往 Writesonic 中的 AI Bot Analytics 页面。 点击"验证集成"以确认你的自定义集成运行正常 验证成功后，你会被重定向到分析仪表板。此过程通常耗时 1–2 分钟，但最长可能需要 5 分钟。 最佳实践 性能考量 异步处理：异步发送分析数据，避免影响响应时间 错误处理：实施适当的错误处理机制，防止分析功能失败影响主应用程序 速率限制：实施客户端速率限制，避免请求过载导致端点崩溃 数据质量 IP 地址：使用尽可能准确的 IP 地址（需考虑代理和负载均衡器） User Agent：始终包含完整的 User-Agent 字符串 URL 标准化：确保 URL 格式正确且完整 安全性 API 密钥保护：妥善保管你的 API 密钥，切勿在客户端代码中暴露 仅限 HTTPS：向 Writesonic 端点发送请求时，始终使用 HTTPS 数据清理：发送前清理用户数据，以防止注入攻击 故障排查 常见问题 401 未授权：检查 API 密钥是否正确，并确保已正确包含在请求头中 422 无法处理的实体：验证你的 JSON 负载是否符合要求的格式 网络错误：确保你的服务器可以发起外发 HTTPS 请求 数据缺失：检查是否捕获了所有可用的请求头和元数据 调试技巧 记录请求：为了便于调试，记录你发送的数据 使用 curl 测试：手动使用 curl 测试端点 检查响应：始终检查 HTTP 响应码和响应体以获取错误详情 更新于 7 个月前 此页面是否对你有帮助？
https://ingestion.writesonic.com/api/v1/analytics/ingest 步骤 2：记录认证请求头 你需要在所有请求中包含以下请求头： 请求头名称：x-api-key 请求头值：复制 Writesonic 提供的 API 密钥（每个项目都有唯一的密钥） 阶段 3：实施集成 请求格式 向该端点 URL 发送 POST 请求，JSON 请求体需包含以下字段： 字段类型描述示例 ip字符串客户端 IP 地址192.168.1.100 x_real_ip字符串X-Real-IP 请求头203.0.113.1 ua字符串请求中的 User-Agent 请求头Mozilla/5.0 (compatible; Googlebot/2.1) country_code字符串ISO 国家代码US referrer字符串Referer 请求头值https://chatgpt.com/ url字符串被请求的 URL 路径https://writesonic.com/about-us method字符串使用的 HTTP 方法POST x_forwarded_for字符串X-Forwarded-For 请求头链203.0.113.1, 198.51.100.1 response_status字符串HTTP 响应状态码200 Curl 示例 curl -X POST 'https://ingestion.writesonic.com/api/v1/analytics/ingest' \ -H "Content-Type: application/json" \ -H "x-api-key: YOUR_API_KEY_HERE" \ -d '[{ "ip": "192.168.1.1", "x_real_ip": "203.0.113.1", "ua": "Mozilla/5.0 (compatible; Googlebot/2.1)", "referrer" : "https://chatgpt.com/", "country_code": "US", "url": "https://writesonic.com/about-us", "method": "GET", "response_status": "200", "x_forwarded_for" : "203.0.113.1,198.51.100.1" }]' 阶段 4：测试与验证 测试你的集成 在你的应用程序中实现代码 向你的网站发送几个测试请求 确认请求已发送至 Writesonic 端点 监控应用程序日志，查看是否有错误发生 在 Writesonic 中验证安装 前往 Writesonic 中的 AI Bot Analytics 页面。 点击"验证集成"以确认你的自定义集成运行正常 验证成功后，你会被重定向到分析仪表板。此过程通常耗时 1–2 分钟，但最长可能需要 5 分钟。 最佳实践 性能考量 异步处理：异步发送分析数据，避免影响响应时间 错误处理：实施适当的错误处理机制，防止分析功能失败影响主应用程序 速率限制：实施客户端速率限制，避免请求过载导致端点崩溃 数据质量 IP 地址：使用尽可能准确的 IP 地址（需考虑代理和负载均衡器） User Agent：始终包含完整的 User-Agent 字符串 URL 标准化：确保 URL 格式正确且完整 安全性 API 密钥保护：妥善保管你的 API 密钥，切勿在客户端代码中暴露 仅限 HTTPS：向 Writesonic 端点发送请求时，始终使用 HTTPS 数据清理：发送前清理用户数据，以防止注入攻击 故障排查 常见问题 401 未授权：检查 API 密钥是否正确，并确保已正确包含在请求头中 422 无法处理的实体：验证你的 JSON 负载是否符合要求的格式 网络错误：确保你的服务器可以发起外发 HTTPS 请求 数据缺失：检查是否捕获了所有可用的请求头和元数据 调试技巧 记录请求：为了便于调试，记录你发送的数据 使用 curl 测试：手动使用 curl 测试端点 检查响应：始终检查 HTTP 响应码和响应体以获取错误详情 更新于 7 个月前 此页面是否对你有帮助？
