验证设备归因

使用 Singular Device Assist 应用和 Attribution Details API 端点进行 设备归因验证的完整指南，适用于集成测试 和追踪链接验证。

归因验证使用场景

何时需要验证归因

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

方法对比

选择验证方法

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

方法一：Device Assist 应用

一款移动应用，可在测试设备上直接快速地对设备归因状态、 安装详情和事件追踪摘要进行可视化验证。

Device Assist 应用概述

应用功能

Device Assist 应用可显示 Singular 为特定设备记录的全面归因信息。

显示的归因数据：

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

使用 Device Assist 应用

分步操作流程

Device Assist 问题排查

常见问题

方法二：Attribution Details API

程序化 API 端点，可为集成测试和 CI/CD 流水线实现自动化归因验证。

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 响应

响应格式

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 响应字段

API 使用示例

实现示例

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"

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"

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"

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')}")

/**
 * 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 问题

最佳实践

在集成测试和活动验证过程中，有效进行归因验证的建议。

测试工作流程

推荐测试流程

1. 使用全新设备： 使用干净的设备或在测试前 重置广告标识符，以避免缓存的归因数据干扰
2. 及时验证： 安装后 5-10 分钟内检查归因， 在测试过程中快速获取反馈
3. 测试多种场景： 验证不同来源的归因（自然量、付费活动、再互动）
4. 记录结果： 记录归因验证结果， 用于集成验证文档
5. 尽量实现自动化： 在自动化测试套件中使用 Attribution Details API，实现持续验证

方法选择指南

各方法适用场景

集成验证清单

归因验证清单

其他资源

归因测试、SDK 集成和追踪链接配置的完整文档。

相关文档

• 使用测试控制台 - SDK 集成测试完整指南
• 如何测试追踪链接 - 追踪链接验证流程
• 了解 Singular 移动应用归因 - 归因方法论与流程
• 追踪链接参数与报告维度 - 完整参数参考
• 再互动归因常见问题 - 再互动归因文档