Verifying Device Attribution

Comprehensive guide for validating device attribution using Singular Device Assist app and Attribution Details API endpoint for integration testing and tracking link verification.

Singular provides two methods for checking device attribution: Device Assist app for mobile testing and Attribution Details API endpoint for programmatic verification.

Verifying attribution is essential part of testing new SDK/S2S integration and validating Singular Links before campaign deployment.

Target Audience	UA Managers, Developers, QA Engineers
Prerequisites	Mobile device for testing (Device Assist app method) Singular API Key (API endpoint method) Device advertising identifier (IDFA, IDFV, GAID, etc.)

Attribution Verification Use Cases

When to Verify Attribution

Device attribution verification critical at multiple stages of integration and campaign deployment lifecycle.

Use Case	Purpose
SDK/S2S Integration Testing	Validate SDK properly tracking installs and attributing to correct sources during integration development. Complete Testing Console Guide
Tracking Link Validation	Test new Singular Links before campaign deployment to ensure proper attribution and parameter passing. How to Test Tracking Link
Campaign Troubleshooting	Diagnose attribution issues in live campaigns by checking test device attribution status
Partner Integration Verification	Confirm attribution data flowing correctly from advertising partners to Singular platform

Method Comparison

Choosing Verification Method

Select appropriate verification method based on testing requirements and technical capabilities.

Method	Best For	Requirements	Limitations
Device Assist App	Quick manual testing Non-technical users Visual verification	Mobile device App installation	Manual process, limited automation
Attribution Details API	Automated testing Programmatic verification CI/CD integration	API key Device identifier HTTP client	Testing only (beta), requires technical knowledge

Method 1: Device Assist App

Mobile app providing quick visual verification of device attribution status, install details, and event tracking summary directly on test device.

Device Assist App Overview

App Capabilities

Device Assist app displays comprehensive attribution information recorded in Singular for specific device.

Attribution Data Displayed:

Install Attribution: Install timestamp, attributed network, and campaign name
Re-engagement Attribution: Re-engagement timestamp, attributed network, and campaign details
Event Summary: Sessions and in-app events tracked by Singular for device
Device Identifiers: IDFA, IDFV, GAID, or other identifiers used for tracking

Using Device Assist App

Step-by-Step Procedure

1	Download Device Assist App Install Singular Device Assist app on test device: iOS:Download from App Store Android:Download from Google Play
2	Launch Attribution Check Open Device Assist app and select Check Implementation from main menu. Additional Features: Device Assist app also provides device identifier lookup and SDK implementation verification tools accessible from main menu.
3	Select Device Identifier App automatically selects appropriate device identifier for platform. Confirm selection and tap Check Implementation again to proceed. Identifier Selection: iOS: IDFA (if ATT authorized) or IDFV (if ATT not authorized or not implemented) Android: GAID (Google Advertising ID) or alternative identifiers if GAID unavailable
4	Review Attribution Details App displays complete attribution information for device as recorded in Singular platform. Attribution Information Displayed Install Attribution Details # Install Timestamp: Date and time of first app launch (install event) Attributed Network: Ad network or source credited with install (e.g., Facebook, Google Ads, Organic) Campaign Name: Marketing campaign attributed to install Additional Parameters: Campaign-specific parameters passed through tracking link Interpreting Install Attribution "Organic": No matching touchpoint found within attribution window - install not attributed to paid campaign "Unattributed": Device tracked but attribution decision pending or incomplete Network Name: Install successfully attributed to specific advertising partner Re-engagement Attribution Details # Re-engagement Timestamp: Date and time of latest re-engagement session Attributed Network: Source credited with bringing user back to app Campaign Name: Re-engagement campaign attributed to session Self-Attributing Networks: Re-engagement attributions from self-attributing networks (Twitter, Facebook, Google Ads, Snapchat, etc.) may show as "Unattributed" for privacy reasons. Re-engagement Attribution Requirements For re-engagement attribution to occur: User must have existing install (not new device) Re-engagement campaign click must occur within configured attribution window Session must occur after re-engagement click Learn more: Re-engagement Attribution FAQ Event Tracking Summary # Device Assist app displays summary of all in-app events tracked by Singular for device. Event Information Shown: Event Name: Name of tracked event (session, purchase, level_complete, etc.) First Event Time: Timestamp of first occurrence Last Event Time: Timestamp of most recent occurrence Event Count: Total number of times event occurred Revenue: Total revenue for revenue events Validating Event Tracking Use event summary to verify: Sessions being tracked correctly Custom events appearing with correct names Revenue events capturing amounts properly Event timestamps matching actual user actions

