Ad Server Data Transfer

Overview

Alke Analytics joins your ad server events to the pageviews collected by the SDK, so that revenue, impressions, requests and viewability become filterable and pivotable on every analytics dimension (page, country, device, traffic source, custom dimension…).

This page is the contract for that delivery. It covers the storage location, the directory layout, the file naming, and the exact column names and types expected for each file type.

1. Prerequisite — the alke_id custom targeting key

Google Ad Manager only writes custom targeting keys into Data Transfer files if those keys are declared in the network. Before any delivery is useful:

1. Create a custom targeting key named exactly alke_id in Google Ad Manager (Inventory → Key-values), of type free-form text.
2. Make sure your ad request tags forward the value produced by the Alke collector.
3. Confirm that the key appears in the customtargeting column of a fresh file.

The value is a lowercase UUID, 36 characters:

alke_id=536c8820-94a6-11f1-836e-318a0522cae2

Alke Analytics extracts it with the pattern alke_id=([0-9a-f\-]{36}) and discards every row that does not carry it. Uppercase hexadecimal, a different key name, or a truncated value all result in silent zero-revenue ingestion.

2. Storage and access

Alke Analytics reads the files directly from that storage. Nothing is pushed to an API, and no other transfer channel is supported.

3. Directory layout

Every file must be reachable at exactly this path, relative to the agreed root prefix:

<file-type>/year=YYYY/month=MM/day=DD/<file-name>.parquet

Example:

networkbackfillimpressions/year=2026/month=08/day=12/part-00007.parquet

Rules:

• <file-type> is one of the eight values in section 4, lowercase, no separators.
• year, month and day are zero-padded (month=08, not month=8).
• The date in the path is the event date — the day the impression, click or request occurred. It is not the date the export ran. See section 7.
• There is no additional nesting. The .parquet files sit directly in the day=DD directory.
• Any number of files per day is fine; they are all read.

File names

File names must match ^[A-Za-z0-9._-]+\.parquet$ — letters, digits, dot, underscore and hyphen only. Any other character (space, quote, %, +, …) causes the file to be rejected.

File immutability

Alke Analytics tracks ingestion per file path and contributes each file’s revenue exactly once. A file that has already been ingested must never be modified in place.

• To add data, deliver a new file in the same directory.
• To correct data already delivered, contact Alke Tech so the affected day can be rebuilt. Overwriting a file silently produces either missing or double-counted revenue.

4. File types

Deliver the file types your setup produces. Direct and backfill (Ad Exchange / Open Bidding) inventory are separate types and must not be merged.

Missing a type degrades the corresponding metric only: without networkrequests there is no fill-rate, without networkactiveviews there is no viewability rate. Impressions are required for any revenue at all.

5. File format

6. Column specifications

Columns not listed here are ignored — extra columns are harmless. Every listed column must be physically present in the file: the schema is inferred from the Parquet file and each column is referenced unconditionally, so a missing column fails the ingestion of the whole file type (UNKNOWN_IDENTIFIER). “Optional” below never means the column may be absent — it means only its value may be empty ('' or 0); the column itself must still be emitted.

An empty value must be an empty string '' or 0, never NULL. A NULL is not rejected: every string and id column is read into a non-nullable field that carries a default, and ClickHouse’s default behaviour writes a NULL as that default ('' / 0) rather than raising an error. This is worse than a missing column — there is no UNKNOWN_IDENTIFIER to notice — because it is silent: a NULL revenue is recorded as 0 (lost revenue, not a failed import). Use COALESCE(col, '') / COALESCE(col, 0) in your export for any column that can be null at source.

Common types

• timestamp string — the event time as text, YYYY-MM-DDTHH:MM:SS. The variant YYYY-MM-DD-HH:MM:SS is also accepted. Must be a string, not a Parquet TIMESTAMP; the first 10 characters are read as the date and characters 12 onward as the time.
• id — integer, or a string of digits. Both are accepted. Decimal types must have scale 0.
• targeting string — semicolon-separated key=value pairs, e.g. device=smartphone;alke_id=536c8820-94a6-11f1-836e-318a0522cae2;pagetype=article.

networkimpressions

Direct impressions carry no revenue column: they are valued from the line item’s cost type and cost per unit, which Alke Analytics reads from the Ad Manager API.

networkbackfillimpressions

All columns of networkimpressions, except creativesize which is replaced by creativesizedelivered, plus:

The currency is configured per publisher on the Alke side and is not read from the file. Confirm it with Alke Tech during onboarding.

networkclicks and networkbackfillclicks

networkrequests and networkbackfillrequests

networkactiveviews and networkbackfillactiveviews

7. Delivery cadence and the attribution window

Alke Analytics attaches an ad event to a pageview day within a window of plus or minus one day around the date in the file path. This absorbs the normal skew between the client clock and the ad server clock.

Two consequences:

• Partition by event date, not by export date. If files are laid out by the time the export ran, every event is shifted by the export lag, and the whole feed rides the edge of the window. A one-day lag is absorbed; a two-day lag loses revenue silently.
• A late file is fine, a misfiled file is not. Delivering the day=12 directory on the 14th works perfectly — the path is what matters, not the delivery time.

There is no required cadence. Delivering continuously as events land is just as good as one batch per day — files accumulate in the day=DD directory of their event date and are picked up as they arrive.

Source retention

Keep delivered files available for at least 30 days. Alke Analytics retains the raw ad server facts for 7 days internally; rebuilding a day older than that requires re-reading the source files.

8. Validation checklist

Before the first production delivery, confirm on one day of data:

• The path resolves to <file-type>/year=YYYY/month=MM/day=DD/*.parquet under the agreed root prefix.
• File names match ^[A-Za-z0-9._-]+\.parquet$.
• Column names are lowercase and match section 6 exactly — no _COL_0, no TIME.
• time is a string, and its first 10 characters are the date.
• customtargeting is populated, and the share of rows containing alke_id= matches the share of traffic where the Alke collector is deployed.
• The extracted alke_id values are 36-character lowercase UUIDs.
• The event dates inside a day=DD directory are that day, not the export day.
• estimatedbackfillrevenue magnitudes are per impression (typically 10⁻⁵ to 10⁻¹).

Alke Tech runs the same checks on the first delivery and reports back before the feed is switched on.