概述

Web 服务器到服务器（Web S2S）会直接从您的服务器将网页转化和互动事件发送到 Singular， 使用与移动端 V1 集成相同的 EVENT 端点。网页路径通过平台参数 p=Web 加以区分。

Web S2S 是一种 浏览器辅助的架构 。若干与归因相关的值 仅在浏览器中可用 — location.href 、 document.referrer 以及浏览器 userAgent 无法在后端重建。必须由一段轻量的客户端代码片段来收集这些值， 然后直接调用该端点，或将它们转发给您的后端，再由后端发起 S2S 调用。

并 没有网页 SESSION 端点 。第一个 __PAGE_VISIT__ 转化事件会替代移动端的 launch 调用，并为该次访问建立归因基线。

端点

Web S2S 使用与移动端 V1 EVENT 端点相同的主机和路径。设置 p=Web 可将请求通过网页归因路径进行路由。

GET https://s2s.singular.net/api/v1/evt

SDID 的生成与持久化

Singular 设备 ID（ sdid ）将来自同一浏览器的所有事件关联到 单个网页设备。在首次加载页面时，如果 localStorage 中不存在 global_singular_id ，则生成一个 UUID v4 并将其存储。在该浏览器发送的每个事件上重复使用相同的值 作为 sdid ，直到 localStorage 被清除。

function getOrCreateSDID() {
  var KEY = 'global_singular_id';
  var sdid = localStorage.getItem(KEY);
  if (!sdid) {
    sdid = crypto.randomUUID(); // UUID v4
    localStorage.setItem(KEY, sdid);
  }
  return sdid;
}

__PAGE_VISIT__ 模式

任何新访问的第一个事件必须是 __PAGE_VISIT__ ，且带有 conversion_event=true 。这将建立后续事件所继承的归因基线。

非转化事件（例如 sng_registration_complete 或 sng_purchase ）使用 conversion_event=false ，并 省略 attribution_data 。它们从最近的 __PAGE_VISIT__ 继承归因。

custom_user_id 规则

• 在注册或登录后，以及在所有后续事件上，都包含 custom_user_id 。
• 将其持久化到 localStorage 或第一方 cookie 中。
• 在注销时删除它。
• 切勿包含 PII。请使用哈希后的或内部的 ID。

参数

Web SDK 在 __PAGE_VISIT__ 上会发送大约 40 个参数，但其中大多数 是 SDK 内部遥测数据，S2S 开发者不应复制这些数据。下面的表格仅涵盖必需和推荐的参数集。

必需参数

推荐参数

对于上面未列出的设备身份和其他共享参数，请参阅 S2S 基础中的通用参数 ，而不要在此重复记录它们。

attribution_data

attribution_data 参数以 URL 编码的 JSON 形式携带来自广告网络的 点击后（click-through）数据。仅在 __PAGE_VISIT__ 转化事件上 发送它。

{
  "partner_name": "Snapchat",
  "is_attributed": "true",
  "touch_timestamp": "",
  "partner_campaign_id": "",
  "partner_campaign_name": "Snap_campaign_1234",
  "partner_creative_id": "",
  "partner_creative_name": "",
  "partner_keyword": "",
  "partner_site": "",
  "partner_site_id": "",
  "partner_site_name": "",
  "partner_sub_site": "",
  "partner_sub_site_name": "",
  "partner_subcampaign_id": "",
  "partner_subcampaign_name": "",
  "_p": ""
}

必需字段

可选字段

e 参数中的网页点击 ID

使用每个合作伙伴所期望的 JSON 键，在事件的 e 负载中传递网络点击 ID：

网页到应用归因

要将网页广告系列上下文带入移动端点击，请从您的落地页构建一个 Singular Link， 并附加已捕获的落地查询字符串。这会将营销参数转发到移动端点击， 以便可以对应用安装进行归因。

在落地时，当 window.location.search （及片段）包含营销参数时， 捕获它并持久化。在渲染应用商店或智能横幅链接时，构建：

function buildWebToAppLink(baseLink, webUrl, deeplink, passthrough, deferredDeeplink) {
  var url = new URL(baseLink); // preserves existing base-link params
  if (webUrl) {
    var q = new URL(webUrl);
    var captured = q.search.slice(1) + (q.hash || ''); // landing query string (+fragment)
    url.searchParams.set('_web_params', captured); // URL-encoded on serialization
  }
  if (deeplink)         url.searchParams.set('_dl', deeplink);
  if (passthrough)      url.searchParams.set('_p', passthrough);
  if (deferredDeeplink) url.searchParams.set('_ddl', deferredDeeplink);
  return url.toString();
}

剪贴板归因（延迟深度链接）

剪贴板归因为延迟深度链接提供确定性匹配。网页代码片段 将一个唯一令牌写入剪贴板；刚安装的应用将其读回，并基于令牌 相等性进行匹配。

function openAppWithClipboardDdl(baseLink, deeplink, passthrough, deferredDeeplink) {
  // 1. Build the web-to-app link (see Web-to-App Attribution).
  var link = buildWebToAppLink(baseLink, capturedWebUrl, deeplink, passthrough, deferredDeeplink);

  // 2. Generate a UUID v4 and form the token.
  var uuid = crypto.randomUUID();
  var tokenUrl = location.protocol + '//' + location.hostname + '/__singular_ddl__/' + uuid;

  // 3. Write ONLY the token to the clipboard (execCommand fallback).
  copyToClipboard(tokenUrl);

  // 4. Append the token to the click as ecid.
  var url = new URL(link);
  url.searchParams.set('ecid', tokenUrl);

  // 5. Open the app / store.
  window.open(url.toString());
}

function copyToClipboard(text) {
  if (navigator.clipboard && navigator.clipboard.writeText) {
    navigator.clipboard.writeText(text);
    return;
  }
  var ta = document.createElement('textarea');
  ta.value = text;
  document.body.appendChild(ta);
  ta.select();
  document.execCommand('copy');
  document.body.removeChild(ta);
}

事件序列示例

首次访问和注册

1. 用户从 Google Ads 到达。发送初始的页面访问：

   • n=__PAGE_VISIT__
   • conversion_event=true
   • sdid=3730aecb-47ba-4d13-bd17-52b4b700956f
   • attribution_data={ "partner_name": "googleadwords_int", "is_attributed": "true", "partner_campaign_name": "brand_us_en" }

2. 用户注册。发送注册事件：

   • n=sng_registration_complete
   • conversion_event=false
   • sdid=3730aecb-47ba-4d13-bd17-52b4b700956f （相同的 SDID）
   • custom_user_id=user_12345abc
   • 无 attribution_data

从新广告系列返回的用户

1. 同一浏览器从一个不同的广告系列返回。发送一个新的页面访问：

   • n=__PAGE_VISIT__
   • conversion_event=true
   • sdid=3730aecb-47ba-4d13-bd17-52b4b700956f （相同的 SDID）
   • attribution_data={ "partner_name": "facebook", "is_attributed": "true", "partner_campaign_name": "retargeting_Q1" }

2. 用户购买。发送购买事件：

   • n=sng_purchase
   • conversion_event=false
   • sdid=3730aecb-47ba-4d13-bd17-52b4b700956f （相同的 SDID）
   • 持久化的 custom_user_id
   • 无 attribution_data