Personyze Wiki Personyze Wiki docs
Deutsch
Open Personyze
Docs/ Entwickler/ REST-API: Objektreferenz
Entwickler

REST-API: Objektreferenz

Jedes Objekt der Personyze-REST-API mit Zweck, Methoden, Spalten, indexierten Spalten und Beispielen.

23 min read Updated 12 Minuten ago

Referenz aller Objekte, die die Personyze-REST-API bereitstellt. Jeder Abschnitt unten behandelt ein Objekt: seinen Zweck, die unterstützten HTTP-Methoden, Spalten (mit Hinweisen zu Typ und Indexierung) und sofort nutzbare curl -Beispiele.

Voraussetzungen — lesen Sie diese zuerst, falls noch nicht geschehen:

Objektverzeichnis

Klicken Sie auf ein Objekt, um zu seinem Abschnitt zu springen. Jeder Abschnitt hat eine eigene Anker-URL — Sie können direkt auf die Referenz jedes Objekts verlinken.

CRUD-Inhalte (Lesen/Schreiben)

Enthalten Ihre Kampagnen, Zielgruppe, Katalog und Konfiguration. Volles CRUD für External API user und höher.

usersKundenprofile. Spaltennamen sind dynamisch.
user_listsBenannte Nutzerlisten (manuell oder importiert).
user_list_usersZugehörigkeit von Nutzern zu user_lists.
actionsPersonalisierungsaktionen. Über REST derzeit nur lesbar.
conditionsZielgruppenbedingungen. Über REST derzeit nur lesbar.
placeholdersDOM-Platzhalter-Container (wo Aktionen rendern).
containers_grab_variableDOM-/JS-Werte zurück ins Besucherprofil übernehmen.
productsZeilen des Produktkatalogs. Spaltennamen sind dynamisch.
articlesZeilen des Artikelkatalogs. Spaltennamen sind dynamisch.

Interaktionen / Ereignisse (überwiegend Schreiben)

Nur angehängte Protokolle von Besucherinteraktionen. Überwiegend von SDKs und Backend-Integrationen genutzt.

products_interactionsEreignisse Ansehen / Warenkorb / Kauf bei Produkten.
eventsAllgemeines Ereignisprotokoll (nur lesbar).
formsProtokoll der Formulareinsendungen (nur lesbar).
doBefehlsverteiler nach dem Prinzip „Fire and Forget“.

Berichte / Archiv (nur lesbar)

sessions_archiveEine Zeile pro Besuchersitzung, mit Metadaten zu Standort/Gerät/Browser.
user_interestsAbgeleitete Interessen, Kategorien, Tags pro Nutzer.
products_stats_*Interaktionszähler pro Produkt über sechs gleitende Zeitfenster.
summary_actionsTäglich aggregierte KPI pro Aktion.

Hilfen für Tracker / SDK

Vom JS-Tracker, nativen SDKs und Integrationen zum Selbststart genutzt. Von Nutzern der REST-API normalerweise nicht direkt aufgerufen.

tracker_codeLiefert das JS-Snippet zum Einbetten in eine Kundenseite (HTML-Ausgabe).

users

Kundenprofile. Jede Zeile ist ein Besucher oder Kunde. Spaltennamen sind dynamisch — über die dokumentierten Verwaltungsspalten hinaus können Sie beliebige eigene Schlüssel/Werte speichern, die Ihr Konto braucht.

GET POST PUT DELETE

Identifizierende / Verwaltungsspalten

Spalte Hinweise
user_id Interner Primärschlüssel von Personyze. Wird beim Einfügen automatisch vergeben. Indexiert.
internal_id Ihre externe Kennung (CRM-ID, Konto-ID, SKU). Indexiert.
fb_id Facebook-Nutzer-ID. Indexiert.
email E-Mail-Adresse des Besuchers. Indexiert.
last_session_time Unix-Sekunden. Indexiert.
data_last_modified Unix-Sekunden. Indexiert.
session_counter Bisher gezählte Sitzungen dieses Nutzers insgesamt.

Gängige Profilfelder (benutzerdefiniert)

first_name, middle_name, last_name, sex, birthday, timezone, current_city, current_state, current_country, religion, political, interests, relationship_status, education_year, plus custom_t_1custom_t_6 (Text), custom_i_1custom_i_4 (Ganzzahl), custom_f_1custom_f_2 (Gleitkomma), custom_d_1, custom_d_2 (Datum) — und alle weiteren Felder, die Sie in Ihrem Konto konfiguriert haben.

Beispiele

# Lookup by your external id
curl 'https://api:KEY@app.personyze.com/rest/users/where/internal_id=42'
# Recent active visitors (last 7 days)
curl 'https://api:KEY@app.personyze.com/rest/users
        /where/last_session_time>1730000000
        /columns/user_id,internal_id,email,first_name,last_session_time
        /order_by_desc/last_session_time
        /limit/1000'
# Create
curl -X POST 'https://api:KEY@app.personyze.com/rest/users' \
     -H 'Content-Type: application/json' \
     -d '{"internal_id":"acct-987","email":"alice@example.com","first_name":"Alice","custom_field_x":"vip"}'
# → 5712334  (new user_id)
# Update
curl -X PUT 'https://api:KEY@app.personyze.com/rest/users/where/internal_id=acct-987' \
     -H 'Content-Type: application/json' \
     -d '{"first_name":"Alicia"}'
# → 1  (rows affected)

