Arenza 现已加入 OpenAI 合作伙伴网络 🎉
arenza
免费诊断
章节目录

连接 Google Search Console

把网站在 Google 中出现过的搜索词和落地页作为买家意图、问句生成的补充依据。

同一个 Arenza 品牌只需连接一次，Shopify 与 Portal 共用连接和数据。

连接或同步不会自动改写已有意图，也不会发起 AI 扫描。

接入前准备

  • 网站已在 Google Search Console 中建立并验证对应资源。没有资源时，请先按 Google 的流程完成验证。
  • 由 GSC 资源所有者添加读取账号；只有查看权限的同事可能看不到添加用户的入口。
  • 由 域名 DNS 管理员添加 TXT 记录。这可能是技术同事、网站服务商或域名管理人员，不一定是 Shopify 后台管理员。
  • 确认 Arenza 品牌的网站域名正确，Shopify 店铺已关联到同一个 Arenza 品牌。仅域名相同的两个品牌记录不会自动共用数据。

不需要提供 Google 密码、下载服务账号 JSON 密钥，或自行创建 Google OAuth 应用。Arenza 的读取账号和专属 TXT 值以当前品牌页面显示为准。

打开连接页面

Portal：登录 Arenza，选择品牌，进入「买家意图 → 搜索数据」，点击「连接 Google Search Console」。站点设置中也有搜索数据入口。

Shopify App：打开「买家意图」或「AI 资产」，找到 Google Search Console 卡片，点击连接或管理。它会在新标签页打开同一品牌的 Portal 连接页面；如需登录，请使用有该品牌访问权限的 Arenza 账号。

第一步：添加只读账号

  1. 在 Search Console 左上角选择目标资源，确认域名与 Arenza 品牌一致。
  2. 由资源所有者进入 设置 → 用户和权限 → 添加用户。
  3. 从 Arenza 连接页复制读取账号邮箱，粘贴到 Google。当前标准读取账号为：
arenza-search-console@brandcert.iam.gserviceaccount.com
  1. 权限选择 Restricted（受限／只读）并保存。不需要授予 Owner 或 Full 权限。

Google 官方权限说明列出了各角色可查看和操作的范围。

第二步：添加品牌专属 DNS TXT

在同一 Arenza 连接页复制 TXT 名称和 TXT 值，交给域名管理员新增一条 TXT 记录。

DNS 字段填写内容
类型TXT
名称／主机记录复制页面显示的完整名称，例如 _arenza-gsc.your-site.example。若 DNS 服务商会自动补上当前域名，主机记录通常只填写 _arenza-gsc；保存后的完整名称必须与 Arenza 显示一致。
值／内容完整复制当前品牌的 arenza-gsc-verification=... 值，不要使用示例、其他品牌的值或手写省略号。
TTL使用 DNS 服务商的默认值即可。

不要覆盖网站已有的 Google 验证记录，也不要修改 A、CNAME、MX 或其他 TXT 记录。专属值用于确认当前 Arenza 品牌对该域名的控制权，不能跨品牌复用。添加后等待 DNS 生效，再继续验证。

第三步：选择资源并同步

  1. 回到 Arenza，检查「Search Console 资源」。默认值适用于对应的 Domain 资源；若 Google 中实际使用 URL-prefix 资源，应填写其完整名称。
  2. 以下为两种资源格式示例，选择实际存在的一种，不是两个都填：
sc-domain:your-site.example
https://your-site.example/
  1. URL-prefix 必须与 Google 中的资源完全一致，包括协议、主机名、路径及结尾 /。当前接入要求资源主机名与品牌网站一致（忽略 www 前缀）；子域名品牌不能使用父域资源。例如品牌网站是 shop.your-site.example，不能填写 sc-domain:your-site.example。
  2. 点击页面上的验证并同步。看到成功状态、上次同步时间及搜索日期后，检查导入的搜索词是否符合该网站。

如果首次验证失败，连接记录可能已经保存。此时按页面提示修复权限或 DNS 后点击同步／重试；不要反复新建连接。资源填写错误时，先断开，再使用正确资源重新连接。

确认两端已共用

  • 返回 Shopify App，切回标签页或点击「刷新状态」。资源名称和上次同步时间应与 Portal 一致。
  • 有搜索词且数据新鲜时，Shopify 显示「可用于生成」。后续主动生成意图或问句时会参考这份数据；已有内容不会自动修改。
  • 成功但没有搜索词，也可能是同步成功后的空结果，不代表连接失败。其他需求数据源仍可使用。
  • 超过七天未成功同步的缓存不参与生成。需要时在连接页手动同步；打开页面、刷新状态或生成意图都不会自动向 Google 拉取新数据。

常见问题

