# Advertising and account reporting — 1.5.1

Open **Publishing → Analytics** for Advertising, Social accounts and Connections. Advertising is also available at **Ads → Reports**. Reports read connected provider data; loading, refreshing and exporting do not launch or change campaigns.

## Advertising

1. Connect an advertising integration under Ads → Accounts. An Instagram publishing connection is not a Meta Ads connection. An administrator connects accounts; ordinary workspace members can read reports. External reviewers cannot access reporting.
2. Choose the connection and optionally one advertising account. Choose 7, 30 or 90 days, or a custom 1–90-day calendar range. Load report. The comparison covers the immediately preceding equal number of days. Provider account time zones apply to ad metrics.
3. Review spend, impressions, clicks, conversions, CTR, cost per conversion, purchase value and purchase ROAS. Conversions may be fractional. Purchase value and ROAS are available only for Meta purchase events; other networks display unavailable.
4. Filter campaigns by currency, current status and name/account search. Sort by a metric. Expand campaigns, then ad sets, to inspect individual ads. A paused campaign can still have historical spend. Status is current status, not the status on every reported day.
5. Change the daily chart metric. The dashed comparison aligns the prior period by relative day. The daily table exposes the underlying values. Missing days/metrics stay unavailable; incomplete campaign coverage is not filled with zero.
6. Open Accounts to see account currency, time zone, provider status, billing status and returned campaign totals. No card details are displayed. Missing account metadata remains unknown.
7. For supported Meta and LinkedIn campaigns, open Audience. Select a supported country, demographic, placement or device dimension. Provider privacy thresholds, reporting delays and permissions can limit rows. Export the returned breakdown as JSON.
8. Export CSV for the filtered campaign hierarchy, prior-period values and daily totals by known currency. Report dates, retrieval time and coverage warnings are included. Print / PDF uses your browser's print dialog. Expand the rows you want printed before opening it.

Changing date/account inputs marks the displayed report stale and disables exports until reloaded. Completed reports are cached for five minutes; Refresh requests a new provider read. Requests are limited to six per minute per workspace to protect provider quota.

## Accuracy and coverage

- Never combine different currencies. Monetary summary cards require one known currency; filter to a currency or account. No foreign exchange conversion is performed. Daily CSV totals exclude unknown currency groups; individual campaign rows retain the raw value and label the currency unknown.
- CTR, CPC, CPM, cost per conversion and ROAS are recomputed from totals, not averaged across campaigns. Reach is not summed across campaigns. Unique reach may be unavailable or approximate upstream.
- API attribution differs by network, objective and conversion configuration. A conversion total is not necessarily a lead count or purchase count. Compare like-for-like campaigns and check the native network's attribution settings.
- Each period reads up to 300 campaigns. Exceeding the cap, history backfill or a provider error shows a partial-data warning and suppresses headline percentage comparisons. Narrow to one account and refresh after backfill.
- Zernio returns at most 100 ad details per ad set. The report warns when details are truncated; campaign/ad-set totals still include the full provider aggregate.
- Empty successful responses mean no returned campaigns. Failed or backfilling responses are labeled incomplete, not zero-performance accounts.
- Workspace ownership, connection and ad-account scope are checked on the server. Campaign ownership is checked before audience requests. Membership is rechecked after provider reads.

## Social accounts and connections

Social accounts retains post analytics, daily breakdowns, previous-period comparisons, follower observations, top posts, historical posting-time suggestions, operational workload counts, CSV and print exports. Social post reports attribute lifetime metrics to posts published in the selected UTC range; they are not engagement received on those dates. Follower growth needs multiple observations. Connections lists actual account names, handles, channels and reconnect status.

## Installation and update

No new API key is needed beyond the deployment's server-side ZERNIO_API_KEY. Analytics availability depends on the connected network, provider plan and permissions. Deploy the updated Convex schema/functions before starting the updated frontend; the new reportLimits table is additive. Existing campaigns, budgets, automations and approval policies are unchanged.

Agent entry points: convex/adReporting.ts (scoped read actions), src/lib/ad-reporting.ts (normalization/calculation/export), src/components/ad-reporting.tsx (report UI), src/components/reporting-zone.tsx (sections), tests/ad-reporting.spec.ts (provider fixtures and authorization).

Provider contract: https://docs.zernio.com/api/openapi — ads/tree, ads/accounts and ads/campaigns/{campaignId}/analytics. Provider fixtures validate integration behavior; live paid-account acceptance still requires a connected advertising account.

## Report builder and branding

Select **Build report** to open the designer. You can save branding/layouts before an advertising account is connected; exports require a loaded report. Builder exports use the loaded account/date scope and the builder's own currency selection, not the dashboard's name/status filters.

- Start with Executive overview, Campaign deep dive or Client presentation. Add/remove/reorder cover, executive summary, metrics, daily trends, campaign comparisons, account breakdowns and recommendations. Mandatory data notes retain source dates, attribution caveats and partial-data warnings.
- Choose up to eight metric cards, a visualization metric, line/area/bar/table daily views, and bar/donut/table campaign/account views. Donuts are available only for nonnegative additive metrics in comparable currencies. Select 3–30 rows and toggle prior-period comparisons. Missing days retain their date positions instead of shifting comparisons.
- Branding includes title, client, subtitle, author, accent, footer and a PNG/JPEG logo up to 180 KB. Logos are embedded; reports do not load a remote tracking URL. Edit commentary under Content. Longer text flows to additional pages.
- Save named workspace layouts or independent copies. Administrators can set a workspace default. Members can create layouts but cannot overwrite the workspace default. Saved revisions prevent silently overwriting a teammate's changes. There are up to 30 layouts per workspace.
- **Download PDF** generates a real PDF locally in A4, US Letter or 16:9. Pages are high-resolution rendered images; PDF text is not currently selectable/tagged. The layout remains editable in the report builder. **Export deck** downloads a self-contained HTML presentation, with arrow-key navigation and an all-pages view; it opens offline. This is an HTML deck, not a PowerPoint file.
- PDF and deck generation do not require AI or send report data to an export service. Exports contain account performance and any commentary you add; share them with the intended client.

## Optional AI report assistant

Configure the workspace's OpenRouter key and text model under Settings → AI tools. In the builder's AI tab, explain the report's purpose and choose Suggest report. The server reads authorized provider metrics, sends period totals and up to 30 campaign names/metrics through OpenRouter, and returns a proposed title, summary, recommendations and layout. Requests use the existing 10/minute and 200/day AI limits and the buyer's credits.

Review the proposed draft before choosing Apply draft. AI cannot alter source metrics, publish a campaign, send a report or change branding. It can still make mistakes in commentary; review before export. The assistant uses a fresh or cached server report and can be newer than the current browser snapshot; refresh the report before final review when data is changing. All report design and exports work with no AI configured.