Server-to-Server - Integration Guide

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

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

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

Advanced Features

Enhance S2S integration with advanced attribution handling, deep linking, cross-device tracking, and platform-specific capabilities.

Apple Search Ads Attribution

iOS Search Ads Integration

Apple Search Ads is a Self-Attributing Network (SAN) requiring platform-specific attribution implementation via Apple frameworks.

Framework Support:

• iOS 14.2 and below: iAd framework
• iOS 14.3 and above: AdServices framework (recommended)

Complete guide: Apple Search Ads Integration Documentation

iAd Framework Implementation

Retrieve and send Apple Search Ads attribution data via iAd framework for iOS 14.2 and below.

Step 1: Retrieve Attribution Data

#import <iAd/iAd.h>

Class ADClientClass = NSClassFromString(@"ADClient");

if (ADClientClass) {
    id sharedClient = [ADClientClass performSelector:@selector(sharedClient)];
    
    if ([sharedClient respondsToSelector:@selector(requestAttributionDetailsWithBlock:)]) {
        [sharedClient requestAttributionDetailsWithBlock:^(NSDictionary *attributionDetails, NSError *error) {
            if (attributionDetails && attributionDetails.count  0) {
                // REPORT attributionDetails FROM YOUR APP TO YOUR SERVER
            }
        }];
    }
}

Step 2: Send to Singular

Report event with reserved name __iAd_Attribution__ via EVENT endpoint , passing attribution JSON as e parameter.

AdServices Framework Implementation

Retrieve and send attribution token via AdServices framework for iOS 14.3 and above.

Step 1: Retrieve Attribution Token

#import <AdServices/AdServices.h>

NSError *error = nil;
Class AAAttributionClass = NSClassFromString(@"AAAttribution");
if (AAAttributionClass) {
    NSString *attributionToken = [AAAttributionClass attributionTokenWithError:&error];
    if (!error && attributionToken) {
        // Handle attributionToken
    }
}

Step 2: Send to Singular

URL-encode token and append to SESSION endpoint as attribution_token parameter on first session after every install and reinstall.

Google Play Install Referrer

Android Install Attribution

Google Play Install Referrer provides most accurate Android install attribution, containing information about user origin before Play Store arrival.

More info: Google Install Referrer Documentation

Implementation Steps:

1. Retrieve install referrer on first app open using Play Install Referrer API
2. Report session via SESSION endpoint including install_ref JSON parameter with required attributes

install_ref Attributes:

Meta Install Referrer

Facebook Attribution Enhancement

Meta Referrer is Android-specific measurement solution providing granular user-level attribution data for app installs, combining Google Play Install Referrer and Meta Install Referrer technologies.

Learn more: Meta Referrer FAQ

Implementation Steps:

1. Retrieve Meta install referrer on first app open per Meta's documentation
2. Report session via SESSION endpoint including meta_ref JSON parameter with required attributes

meta_ref Attributes:

Singular Links & Deep Linking

Implement deep linking and deferred deep linking for Singular tracking links so users move seamlessly from a campaign to a specific screen in your app.

A deep link is a clickable link that opens specific content inside an app. There are two scenarios to support:

• Deep link (direct): the user already has the app installed. They tap a Singular Link and the app opens directly on the right content.
• Deferred deep link (DDL): the user does not have the app yet. They tap the link, install from the store, and on first open the app still routes them to the intended content.

With an SDK integration, Singular handles most of this automatically. In a server-to-server (S2S) integration there is no SDK on the device, so your team is responsible for two extra jobs: passing the deep link your app received up to Singular, and reading the deferred deep link Singular returns and routing the user. Both flow through the SESSION endpoint:

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

Resources: Deep Linking FAQ | Singular Links FAQ

The three configurations at a glance

Step 1: App-level configuration

Before any deep link can work, Singular Links must be recognized by the OS as iOS Universal Links and Android App Links so that tapping a link opens your app instead of a browser. Traditional URI app schemes are supported as a fallback.

Follow the canonical setup guides for the detailed platform steps, then confirm each item below is complete. The detailed steps live in Singular Links Prerequisites and How to Configure Deep Links. The checklist here gives you the required order and the points teams most often miss.

Configuration checklist:

1. Add a link sub-domain in Attribution > Manage Links > Manage Link Domains (for example yourbrand.sng.link). This is the host your Singular Links use.
2. iOS — Universal Links: enable the Associated Domains capability for applinks:yourbrand.sng.link, then copy your App Prefix / Team ID from the Apple Developer Portal into Settings > Apps > [iOS app] > Show Advanced Settings. Optionally register an app-scheme fallback as a URL Type in Xcode.
3. Android — App Links: generate your SHA-256 signing fingerprints (Play Console for production, keytool for debug), add an autoVerify intent filter for your Singular domain to AndroidManifest.xml, then paste the fingerprint into Settings > Apps > [Android app] > Show Advanced Settings > App Links SHA256 fingerprints.
4. Define the deep links in Attribution > Manage Links > Create Link (see the field mapping below).

Mapping the Manage Links redirect fields

When you create the link, three redirect fields map directly to the three deep link concepts used later in the API:

