Documentation
¶
Overview ¶
Package growth implements Audience › Growth (audience-insights brief §3.4, M23): how contacts first joined and whether they left, by source (each form, the subscribe page, each import, API key and integration, people adding contacts; later referrals and recommendations), with the first touch's UTM parameters and referring page, monthly cohort retention, and bounce, complaint and human-open rates per source.
Moving a list isn't growth: imports are counted apart unless asked for.
Index ¶
- Constants
- func DomainOf(page string) string
- func EnglishLabel(src GrowthSource) string
- func Erasure() erasure.Source
- func Label(l i18n.Lang, src GrowthSource) string
- func PageOf(raw string) string
- func Register(h huma.API, s *Service)
- func RegisterAttributor(f Attributor)
- func RegisterJobs(reg *jobs.Registry, s *Service)
- func RegisterKind(k Kind)
- func RegisterNamer(kind string, f Namer)
- func SaveTouch(ctx context.Context, q *store.Queries, contact uuid.UUID, at time.Time, ...) error
- func SourceKey(kind, id string) string
- type Attributor
- type ContactJoin
- type GrowthChart
- type GrowthChartDay
- type GrowthCohort
- type GrowthDepartures
- type GrowthFile
- type GrowthImportItem
- type GrowthListRef
- type GrowthPage
- type GrowthPeriod
- type GrowthQuery
- type GrowthRates
- type GrowthReferrerRow
- type GrowthReferrers
- type GrowthRest
- type GrowthRetention
- type GrowthSeries
- type GrowthSource
- type GrowthSourceList
- type GrowthSourceOption
- type GrowthSourceRow
- type GrowthTiles
- type GrowthTotals
- type GrowthUTM
- type GrowthUTMRow
- type Kind
- type Namer
- type RollupArgs
- type Service
- func (s *Service) Attribute(ctx context.Context, ws *store.Workspace) error
- func (s *Service) ContactJoin(ctx context.Context, ws *store.Workspace, contactID uuid.UUID) (ContactJoin, error)
- func (s *Service) Export(ctx context.Context, ws *store.Workspace, in GrowthQuery) ([]byte, string, error)
- func (s *Service) Page(ctx context.Context, ws *store.Workspace, in GrowthQuery) (GrowthPage, error)
- func (s *Service) Rollup(ctx context.Context, wsID uuid.UUID, tz string, through *time.Time) error
- func (s *Service) RollupAll(ctx context.Context, only uuid.UUID) error
- func (s *Service) Sources(ctx context.Context, ws *store.Workspace) (GrowthSourceList, error)
- func (s *Service) Tick(ctx context.Context) error
- type TickArgs
- type Touch
Constants ¶
const ( KindForm = "form" // a signup form (embedded, popup or hosted) KindSubscribePage = "subscribe_page" // the built-in subscribe page KindImport = "import" // an import that gave contacts the import day as their join date KindCarried = "carried" // the source an import carried over from the old platform KindAPIKey = "api_key" // an API key KindIntegration = "integration" // an integration, with the workflow that calls it KindPerson = "person" // added by someone in ReputeCast KindPreferenceCenter = "preference_center" // a list added in the preference center (one-list view) KindUnknown = "unknown" )
Source kinds of the growth registry.
Variables ¶
This section is empty.
Functions ¶
func EnglishLabel ¶
func EnglishLabel(src GrowthSource) string
EnglishLabel names a source in English, for places that have no app text of their own (CSV exports, agents).
func Erasure ¶
Erasure is where the contact came from. Source, medium, campaign, page and referrer stay: they are kept as a host and path only and Audience › Growth counts joins by them. The free-form UTM content and term go (review 2026-11 DP-1).
func Label ¶
func Label(l i18n.Lang, src GrowthSource) string
Label names a source in a reader's language (the segment builder's growth sources): "Added by a person", "Brevo import (18 Sep)".
func PageOf ¶
PageOf is an address without its scheme, query string or fragment ("https://acme.io/pricing?plan=team#top" → "acme.io/pricing"). It returns "" for anything that isn't an http(s) address.
func RegisterAttributor ¶
func RegisterAttributor(f Attributor)
RegisterAttributor adds a way to attribute joins to a registered kind.
func RegisterJobs ¶
RegisterJobs adds the growth workers and their schedules.
func RegisterKind ¶
func RegisterKind(k Kind)
RegisterKind adds a source kind (phase 5: referral, recommendation).
func RegisterNamer ¶
RegisterNamer adds the names of a registered kind's sources.
Types ¶
type Attributor ¶
Attributor reads a registered kind's source from a contact's own source and its first consent record's (phase 5: "referral:<link>" on a contact who joined through a referral link, "partner:<link>" on a partner signup's consent).
type ContactJoin ¶
type ContactJoin struct {
Attributed bool `json:"attributed"`
Source GrowthSource `json:"source"`
JoinedAt *time.Time `json:"joinedAt,omitempty"`
UTMSource string `json:"utmSource"`
UTMMedium string `json:"utmMedium"`
UTMCampaign string `json:"utmCampaign"`
Referrer string `json:"referrer"`
Page string `json:"page"`
LeftAt *time.Time `json:"leftAt,omitempty"`
LeftKind string `json:"leftKind,omitempty"`
}
ContactJoin is how a contact first joined, for the profile's join line: "Joined Mon 13 Oct · Newsletter signup · linkedin / social / flags-ga · from docs.acme.io/flags".
type GrowthChart ¶
type GrowthChart struct {
Series []GrowthSeries `json:"series"`
Days []GrowthChartDay `json:"days"`
}
GrowthChart is joins above the axis and departures below, by day.
type GrowthChartDay ¶
type GrowthChartDay struct {
Day string `json:"day"`
Joined []int64 `json:"joined"`
Left []int64 `json:"left"`
Imports int64 `json:"imports"`
}
GrowthChartDay is one day of the chart: joins and departures per series (in Series order), and imports when they are included.
type GrowthCohort ¶
type GrowthCohort struct {
Month string `json:"month" doc:"YYYY-MM"`
Contacts int64 `json:"contacts"`
After30 GrowthRetention `json:"after30"`
After90 GrowthRetention `json:"after90"`
}
GrowthCohort is the contacts who joined in one month.
type GrowthDepartures ¶
type GrowthDepartures struct {
Unsubscribed int64 `json:"unsubscribed"`
HardBounced int64 `json:"hardBounced"`
Complained int64 `json:"complained"`
Erased int64 `json:"erased"`
}
GrowthDepartures are departures by kind.
type GrowthFile ¶
type GrowthFile struct {
ContentType string `header:"Content-Type"`
ContentDisposition string `header:"Content-Disposition"`
CacheControl string `header:"Cache-Control"`
Body []byte
}
GrowthFile is a CSV download.
type GrowthImportItem ¶
type GrowthImportItem struct {
Key string `json:"key"`
Name string `json:"name"`
Day string `json:"day"`
Count int64 `json:"count"`
}
GrowthImportItem is one import of the period.
type GrowthListRef ¶
GrowthListRef is the list counted in the one-list view.
type GrowthPage ¶
type GrowthPage struct {
Period GrowthPeriod `json:"period"`
List *GrowthListRef `json:"list,omitempty"`
// Members is true in the one-list view: it counts list members.
Members bool `json:"members"`
IncludeImports bool `json:"includeImports"`
Contacts int64 `json:"contacts"`
Tiles GrowthTiles `json:"tiles"`
Chart GrowthChart `json:"chart"`
Sources []GrowthSourceRow `json:"sources"`
Total GrowthTotals `json:"total"`
Workspace GrowthRates `json:"workspace"`
Departures GrowthDepartures `json:"departures"`
UTM GrowthUTM `json:"utm"`
Referrers GrowthReferrers `json:"referrers"`
Cohorts []GrowthCohort `json:"cohorts"`
CohortSource string `json:"cohortSource"`
CohortSources []GrowthSource `json:"cohortSources"`
Lists []GrowthListRef `json:"lists"`
OnlyImports bool `json:"onlyImports"`
Imports []GrowthImportItem `json:"imports" doc:"Every finished import, for the only-imports state"`
// MinContacts and MinDelivered are the "too few to compare" limits;
// FlagFactor is how many times the workspace's rate flags a source.
MinContacts int64 `json:"minContacts"`
MinDelivered int64 `json:"minDelivered"`
FlagFactor float64 `json:"flagFactor"`
}
GrowthPage is Audience › Growth.
type GrowthPeriod ¶
type GrowthPeriod struct {
Kind string `json:"kind" enum:"30d,90d,12m,custom"`
From string `json:"from" doc:"YYYY-MM-DD"`
To string `json:"to" doc:"YYYY-MM-DD"`
Days int `json:"days"`
}
GrowthPeriod is the period counted, in the workspace timezone.
type GrowthQuery ¶
type GrowthQuery struct {
Period string `query:"period" enum:"30d,90d,12m,custom," doc:"30d (default), 90d, 12m or custom"`
From string `query:"from" maxLength:"10" doc:"First day of a custom period (YYYY-MM-DD)"`
To string `query:"to" maxLength:"10" doc:"Last day of a custom period"`
List string `query:"list" doc:"A list id: count its members instead of contacts"`
// Imports adds imported contacts to the joins (a marker on the chart).
Imports bool `query:"imports"`
// CohortSource limits cohort retention to one source key.
CohortSource string `query:"cohortSource" maxLength:"200"`
}
GrowthQuery is what Audience › Growth shows: a period, all lists or one, with or without imports.
type GrowthRates ¶
type GrowthRates struct {
Sent int64 `json:"sent"`
Delivered int64 `json:"delivered"`
Bounce float64 `json:"bounce"`
Complaint float64 `json:"complaint"`
HumanOpen float64 `json:"humanOpen"`
}
GrowthRates are the workspace's own rates over the period's sends.
type GrowthReferrerRow ¶
GrowthReferrerRow is one referring page.
type GrowthReferrers ¶
type GrowthReferrers struct {
Rows []GrowthReferrerRow `json:"rows"`
None int64 `json:"none"`
Other GrowthRest `json:"other"`
Joins int64 `json:"joins"`
}
GrowthReferrers is the referring pages table.
type GrowthRest ¶
type GrowthRest struct {
Count int `json:"count"`
Joins int64 `json:"joins"`
HumanOpenRate *float64 `json:"humanOpenRate,omitempty"`
}
GrowthRest is the "Other, N …" row of a table.
type GrowthRetention ¶
type GrowthRetention struct {
// State is done, in_progress (some members haven't reached the mark)
// or not_started (none have).
State string `json:"state" enum:"done,in_progress,not_started"`
Rate *float64 `json:"rate,omitempty"`
// CompleteOn is when every member reaches the mark; From is when the
// first one does (a source whose first join is in this cohort).
CompleteOn string `json:"completeOn,omitempty"`
From string `json:"from,omitempty"`
}
GrowthRetention is one cohort's share still subscribed after a mark.
type GrowthSeries ¶
type GrowthSeries struct {
Key string `json:"key"`
Other bool `json:"other"`
Source GrowthSource `json:"source"`
Joined int64 `json:"joined"`
Left int64 `json:"left"`
}
GrowthSeries is one colour of the chart: one of the four biggest sources, or everything else ("other").
type GrowthSource ¶
type GrowthSource struct {
Key string `json:"key"`
Kind string `json:"kind"`
// Name is the form, API key, integration or import platform.
Name string `json:"name"`
// Imported sources are counted apart from growth.
Imported bool `json:"imported"`
// FormKind is embedded, popup or hosted.
FormKind string `json:"formKind,omitempty"`
// ListChoice is true when the form offers more than one list to pick.
ListChoice bool `json:"listChoice,omitempty"`
// Hosts are the sites a form's signups came from in the period.
Hosts []string `json:"hosts"`
// URL is the subscribe page's or a hosted form's address.
URL string `json:"url,omitempty"`
// KeyPrefix is an API key's masked prefix ("rc_live_8f2c…a91d").
KeyPrefix string `json:"keyPrefix,omitempty"`
// Integration and Workflow name an integration source ("Zapier",
// "Beta application (Typeform)").
Integration string `json:"integration,omitempty"`
Workflow string `json:"workflow,omitempty"`
// ImportedAt and ImportCount describe an import; TookImportDay is how
// many of its contacts got the import day as their join date (the
// others kept the date and source they came with).
ImportedAt *time.Time `json:"importedAt,omitempty"`
ImportCount int64 `json:"importCount,omitempty"`
TookImportDay int64 `json:"tookImportDay,omitempty"`
// Carried is the source an import kept ("import:csv", "form:docs");
// CarriedLabel says it in words.
Carried string `json:"carried,omitempty"`
CarriedLabel string `json:"carriedLabel,omitempty"`
// FirstJoin is the source's first join ever.
FirstJoin *time.Time `json:"firstJoin,omitempty"`
Order int `json:"-"`
}
GrowthSource names a source and says what the app needs to describe it. Names are workspace content (a form's or key's name); the app writes the words around them.
type GrowthSourceList ¶
type GrowthSourceList struct {
Items []GrowthSourceOption `json:"items"`
}
GrowthSourceList is every source contacts joined through.
type GrowthSourceOption ¶
type GrowthSourceOption struct {
Source GrowthSource `json:"source"`
Contacts int64 `json:"contacts"`
}
GrowthSourceOption is a source the contacts filter offers, with how many contacts came from it.
type GrowthSourceRow ¶
type GrowthSourceRow struct {
Source GrowthSource `json:"source"`
// Joined is nil for an import while imports are counted apart.
Joined *int64 `json:"joined,omitempty"`
Left int64 `json:"left"`
Net *int64 `json:"net,omitempty"`
// Contacts is how many contacts came from the source; with one list
// picked, how many members it brought to the list in the period.
Contacts int64 `json:"contacts"`
Sent int64 `json:"sent"`
Delivered int64 `json:"delivered"`
// Rates are nil when there are too few to compare.
BounceRate *float64 `json:"bounceRate,omitempty"`
ComplaintRate *float64 `json:"complaintRate,omitempty"`
HumanOpenRate *float64 `json:"humanOpenRate,omitempty"`
// TooFew says why rates aren't shown: contacts (under 50) or messages (under 100 delivered).
TooFew string `json:"tooFew,omitempty" enum:"contacts,messages,"`
// BounceFlag and ComplaintFlag are how many times the workspace's rate a
// flagged source has.
BounceFlag *float64 `json:"bounceFlag,omitempty"`
ComplaintFlag *float64 `json:"complaintFlag,omitempty"`
// contains filtered or unexported fields
}
GrowthSourceRow is one row of the sources table.
type GrowthTiles ¶
type GrowthTiles struct {
Joined int64 `json:"joined"`
Left int64 `json:"left"`
Net int64 `json:"net"`
// NetPct is the net change against the contacts (or members) at the
// start of the period.
NetPct float64 `json:"netPct"`
Imports int64 `json:"imports"`
ImportItems []GrowthImportItem `json:"importItems"`
}
GrowthTiles are the four numbers at the top.
type GrowthTotals ¶
type GrowthTotals struct {
Joined int64 `json:"joined"`
Left int64 `json:"left"`
Net int64 `json:"net"`
}
GrowthTotals is the sources table's last row.
type GrowthUTM ¶
type GrowthUTM struct {
CaptureStartedAt *time.Time `json:"captureStartedAt,omitempty"`
// Joins counts the joins through forms and the subscribe page;
// Captured those since capture began.
Joins int64 `json:"joins"`
Captured int64 `json:"captured"`
NotCaptured int64 `json:"notCaptured"`
NotCapRate *float64 `json:"notCapturedHumanOpenRate,omitempty"`
None GrowthUTMRow `json:"none"`
Rows []GrowthUTMRow `json:"rows"`
Other GrowthRest `json:"other"`
}
GrowthUTM is the UTM table.
type GrowthUTMRow ¶
type GrowthUTMRow struct {
Source string `json:"source"`
Medium string `json:"medium"`
Campaign string `json:"campaign"`
Joins int64 `json:"joins"`
// HumanOpenRate is nil until the combination's contacts got emails.
HumanOpenRate *float64 `json:"humanOpenRate,omitempty"`
}
GrowthUTMRow is one UTM combination.
type Kind ¶
type Kind struct {
Key string
// Imported kinds are counted apart from growth unless "Include
// imports" is on.
Imported bool
// Order groups sources in the table (forms first, imports last).
Order int
}
Kind is a source kind the registry knows. Later phases (referrals, recommendations) register theirs.
type Namer ¶
type Namer func(ctx context.Context, q *store.Queries, ws *store.Workspace) (map[string]string, error)
Namer names a registered kind's sources by id ("Partner · Ops Weekly").
type RollupArgs ¶
RollupArgs adds up the days before today's sends per source.
func (RollupArgs) InsertOpts ¶
func (RollupArgs) InsertOpts() river.InsertOpts
InsertOpts runs on the maintenance queue.
type Service ¶
type Service struct {
Pool *pgxpool.Pool
Q *store.Queries
Audit *audit.Logger
Log *slog.Logger
Now func() time.Time
// SubscribeURL is the address of a workspace's subscribe page
// ("https://news.acme.io/subscribe"), for the source's second line.
SubscribeURL func(ctx context.Context, ws *store.Workspace) string
}
Service is the growth domain.
func (*Service) Attribute ¶
Attribute runs the attribution step for one workspace: the first time it attributes every existing contact; after that what joined or left since.
func (*Service) ContactJoin ¶
func (s *Service) ContactJoin(ctx context.Context, ws *store.Workspace, contactID uuid.UUID) (ContactJoin, error)
ContactJoin returns a contact's attribution.
func (*Service) Export ¶
func (s *Service) Export(ctx context.Context, ws *store.Workspace, in GrowthQuery) ([]byte, string, error)
Export writes the Growth tables as CSV: totals only, never an address. Each export is in the audit log, as report exports are.
func (*Service) Page ¶
func (s *Service) Page(ctx context.Context, ws *store.Workspace, in GrowthQuery) (GrowthPage, error)
Page returns everything Audience › Growth shows.
func (*Service) RollupAll ¶
RollupAll writes the days not rolled up yet in every workspace (or one).
type TickArgs ¶
type TickArgs struct{}
TickArgs attributes new joins and departures in every workspace.
func (TickArgs) InsertOpts ¶
func (TickArgs) InsertOpts() river.InsertOpts
InsertOpts runs on the events queue, once a minute.
type Touch ¶
type Touch struct {
UTMSource, UTMMedium, UTMCampaign, UTMContent, UTMTerm string
// Page is the page with the form and Referrer the page before it,
// both without their query string or fragment ("acme.io/pricing").
Page, Referrer string
}
Touch is where one signup came from.