文档

验证设备归因

使用 Singular 设备辅助应用程序和归因详情 API 端点验证设备归因的综合指南，用于集成测试和跟踪链接验证。

Singular 提供两种检查设备归因的方法：设备辅助应用程序用于移动测试，归因详情 API 端点用于程序化验证。

验证归属是测试新的 SDK/S2S 集成和在活动部署前验证 Singular 链接的重要组成部分。

目标受众	UA 经理、开发人员、QA 工程师
前提条件	用于测试的移动设备（设备辅助应用程序方法） Singular API 密钥（API 端点方法）设备广告标识符（IDFA、IDFV、GAID 等）

归因验证使用案例

何时验证归因

设备归因验证在集成和活动部署生命周期的多个阶段都至关重要。

使用案例	目的
SDK/S2S 集成测试	在集成开发过程中验证 SDK 是否正确跟踪安装并归因于正确的来源。完整的测试控制台指南
跟踪链接验证	在活动部署前测试新的奇异链接，以确保正确的归属和参数传递。如何测试跟踪链接
营销活动故障排除	通过检查测试设备归因状态诊断实时营销活动中的归因问题
合作伙伴集成验证	确认归因数据从广告合作伙伴正确流向 Singular 平台

方法比较

选择验证方法

根据测试要求和技术能力选择合适的验证方法。

验证方法	最适合	要求	局限性
设备辅助应用程序	快速人工测试非技术用户视觉验证	移动设备应用程序安装	手动流程，自动化程度有限
归属详情 API	自动测试程序化验证 CI/CD 集成	API 密钥设备标识符 HTTP 客户端	仅用于测试（测试版），需要技术知识

方法 1：设备辅助应用程序

移动应用程序可直接在测试设备上快速直观地验证设备归属状态、安装详情和事件跟踪摘要。

设备辅助应用程序概述

应用程序功能

设备辅助应用程序显示 Singular 中记录的特定设备的全面归因信息。

显示的归因数据：

安装归因：安装时间戳、归因网络和营销活动名称
再参与归因：再参与时间戳、归因网络和营销活动详情
事件摘要：Singular 为设备追踪的会话和应用内事件
设备标识符：IDFA、IDFV、GAID 或其他用于跟踪的标识符

使用设备辅助应用程序

步骤

1	下载设备辅助应用程序在测试设备上安装 Singular Device Assist 应用程序： iOS：从 App Store 下载安卓：从 Google Play 下载
2	启动归因检查打开设备辅助应用程序，从主菜单中选择 "检查实施"。附加功能：设备辅助应用程序还提供设备标识符查询和 SDK 实施验证工具，可从主菜单访问。
3	选择设备标识符应用程序会自动为平台选择合适的设备标识符。确认选择后再次点击 "检查实施"继续。标识符选择： iOS：IDFA（如果 ATT 已授权）或 IDFV（如果 ATT 未授权或未实施安卓：GAID（谷歌广告 ID），如果没有 GAID，则使用其他标识符
4	查看归因详细信息应用程序显示 Singular 平台记录的设备的完整归因信息。显示的归因信息安装归因详细信息 # 安装时间戳：首次启动应用程序的日期和时间（安装事件归因网络：广告网络或安装来源（如 Facebook、Google Ads、Organic 营销活动名称：归因于安装的营销活动附加参数：通过跟踪链接传递的营销活动特定参数解释安装归因 "有机"：在归因窗口内未发现匹配的接触点 - 安装未归因于付费营销活动 "未归因"：已跟踪设备，但归因决定尚未做出或未完成网络名称：安装成功归因于特定广告合作伙伴重新参与归因详情 # 重新参与时间戳：最近一次重新参与会话的日期和时间归属网络：将用户带回应用程序的来源活动名称：归因于会话的再吸引活动自归因网络：出于隐私原因，来自自归因网络（Twitter、Facebook、Google Ads、Snapchat 等）的再吸引归因可能显示为 "未归因"。再吸引归因要求重新吸引归因用户必须已安装（非新设备再参与活动点击必须发生在配置的归因窗口内会话必须发生在重新吸引点击之后了解更多信息：重新吸引归因常见问题事件跟踪摘要 # 设备辅助应用程序显示 Singular 为设备跟踪的所有应用程序内事件的摘要。显示事件信息：事件名称：跟踪事件的名称（会话、购买、等级完成等首次事件时间：首次发生的时间戳最后事件时间：最近发生事件的时间戳事件计数：事件发生的总次数收入：收入事件的总收入验证事件跟踪使用事件摘要进行验证：会话跟踪正确自定义事件以正确的名称出现收入事件正确捕获金额事件时间戳与实际用户操作相匹配

