Server-to-Server - Fundamentals

Follow
Avatar
Jared Ornstead
Updated

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.

Choosing your integration: SDK or S2S? If you can embed a client SDK, start with the SDK integration docs . Use Server-to-Server when you need server-side event delivery, are on a platform without an SDK, or want full control over data collection. This suite covers the S2S path and is the shared reference for the Mobile, Web, and PC/Console S2S guides.

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

Pure S2S Integration

Pure S2S is a fully server-side implementation: your backend collects the required data, maintains the device graph, and delivers both sessions and events to Singular. See Implementation Phases below for the step-by-step pipeline.

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.

Hybrid Benefits:

  • SDK handles complex session logic, deep linking, and device data collection automatically
  • Server sends events for transactions processed in backend systems
  • Reduced client-side implementation complexity
  • SESSION endpoint not required—SDK manages session lifecycle

Hybrid S2S Data Flow

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 )

Device Graph Maintenance: Both methods require server-side logic to maintain device graph. When SDK detects device identifier changes, update server accordingly to ensure accurate tracking.

Related Resources:

Key Integration Principles

These principles apply to every S2S integration, whatever your platform or approach:

Principle Description
Flexibility Full control over data collection and transmission timing
Feature Parity Supports all SDK functionality when proper data provided
Integration Path Client → Your Server → Singular API
Real-time Processing One request at a time—no batch processing support
Sequential Flow Events must be processed chronologically
No Deduplication Singular does not deduplicate—implement server-side deduplication
Data Permanence Device-level data cannot be deleted after ingestion—validate before sending

Implementation Phases

A complete S2S integration moves through four phases, run in order, with each building on the one before it.

Phase 1: Data Collection

Required Data Points

Set up data collection that captures every required parameter, so Singular has everything it needs to attribute and report accurately.

All Required Parameters Mandatory: Omitting required parameters results in data discrepancies and attribution errors. No parameters are optional.

Async Function Handling: When collecting client-side data for server transmission, wait for asynchronous functions to complete and handle edge cases. Common issue causing missing data and partial attribution.

Implementation Resources:

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.

Attribution Impact:

  • Delayed Sessions: Severely impact attribution accuracy—system requires precise temporal data for campaign association
  • SKAdNetwork Timer: Strict on-device timer window for conversion values makes real-time streaming critical. Delays cause missed conversion value updates and incomplete campaign data

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 connects your server-side API calls back to the client app, which is what enables 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

Before deploying to production, validate the full data pipeline end to end and confirm attribution is accurate.

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

Critical Timing Requirements:

  1. Session Before Events: Single SESSION must be received before any events. SDK triggers session on app open, then sends in-app events. After 1+ minute background, session times out. New session sent when app returns to foreground. Use app lifecycle events and timers for session management
  2. Real-Time Events: Events occurring in app must be sent real-time after their respective session

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)

Integration Complete:

  • ✓ Data collection and storage validated
  • ✓ Real-time streaming to Singular validated
  • ✓ Response handling and logging validated
  • ✓ All testing data flows validated

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.

Privacy Compliance: Adhere to data privacy policies by avoiding personally identifiable information (PII) in custom_user_id . Use hashed username, email, or randomly generated string as unique user identifier.

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: Set to true for a revenue event; false otherwise.
  • 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.

Optional but Recommended: Parameter optional, but some attribution information only shared by partners when user explicitly opted-in.

More info: User Privacy and Limit Data Sharing

Endpoint Reference

Each endpoint reference documents its complete required and optional parameters inline. For the full parameter tables, see the following:

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

Feature guides