Atrea User API

Tmavý režim

Typy notifikací & šablony ​

Notifikační typy ​

Notifikační typ definuje kategorii notifikace — co se oznamuje, jakými kanály a zda to může uživatel vypnout.

Struktura ​

typescript
{
  id: number;
  applicationCode: string;
  code: string;              // unikátní kód v rámci aplikace
  name: string;              // zobrazovaný název (pro UI preferencí)
  description: string | null;

  emailEnabled: boolean;     // email kanál povolen pro tento typ
  pushEnabled: boolean;      // push kanál povolen pro tento typ
  userCanDisable: boolean;   // může uživatel typ vypnout?

  defaultEmail: boolean;     // výchozí stav email pro nové uživatele
  defaultPush: boolean;      // výchozí stav push pro nové uživatele
}

userCanDisable ​

Pokud userCanDisable = false, uživatel nemůže tento typ vypnout ve svých preferencích. Vhodné pro kritické systémové notifikace (bezpečnostní upozornění, platební potvrzení).

Výchozí preference ​

Při prvním přístupu uživatele k notifikačním preferencím se vytvoří záznamy s hodnotami defaultEmail a defaultPush. Uživatel je pak může změnit (pokud userCanDisable = true).

Správa typů ​

bash
# Vytvoření
POST /api/admin/notifications/types/:appCode
{
  "code": "security_alert",
  "name": "Bezpečnostní upozornění",
  "emailEnabled": true,
  "pushEnabled": true,
  "userCanDisable": false,   # uživatel NEMŮŽE vypnout
  "defaultEmail": true,
  "defaultPush": true
}

# Aktualizace
PUT /api/admin/notifications/types/detail/:id

# Smazání
DELETE /api/admin/notifications/types/detail/:id

Šablony ​

Šablona definuje vizuální podobu notifikace pro konkrétní typ a locale.

Struktura ​

typescript
{
  id: number;
  applicationCode: string;
  type: string;              // kód notifikačního typu
  locale: string;            // "cs", "en", "de", ...

  subjectTemplate: string;   // Mustache šablona předmětu
  bodyTemplate: string;      // Mustache HTML šablona těla

  description: string | null;
}

Unikátní kombinace ​

Každá šablona je unikátní kombinací (application, type, locale). Pro jeden typ může existovat více šablon — pro různá locale.

moje-app + new_order + cs   → česká šablona
moje-app + new_order + en   → anglická šablona

Fallback na locale ​

Při odesílání notifikace se locale určí v tomto pořadí:

  1. Pole locale v request body
  2. UserProfile.locale příjemce
  3. Fallback na "cs" pokud šablona pro locale neexistuje
  4. Pokud neexistuje ani "cs" šablona → skipped

Mustache šablony ​

Šablony používají jednoduchou Mustache syntaxi:

Základní syntax ​

{{proměnná}}           — vykreslí hodnotu

Příklad šablony ​

Subject:

Nová objednávka č. {{orderNumber}} od {{customerName}}

Body (HTML):

html
<!DOCTYPE html>
<html>
<body>
  <h1 style="color: {{brandPrimaryColor}}">Nová objednávka!</h1>
  
  <p>Přijali jsme objednávku č. <strong>{{orderNumber}}</strong></p>
  
  <table>
    <tr><td>Zákazník:</td><td>{{customerName}}</td></tr>
    <tr><td>Email:</td><td>{{customerEmail}}</td></tr>
    <tr><td>Hodnota:</td><td>{{totalAmount}} Kč</td></tr>
  </table>
  
  <p>
    <a href="{{orderUrl}}" style="color: {{brandLinkColor}}">
      Zobrazit objednávku
    </a>
  </p>
  
  <hr>
  <small>{{brandFooterText}}</small>
</body>
</html>

Automaticky dostupné proměnné (brand context) ​

ProměnnáObsah
Hlavní barva brandu (hex)
Tmavší varianta hlavní barvy
Barva pozadí
Barva textu
Barva odkazů
URL loga brandu
Text v patičce
Název brandu
Odesílací email

Brand se načte dle UserProfile.brand příjemce. Pokud brand neexistuje, použije se výchozí brand.

Uživatelská data ​

Proměnné z pole data requestu jsou přímo dostupné:

bash
POST /api/internal/notifications
{
  "data": {
    "orderNumber": "2024-042",
    "customerName": "Jan Novák",
    "totalAmount": "15000"
  }
}

V šabloně: , ,

Preview šablony ​

Před nasazením šablony si ji lze vyzkoušet:

bash
POST /api/admin/notifications/templates/preview
Authorization: Bearer <superadmin-token>
{
  "subjectTemplate": "Objednávka č. {{orderNumber}}",
  "bodyTemplate": "<h1>Přijata!</h1><p>{{orderNumber}} — {{totalAmount}} Kč</p>",
  "data": {
    "orderNumber": "TEST-001",
    "totalAmount": "5000"
  },
  "brand": "atrea"
}

Response ​

json
{
  "data": {
    "subject": "Objednávka č. TEST-001",
    "htmlBody": "<h1>Přijata!</h1><p>TEST-001 — 5000 Kč</p>"
  }
}

Checklist pro nový notifikační typ ​

  • [ ] Vytvořit NotificationType přes POST /admin/notifications/types/:appCode
  • [ ] Vytvořit šablonu pro výchozí locale (cs) přes POST /admin/notifications/templates/:appCode
  • [ ] Vytvořit šablony pro ostatní locale (en, de, ...)
  • [ ] Otestovat preview šablony s testovacími daty
  • [ ] Ověřit, že backend aplikace posílá správná data pro šablonu
  • [ ] Zkontrolovat emailEnabled / pushEnabled dle požadavků
  • [ ] Rozhodnout o userCanDisable (kritické notifikace = false)

Atrea User API — interní dokumentace

© 2024 Atrea