# Vlastní pole

> Definujte vlastní pole kontaktů, nastavujte jejich hodnoty ve webovém rozhraní, importem a přes API a používejte je ve filtrech, slučovacích značkách kampaní a automatizacích.

Vlastní pole ukládají ke každému kontaktu další data, například název firmy, tarif nebo datum narození. Pole definujete jednou pro celý workspace, pak je u kontaktů vyplníte a používáte je k filtrování kontaktů, personalizaci kampaní a spouštění automatizací.

## Typy polí

| Typ | Uložená hodnota | Příklad | Vstup ve webovém rozhraní |
| --- | --- | --- | --- |
| **Text** | Řetězec | `"Acme"` | Textové pole |
| **Number** | Číslo | `42` | Číselné pole |
| **Date** | Kalendářní datum, `YYYY-MM-DD` | `"1990-04-12"` | Výběr data |
| **Boolean** | `true`, nebo `false` | `true` | Zaškrtávací políčko |
| **Select** | Jedna možnost | `"pro"` | Rozbalovací seznam |
| **Multi select** | Pole možností | `["news", "offers"]` | Rozbalovací seznam s více volbami |

Každé pole má **název**, který zobrazuje webové rozhraní, a **klíč**, který používá API, importy, filtry a slučovací značky. Hodnoty se u kontaktu ukládají jako objekt JSON s klíči polí:

```json
{
  "company": "Acme",
  "plan": "pro",
  "birthday": "1990-04-12",
  "interests": ["news", "offers"]
}
```

## Vytvořte vlastní pole

1. **Otevřete Custom fields.** Přejděte do **Workspace → Settings → Custom fields** a vyberte **Add custom field**.

2. **Pojmenujte pole.** Do pole **Name** zadejte název, například `Company size`. Emailit z názvu automaticky sestaví klíč: malými písmeny a s každou skupinou jiných znaků nahrazenou znakem `_`, takže z `Company size` vznikne `company_size`.

   Pokud chcete klíč zvolit sami, vyberte **Show advanced options** a upravte pole **Key**. Klíče se vždy uloží v tomto tvaru s malými písmeny a podtržítky a každý klíč může ve workspace existovat jen jednou.

3. **Vyberte typ.** Zvolte **Text**, **Number**, **Date**, **Boolean**, **Select** nebo **Multi select**.

4. **Přidejte možnosti výběrových polí.** U typů **Select** a **Multi select** zadejte alespoň jednu možnost a další přidejte tlačítkem **Add option**. Tyto hodnoty se u kontaktů zobrazí v rozbalovacím seznamu.

5. **Uložte.** Vyberte **Create**. Pole se objeví u každého kontaktu, ve filtrech kontaktů a jako slučovací značka v editorech kampaní.

Stránka Custom fields uvádí všechna pole s názvem, typem a možnostmi. Tlačítkem **Edit** pole přejmenujete, změníte jeho typ nebo klíč, nebo upravíte jeho možnosti.

> **Smazání pole:** Smazáním vlastního pole ho odstraníte z webového rozhraní, filtrů, importů a slučovacích značek a tuto akci nelze vrátit zpět. Než klíč změníte nebo smažete, upravte všechny kampaně, automatizace a kód volající API, které ho používají.

## Nastavte hodnoty

| Kde | Jak |
| --- | --- |
| Webové rozhraní | **Add contact** nebo **Edit** u kontaktu. Vstupy zobrazíte výběrem **Show custom fields**. |
| Import | V průvodci importem namapujte sloupec souboru na vlastní pole. Viz [Import a export kontaktů](/cs/docs/contacts/import-export/). |
| API | Pošlete objekt `custom_fields` s klíči polí. |

Přes API předejte `custom_fields` endpointu [Vytvoření kontaktu](/cs/docs/api-reference/contacts/create/), nebo [Úprava kontaktu](/cs/docs/api-reference/contacts/update/):

```bash
curl https://api.emailit.com/v2/contacts/ada@example.com \
  -X POST \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "custom_fields": {
      "company": "Acme",
      "plan": "pro",
      "birthday": "1990-04-12",
      "interests": ["news", "offers"]
    }
  }'
```

Pravidla, která je dobré znát:

- **`custom_fields` nahradí celý objekt.** Při úpravě uveďte všechny hodnoty, které chcete zachovat, nejen ty, které se mění.
- **Používejte klíče polí, ne názvy.** Hodnoty pro klíče, které nejsou definované v **Custom fields**, se uloží, ale ve webovém rozhraní se nezobrazí.
- **Data musí být ve tvaru `YYYY-MM-DD`.** Emailit převádí na datum hodnoty datum a čas ve formátu ISO a datumové buňky z Excelu. Cokoli jiného vrátí `400` se zprávou „Custom field "Birthday" must be a date in YYYY-MM-DD format“. Data nemají čas ani časové pásmo.
- **Hodnoty výběrových polí se s možnostmi neporovnávají.** Hodnota, která v seznamu možností není, se přesto uloží a webové rozhraní ji dál zobrazuje.

## Filtrujte kontakty podle vlastního pole

Ve webovém rozhraní otevřete **Email Marketing → Contacts**, vyberte **Filter** a zvolte vlastní pole podle názvu. Filtry vlastních polí porovnávají uloženou hodnotu jako text, takže použijte **equals**, **does not equal**, **contains**, **does not contain**, **starts with**, **ends with**, **is empty** nebo **is not empty**.

Přes API použijte `custom_fields.<key>.<condition>` v endpointech [Výpis kontaktů](/cs/docs/api-reference/contacts/list/) a [Export kontaktů](/cs/docs/api-reference/contacts/export/) se stejnými textovými podmínkami (`exact`, `not_exact`, `contains`, `not_contains`, `starts_with`, `ends_with`, `empty`, `not_empty`):

```bash
curl "https://api.emailit.com/v2/contacts?custom_fields.plan.exact=pro&custom_fields.company.contains=acme" \
  -H "Authorization: Bearer $EMAILIT_API_KEY"
```

Pro rozsah, například data narození v 90. letech, použijte parametry `filter[custom_fields.<key>][gte]` a `[lte]`. Porovnávají uložený text, který se u dat ve tvaru `YYYY-MM-DD` řadí správně:

```bash
curl -G "https://api.emailit.com/v2/contacts" \
  --data-urlencode "filter[custom_fields.birthday][gte]=1990-01-01" \
  --data-urlencode "filter[custom_fields.birthday][lte]=1999-12-31" \
  -H "Authorization: Bearer $EMAILIT_API_KEY"
```

Jak se filtry kombinují, popisuje stránka [Filtrování a řazení](/cs/docs/api-reference/filtering/).

## Používejte vlastní pole v kampaních

Do obsahu a předmětu kampaně vložíte vlastní pole slučovací značkou `{{cf.<key>}}`, například `{{cf.company}}`. Editory formátovaného textu a Dragit nabízejí vaše vlastní pole mezi proměnnými, takže klíč psát nemusíte.

```html
<p>Hi {{first_name}}, here's what's new for {{cf.company}}.</p>
```

Pokud kontakt nemá žádnou hodnotu, značka se nahradí prázdným textem. Hodnoty vícevýběrových polí se vykreslí jako seznam oddělený čárkami. Viz [Slučovací značky](/cs/docs/campaigns/merge-tags/).

## Používejte vlastní pole v automatizacích

- **Spouštěč výročí data.** Vyberte pole typu **Date** a automatizace se spustí každý rok v měsíc a den, který je v něm uložený, například na narozeniny. Viz [Spouštěče](/cs/docs/automations/triggers/#date-anniversary).
- **Spouštěč úpravy kontaktu.** Filtrujte podle vlastního pole nebo jeho předchozí hodnoty a reagujte na jeho změnu.
- **Krok podmínky.** Větvěte podle hodnoty vlastního pole.
- **Krok úpravy kontaktu.** Nastavte vlastní pole zadáním jeho klíče.

## Reference API

Definice vlastních polí se spravují jen ve webovém rozhraní. Hodnoty u kontaktů používají objekt `custom_fields` v [API kontaktů](/cs/docs/api-reference/contacts/) a stejný objekt se přijímá i při [přidání odběratele](/cs/docs/api-reference/audiences/subscribers/add/) do seznamu kontaktů.

## Související

  - [Kontakty](/cs/docs/contacts/): Jak do sebe zapadají kontakty, seznamy kontaktů a odběratelé.
  - [Slučovací značky](/cs/docs/campaigns/merge-tags/): Personalizujte kampaně daty kontaktů.

---
Zdroj: https://emailit.com/cs/docs/contacts/custom-fields/