Marketing Audience Building
Summary
Audience building turns targeting intent into previewable, materializable membership. It covers Audience Studio, SQL-backed and rule-backed definitions, identity scope, suppression preview, and the geo saved-selection handoff. It does not own geo source discovery or spatial scoring.
Reader Question
How does marketing decide who can enter a campaign run, and where exactly does geo hand off selected opportunity to marketing?
Surface Or Workflow
Operators enter through audience list/detail, new audience wizard, Audience Studio, and geo selection import. They need to preview candidate counts, inspect rule intent, understand identity scope, and bind audiences to campaigns.
Lifecycle
The lifecycle starts with an audience definition. Marketing validates the definition, identity scope, rule shape, generated SQL, sample rows, and campaign bindings. At run start, runtime audience materialization loads candidate rows, applies suppression and exposure policy, assigns variants, and creates run-owned members and member steps.
Geo crosses in only through saved selections. Geo owns the selected H3 set, aggregate summary, and candidate resolution. Marketing imports the saved selection as an audience source and materializes candidates through normal marketing runtime rules.
Child Threads
marketing-domain-data-model: audience authoring and runtime membership tables.marketing-tenant-and-data-boundary-guardrails: tenant scope and generated SQL safety.- Geo Saved Selections
- Geo Marketing Audience Handoff
Implementation Boundaries
services/marketing/authoring/audience_studio owns audience authoring. services/marketing/authoring/geo_audience_import imports saved geo selections. services/marketing/runtime/audience materializes run members. services/geo/selections remains the geo-owned saved-selection boundary.
Tradeoffs
Audience building has to be flexible without becoming arbitrary database access. The platform accepts more service code and tests so audience authors can work quickly while runtime still receives typed, auditable membership.
Visual
The current visual is a graph neighborhood. The intended visual is an audience lifecycle diagram from definition or geo selection to preview, suppression, materialization, members, and review/runtime use.
Audience As A Contract
Audience building is not just a query builder. It is the contract between a source population and a campaign run. That contract needs to answer four questions: who is eligible, why are they eligible, what policy can remove or modify them, and what exact membership did a run use? If any of those answers are missing, the platform cannot explain outreach after the fact.
The authoring side of the audience workflow is exploratory. Operators need to define rules, inspect generated SQL or rule summaries, preview sample rows, understand counts, and bind the audience to campaigns. They may start from a marketing source, a customer or prospect population, a saved geo selection, or future source types. The system should make exploration efficient without letting arbitrary database access become runtime truth.
The runtime side is stricter. A run materializes the audience it will process. Materialization creates run-owned members and member-step state. It applies suppression and exposure policy, records source context, and preserves enough lineage to explain membership. That is the point where "this audience could include these candidates" becomes "this run included these members under these rules."
Preview, Suppression, And Materialization
Preview is for author confidence. It shows whether the definition appears to select the expected population. A preview can surface generated SQL, counts, sample rows, missing scope, or obvious policy problems. It should be fast enough for iteration and explicit enough that an operator can catch mistakes. But preview is not a substitute for materialization because it does not create the durable membership record a run needs.
Suppression is a first-class stage between candidate membership and contactable membership. It may remove people because of channel policy, prior contact, global suppression, campaign rules, customer status, or other safety constraints. Treating suppression as a named policy stage matters because it lets the operator distinguish "not in the source population" from "in the population but not contactable." Those are different business facts.
Materialization is where the platform commits to a run-specific set. It should record the source type, source identifiers, member identity, suppression outcome, variant assignment, and downstream member-step state. That record is what later rendering, review, delivery, attribution, and repair use. Without materialization, every later stage would have to rerun a potentially changed audience definition.
Geo Handoff
The geo handoff is a good example of why audience building needs a boundary instead of direct table coupling. Geo owns source discovery, geocoding, H3 features, drive-time scoring, map inspection, and saved selections. Marketing does not need to know how every cell was scored in order to run a campaign. Marketing needs a durable selection artifact that can be imported, previewed, suppressed, and materialized under campaign rules.
That handoff preserves both sides. Geo can improve spatial methodology, refresh candidate context, or add new map layers without rewriting campaign runtime. Marketing can change eligibility, suppression, and variant assignment without owning spatial compute. The connection between the two is explicit enough to audit but narrow enough to preserve module ownership.
The same pattern should apply to future sources. If another module produces a reviewed population, marketing should import it through a source contract rather than copying its internals. Audience building is where external or adjacent intent becomes campaign eligibility.
Failure Modes
Audience failures often masquerade as empty counts. The real cause may be a broken source, missing tenant scope, invalid generated SQL, stale geo selection, suppression removing all candidates, identity resolution gaps, variant assignment errors, or runtime materialization problems. The platform should expose those distinctions because the repair path differs.
An authoring error should return to the audience definition. A source freshness problem should point to the source owner. A suppression surprise should show policy detail. A runtime materialization failure should become run-owned state or an issue. A downstream delivery problem belongs to rendering or notification, not audience authoring. This is the reason the audience thread links into methodology, geo handoff, suppression policy, runtime execution, and review rather than trying to explain every detail here.
Reader Heuristics
When reading audience code, check whether a function is previewing, importing, materializing, or using members. Preview can be flexible. Import should create a stable source boundary. Materialization should be deterministic and run-owned. Runtime use should not reinterpret authoring rules. If those verbs are mixed together, the audience system becomes hard to explain and harder to repair.
Audience Quality Signals
Audience quality is not just count size. A large audience can be poor if identity resolution is weak, source freshness is stale, suppression is surprising, or the source population does not match campaign intent. A small audience can be valuable if it is precise and explainable. Audience Studio and runtime materialization should therefore expose enough quality signals for an operator to understand the population before it becomes outreach.
Useful signals include source freshness, sample rows, generated SQL disclosure, identity scope, suppression counts, geo selection metadata, prior exposure, and missing-context warnings. These signals help both authoring and later review. If a campaign underperforms, the team can ask whether the message was wrong, the channel was wrong, or the audience was never a good fit.
That connection to attribution is important. Audience building is the first step in measurement quality. If membership is not explainable, response attribution later becomes guesswork.
Working From The UI Backward
Audience Studio is best understood from the operator's sequence of questions. What population am I starting from? Which criteria narrow it? Which geo selection or saved segment contributes members? What will suppression remove? What identity will runtime use to contact or attribute those members? Can I inspect enough examples to trust the result before it is used by a campaign?
The backend model should make those questions answerable. Generated SQL disclosure helps a technical operator inspect how a definition resolves. Preview rows help catch surprising joins or stale attributes. Suppression counts show how policy changes the final population. Geo metadata tells the reader whether an audience came from parcels, H3 cells, drive-time scoring, or saved selections. Materialized snapshots make a campaign run reproducible even if the source data changes later.
This is also where audience building becomes a cross-module surface rather than a marketing-only feature. Geo analysis, customer records, job history, service area facts, provider identities, and campaign policy can all contribute to audience membership. The audience boundary gives those sources a single explainable contract before runtime uses them.
The same contract helps after the campaign runs. When an operator evaluates results, audience membership should still be explainable. Otherwise attribution and learning collapse into vague impressions rather than useful feedback.
Source Evidence
app/web/app/marketing/audiencesapp/web/app/marketing/geo-analysisapp/api/marketing/audiencesservices/marketing/authoring/audience_studioservices/marketing/authoring/geo_audience_importservices/marketing/runtime/audienceservices/marketing/runtime/geoservices/geo/selectionstests/marketing