Indexierte Spalten / Scan-Grenzen

GET /rest/users ohne where erfordert order_by auf einer indexierten Spalte — user_id, last_session_time, data_last_modified, fb_id, emailoder internal_id. Andernfalls: 400 Cannot do this operation on whole table.

Drosselung

POST /rest/users wird pro Personyze-Konto serialisiert: höchstens ein laufendes Einfügen gleichzeitig. Anfragen, die länger als 1 Sekunde warten, werden abgelehnt mit 400 Too many simultaneous requests — wiederholen Sie mit exponentiellem Backoff.

user_lists

Benannte Nutzerlisten (z. B. „VIPs“, „Newsletter-Abonnenten“). Eine Zeile pro Liste. Die Mitgliedschaft liegt in einem separaten Objekt — siehe user_list_users.

GET POST PUT DELETE

Spalten

Spalte Hinweise
id Primärschlüssel. Automatisch vergeben.
name Anzeigename der Liste. Indexiert.

Beispiele

# All lists
curl 'https://api:KEY@app.personyze.com/rest/user_lists'
# Create
curl -X POST 'https://api:KEY@app.personyze.com/rest/user_lists' \
     -H 'Content-Type: application/json' \
     -d '{"name":"VIPs"}'
# → 17
# Rename
curl -X PUT 'https://api:KEY@app.personyze.com/rest/user_lists/17' \
     -H 'Content-Type: application/json' \
     -d '{"name":"VIP customers"}'
# → 1
# Delete (also clears all memberships in user_list_users via FK cascade)
curl -X DELETE 'https://api:KEY@app.personyze.com/rest/user_lists/17'
# → 1

user_list_users

Mitgliedschaft: welche Nutzer zu welchen user_listsgehören. Eine Zeile pro (user_list_id, user_id) -Paar.

GET POST PUT DELETE

POST akzeptiert entweder eine vorhandene user_idoder einen Suchschlüssel (user_internal_id, user_email) — die API löst ihn zu einer user_idauf und legt bei Bedarf eine Platzhalterzeile in users an.

Spalten

Spalte Hinweise
user_list_id FK → user_lists.id. Teil des zusammengesetzten Schlüssels.
user_id FK → users.user_id. Teil des zusammengesetzten Schlüssels.

Zusätzliche Felder im POST-Body (serverseitig zu user_id aufgelöst und dann verworfen)

Feld Wird aufgelöst zu
user_internal_id user_id für den Nutzer mit dieser internal_id. Legt den Nutzer an, falls er fehlt.
user_email user_id für den Nutzer mit dieser email. Legt den Nutzer an, falls er fehlt.

Beispiele

# Members of list 17
curl 'https://api:KEY@app.personyze.com/rest/user_list_users/where/user_list_id=17/limit/1000'
# Add by user_id
curl -X POST 'https://api:KEY@app.personyze.com/rest/user_list_users' \
     -H 'Content-Type: application/json' \
     -d '{"user_list_id":17,"user_id":5712334}' 
# Add by external id (auto-creates a users row if needed)
curl -X POST 'https://api:KEY@app.personyze.com/rest/user_list_users' \
     -H 'Content-Type: application/json' \
     -d '{"user_list_id":17,"user_internal_id":"acct-987"}' 
# Add by email
curl -X POST 'https://api:KEY@app.personyze.com/rest/user_list_users' \
     -H 'Content-Type: application/json' \
     -d '{"user_list_id":17,"user_email":"alice@example.com"}' 
# Remove
curl -X DELETE 'https://api:KEY@app.personyze.com/rest/user_list_users
        /where/user_list_id=17&user_id=5712334'

actions

Personalisierungsaktionen — was Ihre Kampagnen tun: HTML rendern, ein Pop-up zeigen, eine E-Mail senden, eine Benachrichtigung pushen usw. Über REST derzeit nur lesbar (Anlegen/Bearbeiten über die Oberfläche).

GET POST PUT DELETE

Spalten

Spalte Hinweise
id Primärschlüssel.
version_tag production oder testing.
name Anzeigename der Aktion.
type_id Der Aktionstyp (HTML / Pop-up / E-Mail / Push / …). Aufgelöst aus dem zugrunde liegenden action_js_id.
placeholders JSON-Array der Platzhalter-IDs, auf die die Aktion zielt.
content_type MIME-Typ / Art des Inhalts (aus actions_js).
content_param Name des JS-Parameterschlüssels, dessen Wert der renderbare Inhalt ist.
content_begin Berechnet: öffnendes Fragment des gerenderten Inhalts (nach Ersetzung des Wrappers).
content_end Berechnet: schließendes Fragment.
presenting_rules JSON: Regeln für Timing / Häufigkeit.
libs_app App-Bibliotheken, von denen die Aktion abhängt.

Beispiele

# All production actions
curl 'https://api:KEY@app.personyze.com/rest/actions
        /where/version_tag=production
        /columns/id,name,type_id,placeholders'
# One action's full content
curl 'https://api:KEY@app.personyze.com/rest/actions/where/id=42
        /columns/id,name,content_type,content_param,content_begin,content_end'

conditions

Zielgruppenbedingungen — das Wann von Kampagnen. Über REST nur lesbar.

GET POST PUT DELETE

Spalten

Spalte Hinweise
id Primärschlüssel.
name Anzeigename der Bedingung.

Beispiele

