Singular 网站追踪 SDK 集成：通过页面原生代码集成

关注
Avatar
Jared Ornstead
Updated

 

Singular 网站追踪 SDK 是一项企业级功能。如果您有兴趣使用该功能，请联系您的客户成功经理。

通过 Singular 网站追踪 SDK，您可以将网站内的活动归因于营销接触点，并跟踪网站内的用户事件。它也是Singular跨设备归因解决方案的关键组件，使得分析用户访问旅程和计算跨平台LTV和ROAS成为可能。

要了解更多信息，请参阅我们的跨设备归因常见问题解答和网站归因常见问题解答。

除了这里介绍的本地 JavaScript 版本外，Singular 网站追踪 SDK 还提供 Google Tag Manager 模板。

浏览器兼容性：

Chrome 浏览器： 15+ Edge浏览器：15 以上 Internet Explorer10+
Safari5.1+ 火狐浏览器6+ Opera: 15+

在网站上添加 SDK 脚本

使用以下方法之一在网站或网络应用程序中添加 Singular 网站追踪 SDK。

链接到 Singular CDN 上的脚本

在这种方法中，Singular 将 SDK JavaScript 代码托管在 Singular 的 CDN 上。

在每个要跟踪的页面的 <head> 标签中添加以下代码：

<head>
      <!-- 使用最新版本的 SDK   -->
      <script src="https://web-sdk-cdn.singular.net/singular-sdk/latest/singular-sdk.js">
      </script>
</head>

注：上述代码链接到最新版本的 SDK。如果你想使用特定版本的 SDK，请参照使用以下示例代码：

<head>
      <!-- 使用固定的 SDK 版本   -->
      <script src="https://web-sdk-cdn.singular.net/singular-sdk/1.4.2/singular-sdk.js">
      </script>
</head>

使用 NPM 进行设置

  1. 在项目根目录下运行 npm i singular-sdk，或添加 "singular-sdk"："^1 . 3.5" ，然后运行 npm install 命令。
  2. 在要使用 SDK 的脚本中添加以下代码。
import {singularSdk, SingularConfig} from "singular-sdk";

初始化 SDK

每次加载页面时都应调用 SDK 初始化代码。 它是所有 Singular 归因功能可以工作的先决条件，同时它也会：

  • 当用户使用新的广告数据进入网站或会话超时后，创建新的用户会话。
  • 向 Singular 发送新的 "页面访问 page visit"事件

page visit 事件和用户会话用于计算用户留存率，并实现召回安装的归因。

1.构建 SingularConfig 对象

在初始化 SDK 之前，必须创建一个 SingularConfig 对象。该对象将包含

  • SDK Key 和 SDK Secret：要找到这些密钥，请登录您的 Singular 账户，进入 "开发人员工具 > SDK 集成 > SDK 密钥"。
  • 您的产品 ID：您网站的名称。我们建议使用您网站主域名的反向 DNS 符号，例如 "com.example"。这将用于在整个 Singular 平台上识别您的网站。该值还必须与 Singular 后台应用程序设置页面上的应用程序 bundleID 相匹配。
  • 还可以选择设置任何 SDK 偏好设置（详情请继续阅读）。

要创建基本的 SingularConfig 对象，请使用此代码：

const config = new SingularConfig(sdkKey, sdkSecret, productId);

不过，你可能还想添加设置，以启用 Singular 提供的各种功能。

要添加设置，需要使用 SingularConfig 对象的".with "方法。例如

  // 配置 SDK 将用户 ID 传递给 Singular
  const config = new SingularConfig(sdkKey, sdkSecret, productId)
      .withCustomUserId(userId);

SingularConfig 方法参考

以下是所有可用的".with "方法。