设备辅助故障排除

常见问题

未显示归因数据

可能的原因

应用程序未安装：测试应用程序未安装或尚未在设备上打开
标识符错误：设备辅助检查标识符未被应用程序 SDK 使用
SDK 未初始化：应用程序中未正确初始化 Singular SDK
归属待定：归属决定尚未最终确定（通常需要 1-5 分钟

解决步骤

确认测试应用程序已安装并在设备上至少打开过一次
确认设备标识符与 SDK 中使用的标识符类型（iOS 的 IDFA 与 IDFV）相匹配
应用程序启动后等待 5-10 分钟，再次检查属性
使用测试控制台验证 SDK 集成

归属于错误来源

可能原因

以前的设备使用情况：之前用于测试并缓存归因的设备
多个接触点：归因窗口内的多次活动点击
指纹匹配：概率归因匹配错误点击

解决步骤

重置设备并清除属性：
- 删除测试应用程序
- 重置广告标识符
- 如果已注册，从测试控制台删除设备
测试前使用新设备或重置标识符
使用确定性归因（跟踪链接中的设备 ID）代替指纹进行测试
查看合作伙伴配置中的归因窗口设置

将归因安装为 "有机 "而非 "营销活动

可能原因

归因窗口超出：安装发生在配置的归因窗口之外
无匹配接触点：未找到与设备匹配的点击
指纹不匹配：设备指纹在点击和安装之间发生变化
未点击链接：应用程序直接从商店安装，未点击跟踪链接

解决步骤

在安装应用程序前确认已点击跟踪链接
检查归因窗口设置，为安装留出足够时间
在跟踪链接中使用设备 ID（确定归因）进行可靠测试
确保点击和安装过程中网络连接稳定
在不同设备上测试或重置标识符并重试

方法 2：归因详情 API

程序化 API 端点支持集成测试和 CI/CD 管道的自动归因验证。

测试版功能通知：归属详情 API 端点是测试版功能。仅用于测试目的，请勿在生产应用程序或大容量环境中调用。

API 端点规范

请求格式

端点 URL：

https://api.singular.net/api/attribution/attribution_details

请求方法：GET

完整请求示例：

https://api.singular.net/api/attribution/attribution_details?keyspace=idfa&device_id=12345678-1234-1234-1234-123456789012&api_key=your_api_key_here

查询参数

必填参数

参数类型说明

api_key

字符串

来自平台的奇异报告 API 密钥。

位置：控制面板 → 开发人员工具 → API 密钥 → 报告 API 密钥

重要：使用报告 API 密钥，而不是 SDK 密钥。不同的密钥有不同的用途。

device_id

字符串

设备的广告标识符值。

必须与keyspace参数中指定的标识符类型相匹配。

keyspace

字符串（枚举）

device_id 中提供的广告标识符类型：

idfa - 广告商的 iOS 标识符（需要 ATT 授权
idfv - iOS 供应商标识符（IDFA 不可用时的替代标识符
aifa - 安卓广告标识符（也称为 GAID
sdid - 用于网络跟踪的奇异设备 ID（在 SDK 初始化后使用 singularSdk.getSingularDeviceId() 获取

API 响应

响应格式

API 返回 JSON 数组，其中包含请求设备的属性详细信息。

响应示例