# All tracker/offline conditions
curl 'https://api:KEY@app.personyze.com/rest/conditions/limit/1000'

placeholders

Container vom Typ placeholder — DOM-Plätze, an denen Aktionen Inhalte rendern. Verwalten Sie den Katalog der für Ihre Website definierten Platzhalter.

GET POST PUT DELETE

Spalten

Spalte Hinweise
id Primärschlüssel.
name Anzeigename.
html_id DOM-Selektor / ID, an der der Platzhalter eingebunden wird.
units_count_max Maximale Zahl von Aktionseinheiten, die diesen Platzhalter füllen können. Standard 1.

Beispiele

# All placeholders
curl 'https://api:KEY@app.personyze.com/rest/placeholders'
# One
curl 'https://api:KEY@app.personyze.com/rest/placeholders/14'
# Create
curl -X POST 'https://api:KEY@app.personyze.com/rest/placeholders' \
     -H 'Content-Type: application/json' \
     -d '{"name":"Hero banner","html_id":"#hero","units_count_max":1}'
# → 88
# Update
curl -X PUT 'https://api:KEY@app.personyze.com/rest/placeholders/88' \
     -H 'Content-Type: application/json' \
     -d '{"units_count_max":3}'
# → 1
# Delete
curl -X DELETE 'https://api:KEY@app.personyze.com/rest/placeholders/88'
# → 1

Bereich des Endpunkts.Der Handler begrenzt alle Abfragen auf container_types='placeholder', sodass andere Container-Typen (z. B. „grab variable“) über diesen Endpunkt nicht sichtbar sind — siehe containers_grab_variable.

containers_grab_variable

Container vom Typ „Grab variable“ — übernehmen DOM-/JS-Werte von der Seite des Besuchers zurück ins Besucherprofil. Jeder Container sagt: „Beobachte diese Variable / dieses DOM-Element; sobald es erscheint, erfasse es als Profilfeld.“

GET POST PUT DELETE

Spalten

Spalte Hinweise
id Primärschlüssel.
name Anzeigename.
is_active 1 / 0.
variable_path DOM-Pfad oder JS-Ausdruck, der erfasst wird.
mask Optionaler Regex/Vorlage, angewendet auf die erfasste Zeichenkette.
constant_value Optionaler Fallback / erzwungener Wert.
watch_variable Erneut erfassen, sobald sich die Variable ändert (1 / 0).
profile_column Profilspalte, in die der Wert geschrieben wird.

Beispiele

# All grab-variable containers
curl 'https://api:KEY@app.personyze.com/rest/containers_grab_variable'
# Create
curl -X POST 'https://api:KEY@app.personyze.com/rest/containers_grab_variable' \
     -H 'Content-Type: application/json' \
     -d '{"name":"Cart total",
          "variable_path":"window.dataLayer[0].cart.total",
          "mask":"^([0-9.]+)$",
          "watch_variable":1}'
# → 153
# Update
curl -X PUT 'https://api:KEY@app.personyze.com/rest/containers_grab_variable/153' \
     -H 'Content-Type: application/json' \
     -d '{"is_active":0}' 
# Delete
curl -X DELETE 'https://api:KEY@app.personyze.com/rest/containers_grab_variable/153'

products

Produktkatalog. Jede Zeile ist eine SKU. Spaltennamen sind dynamisch — über die dokumentierten Verwaltungsspalten hinaus können Sie beliebige eigene Felder speichern, die Ihr Katalog braucht.

GET POST PUT DELETE

Identifizierende / Verwaltungsspalten

Spalte Hinweise
id Primärschlüssel. Automatisch vergeben.
internal_id Ihre SKU / externe Kennung.
data_last_modified Unix-Sekunden.
is_in_stock 'yes' / 'no' Enum (nicht 1/0).

Gängige Produktfelder (benutzerdefiniert)

title, description_short, description_long, price, sale_price, image_big_url, image_medium_url, image_small_url, cart_url, brand, manufacturer, category, inventory, expiration_date, size, color, rank, is_new, age_from, age_to, available_location, not_available_locationusw. Die tatsächlichen Felder hängen von der Konfiguration Ihres Kontos ab.

Umbenannte Eingaben (bei POST / PUT)

Eingabe Gespeichert als
image_1 image_big_url
image_2 image_medium_url
image_3 image_small_url

Beispiele

# In-stock products in a category
curl 'https://api:KEY@app.personyze.com/rest/products
        /where/category=tools&is_in_stock=yes
        /columns/id,internal_id,title,price,inventory
        /order_by/title
        /limit/100'
# Lookup by internal_id
curl 'https://api:KEY@app.personyze.com/rest/products/where/internal_id=SKU-1234'
# Insert (or "patch" — duplicate internal_id will UPDATE rather than fail)
curl -X POST 'https://api:KEY@app.personyze.com/rest/products' \
     -H 'Content-Type: application/json' \
     -d '{"internal_id":"SKU-1234",
          "title":"Cordless Drill",
          "price":129.99,
          "is_in_stock":"yes",
          "image_1":"https://cdn.example.com/big.jpg"}'
# → 51234
# Update by internal_id
curl -X PUT 'https://api:KEY@app.personyze.com/rest/products/where/internal_id=SKU-1234' \
     -H 'Content-Type: application/json' \
     -d '{"price":119.99,"is_in_stock":"no"}' 
# Delete
curl -X DELETE 'https://api:KEY@app.personyze.com/rest/products/where/internal_id=SKU-1234'