情况处理方法
看不到「用户和权限」或「添加用户」请 GSC 资源所有者操作；Shopify 管理权限不等于 GSC 所有权。
提示需要域名验证核对 TXT 完整名称和值是否来自当前品牌；检查是否重复补了域名，等待 DNS 生效后重试。
Google 拒绝访问检查读取邮箱、Restricted 权限以及选中的 GSC 资源是否一致。
资源域名不匹配检查 Arenza 品牌网站、Domain／URL-prefix 格式和子域名；需要更改资源时先断开。
正在同步／已有连接等待同步结束后刷新状态；已有连接用同步重试，不重复调用连接。
暂无搜索词或数字与 Google 界面不同当前导入窗口可能没有记录；匿名搜索、Google 仅返回部分主要记录，以及查询／页面维度会影响可见记录。
Shopify 显示不同状态确认关联的是同一个品牌，再刷新状态；不要仅按域名假定两个品牌记录相同。
平台暂不可用或额度限制稍后重试；持续发生时向支持团队提供品牌、资源名称、错误提示和发生时间，不发送 Google 密码或密钥。

数据范围与停用

每次同步读取截至三天前的最近 28 个太平洋时间（PT）自然日，使用 Google Web 搜索，覆盖所有国家和设备；最多导入 10,000 条查询与页面记录。Google 可能隐藏匿名搜索或省略部分记录，因此这不是完整搜索日志。

点击、曝光、CTR 和平均排名是网站搜索表现，不等于全市场搜索量、AI 原始 prompts、AVS、ACS 或销售额。连接不会自动发布或修改店铺。

在任意入口打开同一管理页并断开连接，会移除该品牌连接和缓存，两端都停止使用；已保存到历史意图的证据仍保留。要同时撤销 Google 权限，请由资源所有者在 GSC「用户和权限」中移除读取账号。若同一读取账号仍为其他已授权品牌服务，应先确认影响范围。

API 接口

Portal 已登录应用使用这些接口，文档用于理解集成和排查；普通用户按上面的界面流程操作即可。它们使用 Clerk 会话 JWT + 品牌访问权限，目前不支持用 arn_pat_... Personal Access Token、Website install ID 或 Google access token 替代。不要把会话 token 写进公开网页、文档或 URL。

基础地址：https://api.arenza.ai。{brand_id} 为有访问权限的品牌 UUID。

方法路径请求与结果
GET/api/v1/brands/{brand_id}/search-console读取配置、专属 TXT 挑战、连接状态及缓存；不触发 Google 同步。
POST/api/v1/brands/{brand_id}/search-console/connectJSON 为 {"property":"sc-domain:your-site.example"}；保存连接并验证 DNS、Google 权限，完成首次同步。
POST/api/v1/brands/{brand_id}/search-console/sync无业务请求体；对已有连接显式同步，成功后返回当前状态。
DELETE/api/v1/brands/{brand_id}/search-console移除连接及缓存，返回 {"disconnected":true}；不自动撤销 Google 侧权限。
GET /api/v1/brands/{brand_id}/search-console HTTP/1.1
Host: api.arenza.ai
Authorization: Bearer <CLERK_SESSION_JWT>

GET、成功连接和成功同步返回同一状态结构：configured、reader_email、default_property、verification 和 connection。verification 包含当前品牌的 TXT name／value；connection 未连接时为 null，否则包含 property、status、last_error、last_synced_at、syncing 及 snapshot。快照含 startDate、endDate、capturedAt、limited 和 rows；每行含 query、page、clicks、impressions、ctr、position，其中 ctr 是 0 到 1 的比率。成功请求返回 200；configured:true 只代表平台可配置，不代表品牌已连通。

业务错误通常返回 {"error":{"code":"..."}}。处理建议：

HTTP／代码含义与下一步
401会话缺失、无效或过期，重新登录。
400 invalid_property／property_domain_mismatch检查资源格式和品牌网站。
403 domain_verification_required补齐或修正当前品牌的 DNS TXT。
403 access_denied修正 GSC 读取授权和资源名称。
404／not_connected品牌不可访问，或同步前尚无连接。
409 already_connected先 GET 检查已有连接，再同步；需要换资源时先断开。
409 sync_in_progress／connection_changed等待或重新 GET，依据最新状态操作。
429 quota_exceeded退避后重试，不循环提交。
503 not_configured／google_unavailable平台配置或 Google 请求失败；先读取状态，必要时联系支持。

上次同步租约过期时，状态读取还可能返回 200，并在 connection.last_error 中标记 sync_interrupted。先核对最新状态，再重试同步。

同步失败会保留上一次完整快照，但错误状态的数据不用于生成；同步成功的空结果会替换旧数据。请求超时或结果未知时先 GET 核对，不盲目重试连接。

Shopify App 通过服务端内部适配器读取同一品牌状态，不需要客户持有 HMAC 密钥、安装代次或另外申请 GSC 凭据；该内部接口不是公开浏览器 API。

官方参考