# `UtmParameters`

Where a visit came from (Google Analytics' UTM parameters): written as the query that carries them, `utm_source=mailing&utm_medium=email&utm_campaign=autumn_sale`; the term and the content only where a campaign uses them.

[Web and network](types.md#web-and-network); not ordered; since Jadpo 0.1.0.

## Make one

Build one from its fields, `UtmParameters { source: ...  medium: ...  campaign: ... }`.

`text.parse(raw, as: UtmParameters)` reads one from its text; text that isn't one at all fails `malformed`, such as `utm_source=mailing` or `""`.

## Fields

| Field | Type |
|---|---|
| `source` | `Text` |
| `medium` | `Text` |
| `campaign` | `Text` |
| `term` | `Text?` |
| `content` | `Text?` |

## Text, JSON and storage

`text.from` writes its canonical text, the one form `text.parse` reads back. JSON sends an object of its parts.

| Text | JSON |
|---|---|
| `utm_source=mailing&utm_medium=email&utm_campaign=autumn_sale` | `{"source":"mailing","medium":"email","campaign":"autumn_sale","term":null,"content":null}` |
| `utm_source=search&utm_medium=cpc&utm_campaign=spring&utm_term=running%20shoes&utm_content=banner` | `{"source":"search","medium":"cpc","campaign":"spring","term":"running shoes","content":"banner"}` |

It is stored in 5 columns, each named for the field, `_` and its suffix. This is `utm_source=search&utm_medium=cpc&utm_campaign=spring&utm_term=running%20shoes&utm_content=banner`:

| Column | Type | Holds |
|---|---|---|
| `<field>_source` | `text` | `'search'` |
| `<field>_medium` | `text` | `'cpc'` |
| `<field>_campaign` | `text` | `'spring'` |
| `<field>_term` | `text` | `'running shoes'` |
| `<field>_content` | `text` | `'banner'` |

## Shown to people

`text.format(value, locale:)` shows it to people in their locale.

With `locale: Locale.en_gb`:

| Value | Shown |
|---|---|
| `utm_source=mailing&utm_medium=email&utm_campaign=autumn_sale` | `utm_source=mailing&utm_medium=email&utm_campaign=autumn_sale` |
| `utm_source=search&utm_medium=cpc&utm_campaign=spring&utm_term=running%20shoes&utm_content=banner` | `utm_source=search&utm_medium=cpc&utm_campaign=spring&utm_term=running%20shoes&utm_content=banner` |

## Operations

It has the contract's own operations: `text.parse`, `text.from`, `text.format`, `json.read`, `json.write` and `==`. It isn't ordered, so `<` and sorting don't take it. [Every standard type meets one contract](../topics/every-standard-type-meets-one-contract.md) says how they work.