Upsert-Verhalten bei POST.POST arbeitet mit Patch bei Duplikat: Eine vorhandene internal_id aktualisiert die Zeile, statt fehlzuschlagen. Für den Massenimport aus einer Feed-URL nutzen Sie die geplante Feed-Synchronisierung in der Personyze-Oberfläche statt REST-Aufrufen pro Zeile.

articles

Artikelkatalog (Blogbeiträge, News, Einträge in Wissensdatenbanken). Dieselbe Form wie products , aber für redaktionelle Inhalte.

GET POST PUT DELETE

Identifizierende / Verwaltungsspalten

Spalte Hinweise
id Primärschlüssel. Automatisch vergeben.
internal_id Ihre externe Kennung (Slug, CMS-ID).
data_last_modified Unix-Sekunden.
is_published 'yes' / 'no' Enum.

Gängige Artikelfelder (benutzerdefiniert)

title, description_short, description_long, image_big_url, image_medium_url, image_small_url, author, publish_date, category, tags, rankusw. Die tatsächliche Liste hängt von der Konfiguration other_columns_info Ihrer Website ab.

Umbenannte Eingaben

Eingabe Gespeichert als
image_1 image_big_url
image_2 image_medium_url
image_3 image_small_url

Beispiele

# Recent published articles
curl 'https://api:KEY@app.personyze.com/rest/articles
        /where/is_published=yes
        /columns/id,internal_id,title,author,publish_date
        /order_by_desc/publish_date
        /limit/100'
# Lookup by internal_id
curl 'https://api:KEY@app.personyze.com/rest/articles/where/internal_id=how-to-personalize'
# Insert
curl -X POST 'https://api:KEY@app.personyze.com/rest/articles' \
     -H 'Content-Type: application/json' \
     -d '{"internal_id":"how-to-personalize",
          "title":"How to personalize your site",
          "author":"Alice",
          "is_published":"yes",
          "image_1":"https://cdn.example.com/big.jpg"}' 
# Update
curl -X PUT 'https://api:KEY@app.personyze.com/rest/articles/where/internal_id=how-to-personalize' \
     -H 'Content-Type: application/json' \
     -d '{"is_published":"no"}' 
# Delete
curl -X DELETE 'https://api:KEY@app.personyze.com/rest/articles/where/internal_id=how-to-personalize'

Artikelinteraktionen laufen über den Endpunkt do.POST arbeitet mit Patch bei Duplikat (wie products). Um Besucherinteraktionen mit Artikeln zu tracken (angesehen / kommentiert / gemocht), nutzen Sie do mit den Article … -Befehlen — ein eigenes REST-Objekt gibt es derzeit nicht.

products_interactions

Protokoll der Interaktionen mit Produkten: Aufrufe, Warenkorb-Hinzufügungen, Käufe, „favorite“, „delivered“. Überwiegend angehängt. Gestützt auf eine Archivtabelle.

GET POST PUT DELETE

Spalten

Spalte Hinweise
user_id FK → users.user_id. Indexiert.
product_internal_id FK → products.internal_id. Führende Spalte eines zusammengesetzten Index [product_internal_id, user_id, transaction_time].
quantity Standard 1 beim Einfügen.
status Einer von viewed, delivered, extra (≈ in den Warenkorb gelegt), favorite, goal (Kauf). Indexiert.
action_id Wurde die Interaktion einer Personyze-Aktion zugeordnet, deren ID. Andernfalls null.
transaction_time Unix-Sekunden — Zeitpunkt der Bestellung/Transaktion.
time Unix-Sekunden — wann die Zeile protokolliert wurde. Indexiert.
amount Geldwert (gemäß den Währungseinstellungen der Website).

Einfügen: den Nutzer identifizieren

POST akzeptiert eines davon, um den Nutzer zu identifizieren:

Feld Wird aufgelöst zu
user_id (numerisch) Direkte Suche per Primärschlüssel.
user_internal_id user_id des Nutzers mit dieser internal_id. Legt automatisch eine Platzhalterzeile in users an, falls sie fehlt.
user_email user_id des Nutzers mit dieser email. Wird bei Bedarf automatisch angelegt.

Beispiele

# All purchases in a window, paged
curl 'https://api:KEY@app.personyze.com/rest/products_interactions
        /where/status=goal&time>1730000000
        /order_by_desc/time
        /limit/1000'
# A specific user's history with a product
curl 'https://api:KEY@app.personyze.com/rest/products_interactions
        /where/product_internal_id=SKU-1234
        /columns/user_id,status,quantity,amount,transaction_time'
# Log a purchase
curl -X POST 'https://api:KEY@app.personyze.com/rest/products_interactions' \
     -H 'Content-Type: application/json' \
     -d '{"user_internal_id":"acct-987",
          "product_internal_id":"SKU-1234",
          "quantity":2,
          "status":"goal",
          "transaction_time":1734000000,
          "amount":259.98}' 
# Delete by composite key
curl -X DELETE 'https://api:KEY@app.personyze.com/rest/products_interactions
        /where/user_id=5712334&product_internal_id=SKU-1234&status=viewed'

Indexierte Spalten

user_id, [product_internal_id, user_id, transaction_time], status, time. Abfragen ohne where auf einer davon (oder order_by auf derselben) werden als vollständige Tabellenscans abgelehnt.

events

