Singular

Send conversion and engagement events to Singular server-to-server for mobile attribution, marketing analytics, and ROAS measurement.

⚠️

This blueprint is currently alpha — schema and behaviour may change before GA.

Prerequisites

Before configuring Singular in Signal, you need a Singular account, an app registered in the Singular dashboard, and your SDK Key and Server-to-Server Key.

Get your Singular credentials

Go to singular.net and sign in.
Confirm you have admin access to the organisation you want to send events into.

Step 2: Register your app

Open Settings > Apps.
Click Add App and register your iOS or Android app (or both).
Note the App Long Name Singular assigns — this is sometimes required when filtering events. [verify with current vendor docs]

Step 3: Find your SDK Key

In Settings > SDK Keys, locate the SDK Key for your app.
Copy the value — it is used for both SDK and S2S event tracking.

Step 4: Generate a Server-to-Server (S2S) Key

In Settings > Server-to-Server Integration, click Generate New Key.
Give the key a descriptive name (e.g. “Datafly Signal”).
Copy the value immediately — it is only shown once.

⚠️

The S2S key authenticates all server-side event delivery. Store it in your secrets manager.

Configure the integration in Signal

Configuration Fields

Field	Required	Description
`sdk_key`	Yes	Your Singular SDK key from Settings > SDK Keys.
`s2s_key`	Yes	The Server-to-Server key from Settings > Server-to-Server Integration.

Management UI Setup

Go to Integrations in the sidebar.
Open the Integration Library tab.
Find Singular or filter by Attribution.
Click Install and enter your SDK Key and S2S Key.
Click Install Integration.

Management API Setup

curl -X POST http://localhost:8084/v1/admin/integration-catalog/singular/install \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Singular",
    "variant": "retail",
    "config": {
      "sdk_key": "your_sdk_key",
      "s2s_key": "your_s2s_key"
    },
    "delivery_mode": "server_side"
  }'

Event Mapping

The Retail variant maps the following Datafly events to Singular event names:

Datafly Event	Singular Event	Notes
`Product Added`	`add_to_cart`	Product details as event attributes
`Order Completed`	`purchase`	Requires `revenue`, `currency`, `transaction_id`
Custom events	Passed through	Add the Singular event name in the blueprint event map

Identity

The default blueprint forwards the following identifiers to Singular:

Source	Singular field
`user_id`	`customer_id`
`context.ip`	`ip_address`
`context.user_agent`	`user_agent`

Singular’s primary attribution key is the device identifier — idfa / idfv on iOS, gps_adid on Android — plus the app install referrer. Pass these from your mobile app via the Datafly mobile SDK so Singular can join sessions to the install record.

Default consent category: advertising. Gate behind advertising consent and respect ATT (iOS) and Android ad-ID preferences.

Verify it’s working

Trigger a test event from a test device.
In the Signal Management UI, open your Singular integration and watch the Live Events stream.
In Singular, open Attribution > Logs (or Live View) and filter by your test device — events appear in near real-time.
Confirm 200 responses in Signal’s Live Events log.

Troubleshooting

Symptom	Cause	Fix
`401 Unauthorized`	Invalid S2S key	Generate a new S2S key in Settings > Server-to-Server Integration.
Events not joining install attribution	Missing device identifier	Capture `idfa`, `idfv`, or `gps_adid` from the Singular SDK and pass them via the Datafly mobile SDK.
Custom events not in reports	Event not registered	Some Singular reports only show known event names — register custom events in Settings. [verify with current vendor docs]
Revenue not tracked	Missing `revenue` or `currency`	Ensure `Order Completed` events include `total`/`revenue` and `currency`.

Blueprint

The Singular blueprint version is 0.1.0 (alpha). It ships with a Retail variant covering add_to_cart and purchase events.