[
  {
    "app_long_name": "com.example.myapp",
    "app_name": "My App",

    "install_info": {
      "install_time": "2020-06-10 11:58:46",
      "network": "Network 1",
      "additional_parameters": {
        "kw": "my keyword",
        "pcid": "1234"
      },
      "campaign_name": "Campaign Name",
      "view_through_attribution": false
    },

    "re_engagement_info": {
      "notes": "Attributions from Self-Attributing networks including: Twitter, Facebook, Google Ads, Snapchat, etc are redacted and always show as 'Unattributed'",
      "install_time": "2020-06-15 15:27:12",
      "network": "Unattributed"
    },

    "uninstall_pre_requisites": {
      "gcm_token": "enE8iQR10RI:APA91bERgfA_xm8T7zgqH9OW_1s05SFFmKnle1zIm0cMrDfuaSxEmC_3j72dj4qN36vh5V8TAEnrXa3Pq3SmLW-XNOHP7daMwcBrBTibdkv_pKMJbN9SbefV6_9nuEfIeI5Zhtz0nlLY"
    },

    "events": [
      {
        "event_name": "Session",
        "first_event_time": "2020-04-02 00:09:55",
        "last_event_time": "2020-04-07 20:59:55",
        "event_count": 2
      },
      {
        "event_name": "Save New Transaction",
        "first_event_time": "2020-04-02 00:11:51",
        "last_event_time": "2020-04-02 00:11:51",
        "event_count": 1
      }
    ]
  }
]

响应参数

JSON 响应字段

字段	字段
`app_long_name`	应用程序捆绑标识符（如 com.example.myapp）
`app_name`	在 Singular 平台中配置的应用程序显示名称
`install_info`	包含安装属性详细信息和决策信息的对象： `install_time` - 首次应用会话（安装）的时间戳 `network` - 归因于安装的广告网络 `campaign_name` - 归因于安装的广告系列名称 `view_through_attribution` - 基于广告印象（true）与广告点击（false）的归因布尔值。了解更多信息：Singular 的安装归因流程 `additional_parameters` - 通过跟踪链接传递的自定义参数。详情：跟踪链接参数和报告维度
`re_engagement_info`	结构与`install_info`相同的对象，但用于再接触归因。了解更多信息：再吸引归因常见问题隐私注意事项：来自自我归因网络（Facebook、Google Ads、Twitter、Snapchat）的再吸引归因显示为 "未归因"，以符合隐私规定。
`events`	包含 SDK 跟踪的应用内事件摘要的对象数组： `event_name` - 跟踪事件名称 `first_event_time` - 首次出现的时间戳 `last_event_time` - 最近发生事件的时间戳 `event_count` - 事件发生总数 `revenue` - 收入事件的总收入（如适用
`uninstall_pre_requisites`	包含卸载跟踪配置的对象： `apns` (iOS)-苹果推送通知服务令牌。配置：iOS 卸载跟踪 `gcm_token` (Android) - Firebase 云消息令牌。配置：Android 卸载跟踪

API 使用示例

实施示例

iOS 设备 (IDFA)

curl -X GET "https://api.singular.net/api/attribution/attribution_details?keyspace=idfa&device_id=12345678-1234-1234-1234-123456789012&api_key=your_api_key_here"

安卓设备 (GAID)

curl -X GET "https://api.singular.net/api/attribution/attribution_details?keyspace=aifa&device_id=12345678-1234-1234-1234-123456789012&api_key=your_api_key_here"

网络跟踪 (SDID)

curl -X GET "https://api.singular.net/api/attribution/attribution_details?keyspace=sdid&device_id=singular_device_id_value&api_key=your_api_key_here"

Python 实现

import requests
import json

def check_attribution(keyspace, device_id, api_key):
    """
    Check device attribution using Singular API
    
    Args:
        keyspace: Device identifier type (idfa, idfv, aifa, sdid)
        device_id: Device identifier value
        api_key: Singular Reporting API key
    
    Returns:
        Attribution data as JSON or None if error
    """
    url = "https://api.singular.net/api/attribution/attribution_details"
    
    params = {
        'keyspace': keyspace,
        'device_id': device_id,
        'api_key': api_key
    }
    
    try:
        response = requests.get(url, params=params)
        response.raise_for_status()
        return response.json()
    except requests.exceptions.RequestException as e:
        print(f"Error checking attribution: {e}")
        return None

# Example usage
attribution_data = check_attribution(
    keyspace='idfa',
    device_id='12345678-1234-1234-1234-123456789012',
    api_key='your_api_key_here'
)

if attribution_data:
    print(json.dumps(attribution_data, indent=2))
    
    # Extract install info
    if attribution_data and len(attribution_data)  0:
        install_info = attribution_data[0].get('install_info', {})
        print(f"\nInstall Network: {install_info.get('network')}")
        print(f"Campaign: {install_info.get('campaign_name')}")
        print(f"Install Time: {install_info.get('install_time')}")