方法 方法描述 了解更多
.withCustomUserId(customId) 向 Singular 发送用户 ID 设置用户 ID
.withProductName(productName) 产品的可选显示名称  
.withLogLevel(logLevel) 配置日志级别：0 - 无（默认）；1 - 警告；2 - 信息；3 - 调试。  
.withSessionTimeoutInMinutes(timeout） 以分钟为单位设置会话超时时长（默认：30 分钟）

 
.withAutoPersistentSingularDeviceId（domain） 启用自动跨子域跟踪 使用 Cookie 自动持续

.withPersistentSingularDeviceId（singularDeviceId）

 启用手动跨子域跟踪 手动设置Singular 设备 ID
.withInitFinishedCallback(callback) 设置用于 SDK 初始化完成后调用回调函数 初始化完成时调用回调函数

2.初始化 Singular SDK

创建 SingularConfig 配置对象后，使用 init 方法初始化 Singular，并传递配置对象。

init 方法可以在代码中的任何位置调用，但必须在上报任何事件之前调用。我们建议在加载要跟踪的每个页面时调用 init方法。

init方法
说明 使用 SingularConfig 对象中设置的配置选项初始化 SDK。
签名 init(config)
使用示例 
  function initSingular() {
      const config = new SingularConfig(sdkKey, 
        sdkSecret, productId);
      singularSdk.init(config);
  }

重要：对于单页面应用程序（SPAs），每次路由到不同页面时都要调用 singularSdk.pageVisit()。不要在加载的第一个页面上调用 singularSdk.pageVisit()，因为 singularSdk.init 已经上报了页面访问事件page visit。

初始化完成后调用回调函数

要设置初始化完成后调用的回调函数，请在 SingularConfig 对象上使用 .withInitFinishedCallback(callback)方法。

withInitFinishedCallback 方法
说明 设置初始化过程结束后调用的回调函数。
特征 withInitFinishedCallback(callback)
使用示例 
  function initSingular() {      
    const config = new SingularConfig(sdkKey, sdkSecret, productId)
      .withInitFinishedCallback(initParams=> {
        // init 方法结束后，将调用该回调
  
        // 您可以从这里获取 "Singular Device ID (SDID)"。
        const singularDeviceId = initParams.singularDeviceId;
      });
  singularSdk.init(config);
  }

向 Singular 发送用户 ID（可选）

您可以使用 Singular SDK 方法向 Singular 发送内部用户 ID。

注：如果使用 Singular 的跨设备解决方案，则必须在所有平台上收集用户 ID。

  • 用户 ID 可以是任何标识符，但不能暴露 PII（个人身份信息），例如，不能使用用户的电子邮件地址、用户名或电话号码。Singular 建议使用仅对您的第一方数据具有唯一性的哈希值。
  • 传递给Singular的用户ID值也应该是在您的所有平台（Web/移动/PC/控制台/离线）上获取的相同的内部用户ID。
  • Singular 将在用户级数据导出、ETL 和内部 BI 回传（如果配置）中包含用户 ID。用户 ID 是第一方数据，Singular 不会与其他方共享。
  • 使用Singular SDK方法设置的用户ID值将一直存在，直到使用 logout() 方法取消设置或删除浏览器本地存储。关闭或刷新网站不会取消设置用户 ID。
  • 在私人/隐身模式下，SDK 无法保持所设置的用户 ID，因为浏览器会在关闭时自动删除本地存储。

要设置用户 ID，请使用 login() 方法。要取消设置（例如，如果用户 "登出"账户），请调用 logout() 方法。

注意：如果多个用户使用一台设备，我们建议实施登出流程，为每次登录和登出，设置和取消设置用户 ID。

如果在网站上初始化 Singular SDK 时已经知道用户 ID，则在配置对象中设置用户 ID。这样，Singular 就能从第一次会话中获得用户 ID。不过，在用户注册或登录之前，用户 ID 通常是不可用的。在这种情况下，请在注册流程完成后调用 login() 。

SingularSDK login() 方法
说明 向 Singular 发送用户 ID。
签名 login(customUserId)
使用示例 
singularSdk.login("custom_user_id");
SingularSDK logout() 方法
说明 取消已发送至 Singular 的用户 ID。
签名 logout()
使用示例 
singularSdk.logout();

可选：自定义用户 ID 设备映射

重要：此高级企业功能仅在特殊情况下可用。实施前请咨询 Singular 解决方案工程师。

Singular 可以通过服务器到服务器集成接收额外的移动事件跟踪数据。要使用此功能，必须将用户 ID 映射到 Singular 的移动设备跟踪标识符。

注意：在初始化 Singular SDK 后或获得用户 ID 后，请尽快调用此方法。

SingularSDK setDeviceCustomUserId 方法
说明 设置与登录时使用的相同的自定义用户 ID，并将其映射到 Singular 的跟踪标识符。
签名 singularSdk.setDeviceCustomUserId(userId)
使用示例 
singularSdk.setDeviceCustomUserId("customUserId");

可选：跟踪事件和收入

跟踪事件（非收入）

Singular 可以收集网站内用户事件的相关数据，以帮助分析营销活动的效果并衡量关键绩效指标。例如，您可能希望收集有关用户登录、注册或教程完成情况等相关数据。

您可以使用event方法向 Singular 发送事件。

注意

  • 我们强烈建议以英文传递事件名称和属性，以保证与第三方合作伙伴和分析解决方案（如果您计划使用它们）的兼容性。
  • 事件名称限制为 32 个 ASCII 字符。转换为 UTF-8 后，非 ASCII 字符的字符串必须小于 32 字节。
  • 属性和值总长度限制为 500 个 ASCII 字符。
event 方法
描述 向 Singular 报告用户事件，可携带或不携带附加信息。
签名

singularSdk.event(eventName, args)

注意： "args "是一个包含键值对的 JavaScript 对象。如果不想传递任何附加参数，请仅使用事件名称调用 event 方法。
使用示例 
  // 发送不带参数的Registration_Completed事件
  singularSdk.event("Registration_Completed");

  // 发送名为Registration_Completed的事件，并携带事件属性
  singularSdk.event("Registration_Completed",
                    {key1: 'value1',
                     key2: 'value2'});

跟踪收入

Singular 可以收集通过网站获得的收入数据，以帮助分析营销活动的绩效和投资回报率。Singular 会在报告、日志导出和回传中提供这些数据。

使用 "revenue"方法报告事件，"revenue"允许你传递自定义事件名称，这样你就能在Singular报告中按不同类型的收入事件查看收入统计数据。

注意 任何以不同货币报告的收入都将自动转换为贵组织首选的货币币种，具体币种在您的 Singular 账户中设置。

revenue 方法
说明 向 Singular 发送带有可选附加信息的收入事件。
签名

singularSdk.revenue(eventName, currency, amount, args)

注意：

  • 货币以符合 ISO 4217 标准的三个字母货币代码形式传递，如 "USD"、"EUR "或 "INR"。
  • 金额值可以传递为十进制值。
使用示例 
  // 向 Singular 发送收入事件 
  singularSdk.revenue("Item_Purchased","USD", 5.50);

  // 向 Singular 发送带有附加参数的收入事件
  singularSdk.revenue("Item_Purchased","USD", 5.50,
                      {key1: 'value1',
                       key2: 'value2');

可选：跨子域跟踪

默认情况下，Singular 网站 SDK 会生成一个 Singular 设备 ID，并使用浏览器存储将其持久化。由于该存储无法在子域之间共享，SDK 最终会为每个子域生成一个新 ID。

如果要跨子域持久化 Singular 设备 ID，可以采用以下任意可选方案：

方法 A：使用 Cookie 自动持久化

你可以让 Singular SDK 使用自定义的第一方 cookie 来持久化 Singular 设备 ID。使用以下方法并设置要跟踪的主域。

withAutoPersistentSingularDeviceId 方法
说明 使用配置选项初始化 SDK，包括自动持久化 Singular 设备 ID 的主域。
签名 withAutoPersistentSingularDeviceId(domain)
使用示例 
  function initSingular() {
    const config = new SingularConfig(sdkKey, sdkSecret, productId)
      .withAutoPersistentSingularDeviceId(“example.com”);
    singularSdk.init(config);
  }

方法 B（高级）：手动设置Singular设备 ID

如果不想让 Singular SDK 自动持久化设备 ID，可以跨域手动持久化 ID，例如使用顶级域 cookie 或服务器端 cookie。该值应该是Singular之前生成的 ID，格式为有效的 uuid4。

注：调用 init 方法或设置 InitFinishedCallback 回调方法后，可以使用 singularSdk.getSingularDeviceId() 读取 Singular 设备 ID。

withPersistentSingularDeviceId 方法

说明

使用配置选项（包括要持久化的Singular设备 ID）初始化 SDK。
签名 withPersistentSingularDeviceId(singularDeviceId)
使用示例 
  function initSingular() {
    const config = new SingularConfig(sdkKey, sdkSecret, productId)
      .withPersistentSingularDeviceId(singularDeviceId);
    singularSdk.init(config);
  }

可选：获取 Match ID

重要： 这是一项高级功能。实施前请咨询 Singular 的解决方案工程师。

Singular 可以根据每个用户确定的唯一 Match ID，对来自 PC 和游戏平台的服务器端安装进行归因。要使用此功能，请在初始化后从 Singular 的 Web SDK 获取 Match ID。

getMatchID 方法
说明 获取此网络会话的唯一 Match ID
签名 singularSdk.getMatchID()
使用示例 
  // 获取用户 Match ID，以便将其纳入其他平台的首次会话
  singularSdk.getMatchID()