Skip to content
Clarisights Knowledge Center home
InboxAsk a human

Connecting Singular on Clarisights

Singular is a unified marketing analytics platform that aggregates ad-network spend with mobile attribution. Connecting Singular to Clarisights pulls Singular's blended event, cohort (LTV / ROAS), and SKAdNetwork reports so you can analyze post-install performance side-by-side with your direct ad-channel data in Clarisights.

At a glance

AuthenticationAPI key (Singular Reporting API)
Permissions neededReporting API access on the Singular org. The key must be able to call create_async_report, get_report_status, and reporting/filters
Account discoveryApp-based — every Singular app linked to the API key is offered. Ad-channel sources (the underlying networks Singular blends) are configured via Analytics Connections in Clarisights
Data freshnessDaily; rolling 7-day refresh window per default DAG
Lookback window7 days by default; cohort pulls automatically extend the window to cover the longest configured cohort period (up to 30 days)
Backfill on connectLast 7 days (longer for cohort data depending on configured cohort periods)
TimezoneUTC (Singular reports are requested with day-level granularity in UTC)
CurrencyUSD by default; display_unenriched is disabled so Singular returns enriched, deduplicated data
Levels supportedApp (Account) · Source · Campaign · Ad Set · Ad · Keyword
Limited rolloutNo

Prerequisites

  • An active Singular account with at least one app and one connected ad-network source

  • A Singular Reporting API key — generate from Singular dashboard → Settings → API Keys

  • The list of Clarisights ad channels you want to deref Singular data into (e.g. Facebook, Google Ads, Apple Search Ads, TikTok). Each ad channel must already be configured in Clarisights so cohort metrics can be linked back to the originating campaign / ad

Steps to Connect

Step 1 — Generate a Reporting API key in Singular

Sign in to Singular. Open Settings → API Keys and copy the Reporting API Key. Store it securely — the key grants read access to every app and source under your Singular org.

[TODO: Screenshot needed — Singular Settings API Keys page.]

Treat the Reporting API key like a password. If it is exposed, rotate it from the same page in Singular.

Step 2 — Add Singular in Clarisights

In Clarisights, go to Integrations → Singular → Add Account.

[TODO: Screenshot needed — Clarisights Integrations page Singular row.]

Step 3 — Enter the API key

Provide a friendly Account Name and paste your Reporting API Key. Click Validate.

Clarisights calls Singular's reporting/filters endpoint to confirm the key works and to discover the apps and ad sources available.

⚠ "Invalid API key" → The key is malformed, has been rotated, or belongs to a different Singular product (e.g. Audience API). Re-issue a Reporting API key from Singular Settings and retry.

Step 4 — Configure ad channel connections

For every ad channel you want Singular cohort / event metrics to attach to (Facebook, Google Ads, etc.), open the channel under Integrations in Clarisights and ensure Singular is enabled as an analytics source. The Clarisights team will configure the dereferencing path (campaign → ad set → ad) for each channel; reach out to support if a new channel needs Singular wiring.

Step 5 — Configure cohort periods and SKAN events

Cohort periods (1d, 3d, 5d, 7d, 14d, 30d) and SKAN events are configured server-side under your company's Singular preferences. The defaults are reasonable for most customers; contact Clarisights support to add or remove cohort windows or to whitelist specific SKAN custom events.

Verify the connection

  • Go to Integrations → Singular. Each connected app should appear with its app ID and internal status.

  • First data appears within 24 hours of the next scheduled sync. Async reports can take several minutes to complete on Singular's side.

  • Quick start: open a report on one of your ad channels (e.g. Facebook) and add Singular metrics such as SGN: Revenue, SGN: Installs, or any configured cohort metric (e.g. SGN: Revenue (7d)).

Data available

Hierarchy

Singular returns data along the original ad-network's hierarchy. Each Clarisights ad channel maps Singular's identifiers to its native level structure:

Native level (Singular)

Clarisights level

App

Account (per ad channel)

Source (Singular ad-network name)

Ad channel (e.g. Facebook, Google Ads, Apple Search Ads)

Unified Campaign (unified_campaign_id / unified_campaign_name)

Campaign

Ad Network Sub-Campaign (adn_sub_campaign_id / adn_sub_campaign_name)

