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

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

前提条件

在集成 Singular 网站 SDK 之前，请确保满足以下前提条件：

• 已在网站上配置Google Tag Manager。
• 您已根据需要为要发送到 Singular 的事件（转换事件和任何自定义事件）设置了Google Tag Manager 触发器。
• 您已根据需要为要发送到 Singular 的事件设置了Google Tag Manager 变量。例如，如果要发送交易事件并包含交易收入，就需要为交易金额和货币设置变量。

标签 1 - 添加 SDK 库

在初始化 Singular SDK 或触发任何 Singular 函数之前，必须在网站上加载或注入 Singular JavaScript 库。为确保这一点，将使用 Google 标签管理器（GTM）中的自定义 HTML 标签选项注入该库。

为保持正常功能，网站的所有页面都必须包含该库。我们将使用 GTM 中的 "窗口已加载 "触发器来控制库注入的时间，确保库在页面内容完全加载后加载。

• 创建一个自定义 HTML 标签来加载 SDK 库，并添加获取客户端提示数据的权限。
• 将标记命名为 "Singular - SDK Loader
• 在 HTML 窗口中插入以下代码

  <script>
  (function() {
    // Check if singularSdk is already loaded
  
  
    if (window.singularSdk) {
      return; // SDK already loaded, no need to load again
  
  
    }
  
    // Inject the meta tag for client hints delegation
  
  
    var metaTag = document.createElement('meta');
    metaTag.setAttribute('http-equiv', 'delegate-ch');
    metaTag.setAttribute('content', 'sec-ch-ua-model https://sdk-api-v1.singular.net; sec-ch-ua-platform-version https://sdk-api-v1.singular.net; sec-ch-ua-full-version-list https://sdk-api-v1.singular.net');
    document.head.appendChild(metaTag);
    
    // Create and load the Singular SDK script
  
  
    var script = document.createElement('script');
    script.src = 'https://web-sdk-cdn.singular.net/singular-sdk/latest/singular-sdk.js';
    script.async = true;
  
    // Once the script is loaded, push to dataLayer
  
  
    script.addEventListener('load', function() {
      window.dataLayer = window.dataLayer || [];  // Ensure dataLayer is initialized
  
  
      window.dataLayer.push({
        event: 'singularSDKLibraryLoaded'
      });
    });
  
    // Append the script tag to the head of the document
  
  
    document.head.appendChild(script);
  })();
  </script>
  

• 在 "高级设置 "下，将标签启动优先级设为99
• 在 "触发 "部分，为"窗口已加载"添加触发器
• 保存标签

标签 2 - SDK 初始化标签

Singular SDK 初始化代码必须在每次加载页面时执行，但只能在 Singular - SDK Loader 标签触发后执行。为确保这一点，我们将使用 Singular - SDK Loader 标签创建的数据层事件作为触发器。

初始化 Singular SDK 是所有 Singular 归属功能的先决条件。它有两个关键目的：

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

这些 "页面访问 "事件和用户会话对于计算用户保留率和实现再参与归因至关重要。

// Configure the SDK to pass the user ID to Singular


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

将用户 ID 发送至 Singular（可选）

您可以使用 Singular SDK 方法向 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() 方法。

如果在网站上初始化 Singular SDK 时已经知道用户 ID，则在配置对象中设置用户 ID。这样，Singular 就能从第一次会话中获得用户 ID。不过，在用户注册或登录之前，用户 ID 通常是不可用的。在这种情况下，请在注册流程完成后调用login() 。建议在用户执行身份验证流程时推送一个数据层事件，该事件可与 GTM 自定义事件触发器一起使用，以触发 Singular 登录功能。

• 创建自定义 HTML 标签来处理身份验证
• 将标签命名为 "Singular - 身份验证标签
• 在 HTML 窗口中插入以下代码

  <script>
  (function() {
    // Ensure sessionStorage is available
  
  
    if (typeof sessionStorage === 'undefined') {
      console.warn('sessionStorage is not supported in this environment.');
      return;
    }
  
    // Check if the event has already been triggered in this session
  
  
    if (sessionStorage.getItem('sng_login_triggered')) {
      console.log('Singular SDK event already triggered this session.');
      return; // Exit if the event was triggered before in this session
  
  
    }
  
    // Check if singularSdk is available and initialized
  
  
    if (window.singularSdk && typeof singularSdk.login === 'function' && typeof singularSdk.event === 'function') {
      
      // Dynamically fetch UserID if available (replace with actual method if applicable)
  
  
      var userID = window.userID || "User123456789"; // Example fallback value for userID
  
  
  
      try {
        // After Authentication, Pass the UserID as the Singular Custom User ID Value
  
  
        singularSdk.login(userID);
  
        // Send the Registration_Completed event (or similar event)
  
  
        singularSdk.event("sng_login");
  
        // Set a flag in sessionStorage to indicate that the event was triggered
  
  
        sessionStorage.setItem('sng_login_triggered', 'true');
  
        console.log('Singular SDK event triggered successfully.');
      } catch (error) {
        console.error('Error triggering Singular SDK event:', error);
      }
    } else {
      console.warn('Singular SDK is not loaded or required methods are unavailable.');
    }
  })();
  </script>
  

• 在 "触发 "部分，为自定义事件添加一个触发器。
• 将触发器命名为"奇异身份验证
• 指定触发器事件名称，与用户在网站上进行身份验证后可用的数据层事件名称相对应。
• 保存标签