Allgemeines Ereignisprotokoll — eine Zeile pro getracktem Ereignis, erfasst vom JS-Tracker, SDK oder dem Endpunkt do . Über REST derzeit nur lesbar.

GET POST PUT DELETE

Spalten

Spalte Hinweise
id Primärschlüssel.
user_id FK → users.user_id. Indexiert.
time Unix-Sekunden.
visit_id FK → Besuchszeile.
container_id FK → containers.id (die Quelle des Ereignisses). Indexiert.
container_types Der Typ des Containers (click event, submit eventusw.).
value Nutzlast-Zeichenkette des Ereignisses.
first_visit_id Erste visit_id der Sitzung.
session_start_time Unix-Sekunden.

Beispiele

# Recent events for a user
curl 'https://api:KEY@app.personyze.com/rest/events
        /where/user_id=5712334
        /order_by_desc/time
        /limit/100'
# Events from a specific container in a window
curl 'https://api:KEY@app.personyze.com/rest/events
        /where/container_id=1234&time>1730000000&time<1731000000
        /columns/id,user_id,time,value
        /order_by_desc/time
        /limit/1000'

Wann events und wann summary_actions.Die Tabelle ist groß; Abfragen müssen auf einer indexierten Spalte filtern (id, user_id, container_id, …), sonst wird die Anfrage abgelehnt. Für aggregierte KPIs über die Zeit nutzen Sie stattdessen summary_actions — es hat vorberechnete Tageszähler pro Aktion.

forms

Protokoll der Formulareinsendungen. Eine Zeile pro vom Tracker erfasstem Absenden eines Formulars. Über REST derzeit nur lesbar.

GET POST PUT DELETE

Spalten

Spalte Hinweise
user_id FK → users.user_id. Indexiert.
time Unix-Sekunden.
action_id Personyze-Aktion, die dieses Formular ausgelöst hat bzw. zu der es gehört, falls vorhanden.
session_start_time Unix-Sekunden.
plus data (JSON) Die eingesendeten Formulardaten, als JSON gepackt. Inline gelesen (ihre Schlüssel erscheinen als Spalten in der Antwort).

Das data -JSON wird beim Lesen automatisch in Schlüssel der obersten Ebene aufgelöst — fordern Sie bestimmte eigene Felder per Namen an.

Beispiele

# Submissions for a user
curl 'https://api:KEY@app.personyze.com/rest/forms
        /where/user_id=5712334
        /order_by_desc/time
        /limit/100'
# Submissions tied to a specific action
curl 'https://api:KEY@app.personyze.com/rest/forms
        /where/action_id=42&time>1730000000
        /columns/user_id,time,email,name,message
        /limit/1000'

Zu den indexierten Spalten gehören user_id, action_idund time. Abfragen müssen auf einer davon filtern.

do

Befehlsverteiler nach dem Prinzip „Fire and Forget“: Senden Sie eine einzelne Aktualisierung des Nutzerprofils oder ein Interaktionsereignis, ohne das Tracker-Protokoll zu sprechen. Der Body ist ein Array von Befehlen; jeder wird unabhängig verarbeitet.

GET POST PUT DELETE

Aufbau der Anfrage

[
    [<key-type>, <key-value>, <command>, <arg1>, <arg2>, ...],
    [<key-type>, <key-value>, <command>, <arg1>, <arg2>, ...],
    ...
]
  • <key-type>: "user_id", "internal_id"oder "email". Optional — weglassen bei Befehlen, die sich nicht an einen Nutzer richten.
  • <key-value>: die entsprechende Kennung.
  • <command>: eine Zeichenkette (ohne Beachtung der Groß-/Kleinschreibung). Siehe Liste unten.
  • <arg…>: befehlsspezifische Positionsargumente.

Ein erfolgreiches POST liefert nichts zurück; Fehler lösen eine Ausnahme aus (der ganze Batch bricht beim ersten Fehler ab).

Befehle

Nutzerprofil

["internal_id", "acct-987", "User profile", "first_name", "Alice", "custom_t_1", "VIP"]

Nach dem Befehlsnamen wechseln die Argumente ab: field, value, field, value, …

Produktinteraktionen

["internal_id", "acct-987", "Product viewed",          "SKU-1234"]
["internal_id", "acct-987", "Product added to cart",   "SKU-1234", "quantity", 2]
["internal_id", "acct-987", "Product liked",           "SKU-1234"]
["internal_id", "acct-987", "Product purchased",       "SKU-1234", "quantity", 2, "amount", 259.98]
["internal_id", "acct-987", "Product removed from cart","SKU-1234"]
["internal_id", "acct-987", "Product unliked",         "SKU-1234"]

Nach der SKU optionale Schlüssel-Wert-Paare: "quantity", "amount", "action_id", "transaction_time".

Artikelinteraktionen

["email", "alice@example.com", "Article viewed",   "how-to-personalize"]
["email", "alice@example.com", "Article liked",    "how-to-personalize"]
["email", "alice@example.com", "Article commented","how-to-personalize"]
["email", "alice@example.com", "Article unliked", "how-to-personalize"]
["email", "alice@example.com", "Article goal",     "how-to-personalize"]

Beispiele

# Tag a user as VIP
curl -X POST 'https://api:KEY@app.personyze.com/rest/do' \
     -H 'Content-Type: application/json' \
     -d '[["internal_id","acct-987","User profile","custom_t_1","VIP","first_name","Alice"]]' 