Device Assist Troubleshooting

Common Issues

No Attribution Data Displayed

Possible Causes

App Not Installed: Test app not installed or not opened yet on device
Wrong Identifier: Device Assist checking identifier not used by app SDK
SDK Not Initialized: Singular SDK not properly initialized in app
Attribution Pending: Attribution decision not finalized yet (typically takes 1-5 minutes)

Resolution Steps

Verify test app installed and opened at least once on device
Confirm device identifier matches identifier type used in SDK (IDFA vs IDFV for iOS)
Wait 5-10 minutes after app launch and check attribution again
Verify SDK integration using Testing Console

Attribution to Wrong Source

Possible Causes

Previous Device Usage: Device previously used for testing with cached attribution
Multiple Touchpoints: Multiple campaign clicks within attribution window
Fingerprint Matching: Probabilistic attribution matched wrong click

Resolution Steps

Reset device and clear attribution:
- Delete test app
- Reset advertising identifier
- Delete device from Testing Console if registered
Use fresh device or reset identifier before testing
Use deterministic attribution (device ID in tracking link) instead of fingerprinting for testing
Review attribution window settings in Partner Configuration

Install Attributed as Organic Instead of Campaign

Possible Causes

Attribution Window Exceeded: Install occurred outside configured attribution window
No Matching Touchpoint: No click found matching device
Fingerprint Mismatch: Device fingerprint changed between click and install
Link Not Clicked: App installed directly from store without clicking tracking link

Resolution Steps

Verify tracking link clicked before installing app
Check attribution window settings allow sufficient time for install
Use device ID in tracking link (deterministic attribution) for reliable testing
Ensure stable network connection during click and install
Test on different device or reset identifier and retry

Method 2: Attribution Details API

Programmatic API endpoint enabling automated attribution verification for integration testing and CI/CD pipelines.

Beta Feature Notice: Attribution Details API endpoint is beta feature. Use for testing purposes only - do not call inside production app or high-volume environments.

API Endpoint Specification

Request Format

Endpoint URL:

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

Request Method: GET

Complete Request Example:

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

Query Parameters

Required Parameters

Parameter Type Description

api_key

String

Singular Reporting API Key from platform.

Location: Dashboard → Developer Tools → API Keys → Reporting API Key

Important: Use Reporting API Key, not SDK Key. Different keys serve different purposes.

device_id

String

Device's advertising identifier value.

Must match identifier type specified in keyspace parameter.

keyspace

String (Enum)

Type of advertising identifier provided in device_id:

idfa - iOS Identifier for Advertisers (requires ATT authorization)
idfv - iOS Identifier for Vendors (alternative when IDFA unavailable)
aifa - Android Identifier for Advertising (also known as GAID)
sdid - Singular Device ID for web tracking (retrieve using singularSdk.getSingularDeviceId() after SDK initialization)

API Response

Response Format

API returns JSON array containing attribution details for requested device.

Sample Response

[
  {
    "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
      }
    ]
  }
]

Response Parameters

JSON Response Fields

Field	Description
`app_long_name`	App bundle identifier (e.g., com.example.myapp)
`app_name`	App display name as configured in Singular platform
`install_info`	Object containing install attribution details and decision information: `install_time` - Timestamp of first app session (install) `network` - Ad network credited with install `campaign_name` - Campaign name attributed to install `view_through_attribution` - Boolean indicating attribution based on ad impression (true) vs ad click (false). Learn more: Singular's Install Attribution Process `additional_parameters` - Custom parameters passed through tracking link. Details: Tracking Link Parameters and Report Dimensions
`re_engagement_info`	Object with same structure as `install_info` but for re-engagement attribution. Learn more: Re-engagement Attribution FAQ Privacy Note: Re-engagement attributions from self-attributing networks (Facebook, Google Ads, Twitter, Snapchat) appear as "Unattributed" for privacy compliance.
`events`	Array of objects containing in-app event summary tracked by SDK: `event_name` - Name of tracked event `first_event_time` - Timestamp of first occurrence `last_event_time` - Timestamp of most recent occurrence `event_count` - Total number of event occurrences `revenue` - Total revenue for revenue events (if applicable)
`uninstall_pre_requisites`	Object containing uninstall tracking configuration: `apns` (iOS) - Apple Push Notification Service token. Configuration: iOS Uninstall Tracking `gcm_token` (Android) - Firebase Cloud Messaging token. Configuration: Android Uninstall Tracking

API Usage Examples

Implementation Examples

