sidebar_position: 10 sidebar_label: Ad Networks

Ad Networks

Connect advertising platforms to track conversions and optimize ROAS.

Ad Networks lets you send conversion data from your links and install events directly to the advertising platforms you use to run campaigns. When a user clicks your ad, installs your app, or completes a purchase, Linkzly forwards that conversion event to your connected ad platform so it can attribute the action to the right campaign and optimize future spend.

How it works: Linkzly uses server-to-server (S2S) API calls to send events to ad platforms. There is no JavaScript pixel or client-side tracking script involved. Events are delivered directly from Linkzly's backend to the provider's API, which improves reliability and works even when users have ad blockers enabled.

Navigating to Ad Networks

In the left sidebar, under the Integration section, click Ad Networks (Megaphone icon).

You land on the main Ad Networks page with two tabs:

Tab	What it shows
Providers	All advertising platforms available to connect, with their status
Connections	Your active integrations — connected, pending, or failed

Each tab has a badge showing the count for that view, and a search bar to filter by name.

Providers Tab

The Providers tab lists all advertising platforms supported by Linkzly. Each provider card shows:

Provider logo
Provider name and description
Category badge (e.g., SEARCH, SOCIAL, APP)
Feature tags (up to 4 visible, with a "+X more" indicator if there are additional)
A documentation link (external icon, top-right corner)
A connect button or status indicator

Available Providers

Provider	Category	Features
Google Ads	Search	Conversion Tracking, App Install Attribution, ROAS Optimization, Offline Conversions
Meta Ads	Social	Conversions API, App Events, Custom Audiences, Offline Conversions
Snapchat Ads	Social	Snap Pixel, App Conversions, Offline Conversions

Coming Soon

Provider	Category	Notes
TikTok Ads	Social	—
Apple Search Ads	App	Premium
X Ads	Social	—

Provider cards for Coming Soon platforms show a clock icon badge and a disabled "Coming Soon" button. If a provider is already connected, the card shows a green "Connected" badge and the button changes to "Add Another Connection".

Connecting an Ad Network

Clicking "Connect {Provider}" on a provider card opens a 3-step setup wizard.

Step 1: Connect Account (OAuth)

Click Connect with {Provider} to begin the OAuth authorization flow. You will be redirected to the provider's website to log in and grant Linkzly the necessary permissions.

After authorizing, you are redirected back to Linkzly. The step shows a green confirmation box with a checkmark, your connected email address, and a Disconnect button if you need to switch accounts.

Linkzly uses OAuth 2.0 with CSRF state protection for all providers. Your access and refresh tokens are stored encrypted (AES-256) in the database and are automatically refreshed before they expire.

Step 2: Select Account

Choose which ad account to use for this integration from the dropdown. Options are listed as "{Account Name} ({Account ID}) [status]".

Provider	Dropdown Label
Google Ads	Google Ads Account
Meta Ads	Meta Ad Account
Snapchat Ads	Snap Ad Account

Step 3: Map Conversions

Select the conversion event you want to send to the provider. This maps a Linkzly install event to a specific conversion action defined in your ad account.

Provider	Dropdown Label
Google Ads	Conversion Action
Meta Ads	Pixel Event
Snapchat Ads	Snap Pixel Event

Options are listed as "{Event Name} ({Category})".

Finally, enter an Integration Name to identify this connection (for example, "Google Ads - Main Account"). This field is required.

Click Create Integration to finish. The button remains disabled until all fields are filled in.

Managing Connections

The Connections tab lists all integrations you have created.

Connection Card

Each connection card displays:

Provider logo
Integration name (the custom name you entered during setup)
Status badge — see the table below
Inactive badge — shown if the integration has been deactivated
Details line: "{Provider Name} | {Account Name} | {Conversion Event Name}"
"Connected as: {email}" — the OAuth account used
"Last sync: {date}" — hidden on mobile
Configure button (Settings icon) — opens the integration detail page
⋮ action menu

Connection Statuses

Status	Color	Meaning
connected	Green	The integration is active and sending events successfully
pending	Yellow	OAuth is in progress or the integration is being set up
failed	Red	Event delivery has failed — check configuration
disconnected	Gray	The integration has been manually disconnected
expired	Orange	The OAuth token has expired and needs to be re-authorized

Connection Statistics

Each connection tracks the following metrics:

Stat	Description
Total Events Sent	Cumulative count of events forwarded to this provider
Successful Events	Events accepted by the provider
Failed Events	Events that could not be delivered
Last Sync	Timestamp of the most recent sync attempt

Action Menu (⋮)

Click the ⋮ icon on any connection card to access:

Action	Description
Test Connection	Sends a test event to verify the integration is working
Sync Now	Triggers an immediate sync (the icon spins while syncing)
Activate / Deactivate	Toggles whether the integration is actively sending events
Delete	Permanently removes the integration