# Log a purchase + a profile update in one round-trip
curl -X POST 'https://api:KEY@app.personyze.com/rest/do' \
     -H 'Content-Type: application/json' \
     -d '[
       ["email","alice@example.com","Product purchased","SKU-1234","quantity",2,"amount",259.98],
       ["email","alice@example.com","User profile","customer_segment","loyal"]
     ]' 

Wann do und wann typisierte Endpunkte.Suchschlüssel (internal_id / email) legen automatisch eine Platzhalterzeile in users an, wenn kein Nutzer passt. Für Interaktionsprotokollierung mit hohem Durchsatz nutzen Sie lieber products_interactions (typisiert und indexiert) oder die gebündelte Ereignis-API des SDK.

sessions_archive

Eine Zeile pro Besuchersitzung (ein zusammenhängendes Aktivitätsfenster). Gestützt auf die langlebige Archivtabelle — viel breiter als events, mit Metadaten zu Standort, Gerät, Bildschirm und Browser.

GET POST PUT DELETE

Identifizierend / Verwaltung

Spalte Hinweise
first_visit_id Primärschlüssel. Die ID der ersten visit -Zeile in dieser Sitzung.
user_id FK → users.user_id. Indexiert.
session_start_time Unix-Sekunden.
last_session_time Unix-Sekunden.
session_counter Die wievielte Sitzung dieses Nutzers (1, 2, 3, …).
total_visits In der Sitzung angesehene Seiten.
time_in_focus Sekunden, in denen der Tab tatsächlich im Fokus war.
time_total Sekunden vom Beginn bis zur letzten Aktivität.

Geografie / Locale / Gerät

Spalte Hinweise
time_zone Zeitzonenversatz des Besuchers (Stunden).
country_code, region_code, city Geografie (aus der IP). city wird aus der gemeinsamen Nachschlagetabelle verknüpft und ist daher ein lesbarer Name (null wenn kein Treffer).
lang_0, lang_1, lang_2 Die ersten drei Einträge von Accept-Language.
screen_width, screen_height, screen_depth Pixel / Farbtiefe.

Interaktionszähler

Spalte Hinweise
total_goal_value, total_n_goals Zielaggregate der Sitzung.
page_click, page_right_mouse, page_key_up, page_scroll Zählungen pro Ereignis.

Landing-URL & Referrer

Spalte Hinweise
url_prefix, url_host_port, url_path, url_query, url_fragment URL der ersten Seite der Sitzung, in Teile zerlegt. url_prefix ist die Kodierung von Schema+www.
referrer_prefix, referrer_host_port, referrer_path, referrer_query, referrer_fragment Dieselbe Form, für den Referrer.
referrer_type Numerisches Kennzeichen (Suche / Social / direkt / …).
search_word Suchanfrage bei Ankunft über eine Suchmaschine.

UTM / Werbekampagne

ad_campaign, ad_source, ad_medium, ad_term, ad_content — die Standard-UTM-Parameter, wie beim Landing erfasst.

Beispiele

# Sessions for a user, most recent first
curl 'https://api:KEY@app.personyze.com/rest/sessions_archive
        /where/user_id=5712334
        /columns/first_visit_id,session_start_time,total_visits,country_code,city
        /order_by_desc/session_start_time
        /limit/100'
# Single session by primary key
curl 'https://api:KEY@app.personyze.com/rest/sessions_archive
        /where/first_visit_id=900000000123
        /columns/user_id,session_start_time,total_visits,total_goal_value'

Indexierte Spalten: first_visit_id, user_id, plus mehrere weitere. Abfragen müssen auf einer indexierten Spalte filtern, sonst wird die Anfrage als vollständiger Tabellenscan abgelehnt.

user_interests

Interessen, Kategorien, Tags sowie Family-/Cross-/Upsale-Tags pro Nutzer, abgeleitet von der Tracker-Pipeline. Eine Zeile pro (user_id, value, class, time). Nur lesbar.

GET POST PUT DELETE

Spalten

Spalte Hinweise
user_id FK → users.user_id. Indexiert.
value Das Interessen-Token (z. B. Kategoriename, Tag, Stichwort).
class interest, category, tag, family, cross category, upsale category.
rank Gleitkomma. Relevanzwert innerhalb der Klasse.
n_times Wie oft dieser Wert für den Nutzer beobachtet wurde.
time Unix-Sekunden — wann das Interesse zuletzt aktualisiert wurde. Indexiert.

Indexierte Spalten: user_id, time. Abfragen müssen auf einer indexierten Spalte filtern.

Beispiele

# All interests for one user, strongest first
curl 'https://api:KEY@app.personyze.com/rest/user_interests
        /where/user_id=5712334
        /columns/value,class,rank,n_times,time
        /order_by_desc/rank
        /limit/100'
# Only categories, recently updated
curl 'https://api:KEY@app.personyze.com/rest/user_interests
        /where/user_id=5712334&class=category
        /order_by_desc/time
        /limit/50'

products_stats_*

Aggregierte Interaktionszähler pro Produkt, gepflegt von der Offline-Zusammenfassungspipeline. Sechs gleitende Zeitfenster stehen unter getrennten Pfaden bereit — wählen Sie das, das zu Ihrem Berichtszeitraum passt. Alle teilen dieselbe Spaltenform und dieselben Indizes; nur das Zeitfenster unterscheidet sich.

GET POST PUT DELETE

Endpunkte