Ad Group (Ad Set / Ad Group / Ad Squad depending on the ad channel)

Ad Network Creative (adn_creative_id / adn_creative_name)

Ad

Keyword (keyword_id / keyword)

Keyword (Apple Search Ads only)

Dimensions

Dimension

Level

Description

App

Account

Singular app name (linked to the iOS / Android app)

OS / Platform

Account

iOS, Android, or Web

Source

Account

Singular's name for the ad network (e.g. facebook, adwords, applesearchads)

Unified Campaign / ID

Campaign

Singular's normalized campaign across deeplinks and tracking variants

Adn Sub-Campaign / ID

Ad Group

Ad-network sub-campaign / ad-set name and ID

Adn Creative / ID

Ad

Ad-network creative name and ID

Keyword / ID

Keyword

Keyword text and ID (Apple Search Ads only)

Country

Any

ISO country code (Singular returns ISO format)

Date

Any

Report date (UTC)

Metrics

Event metrics (prefix SGN:) — standard delivery and conversion counts

Metric

Description

Impressions / Clicks / Installs

Aggregated delivery from the ad-network sources Singular ingests

Spend

Total spend in USD (Singular's enriched view)

Custom in-app event counters

Any in-app event configured in Singular is exposed as SGN: event_name

Platform-specific event metrics — iOS_, android_, and web_ variants of every event metric (e.g. iOS : SGN: Installs, android : SGN: Revenue) are auto-generated.

Cohort metrics (LTV by cohort window) — returned for the cohort periods configured for your company. Each cohort metric is exposed once per period:

Metric

Description

SGN: Revenue (actual / 1d / 3d / 5d / 7d / 14d / 30d)

Cohort revenue accumulated within N days of install

SGN: cohort_metric (period)

Any cohort metric configured in Singular (ROAS, ARPU, retention rate, etc.) is exposed at every configured period. Precision is 2 decimal places.

Supported cohort periods: actual (no window), 1d, 3d, 5d, 7d, 14d, 30d. Each is also auto-broken into iOS / Android / Web variants where applicable.

SKAdNetwork (SKAN) metrics

Metric

Description

SKAN Installs

Apple-attributed SKAN installs reported by Singular

SKAN Revenue / Conversion Values

Modeled cohort revenue and counts by conversion value bucket

SKAN Custom Events

Custom SKAN events configured in your Singular SKAN schema (whitelisted per company)

Limitations & known constraints

  • Async report latency: Singular reports are submitted as async jobs and polled. Clarisights polls for up to 30 minutes per report (60 retries at 30 second intervals). Very wide pulls or delayed Singular runs can push beyond this and require a re-run.

  • Daily row limits: Singular caps the org at ~3M reporting rows per day and ~200K rows per multi-day query. Configure cohort periods and dimensions conservatively to stay within limits.

  • Concurrency cap: up to 100 async reports may run concurrently per API key. Clarisights respects this rate limit.

  • Source dimension required for deref: rows without a Singular source identifier cannot be derefenced into a Clarisights ad channel and are skipped.

  • Cohort actuals vs windows: actual period metrics measure events on the report day; windowed metrics (1d/7d/30d) measure cohort accumulation. Windowed metrics for recent installs are still maturing and will continue to update for the duration of the longest cohort period.

  • Token revocation: if the Reporting API key is rotated or revoked in Singular, the integration stops syncing until a new key is provided.

Operating notes

  • Refresh schedule: data is pulled daily on a rolling 7-day window (cohort pulls automatically extend the window to cover the longest configured cohort period).

  • Lookback: 7 days base; cohort look-back equals the largest configured cohort period (up to 30 days).

  • Adding new ad channels: when a new ad channel is configured in Singular, contact Clarisights support to wire it into the deref path so cohort metrics can attach to the right Clarisights account / campaign / ad.

  • Currency conversion: Singular returns spend and revenue in USD; Clarisights then converts to your reporting currency.

  • Credential rotation: update the Reporting API key any time from Integrations → Singular → Edit Credentials.

Need help?

When contacting support from the in-app messenger, please include:

  • The integration name and Singular App / Source (Integrations → Singular)

  • Which report type is affected (Event / Cohort / SKAN)

  • The exact error message or screenshot

  • The step where the issue occurred

  • When the issue started