Deleting a Connection

When you click Delete, a confirmation dialog appears:

"Are you sure you want to delete '{name}'? This will stop sending conversion events to {provider}. This action cannot be undone."

You must confirm to proceed. Deletion immediately stops all event forwarding to that provider.

Empty State

If you have not created any connections yet, the Connections tab shows:

"No connections yet — Connect your first ad network to start tracking conversions"

A Browse Providers button takes you back to the Providers tab.

How Tracking Works

Server-to-Server (S2S) API

Linkzly uses server-to-server API calls exclusively. There is no JavaScript pixel or client-side tracking script. When a qualifying install or conversion event occurs, Linkzly's backend sends the event payload directly to the provider's API endpoint.

This approach offers several advantages:

Ad blocker resistant — No client-side script means ad blockers and browser restrictions do not interfere with event delivery
Higher accuracy — Events are sent from the server, not dependent on the user's browser or device
Privacy-safe — No third-party scripts running in your users' browsers

Inbound Postbacks

If you are using a mobile attribution platform or external system that sends postbacks to Linkzly, use this endpoint:

POST /api/ad-networks/postbacks/install

Authenticate requests with the x-postback-secret header (use the value from your AD_NETWORK_POSTBACK_SECRET environment variable). When Linkzly receives a valid install postback, it distributes the event to all active integrations for your organization in parallel.

Data Fields Sent Per Event

Standard fields sent with every conversion event:

Field	Description
`eventName`	The name of the conversion event
`eventTime`	Unix timestamp of when the event occurred
`userId`	Your user's identifier
`email`	User email (hashed where required by provider)
`phone`	User phone number (hashed where required by provider)
`clientIpAddress`	IP address of the device
`clientUserAgent`	Browser or app user agent string
`transactionId`	Unique ID for deduplication
`value`	Monetary value of the conversion
`currency`	ISO currency code (e.g., `USD`, `EUR`)

Provider-specific click IDs are also included when available:

Provider	Click ID Fields
Google Ads	`gclid`, `gbraid`, `wbraid`
Meta Ads	`fbc` (Facebook Click ID), `fbp` (Facebook Pixel ID)
Snapchat Ads	`sccid` (Snapchat Click ID), `uuid_c1`, `mobileAdId`

Additional arbitrary fields can be passed in a customData JSON object for provider-specific parameters not covered above.

Provider Details

Google Ads

API: Google Ads API v19, OAuth 2.0

Account format: Customer ID with dashes — XXX-XXX-XXXX

Click ID requirements: At least one of gclid, gbraid, or wbraid must be present for Google to match the conversion back to a specific ad click.

Currency: If a conversion value is included, a currency code is required.

Event type label: Conversion Action

Meta Ads

API: Meta Graph API v21.0, Conversions API v2, OAuth 2.0

Required identifier: Pixel ID. At least one of the following must be present: fbc, fbp, or user data (email, phone, or userId). Meta uses these to match events to users in their system.

Click IDs:

fbc — Facebook Click ID (captured from the _fbc cookie, populated when a user clicks a Facebook ad)
fbp — Facebook Pixel ID (captured from the _fbp cookie)

Event type label: Pixel Event

Snapchat Ads

API: Snapchat API v2, OAuth 2.0

Required identifier: Snap Pixel ID. At least one of the following must be present: sccid, uuid_c1, or user data.

Click IDs:

sccid — Snapchat Click ID
uuid_c1 — Snapchat user identifier cookie
mobileAdId — Mobile advertising ID (IDFA or GAID)

Event type label: Snap Pixel Event

Tips

Name your integrations clearly. If you connect the same provider multiple times (e.g., multiple ad accounts), use descriptive names like "Google Ads - Brand Campaigns" and "Google Ads - Performance Max" so you can tell them apart in the Connections list.
Use Test Connection before going live. After creating an integration, use the ⋮ menu to run a test. This confirms the OAuth token is valid and events are reaching the provider before real traffic flows through.
Check failed events promptly. A rising failed event count usually means a token has expired or a required click ID field is missing. Open the ⋮ menu and run "Sync Now" after fixing the issue to resume delivery.
Re-authorize expired tokens. If a connection shows an "expired" status, click Configure and go through the OAuth flow again to issue a fresh token. Linkzly automatically refreshes tokens that are close to expiry, but a manual re-authorization may be needed if the token was revoked by the provider.
Google Ads click IDs are required for attribution. Conversions sent without gclid, gbraid, or wbraid cannot be matched to a specific ad click in Google Ads and will not contribute to bidding optimization. Make sure your landing pages or app flows are passing these values through to the conversion event.
Deactivate, do not delete, when pausing campaigns. If you want to temporarily stop sending events to a provider, use Deactivate from the ⋮ menu. This preserves your configuration. Deleting a connection removes all settings and cannot be undone.