Developer handoff: engineering should provide the deep link scheme(s) per platform and the list of destination URLs (for example myapp://autumnfashion).

Step 2: SESSION (inbound) — send the deep link to Singular

When the app opens from a Singular Link, capture the full opening URL and send it to Singular on the SESSION request in the openuri parameter (URL-encoded). This is how Singular attributes the session to the link and reports the deep link result. Required when using Singular Links.

Singular Link parameters carried on the URL

Capture the opening URL in the app

The app needs handler code that receives the opening URL and forwards it to your server for inclusion on the SESSION request.

iOS (Swift):

// Custom scheme / direct opens
func scene(_ scene: UIScene,
           openURLContexts URLContexts: Set<UIOpenURLContext>) {
    guard let url = URLContexts.first?.url else { return }
    SessionReporter.report(openURL: url.absoluteString)
}

// Universal Links arrive via:
func scene(_ scene: UIScene,
           continue userActivity: NSUserActivity) {
    if let url = userActivity.webpageURL {
        SessionReporter.report(openURL: url.absoluteString)
    }
}

Android (Kotlin):

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    intent?.data?.let { uri ->
        SessionReporter.report(uri.toString())
    }
}

override fun onNewIntent(intent: Intent?) {
    super.onNewIntent(intent)
    intent?.data?.let { SessionReporter.report(it.toString()) }
}

Send the SESSION request with openuri

From your server, include the captured URL (URL-encoded) as openuri:

curl -G https://s2s.singular.net/api/v1/launch \
  --data-urlencode "a=<SDK key>" \
  --data-urlencode "p=Android" \
  --data-urlencode "i=com.yourcompany.app" \
  --data-urlencode "aifa=<GAID>" \
  --data-urlencode "n=YourAppName" \
  --data-urlencode "openuri=myapp://home/page?queryparam1=value1"

Short link resolution

If the user opened a shortened Singular Link, also send singular_link_resolve_required=true. Singular returns the expanded long link so you can parse the deep link and passthrough values.

Sample response:

{
  "status": "ok",
  "resolved_singular_link": "https://myapp.sng.link/A59c0/nha7?_dl=myapp%3A%2F%2Fdeeplink&_ddl=myapp%3A%2F%2Fdeferred-deeplink&_p=passthroughvalue"
}

Dynamic passthrough parameters

If your organization configured dynamic passthrough for a link, the deep link URL includes the _p parameter with a URL-encoded JSON string or unstructured string for content routing. See Dynamic Passthrough Parameters.

Reference: SESSION Endpoint API Reference (Deep Linking Parameters).

Step 3: SESSION (outbound) — relay the deferred deep link to the app

For a user who installs the app after tapping the link, the deferred deep link is returned by Singular in the SESSION response on the first session after install. Your server must relay that value back to the app so it can route the user.

Request the DDL on the first session

On the first SESSION request after an install, add these two parameters:

Sample SESSION request (install + DDL enabled):

curl -G https://s2s.singular.net/api/v1/launch \
  --data-urlencode "a=<SDK key>" \
  --data-urlencode "p=Android" \
  --data-urlencode "i=com.yourcompany.app" \
  --data-urlencode "aifa=<GAID>" \
  --data-urlencode "n=YourAppName" \
  --data-urlencode "install=true" \
  --data-urlencode "ddl_enabled=true"

Read the response and relay it to the app

If the install came from a tracking link carrying a deferred deep link, Singular returns:

Sample SESSION response:

{
  "deferred_deeplink": "myapp://deferred-deeplink",
  "status": "ok",
  "deferred_passthrough": "passthroughvalue"
}

Testing & validation

• Deferred deep link: on a device without the app, tap the link and confirm you land on the store. Install and open, and the app should show the intended content.
• Direct deep link: with the app installed, tap the link and confirm the app opens directly on the intended content.
• SESSION ordering: confirm a single SESSION is received before any events, and that the SESSION response is parsed and passed to the client (critical for deferred deep links).
• openuri populated: verify deep-link opens send a SESSION with openuri set, regardless of the timeout window.

Testing guides: Test Your Integration | Test a Tracking Link

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

Uninstall Tracking

Silent Push Notification Setup

Track uninstalls using device silent push notifications by sending push token with every session notification.

Setup Requirements:

1. Follow platform-specific uninstall tracking setup:
   • iOS Uninstall Tracking Setup
   • Android Uninstall Tracking Setup
2. Append platform-specific token to SESSION request:
   • iOS: apns_token (APNs device token)
   • Android: fcm (FCM device token)

iOS Install Receipt

Receipt Validation

Pass iOS install receipt in install_receipt parameter when reporting iOS session.

import Foundation
import StoreKit

class ReceiptManager {
    static func getInstallReceipt() - String? {
        if #available(iOS 18.0, *) {
            let semaphore = DispatchSemaphore(value: 0)
            var result: String?
            
            Task {
                do {
                    let transaction = try await AppTransaction.shared
                    result = transaction.jwsRepresentation
                    semaphore.signal()
                } catch {
                    debugPrint("Failed to get app transaction: \(error.localizedDescription)")
                    semaphore.signal()
                }
            }
            
            semaphore.wait()
            return result
            
        } else {
            guard let receiptURL = Bundle.main.appStoreReceiptURL else {
                debugPrint("Receipt URL not found")
                return nil
            }
            
            do {
                let receiptData = try Data(contentsOf: receiptURL, options: .uncached)
                return receiptData.base64EncodedString(options: [])
            } catch {
                debugPrint("Failed to read receipt: \(error.localizedDescription)")
                return nil
            }
        }
    }
}

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