Tracking and attribution

Developer Hub

Dev Hub

Awell Hosted Pages supports UTM parameters and custom tracking data, enabling you to attribute sessions to specific marketing campaigns, partners, and traffic sources. Tracking data is captured when sessions are created and can be queried from BigQuery for reporting and analytics.

Why use tracking?

Adding tracking parameters to your Hosted Pages links helps you:

Measure campaign performance — Understand which campaigns drive the most session completions
Attribute traffic sources — Know where your patients are coming from (email, ads, partners, etc.)
A/B test content — Compare different ad creatives or landing pages
Track partner referrals — Monitor affiliate or partner-driven traffic with custom parameters

Adding tracking parameters

Standard UTM parameters

You can append standard UTM parameters to any Hosted Pages URL. These parameters are automatically captured when the session is created.

Parameter	Description	Example
`utm_source`	Which site/platform sent the traffic	`google`, `facebook`, `newsletter`
`utm_medium`	Type of link or marketing medium	`email`, `cpc`, `social`, `organic`
`utm_campaign`	Campaign identifier	`spring_promo`, `product_launch`
`utm_term`	Search terms (for paid search)	`healthcare software`
`utm_content`	Ad/content identifier for A/B testing	`banner_ad_1`, `text_link_v2`

URL examples

Custom domains

Replace goto.awell.health with your custom URL if you have configured one.

Custom tracking parameters

In addition to standard UTM parameters, you can pass any custom key-value pairs in the query string. These are captured in the tracking_custom field and can include:

Partner or affiliate IDs
Referral codes
Promo codes
Any other attribution data

Querying tracking data in BigQuery

Tracking data is stored in the hosted_sessions table in your BigQuery dataset. All tracking fields are nullable — sessions created without tracking data will have NULL values.

Available tracking fields

UTM parameter columns

These are stored as STRING columns and are nullable.

Column	Description
`tracking_utm_source`	The traffic source
`tracking_utm_medium`	The marketing medium
`tracking_utm_campaign`	The campaign identifier
`tracking_utm_term`	Search terms
`tracking_utm_content`	Content/ad identifier

JSON columns

These are stored as JSON columns and are nullable.

Column	Description
`tracking`	Full tracking object containing all UTM params plus any additional data
`tracking_custom`	Custom tracking key-value pairs (non-UTM parameters)

Basic query examples

View all sessions with tracking data

Count completed care flows by traffic source

Querying custom tracking data

Extract specific fields from the tracking_custom JSON column:

Advanced analysis examples

Conversion funnel by traffic source

Form completion rate by campaign

You can measure form completion rates by joining with other tables. Here are a couple of approaches:

Using the `forms` JSON column

The hosted_sessions table includes a forms JSON column that tracks which forms were completed within the session:

Using the `activities` table

You can also join with the activities table and filter by form name:

Finding form names and IDs

You can find form names by querying the activities table: SELECT DISTINCT object_name, object_id FROM activities WHERE object_type = 'form'

Tips and best practices

Establish consistent naming conventions for your UTM parameters (e.g. always lowercase, use underscores), which makes analysis much easier
Always use time filters — Add created_at >= ... filters to improve query performance on large datasets.
Check for NULL values — Many sessions may not have tracking data. Always filter with IS NOT NULL when analyzing tracked sessions.
Filter by status — Consider filtering by session status (or care flow status) for meaningful metrics:
Handle JSON parsing safely — Use SAFE.JSON_VALUE() if you encounter parsing errors with malformed JSON in custom tracking fields.
Dataset names — Replace your-project.your_dataset with your actual BigQuery project and dataset name (e.g., awell-production.customer_name).

Sessions and Links Built-in and customizable features