JavaScript 实现

/**
 * Check device attribution using Singular API
 * 
 * @param {string} keyspace - Device identifier type (idfa, idfv, aifa, sdid)
 * @param {string} deviceId - Device identifier value
 * @param {string} apiKey - Singular Reporting API key
 * @returns {Promise} Attribution data or error
 */
async function checkAttribution(keyspace, deviceId, apiKey) {
    const url = 'https://api.singular.net/api/attribution/attribution_details';
    
    const params = new URLSearchParams({
        keyspace: keyspace,
        device_id: deviceId,
        api_key: apiKey
    });
    
    try {
        const response = await fetch(`${url}?${params.toString()}`);
        
        if (!response.ok) {
            throw new Error(`HTTP error! status: ${response.status}`);
        }
        
        return await response.json();
    } catch (error) {
        console.error('Error checking attribution:', error);
        throw error;
    }
}

// Example usage
checkAttribution(
    'idfa',
    '12345678-1234-1234-1234-123456789012',
    'your_api_key_here'
)
.then(data = {
    console.log('Attribution Data:', JSON.stringify(data, null, 2));
    
    // Extract install info
    if (data && data.length  0) {
        const installInfo = data[0].install_info || {};
        console.log('\nInstall Network:', installInfo.network);
        console.log('Campaign:', installInfo.campaign_name);
        console.log('Install Time:', installInfo.install_time);
    }
})
.catch(error = {
    console.error('Failed to check attribution:', error);
});

API 故障排除

常见 API 问题

空数组响应

问题

API 返回空数组[] ，而不是属性数据。

可能的原因

无属性数据：设备从未安装应用程序或未跟踪会话
标识符错误：设备 ID 或键空间不正确
时间问题：归因数据尚未处理（通常为安装后 1-5 分钟

解决步骤

验证设备 ID 复制正确，无多余空格
确认密钥空间与标识符类型（iOS 的 idfa 与 idfv）相匹配
安装应用程序后等待 5-10 分钟，然后重试查询
使用 "设备辅助 "应用程序检查设备属性，以验证应用程序是否已安装和跟踪

验证错误

问题

API 返回验证错误或 401 未授权响应。

可能的原因

API 密钥无效：API 密钥不正确或未提供
密钥类型错误：使用 SDK 密钥而非报告 API 密钥
密钥过期：API 密钥已撤销或重新生成

解决步骤

导航至控制面板 → 开发人员工具 → API 密钥 → 报告 API 密钥
复制报告 API 密钥（不是 SDK 密钥）
验证请求中粘贴的 API 密钥是否正确
如果密钥最近重新生成，确保使用新的密钥值

安全警告：切勿将 API 密钥提交到版本控制中或在客户端代码中公开。使用环境变量或安全配置管理。

速率限制错误

问题

API 返回 429 请求过多或速率限制错误。

可能原因

请求过多：短时间内调用 API 的次数过多
生产使用：在生产环境中使用 API（非预期用例

解决步骤

在代码中实施指数级延迟和重试逻辑
间隔 API 请求（建议调用间隔至少 1 秒钟
尽可能缓存属性数据，以减少 API 调用次数
如果合法测试需要更高的速率限制，请联系 Singular 支持部门

测试版限制：属性详情 API 仅用于测试。请勿在请求量较大的生产应用程序中使用。

最佳实践

在集成测试和营销活动验证期间进行有效归因验证的建议。

测试工作流程

建议的测试流程

使用新设备：使用干净的设备进行测试，或在测试前重置广告标识符，以避免缓存归因
立即验证：在安装后 5-10 分钟内检查属性，以便在测试期间快速反馈
测试多种情况：验证不同来源的归因（有机、付费营销活动、再接触
记录结果：记录归因验证结果，作为集成验证文档
尽可能实现自动化：在自动化测试套件中使用归因详情 API 进行持续验证

方法选择指南

何时使用每种方法

场景	推荐方法
快速手动测试	设备辅助应用程序 - 开发过程中最快的视觉验证
自动测试	归因细节 API - 在 CI/CD 流程中进行编程验证
非技术测试	设备辅助应用程序 - 无需编码或 API 知识
批量设备验证	归因详情 API - 多设备检查脚本
事件跟踪验证	两种方法 - 设备辅助工具用于快速检查，API 用于详细事件分析

