Server-to-Server - Fundamentals

Implement Singular's REST API for complete server-side tracking as an alternative to SDK integration, enabling full control over data collection, transmission, and attribution workflows.

Overview

Server-to-Server Use Case

Server-to-server (S2S) integration provides REST API endpoints for building complete attribution and analytics solutions running from your backend infrastructure without embedding Singular SDK in client applications.

Integration Approaches:

• Pure S2S: 100% server-side implementation handling both session and event tracking
• Hybrid: Singular SDK manages sessions while server-side handles event tracking

Hybrid Integration Pattern

Hybrid integration combines Singular SDK for session management with server-side EVENT API for backend event tracking, balancing ease of implementation with server-side flexibility.

Device Data Retrieval Methods:

1. Client-Managed Flow: Capture required data points on client and forward to server via internal API for use with Singular EVENT endpoint
2. Internal BI Postback: Configure Singular Internal BI postback to receive real-time JSON payload with device identifiers after install, re-engagement, or events ( Setup Guide )

Implementation Resources:

• EVENT Endpoint Required Parameters
• Retrieving Device Data Guide (iOS/Android code samples)

Key Integration Principles

Integration Requirements

Pure S2S integration requires comprehensive data pipeline implementation for session and event tracking.

1. Data Collection: Collect required data points from client applications
2. Device Graph: Forward data to server and maintain device identifier storage
3. Session Requests: Send session notifications via SESSION API
4. Response Handling: Process and relay Singular responses back to client app
5. Event Requests: Forward events via EVENT API

Related S2S Guides

This article is the shared reference for the S2S suite. Use the guide that matches your platform, and the endpoint references for full parameter detail.

Platform guides

• Mobile App S2S Guide
• Web S2S Implementation Guide
• PC & Console Game Integration Guide

Endpoint references

• SESSION Endpoint API Reference
• EVENT Endpoint API Reference
• PC & Console API Endpoint Reference

Feature guides

• Deep Linking Guide
• SKAdNetwork 4 Implementation Guide
• Tracking Ad Revenue API Reference

REST API Endpoints

Singular provides two primary REST API endpoints for server-to-server session and event tracking.

Session Endpoint

Session Tracking API

SESSION endpoint notifies Singular of app open events to initialize user sessions for attribution and retention tracking.

GET https://s2s.singular.net/api/v1/launch

Complete reference: SESSION Endpoint API Reference

Event Endpoint

Event Tracking API

EVENT endpoint tracks in-app events and revenue for attribution analysis and campaign optimization.

GET https://s2s.singular.net/api/v1/evt

Complete reference: EVENT Endpoint API Reference

Common Parameters

These parameters are shared across the SESSION and EVENT endpoints of Singular's S2S REST API. This section holds their canonical definitions; other S2S articles link here rather than redefining them.

Authentication

Device Identifiers

Device identifiers vary by platform and availability. Include all applicable identifiers for your platform. Omit any identifier that is unavailable—never pass NULL or an empty string.

Device Parameters

Application Parameters

Network and Location Parameters

Data Privacy Parameters

{"limit_data_sharing":false}

{"limit_data_sharing":true}

Cross-Device Support

Implementation Phases

Successful S2S integration requires four key implementation phases executed sequentially for optimal data quality and attribution accuracy.

Phase 1: Data Collection

Required Data Points

Establish robust data collection strategy capturing all required parameters for Singular platform functionality.

Implementation Resources:

• SESSION Endpoint Required Parameters
• EVENT Endpoint Required Parameters
• Retrieving Device Data Guide (iOS/Android code samples)
• SKAdNetwork 4 Implementation Guide (iOS specific data points)

Phase 2: Real-Time Streaming

Critical Timing Requirements

Real-time data streaming maintains attribution accuracy and enables time-sensitive features like SKAdNetwork conversion value updates.

Best Practices:

• Implement server-side event listeners for app session starts
• Forward session data immediately with all required parameters
• Implement server-side event listeners for in-app events
• Forward event data immediately with all required parameters
• Use webhook architecture for reliable data transmission
• Implement retry mechanisms for failed requests
• Monitor data flow for quality assurance

Phase 3: Response Handling

Bidirectional Communication

Response handling bridges server-side API interactions with client-side functionality, enabling deferred deep linking and conversion value updates.

Key Response Types:

• Deferred Deep Links: API response contains pending deep link data requiring immediate relay to app for user routing and personalization
• Conversion Values: iOS SKAdNetwork conversion values must be promptly forwarded to app for accurate campaign measurement

Best Practices:

• Implement response handling on server infrastructure
• Parse and validate Singular API responses
• Forward relevant response data to client app (essential for iOS SKAdNetwork)
• Implement client-side response processing
• Handle errors gracefully with proper HTTP status codes
• Log failed responses for retry mechanisms

Phase 4: Testing & Validation

Data Flow Verification

Testing phase validates complete data pipeline functionality and attribution accuracy before production deployment.

Session Attribution Processes:

• First Session (New Install): Singular recognizes new install and triggers install attribution process
• Re-engagement Qualified: Singular triggers re-engagement attribution process ( Re-engagement FAQ )
• Standard Session: Singular records session for user activity and retention metrics

Validation Checklist:

• Test session data flow—validate first and subsequent sessions have correct data points and values
• Confirm events received only after session reported to Singular (events before session create organic attribution)
• Confirm session response handled and passed to client app (critical for deferred deep links)

Testing guide: S2S Integration Testing Guide

Additional Features

Implement cross-device tracking, revenue tracking, uninstall monitoring, and data privacy compliance for comprehensive analytics.

Cross-Device Tracking

Custom User ID Implementation

Leverage custom_user_id parameter to associate users with device-level sessions for cross-device reporting and user-level analytics.

Enables comprehensive cross-device reporting, user-level data exports, and Internal BI postbacks while maintaining user privacy.

More info: Custom User ID Parameter

Revenue Tracking

In-App Purchase Reporting

Track revenue from in-app purchases for ROI analysis, campaign performance measurement, and export/postback enrichment.

Use EVENT endpoint with revenue parameters :

• is_revenue_event : Marks event as revenue event (skip if event name is __iap__ or amount > 0)
• purchase_receipt : Android/iOS In-App Purchase object—highly recommended for transaction details and report enrichment
• receipt_signature (Android): Highly recommended for transaction validation and fraud prevention
• amt : Revenue amount as Double (e.g., "amt=1.99")
• cur : ISO 4217 currency code (e.g., "cur=USD")

Implementation guide: Subscription State Management

Data Privacy Compliance

User Consent Handling

Notify Singular of end-user consent for data sharing to comply with GDPR, CCPA, and other privacy regulations.

Use data_sharing_options parameter to communicate user choice:

• {"limit_data_sharing":false} : User consented (opted-in) to share information
• {"limit_data_sharing":true} : User refused to share information

Singular uses limit_data_sharing in User Privacy Postbacks and passes information to partners requiring compliance.

More info: User Privacy and Limit Data Sharing