Getting Started and Onboarding Process

Onboarding Process

The onboarding process consists of two simple steps:

• Implement link tracking to your URLs using a proprietary and simple method

• Delegate API access to the marketing platforms

Which UTM parameters does Ad Performance require

Standard UTM parameters (always required)

These are the baseline UTMs already recognized by Piano Analytics for marketing source attribution:

• utm_source

• utm_medium

• utm_campaign

If these are missing or empty, Ad Performance cannot attribute the visit to a campaign at all.

Supplementary UTM parameters required by Ad Performance

In addition to the standard UTMs, Ad Performance reads the following parameters to identify the specific campaign, ad group, ad, and platform within the ad account:

The IDs are typically populated dynamically by the ad platform's own templating syntax (for example, {{campaign.id}} in Meta Ads or {campaignid} in Google Ads).

Examples

Google Ads — final URL suffix

&utm_source=google&utm_medium=cpc&utm_campaign={campaign}
&utm_cid={campaignid}&utm_agid={adgroupid}

Meta Ads — URL parameters

&utm_source=meta&utm_medium=cpc&utm_campaign={{campaign.name}}
&utm_cid={{campaign.id}}&utm_agid={{adset.id}}&utm_adid={{ad.id}}
&utm_platform={{site_source_name}}

Common pitfalls

• URL shorteners (bit.ly, etc.) break Ad Performance. Shorteners redirect through their own URL, which strips the original parameters before the landing page is loaded. Use the ad platform's own tracking template instead of a third-party shortener.

• Existing UTM properties on events are event-scoped. UTM properties only populate on the event where the URL contained them (typically the first page.display). For conversion tracking, see the section on visit-scoped src_… properties in the standard UTMs FAQ.

• utm_cid is distinct from utm_campaign. utm_campaign carries the human-readable campaign name; utm_cid carries the numeric ID that Ad Performance uses to join to the platform's cost data. Including only one of them is insufficient.

How the delegation works

1. Tell Piano which accounts you want to connect. Provide a list of the ad account IDs you want included, the platform for each (Google Ads or Meta Ads), and any naming context (for example, regional accounts: "EU", "US", "APAC"). You may have multiple accounts per platform — list each separately.

2. Receive delegation links. Piano sends one delegation link per account. Each link is valid for a limited time after generation (typically a few days); if the link expires before you click it, ask Piano to reissue it.

3. Authorize from an account with admin rights. Click the delegation link while logged into the relevant ad platform with an administrator account on the target organization (not just an individual user account). Standard users cannot authorize API delegation.

4. Confirm activation. Once delegation is granted, Piano enables Ad Performance for that account. Data begins flowing on the next daily import.

Adding accounts later

You don't need to enumerate every account up front. New accounts can be added at any time:

1. Open a Support ticket (or contact your account manager) with the new account IDs and platform.

2. Receive a delegation link for each new account.

3. Authorize as above. The new accounts start flowing data on the next daily import after delegation completes.

Adding accounts beyond your contracted limit incurs the per-account add-on fee — see the Key Information article for current pricing.

Regional accounts and multi-account setups

For organizations with regional or product-line ad accounts (for example, separate Google Ads accounts for EU, US, and APAC), each account is connected individually via its own delegation link. Once connected, all accounts feed into the same Ad Performance data model in your Piano Analytics organization, so cross-account analysis (e.g., total spend across all regions) is possible directly from the Ad Performance Workspaces board.

Trial

If you are unsure, Piano Analytics offers a 30-day trial of the Ad Performance feature so you can evaluate it on real campaign data before committing to a subscription.

What the trial includes

• Duration: 30 days from activation.

• Scope: One ad account — either a single Google Ads account or a single Facebook/Meta Ads account, not both.

• Functionality: Full Ad Performance behavior for the trialed account — automated daily data import, the dedicated Ad Performance data model (AP properties), and access to the standard Workspaces board for Ad Performance.

You can use the trial to validate the value of the feature on real data, train your team on the boards, and confirm that your UTM parameter setup meets the Ad Performance requirements before going live more broadly.

Prerequisites

Before requesting a trial, make sure:

• Your tagging is on Piano Analytics SDK 6.0+ (or, for sites still on legacy tagging, SmartTag 5.29.4+).

• The ad account you want to trial is on a supported platform: Google Ads or Facebook/Meta Ads. (Search Ads 360 is not supported by Ad Performance, trial or otherwise.)

• The URLs you use in that ad account's campaigns include the supplementary UTM parameters required by Ad Performance. See the dedicated UTM parameters article for the exact list.

• URLs are not shortened by a third-party URL shortener — Ad Performance cannot read the necessary UTM parameters from shortened URLs.

How to request the trial

1. Contact your Piano Analytics account manager (or support@piano.io if you don't yet have one assigned) and ask for an Ad Performance trial.

2. Provide the ad account ID you want to trial and the platform (Google Ads or Meta).

3. Piano will send you a delegation link for the platform. Click the link and grant Piano Analytics the necessary API access to the account.

4. Once delegation is confirmed, Piano enables Ad Performance on the trialed account. Data begins flowing on the next daily import cycle (J+1 — see the data ingestion note in the eligibility doc).

After the trial

At the end of the 30-day window:

• If you decide to subscribe, your account manager will convert the trial into a paid Ad Performance subscription. Data continuity is preserved — no re-onboarding needed.

• If you do not subscribe, the trialed account is disconnected and Ad Performance stops importing data from it. Historical data collected during the trial remains visible in your Piano Analytics account for the standard data retention period.