iOS Device (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"

Android Device (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"

Web Tracking (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 Implementation

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 Implementation

/**
 * 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 Troubleshooting

Common API Issues

Empty Array Response

Issue

API returns empty array [] instead of attribution data.

Possible Causes

No Attribution Data: Device never installed app or no session tracked
Wrong Identifier: Device ID or keyspace incorrect
Timing Issue: Attribution data not processed yet (typically 1-5 minutes after install)

Resolution Steps

Verify device ID copied correctly without extra spaces
Confirm keyspace matches identifier type (idfa vs idfv for iOS)
Wait 5-10 minutes after app install and retry query
Check device attribution using Device Assist app to verify app installed and tracked

Authentication Error

Issue

API returns authentication error or 401 Unauthorized response.

Possible Causes

Invalid API Key: API key incorrect or not provided
Wrong Key Type: Using SDK Key instead of Reporting API Key
Key Expired: API key revoked or regenerated

Resolution Steps

Navigate to Dashboard → Developer Tools → API Keys → Reporting API Key
Copy Reporting API Key (NOT SDK Key)
Verify API key pasted correctly in request
If key recently regenerated, ensure using new key value

Security Warning: Never commit API keys to version control or expose in client-side code. Use environment variables or secure configuration management.

Rate Limiting Error

Issue

API returns 429 Too Many Requests or rate limit error.

Possible Causes

Excessive Requests: Too many API calls in short time period
Production Usage: API used in production environment (not intended use case)

Resolution Steps

Implement exponential backoff and retry logic in code
Space out API requests (minimum 1 second between calls recommended)
Cache attribution data when possible to reduce API calls
Contact Singular Support if legitimate testing requires higher rate limits

Beta Limitation: Attribution Details API designed for testing only. Do not use in production applications with high request volumes.

Best Practices

Recommendations for effective attribution verification during integration testing and campaign validation.

Testing Workflow

Recommended Testing Process

Use Fresh Devices: Test with clean devices or reset advertising identifiers before testing to avoid cached attribution
Verify Immediately: Check attribution within 5-10 minutes of install for quick feedback during testing
Test Multiple Scenarios: Validate attribution for different sources (organic, paid campaigns, re-engagement)
Document Results: Record attribution verification results for integration validation documentation
Automate When Possible: Use Attribution Details API in automated test suites for continuous validation

Method Selection Guide

When to Use Each Method

Scenario	Recommended Method
Quick Manual Testing	Device Assist App - fastest visual verification during development
Automated Testing	Attribution Details API - programmatic verification in CI/CD pipelines
Non-Technical Testing	Device Assist App - requires no coding or API knowledge
Batch Device Verification	Attribution Details API - script multiple device checks
Event Tracking Validation	Both methods - Device Assist for quick check, API for detailed event analysis

Integration Validation Checklist

Attribution Verification Checklist

Complete Attribution Validation:

Install attributed to correct network/source
Campaign name matches expected campaign
Attribution timestamp reasonable (within expected timeframe)
Attribution method appropriate (click vs impression)
Custom parameters passed correctly through tracking link
Session events tracked properly
Custom events appearing with correct names
Revenue events capturing amounts and currency
Re-engagement attribution working (if applicable)
Uninstall tracking configured (if implemented)

Additional Resources

Complete documentation for attribution testing, SDK integration, and tracking link configuration.

How to Verify Device Attribution

Verifying Device Attribution

Attribution Verification Use Cases

When to Verify Attribution

Method Comparison

Choosing Verification Method

Method 1: Device Assist App

Device Assist App Overview

App Capabilities

Using Device Assist App

Step-by-Step Procedure

Download Device Assist App

Launch Attribution Check

Select Device Identifier

Review Attribution Details

Attribution Information Displayed

Interpreting Install Attribution

Re-engagement Attribution Requirements

Validating Event Tracking

Device Assist Troubleshooting

Common Issues

Possible Causes

Resolution Steps

Possible Causes

Resolution Steps

Possible Causes

Resolution Steps

Method 2: Attribution Details API

API Endpoint Specification

Request Format

Query Parameters

Required Parameters

API Response

Response Format

Sample Response

Response Parameters

JSON Response Fields

API Usage Examples

Implementation Examples

iOS Device (IDFA)

Android Device (GAID)

Web Tracking (SDID)

Python Implementation

JavaScript Implementation

API Troubleshooting

Common API Issues

Issue

Possible Causes

Resolution Steps

Issue

Possible Causes

Resolution Steps

Issue

Possible Causes

Resolution Steps

Best Practices

Testing Workflow

Recommended Testing Process

Method Selection Guide

When to Use Each Method

Integration Validation Checklist

Attribution Verification Checklist

Additional Resources

Related Documentation