Pfad Zeitfenster
/rest/products_stats_1day letzter 1 Tag
/rest/products_stats_2day letzte 2 Tage
/rest/products_stats_4day letzte 4 Tage
/rest/products_stats_week letzte 7 Tage
/rest/products_stats_recent kürzlich (gleitend — von der Pipeline festgelegt)
/rest/products_stats_all gesamte Laufzeit

Identifizierend

Spalte Hinweise
internal_id Primärschlüssel. Die externe Kennung des Produkts (Katalog-SKU / von Ihnen gelieferte ID). Indexiert.

Zähler pro Produkt (Zahl der Interaktionen mit diesem Produkt im Zeitfenster)

Spalte Hinweise
n_viewed Zahl der Aufrufereignisse. Indexiert.
n_delivered Zahl der ausgelieferten (angezeigten) Empfehlungen. Indexiert (zusammengesetzt mit n_viewed).
n_extra „Extra“-Interaktionen (z. B. in den Warenkorb). Indexiert (zusammengesetzt mit n_viewed).
n_favorite Favorisiert / auf die Wunschliste gesetzt. Indexiert (zusammengesetzt mit n_viewed).
n_goal Zielabschlüsse (Käufe). Indexiert (zusammengesetzt mit n_viewed).

Verteilungsstatistiken über den ganzen Katalog

Derselbe Wert in jeder Zeile — beschreibt den ganzen Katalog in diesem Zeitfenster. Für jede Kennzahl M ∈ {viewed, delivered, extra, favorite, goal}:

Spalte Hinweise
overall_n_<M> Summe über alle Produkte.
overall_avg_<M> Mittelwert über alle Produkte.
overall_avg_nonzero_<M> Mittelwert über Produkte mit mindestens einem Ereignis.
percentile_<M> Perzentilrang dieser Zeile für die Kennzahl.

Die letzten 3 Zielnutzer (jüngste Käufer dieses Produkts)

Spalte Hinweise
last_goal_user_id_0, last_goal_user_id_1, last_goal_user_id_2 Einzeln indexiert.
last_goal_user_time_0, last_goal_user_time_1, last_goal_user_time_2 Unix-Sekunden.

Indexierte Spalten

internal_id, n_viewed, n_delivered, n_extra, n_favorite, n_goal, last_goal_user_id_0, last_goal_user_id_1, last_goal_user_id_2. Abfragen müssen auf einer davon filtern (oder order_by).

Beispiele

# Top 50 most-viewed products this week
curl 'https://api:KEY@app.personyze.com/rest/products_stats_week
        /where/n_viewed>0
        /columns/internal_id,n_viewed,n_delivered,n_extra,n_goal,percentile_viewed
        /order_by_desc/n_viewed
        /limit/50'
# Lookup one product's lifetime stats
curl 'https://api:KEY@app.personyze.com/rest/products_stats_all
        /where/internal_id=SKU-12345'
# What a specific user purchased recently (matches against last 3 goal users)
curl 'https://api:KEY@app.personyze.com/rest/products_stats_recent
        /where/last_goal_user_id_0=5712334
        /columns/internal_id,n_goal,last_goal_user_time_0'

summary_actions

Täglich aggregierte KPIs pro Aktion — eine Zeile pro (day, action_id) für Aktionen, die an eine bestimmte Kampagne gebunden sind (condition_id). Nur lesbar.

GET POST PUT DELETE

Strenge Indexanforderung.Nur day ist indexiert. Jede Anfrage muss where/day… enthalten — einen Ausweg nur mit order_bygibt es nicht.

Identifizierend

Spalte Hinweise
day Unix-Zeitstempel (Sekunden) von 0:00 Uhr des Tages in Greenwich (GMT+0000).
action_name Name der Aktion.
action_id ID der Aktion.
campaign_name Name der Kampagne, zu der die Aktion gehört.
campaign_id ID der Kampagne, zu der die Aktion gehört.

Reichweite der Aktion

Spalte Hinweise
n_executed Wie oft ausgeführt (Aktionen gelten als ausgeführt, auch wenn der sichtbare Inhalt noch nicht angezeigt wird).
n_delivered Wie oft wir von der Browserseite die Rückmeldung erhalten haben, dass der Inhalt sichtbar wurde.
n_extra Hängt vom Aktionstyp ab. Bei HTML-Aktionen: Zahl der Klicks. Bei Formularaktionen: Zahl der Einsendungen.
n_failed Nur bei E-Mail-Aktionen gezählt. Wie oft der E-Mail-Versand fehlgeschlagen ist (z. B. ungültige Adresse).
n_closed Wie oft der Nutzer den Button „Schließen“ geklickt hat, nachdem der Inhalt der Aktion sichtbar wurde.
n_sessions_executed In wie vielen verschiedenen Sitzungen es mindestens ein n_executed für diese Aktion gab.
n_sessions_delivered In wie vielen verschiedenen Sitzungen es mindestens ein n_delivered.
n_sessions_extra In wie vielen verschiedenen Sitzungen es mindestens ein n_extra.
n_sessions_failed In wie vielen verschiedenen Sitzungen es mindestens ein n_failed.
n_sessions_closed In wie vielen verschiedenen Sitzungen es mindestens ein n_closed.

Produktzuordnung (wenn diese Aktion Produkte empfohlen hat)

