Események beküldése API-n keresztül

Hogy lehet eseményeket beküldeni az AtomDMP rendszerébe.

2022.11.01 — Posted by Webb & Flow


API kapcsolat

Az esemény beküldő API a https://api.atomdmp.com domain alatt érhető el. Az események beküldése 2 módon lehetséges:

  • nem igényel authentikációt
  • authentikációhoz kötött

A projekt indításakor kell meghatározni, hogy az API elfogadjon-e authentikáció nélküli adatbeküldést. ( Authentikáció nélküli lehet egy weblapba épített javascript kód, authentikációhoz kötött lehet egy backend hívás). A kommunikáció JSON formátumban történik.

Esemény beküldése authentikáció nélkül

Kizárólag akkor lehet authentikáció nélkül eseményt beküldeni, ha a https://simple.atomdmp.com felületen a Config / Script menü alatt az “Accept unauthorized events” értéke “Yes” (ez az alap beállítás):

Amennyiben ez le van tiltva, kizárólag authentikált módon lehet eseményeket beküldeni.

Eseményeket a POST /track/event végponton lehet beküldeni.

Paraméterek:

  • domain
    • kötelező
    • annak a projektnek a domain neve, amibe az eseményt küldeni kell
  • email
    • kötelező
    • az eseményt kiváltó user email címe
  • event
    • kötelező
    • az esemény neve
  • params
    • opcionális
    • 1 szintű asszociatív tömb
    • minden érték egy skaláris érték lehet
      • string
      • int
      • float
      • dátum esetén datetime string valamelyik formátumban a következők közül:
        • W3C
        • unix timestamp (PHP: U)
        • ÉÉÉÉHHNN (PHP: Ymd)
        • ÉÉÉÉ-HH-NN (PHP: Y-m-d)
        • ÓÓPPSS (PHP: His)
        • ÓÓ:PP:SS (PHP: H:i:s)

Az authentikáció nélküli küldéskor az API a kérés beérkezésének pillanatát fogja elmenteni az esemény idejéhez.

Esemény beküldése authentikációval

Authentikált módon bármikor lehet eseményeket beküldeni, de először létre kell hozni a projektben egy service account-ot. Lásd az AtomDMP Service account kezelés dokumentumot.

Eseményeket a POST /track/event végponton lehet beküldeni.

A kérésnél meg kell adni a megfelelő service account adatait Basic HTTP authentikációval. Az esemény beküldéshez a service account-nak rendelkeznie kell az “event.insert” szerepkörrel.

Paraméterek:

  • email
    • kötelező
    • az eseményt kiváltó user email címe
  • event
    • kötelező
    • az esemény neve
  • date
    • opcionális
    • az esermény ideje
    • datetime string W3C formátumban
    • múltbeli esemény beküldése esetén van rá szükség (lásd lentebb)
  • params
    • opcionális
    • 1 szintű asszociatív tömb
    • minden érték egy skaláris érték lehet
      • string
      • int
      • float
      • dátum esetén datetime string valamelyik formátumban a következők közül:
        • W3C
        • unix timestamp (PHP: U)
        • ÉÉÉÉHHNN (PHP: Ymd)
        • ÉÉÉÉ-HH-NN (PHP: Y-m-d)
        • ÓÓPPSS (PHP: His)
        • ÓÓ:PP:SS (PHP: H:i:s)

Amennyiben a date mező nincs megadva, az API a kérés beérkezésének pillanatát fogja elmenteni az esemény idejéhez.

Authentikált esemény beküldés esetén nem szabad a “domain” paramétert küldeni, mivel ebben az esetben maga a service account határozza meg a projekt domain nevét.

Események feldolgozása

A begyűjtött eseményeket a rendszer óránként egyszer dolgozza fel a korábban beállított Event Script-ek alapján. Amennyiben egy esemény hatására megváltozik egy profil egy adat mezeje, annak a módosítási dátuma nem az esemény feldolgozási ideje lesz, hanem az esemény eredeti ideje, ami a date mezőben lett megadva. Amennyiben egy olyan esemény kerül feldolgozásra, aminek az eredeti ideje régebbi, mint az általa módosítandó adat mező utolsó módosítási ideje, az adatmező utolsó módosítási ideje nem fog változni.

Múltbeli esemény beküldése (csak authentikációval)

Amennyiben egy múltbeli eseményt kell beküldeni (például utólagos beküldés projekt migráláskor, vagy üzemszerűen cron-ból, háttérben küldött események), egyszerűen a date mezőben meg kell adni az esemény eredeti idejét.

Múltbeli eseményt kizárólag authentikált módon lehet küldeni.

Figyelni kell, hogy lehetőleg 1-2 óránál régebbi esemény ne kerüljön be a rendszerbe, mivel azok eredeti ideje lesz beállítva az adat mezők módosítási idejeiben, emiatt minél régebbi az esemény, annál nagyobb eséllyel fordulhat elő, hogy az utolsó érték nem akkor lesz beállítva, amit az utolsó módosítási idő mutat. Ez leginkább akkor fordulhat elő, ha

  • nem sorfolytonosan kerülnek az a rendszerbe az események, azaz az események ideje össze-vissza ugrál
  • egyszerre van használva az eseményen keresztüli módosítás és az AtomDMP adatbázis API-ja