集成验证核对表

归因验证核对表

完全归因验证：

安装归因于正确的网络/来源
活动名称与预期活动相符
归因时间戳合理（在预期时间范围内）
归因方法适当（点击与印象）
通过跟踪链接正确传递自定义参数
会话事件跟踪正确
自定义事件名称正确
收入事件捕获金额和货币
再参与归因有效（如适用）
已配置卸载跟踪（如果已实施）

其他资源

属性测试、SDK 集成和跟踪链接配置的完整文档。

1	下载设备辅助应用程序在测试设备上安装 Singular Device Assist 应用程序： iOS：从 App Store 下载安卓：从 Google Play 下载
2	启动归因检查打开设备辅助应用程序，从主菜单中选择 "检查实施"。附加功能：设备辅助应用程序还提供设备标识符查询和 SDK 实施验证工具，可从主菜单访问。
3	选择设备标识符应用程序会自动为平台选择合适的设备标识符。确认选择后再次点击 "检查实施"继续。标识符选择： iOS：IDFA（如果 ATT 已授权）或 IDFV（如果 ATT 未授权或未实施安卓：GAID（谷歌广告 ID），如果没有 GAID，则使用其他标识符
4	查看归因详细信息应用程序显示 Singular 平台记录的设备的完整归因信息。显示的归因信息安装归因详细信息 # 安装时间戳：首次启动应用程序的日期和时间（安装事件归因网络：广告网络或安装来源（如 Facebook、Google Ads、Organic 营销活动名称：归因于安装的营销活动附加参数：通过跟踪链接传递的营销活动特定参数解释安装归因 "有机"：在归因窗口内未发现匹配的接触点 - 安装未归因于付费营销活动 "未归因"：已跟踪设备，但归因决定尚未做出或未完成网络名称：安装成功归因于特定广告合作伙伴重新参与归因详情 # 重新参与时间戳：最近一次重新参与会话的日期和时间归属网络：将用户带回应用程序的来源活动名称：归因于会话的再吸引活动自归因网络：出于隐私原因，来自自归因网络（Twitter、Facebook、Google Ads、Snapchat 等）的再吸引归因可能显示为 "未归因"。再吸引归因要求重新吸引归因用户必须已安装（非新设备再参与活动点击必须发生在配置的归因窗口内会话必须发生在重新吸引点击之后了解更多信息：重新吸引归因常见问题事件跟踪摘要 # 设备辅助应用程序显示 Singular 为设备跟踪的所有应用程序内事件的摘要。显示事件信息：事件名称：跟踪事件的名称（会话、购买、等级完成等首次事件时间：首次发生的时间戳最后事件时间：最近发生事件的时间戳事件计数：事件发生的总次数收入：收入事件的总收入验证事件跟踪使用事件摘要进行验证：会话跟踪正确自定义事件以正确的名称出现收入事件正确捕获金额事件时间戳与实际用户操作相匹配

如何验证设备归属

验证设备归因

归因验证使用案例

何时验证归因

方法比较

选择验证方法

方法 1：设备辅助应用程序

设备辅助应用程序概述

应用程序功能

使用设备辅助应用程序

步骤

下载设备辅助应用程序

启动归因检查

选择设备标识符

查看归因详细信息

显示的归因信息

解释安装归因

再吸引归因要求

验证事件跟踪

设备辅助故障排除

常见问题

可能的原因

解决步骤

可能原因

解决步骤

可能原因

解决步骤

方法 2：归因详情 API

API 端点规范

请求格式

查询参数

必填参数

API 响应

响应格式

响应示例

响应参数

JSON 响应字段

API 使用示例

实施示例

iOS 设备 (IDFA)

安卓设备 (GAID)

网络跟踪 (SDID)

Python 实现

JavaScript 实现

API 故障排除

常见 API 问题

问题

可能的原因

解决步骤

问题

可能的原因

解决步骤

问题

可能原因

解决步骤

最佳实践

测试工作流程

建议的测试流程

方法选择指南

何时使用每种方法

集成验证核对表

归因验证核对表

其他资源

相关文档