Spalte Hinweise
products_goal_n_times Wie viele Produkte (über alle Besucher) in einer Sitzung, in der diese Aktion ausgeführt wurde, „gekauft“ erreicht haben. Zählt jedes Kaufereignis eines Produkts; eine einzelne Bestellung mit 3 Artikeln zählt also 3.
products_goal_n_sessions In wie vielen verschiedenen Sitzungen nach Ausführung dieser Aktion mindestens ein Produkt gekauft wurde.
products_goal_value Summe der Geldwerte aller gekauften Produkte, gezählt in products_goal_n_times.
products_recom_viewed_n_times Wie oft ein von dieser Aktion empfohlenes Produkt anschließend angesehen wurde.
products_recom_viewed_n_sessions In wie vielen verschiedenen Sitzungen mindestens ein empfohlenes Produkt angesehen wurde.
products_recom_extra_n_times Wie oft ein empfohlenes Produkt anschließend in den Warenkorb gelegt wurde (oder anderweitig die „Extra“-Interaktion erreicht hat).
products_recom_extra_n_sessions In wie vielen verschiedenen Sitzungen mindestens ein empfohlenes Produkt die „Extra“-Interaktion erreicht hat.
products_recom_extra_value Summe der Geldwerte aller empfohlenen Produkte mit „Extra“-Interaktion.
products_recom_goal_n_times Wie oft ein empfohlenes Produkt anschließend gekauft wurde.
products_recom_goal_n_sessions In wie vielen verschiedenen Sitzungen mindestens ein empfohlenes Produkt gekauft wurde.
products_recom_goal_value Summe der Geldwerte aller gekauften empfohlenen Produkte.

Artikelzuordnung

Dieselbe Form wie die Produktzuordnung, aber für Artikel: articles_recom_viewed_n_times, articles_recom_viewed_n_sessions, articles_recom_extra_n_times, articles_recom_extra_n_sessions, articles_recom_extra_value, articles_recom_goal_n_times, articles_recom_goal_n_sessions, articles_recom_goal_value.

Eigene Zielereignisse pro Konto

Ein Konto kann bis zu 12 Zielereignisse konfigurieren. Für jeden in Ihrem Konto konfigurierten Ereignis-Container mit einem von null verschiedenen goal_event_index (N von 1 bis 12) erscheinen in der Antwort vier zusätzliche Spalten:

  • goal_event_N_name — Anzeigename des konfigurierten Zielereignisses. Als literale Zeichenkette zurückgegeben, in jeder Zeile gleich.
  • goal_event_N_n_times — Wie oft dieses Zielereignis in einer Sitzung ausgelöst wurde, in der die Aktion ausgeführt wurde.
  • goal_event_N_n_sessions — In wie vielen verschiedenen Sitzungen dieses Zielereignis nach Ausführung der Aktion mindestens einmal ausgelöst wurde.
  • goal_event_N_value — Summe der Geldwerte, die für dieses Zielereignis über die gezählten Male gemeldet wurden, in goal_event_N_n_times (null, sofern der Container des Zielereignisses nicht so konfiguriert ist, dass er einen Wert erfasst).

Beispiele

# Last 30 days, daily KPIs per action
curl 'https://api:KEY@app.personyze.com/rest/summary_actions
        /where/day>1730000000
        /columns/day,action_name,n_executed,n_delivered,n_extra,products_goal_value
        /order_by_desc/day
        /limit/1000'
# A specific action's lifetime
curl 'https://api:KEY@app.personyze.com/rest/summary_actions
        /where/action_id=42&day>1700000000
        /order_by/day
        /limit/1000'

tracker_code

Liefert das JS-Snippet, das Sie in Ihre Website einbetten, um den Personyze-Tracker zu starten. Der Inhalt ergibt sich aus den Einstellungen Ihres Kontos (Konto-ID, Tracking-Host, Flags für async/no-hide).

GET POST PUT DELETE

Antwort

Ein einfaches text/html (oder JS in<script>) Snippet, bereit zum Einbinden in einen <head>. Der Body ist kein JSON — das ist der einzige REST-Endpunkt, der rohes HTML liefert.

Beispiel

curl 'https://api:KEY@app.personyze.com/rest/tracker_code'
<script>(function(s){
    s.async = true;
    s.src = '//lcounter.personyze.com/stat-track-lib.js';
    s.onload = function() {
        _S_T.async = true;
        _S_T.setup(5919, "example.com www.example.com");
    };
    (document.querySelector('head') || document.documentElement).appendChild(s);
}(document.createElement('script')))</script>

Konventionen des Tracker-Snippets.Das Snippet enthält Ihre Konto-ID und die Liste der für dieses Konto registrierten zulässigen Hostnamen. Bearbeiten Sie es nicht von Hand; rufen Sie es neu ab, wenn Sie über die Oberfläche neue Domains hinzufügen. Für native SDK-Clients (iOS / Android) ist dieser Endpunkt nicht relevant — das SDK spricht das Tracker-Protokoll direkt über interne Endpunkte.

Nächste Schritte

📖 Syntax der PfadparameterAusführlich zu where/columns/order_by/limit mit allen Operatoren und Beispielen. Lesen →
🔑 AuthentifizierungUmgang mit API-Schlüsseln, Header-Format, Fehlercodes, Setups mit mehreren Konten. Lesen →
🛠 EntwicklerressourcenSDKs, GitHub-Repositorys und weitere Entwicklerwerkzeuge. Lesen →
Did this page answer your question?
Thank you — that goes to whoever maintains this page.