Objekt-Tags API (Beta)
Objekt-Tags speichern strukturierte Daten über einen Benutzer in einem einzigen Tag. Ein Tag vom Typ Object enthält ein Objekt mit benannten Feldern, zum Beispiel die letzte Bestellung order mit ihren Feldern amount und status. Ein Tag vom Typ ObjectList enthält ein Array solcher Objekte, zum Beispiel alle Bestellungen orders. Ein Feld kann selbst ein Objekt oder eine Liste von Objekten sein, zum Beispiel die Adresse address eines Profils profile. Sie definieren die Felder einmal, schreiben und lesen Werte über die Tag-API, erstellen Segmente nach Feldwerten und fügen die Werte mit Liquid in Nachrichten ein.
Funktionsweise von Objekt-Tags
Anchor link toEin Objekt-Tag hat ein Schema und einen Wert. Das Schema besteht aus dem Tag-Namen und einer Liste von Feldern, jedes mit seinem eigenen Typ. Der Wert wird in den Feldern gespeichert, für jeden Benutzer separat.
- Feld. Jedes Feld ist ein Tag mit dem Namen
<object>.<field>, zum Beispielorder.amount. Sie segmentieren nach Feldern, und unter diesem Namen können Sie ein Feld einesObject-Tags schreiben. Object-Wert. Ein Objekt pro Benutzer, zum Beispiel"order": {"amount": 120, "status": "paid"}.ObjectList-Wert. Ein Array von Objekten mit denselben Feldern, zum Beispiel"orders": [{"amount": 120, "status": "paid"}, {"amount": 50}].- Verschachteltes Objekt. Ein Feld vom Typ
OBJECTmit eigenen Feldern, zum Beispielprofile.addressmit dem Feldprofile.address.city. - Verschachtelte Liste. Ein Feld vom Typ
OBJECT_LIST, ein Array von Objekten innerhalb eines Objekt-Tags, zum Beispielprofile.visits. Siehe Verschachtelte Objekte und Listen.
In der API heißen die Tag- und Feldtypen OBJECT und OBJECT_LIST. Im Control Panel heißen sie Objekt und Liste von Objekten. Auf dieser Seite bezeichnet eine Liste von Objekten ein ObjectList-Tag oder eine verschachtelte Liste.
Objekt-Tags sind immer User-specific. Das bedeutet, dass der Wert dem Benutzer gehört, nicht einem einzelnen Gerät, und auf alle Geräte des Benutzers kopiert wird. Für reguläre Tags siehe Tags API.
Verschachtelte Objekte und Listen
Anchor link toEin Feld eines Objekt-Tags kann statt eines einzelnen Werts eigene Felder enthalten. Ein verschachteltes Objekt, ein Feld vom Typ OBJECT, enthält ein Objekt. Eine verschachtelte Liste, ein Feld vom Typ OBJECT_LIST, enthält eine Liste von Objekten. Auch ein Element einer Liste kann verschachtelte Objekte und Listen enthalten. Jedes Feld behält seinen vollständigen Namen mit Punkten, zum Beispiel profile.address.city, und Sie segmentieren nach diesen Namen.
Ein profile-Tag vom Typ OBJECT und ein orders-Tag vom Typ OBJECT_LIST können zum Beispiel diese Struktur haben:
profile OBJECT├── address OBJECT│ ├── city STRING│ └── geo OBJECT│ └── lat STRING└── visits OBJECT_LIST └── code STRING
orders OBJECT_LIST├── sku STRING├── meta OBJECT│ └── color STRING└── lines OBJECT_LIST └── qty INTEGERDurchsuchbare und nur gespeicherte Felder
Anchor link toWas Sie mit einem Feld tun können, hängt davon ab, wie viele Listen von Objekten über ihm liegen:
- Keine Liste über dem Feld. Sie können nach einem Feld wie
profile.address.citysegmentieren, es einzeln über seinen vollständigen Namen schreiben und in Nachrichten verwenden. - Eine Liste über dem Feld. Sie können nach einem Feld wie
profile.visits.codeoderorders.meta.colorsegmentieren und es in Nachrichten verwenden. Schreiben Sie es nur als Teil der gesamten Liste. - Zwei Listen über dem Feld. Ein Feld wie
orders.lines.qtywird nur gespeichert. Verwenden Sie es in Nachrichten, aber nicht in Segmenten.
Limits
Anchor link toPushwoosh wendet diese Limits auf Objekt-Tags an, einschließlich verschachtelter Objekte und Listen:
| Limit | Wert | Bei Überschreitung |
|---|---|---|
| Verschachtelungstiefe | 3 Ebenen von Objekten und Listen. Das Tag selbst ist die erste Ebene, daher ist profile.address.geo das tiefste zulässige Objekt | Die Schema-Methode gibt HTTP 400 zurück, siehe Fehler |
| Felder in einem Objekt | 1 bis 20, für das Tag und für jedes verschachtelte Objekt oder jede verschachtelte Liste | Die Schema-Methode gibt HTTP 400 zurück, siehe Fehler |
| Felder mit Werten in einem Objekt-Tag | 50, einschließlich verschachtelter Felder. Felder vom Typ OBJECT und OBJECT_LIST zählen nicht | Die Schema-Methode gibt HTTP 400 zurück, siehe Fehler |
| Vollständiger Feldname | 64 Zeichen, zum Beispiel profile.address.city | Die Schema-Methode gibt HTTP 400 zurück, siehe Fehler |
| Elemente in einer Liste von Objekten | 100, für das Tag und für jede verschachtelte Liste | Der gesamte geschriebene Wert wird abgelehnt |
| Größe eines geschriebenen Werts | 64 KB JSON | Der gesamte geschriebene Wert wird abgelehnt |
Ein abgelehnter Wert wird genauso behandelt wie ein Wert mit einem falschen Feldtyp, siehe Schreiben ersetzt den gesamten Wert.
Schema-Regeln
Anchor link toPushwoosh prüft diese Regeln, wenn Sie ein Objekt-Tag erstellen oder ein Feld hinzufügen:
- Objekt- und Feldnamen enthalten nur lateinische Buchstaben, Ziffern und
_. - Das Tag und jedes verschachtelte Objekt oder jede verschachtelte Liste haben 1 bis 20 Felder. Die anderen Limits gelten ebenfalls. Bei Feldnamen wird die Groß- und Kleinschreibung nicht beachtet, daher sind
Amountundamountdasselbe Feld. - Ein Feld hat einen dieser Typen:
INTEGER,STRING,LIST,DATE,BOOLEAN,PRICE,VERSION,OBJECT,OBJECT_LIST. Ein Feld vom TypOBJECToderOBJECT_LISTbenötigt eigenefields. Zeitzonenfelder werden nicht unterstützt. - Ein Feld kann keinen Namen erhalten, den bereits ein anderes Tag hat. Wenn ein Tag
order.noteexistiert, schlägt das Hinzufügen des Feldesnotezuordermittag order.note already existsfehl. - Ein Objekt kann sein letztes Feld nicht verlieren. Löschen Sie stattdessen das Objekt.
- Ein Feld oder ein Objekt-Tag, das verwendet wird, kann nicht gelöscht werden. Ein verschachteltes Objekt oder eine verschachtelte Liste gilt als verwendet, wenn etwas darin verwendet wird. Der Fehler listet auf, wo es verwendet wird, zum Beispiel
field is in use: segment Big buyers, in-app Spring sale. Segmente, In-Apps, laufende Customer Journey-Kampagnen, Presets, E-Mail-Vorlagen und andere Elemente, die auf das Tag verweisen, zählen als Verwendungen.
Objekt-Tags im Control Panel verwalten
Anchor link toErstellen Sie ein Objekt-Tag ohne verschachtelte Objekte und Listen im Control Panel:
- Klicken Sie auf der Seite Tags Ihres Control Panel auf Tag erstellen.
- Geben Sie den Tag-Name ein.
- Wählen Sie unter Werttyp Objekt oder Liste von Objekten.
- Geben Sie unter Felder den Namen des ersten Feldes ein.
- Wählen Sie den Typ des Feldes.
- Um ein weiteres Feld hinzuzufügen, klicken Sie auf Feld hinzufügen.
- Klicken Sie auf Erstellen.
Auf der Tag-Seite können Sie ein Feld hinzufügen oder neben einem Feld auf Entfernen klicken, um es zu löschen. Das Control Panel kann kein verschachteltes Objekt und keine verschachtelte Liste erstellen und deren Felder nicht ändern. Ein über die API erstelltes verschachteltes Objekt oder eine verschachtelte Liste zeigt es als ein Feld vom Typ Objekt oder Liste von Objekten an. Wenn Sie dieses Feld löschen, wird es mit allem darin gelöscht.
Schema verwalten
Anchor link toErstellen und ändern Sie Objekt-Tags mit den folgenden REST-Methoden. Verwenden Sie /json/1.3/addTag nur für reguläre Tags, da diese Methode keine Felder definieren kann.
Basis-URL
Anchor link tohttps://rpc-api.svc-nue.pushwoosh.comAuthentifizierung
Anchor link toJede Anfrage muss einen Authorization-Header mit Ihrem Server API Token enthalten. Ein Device API Token erhält HTTP 403 a device API token cannot call this method, use an account API token.
Authorization: Api YOUR_API_TOKENEndpunkte
Anchor link toDiese Methoden verwalten das Schema von Objekt-Tags und lesen die Werte ihrer Felder:
| Methode | Pfad | Beschreibung |
|---|---|---|
POST | /api/tags | Ein Objekt-Tag mit seinen Feldern erstellen |
GET | /api/tags/{name} | Ein Objekt-Tag mit seinen Feldern abrufen |
GET | /api/tags | Tags auflisten. Ein Objekt-Tag wird mit allen seinen fields zurückgegeben, einschließlich verschachtelter, und die Felder werden nicht als separate Tags aufgelistet |
POST | /api/tags/{name}/fields | Ein Feld zu einem Objekt-Tag, einem verschachtelten Objekt oder einer verschachtelten Liste hinzufügen |
DELETE | /api/tags/{name}/fields/{field} | Ein Feld, ein verschachteltes Objekt oder eine verschachtelte Liste löschen |
DELETE | /api/tags/{name} | Ein Objekt-Tag mit allen seinen Feldern löschen |
GET | /api/tags:values | Die gespeicherten Werte eines Felds auflisten, siehe Gespeicherte Werte eines Felds |
POST /api/tags gibt das Objekt-Tag zurück, und beide Feldmethoden geben das in {name} genannte Objekt nach der Änderung zurück, eingeschlossen in {"tag": {...}}. DELETE /api/tags/{name} gibt {} zurück.
Wenn Objekt-Tags für Ihr Konto nicht aktiviert sind, schlagen POST /api/tags mit einem Objekttyp und beide Feldmethoden mit HTTP 403 object tags are not enabled for the account fehl. GET /api/tags/{name} und DELETE /api/tags/{name} geben HTTP 404 tag not found zurück, und GET /api/tags listet keine Objekt-Tags auf. Ohne aktivierte Objekt-Tags können Sie keines erstellen, daher gibt es nichts, wohin Werte geschrieben werden könnten.
Objekt-Tag erstellen
Anchor link toPOST /api/tags
Request-Body
Anchor link to| Name | Typ | Beschreibung |
|---|---|---|
| name* | string | Name des Objekt-Tags. |
| type* | string | OBJECT für ein Objekt oder OBJECT_LIST für eine Liste von Objekten. |
| fields* | array | Felder des Objekts, 1 bis 20. |
| fields[].name* | string | Feldname. Das Feld wird zum Tag <name>.<fields[].name>. |
| fields[].type* | string | Feldtyp: INTEGER, STRING, LIST, DATE, BOOLEAN, PRICE, VERSION, OBJECT oder OBJECT_LIST. |
| fields[].fields | array | Felder eines verschachtelten Objekts oder einer verschachtelten Liste, 1 bis 20, im selben Format. Erforderlich für die Typen OBJECT und OBJECT_LIST, für andere Typen ignoriert. |
{ "name": "orders", "type": "OBJECT_LIST", "fields": [ { "name": "amount", "type": "INTEGER" }, { "name": "status", "type": "STRING" } ]}{ "tag": { "name": "orders", "type": "OBJECT_LIST", "system": false, "user_specific": true, "has_right_ace_modify": true, "fields": [ { "name": "amount", "type": "INTEGER", "fields": [] }, { "name": "status", "type": "STRING", "fields": [] } ] }}Das Tag wird unabhängig vom Wert von user_specific als User-specific erstellt. GET /api/tags/{name} gibt dasselbe Objekt ohne den tag-Wrapper zurück. Die Felder sind nach Namen sortiert, und ein Feld ohne verschachtelte Felder wird mit einem leeren fields-Array zurückgegeben.
Um verschachtelte Objekte und Listen zu erstellen, geben Sie einem Feld den Typ OBJECT oder OBJECT_LIST und eigene fields. Eine Anfrage erstellt die gesamte Struktur:
{ "name": "profile", "type": "OBJECT", "fields": [ { "name": "address", "type": "OBJECT", "fields": [ { "name": "city", "type": "STRING" }, { "name": "geo", "type": "OBJECT", "fields": [{ "name": "lat", "type": "STRING" }] } ] }, { "name": "visits", "type": "OBJECT_LIST", "fields": [{ "name": "code", "type": "STRING" }] } ]}Verschachtelte Felder werden mit Namen relativ zu ihrem Objekt zurückgegeben, zum Beispiel city innerhalb von address. GET /api/tags/{name} akzeptiert nur den Namen des Tags selbst. Ein verschachtelter Name wie profile.address gibt HTTP 404 tag not found zurück.
Feld hinzufügen
Anchor link toPOST /api/tags/{name}/fields
{ "field": { "name": "note", "type": "STRING" }}Um ein Feld zu einem verschachtelten Objekt oder einer verschachtelten Liste hinzuzufügen, geben Sie deren vollständigen Namen in {name} an, zum Beispiel POST /api/tags/profile.address/fields oder POST /api/tags/profile.visits/fields. Das neue Feld kann ein verschachteltes Objekt oder eine verschachtelte Liste mit eigenen fields sein:
{ "field": { "name": "company", "type": "OBJECT", "fields": [{ "name": "title", "type": "STRING" }] }}Sie können das neue Feld sofort als Teil des gesamten Tag-Werts schreiben. Das Hinzufügen eines Feldes schlägt fehl, wenn das Objekt bereits 20 Felder hat, wenn das Feld ein anderes Limit verletzt oder wenn ein Tag mit dem vollständigen Feldnamen existiert, siehe Fehler.
Feld löschen
Anchor link toDELETE /api/tags/{name}/fields/{field}
Zum Beispiel löscht DELETE /api/tags/orders/fields/note das Feld orders.note. Um ein Feld eines verschachtelten Objekts oder einer verschachtelten Liste zu löschen, geben Sie deren vollständigen Namen in {name} an: DELETE /api/tags/profile.address/fields/city.
Das Löschen eines verschachtelten Objekts oder einer verschachtelten Liste löscht alles darin: DELETE /api/tags/profile/fields/address löscht auch profile.address.city und profile.address.geo. Sie können weder das letzte Feld eines Objekts noch ein Feld, ein verschachteltes Objekt oder eine verschachtelte Liste löschen, das bzw. die verwendet wird, siehe Fehler.
Fehler
Anchor link toFehler haben das Format {"code": <n>, "message": "...", "details": [...]}. Beim Erstellen eines Objekt-Tags hat eine 400-Meldung die Form validate: rpc error: code = InvalidArgument desc = <message>, wobei <message> der Text aus der Tabelle ist. In diesen Meldungen ist <object> der vollständige Name des Objekts, zum Beispiel profile.address.
| HTTP-Status | Meldung | Ursache |
|---|---|---|
| 400 | object tag and field names must contain only letters, digits and underscores | Ein Name enthält ein anderes Zeichen. |
| 400 | <object>: an object needs 1 to 20 fields | Beim Erstellen hat das Tag, ein verschachteltes Objekt oder eine verschachtelte Liste keine Felder oder mehr als 20 Felder. |
| 400 | an object has at most 20 fields | Das Objekt, zu dem Sie ein Feld hinzufügen, hat bereits 20 Felder. |
| 400 | <object>.<field>: objects nest at most 3 levels deep | Ein Feld vom Typ OBJECT oder OBJECT_LIST läge auf der vierten Ebene. |
| 400 | an object tag holds at most 50 fields with values, nested ones included | Das Objekt-Tag hätte mehr als 50 Felder mit Werten. |
| 400 | field <name> is given twice | Zwei Felder haben denselben Namen, ohne Beachtung der Groß- und Kleinschreibung. |
| 400 | <object>.<field>: object and field names together cannot be longer than 64 characters | Der vollständige Feldname ist zu lang. |
| 400 | <object>.<field>: field type must be INTEGER, STRING, LIST, DATE, BOOLEAN, PRICE, VERSION, OBJECT or OBJECT_LIST | Nicht unterstützter Feldtyp. |
| 400 | an object needs at least one field; delete the object instead | Sie haben versucht, das letzte Feld eines Objekts zu löschen. |
| 400 | field is in use: ..., tag is in use: ... | Das Feld, etwas innerhalb des verschachtelten Objekts oder der verschachtelten Liste oder das Objekt-Tag wird in Segmenten, In-Apps, Customer Journey-Kampagnen oder anderen Elementen verwendet. |
| 403 | object tags are not enabled for the account | Objekt-Tags sind für das Konto nicht aktiviert. |
| 403 | a device API token cannot call this method, use an account API token | Die Anfrage verwendet ein Device API Token. |
| 404 | tag not found | GET oder DELETE /api/tags/{name}: Es gibt kein solches Tag, der Name ist ein Feld, oder Objekt-Tags sind nicht aktiviert. |
| 404 | object tag not found, field not found | Feldmethoden: Es gibt kein solches Objekt-Tag, verschachteltes Objekt, keine solche verschachtelte Liste oder kein solches Feld. Ein {name}, das ein Feld mit einem Wert ist, gibt ebenfalls object tag not found zurück. |
| 409 | tag already exists | Ein Tag mit dem Namen des Objekt-Tags existiert. |
| 409 | tag <object>.<field> already exists | Ein Tag mit dem vollständigen Namen des Feldes existiert. |
Werte schreiben
Anchor link toSchreiben Sie Werte von Objekt-Tags mit /setTags und /bulkSetTags. Diese Methoden behalten ihre eigene Authentifizierung: /setTags erwartet ein Device API Token im Header Authorization: Token, und /bulkSetTags erwartet das API-Zugriffstoken in auth. Senden Sie einen Object-Wert als JSON-Objekt und einen ObjectList-Wert als Array von Objekten:
{ "request": { "application": "XXXXX-XXXXX", "userId": "user_42", "tags": { "order": { "amount": 120, "status": "paid" }, "orders": [ { "amount": 120, "status": "paid" }, { "amount": 50 } ] } }}Wenn Sie den Wert per HWID festlegen, wird er beim Benutzer dieses Geräts gespeichert. POST /api/devices:set_tags unter der Basis-URL der Schema-Methoden schreibt Objekt-Tags nach denselben Regeln. Seine Antwort listet die Felder von Objekten als flache Namen auf, zum Beispiel "profile.address.city".
Ein verschachteltes Objekt erwartet ein JSON-Objekt, eine verschachtelte Liste ein Array von Objekten:
"tags": { "profile": { "address": { "city": "Berlin", "geo": { "lat": "52.5" } }, "visits": [{ "code": "v1" }] }, "orders": [ { "sku": "A-1", "meta": { "color": "red" }, "lines": [{ "qty": 2 }, { "qty": 3 }] } ]}Jedes Feld nimmt einen Wert im Format seines Typs an:
| Feldtyp | Beispielwert |
|---|---|
INTEGER | 120 |
STRING | "paid" |
LIST | ["gift", "express"] |
DATE | "2026-10-02 22:11" (UTC), "2026-10-02" oder ein Unix-Zeitstempel in Sekunden |
BOOLEAN | true oder false |
PRICE | 19.95 |
VERSION | "1.0.0" |
Schreiben ersetzt den gesamten Wert
Anchor link toJeder Schreibvorgang ersetzt den gespeicherten Wert des Objekt-Tags:
- Ein Feld, das im neuen Wert fehlt, wird gelöscht. Ein als
nullgesendetes Feld wird ebenfalls gelöscht. null,[]oder""löscht den gesamten Wert.{}löscht alle Felder einesObject-Tags.- Ein Schlüssel, der kein Feld des Objekts ist, wird übersprungen.
- Wenn ein Feldwert auf einer beliebigen Ebene nicht zum Feldtyp passt, wird der gesamte Wert des Tags abgelehnt und der gespeicherte Wert bleibt unverändert. Dasselbe passiert, wenn der Wert ein Limit verletzt: eine Liste mit mehr als 100 Elementen oder mehr als 64 KB JSON.
/setTags meldet einen abgelehnten Wert nicht in seiner Antwort und gibt HTTP 200 zurück. Prüfen Sie das Ergebnis mit /getTags oder verwenden Sie /bulkSetTags, das für jedes Tag ein Ergebnis meldet.
Ausgeblendete Felder
Anchor link toEin ausgeblendetes Feld ist ein Feld, das Pushwoosh für die eigene Verwendung als ausgeblendet markiert. Mit den Schema-Methoden auf dieser Seite können Sie ein Feld weder erstellen noch ausblenden. /getTags gibt ausgeblendete Felder nicht zurück, daher enthält ein Wert, den Sie lesen und zurückschreiben, sie nie. Was beim Schreiben mit ihnen passiert, hängt vom Typ ab:
Object. Ein ausgeblendetes Feld, das im neuen Wert fehlt, bleibt auf jeder Ebene erhalten. Ein sichtbares verschachteltes Objekt, das im neuen Wert fehlt, wird mit allem darin gelöscht, einschließlich ausgeblendeter Felder. Wenn Sie den gesamten Wert löschen, werden auch ausgeblendete Felder gelöscht.ObjectList. Das Schreiben der Liste ersetzt alle ihre Elemente, und ausgeblendete Felder der alten Elemente gehen verloren. Ein Element hat keine Kennung, daher kann ein neues Element keinem alten zugeordnet werden. Dasselbe gilt für eine verschachtelte Liste.
Einen Teil eines Object schreiben
Anchor link toSchreiben Sie ein einzelnes Feld, ein verschachteltes Objekt oder eine verschachtelte Liste eines Object-Tags über den vollständigen Namen statt des gesamten Tag-Werts. increment und die anderen Operationen von /setTags funktionieren mit Feldern:
"tags": { "order.status": "shipped", "order.amount": { "operation": "increment", "value": 5 }}Dasselbe funktioniert für ein Feld eines verschachtelten Objekts, über dem nur Objekte liegen, zum Beispiel "profile.address.city": "Paris".
Ein verschachteltes Objekt oder eine verschachtelte Liste, über dem bzw. der nur Objekte liegen, kann einzeln über den vollständigen Namen geschrieben werden, zum Beispiel profile.address oder profile.visits. Der Wert ersetzt nur diesen Teil, und der Rest von profile bleibt unverändert. Die Limits von 100 Elementen und 64 KB gelten ab diesem Wert:
"tags": { "profile.address": { "city": "Paris" }, "profile.visits": [{ "code": "v2" }]}Nichts innerhalb einer Liste von Objekten kann einzeln geschrieben werden, da nicht klar ist, welches Element geändert werden soll. Das betrifft ein Feld eines ObjectList-Tags, zum Beispiel orders.sku, und alles innerhalb eines Elements, zum Beispiel orders.meta oder profile.visits.code. /setTags überspringt einen solchen Wert. Senden Sie stattdessen die gesamte Liste.
Objekt-Tags werden nicht automatisch erstellt
Anchor link toEin Wert mit einem Objekt oder einem Array von Objekten für ein nicht existierendes Tag wird übersprungen. Die automatische Tag-Erstellung erstellt keine Objekt-Tags, erstellen Sie daher zuerst das Schema mit POST /api/tags.
bulkSetTags-Ergebnisse
Anchor link toMit detailed=true gibt /bulkSetTags-Status für ein Objekt-Tag zusätzlich zu ok, tag not found und wrong value. expect :<type> eines dieser Ergebnisse zurück:
| Ergebnis | Ursache |
|---|---|
object tags are stored on the user only | Das Objekt-Tag ist nicht User-specific. |
cannot load the fields of the object | Pushwoosh konnte die Felder des Objekt-Tags nicht lesen. |
wrong value. expect an object (a map) or, for a list of objects, an array of maps | Der Wert passt nicht zum Objekt-Tag, ein Feldwert auf einer beliebigen Ebene passt nicht zu seinem Typ, oder der Wert verletzt ein Limit. |
a field of a list of objects cannot be set on its own, set the whole list | Der Wert wird für etwas innerhalb einer Liste von Objekten festgelegt, zum Beispiel orders.sku oder orders.meta. |
Werte lesen
Anchor link to/getTags gibt einen Object-Wert als JSON-Objekt und einen ObjectList-Wert als Array von Objekten zurück:
{ "status_code": 200, "status_message": "OK", "response": { "result": { "order": { "amount": 120, "status": "paid" }, "orders": [ { "amount": 120, "status": "paid" }, { "amount": 50 } ] } }}Verschachtelte Objekte und Listen werden auf jeder Ebene in derselben Form zurückgegeben, in der Sie sie schreiben, zum Beispiel "profile": {"address": {"city": "Berlin"}, "visits": [{"code": "v1"}]}.
Feldwerte werden in /getTags genauso zurückgegeben wie die Werte regulärer Tags: ein Date als Unix-Zeitstempel in Sekunden, ein Price als Zeichenfolge wie "120.00" und ein Boolean als 1 oder 0.
Gespeicherte Werte eines Felds
Anchor link toGET /api/tags:values auf der Basis-URL listet die unterschiedlichen Werte eines Felds auf, mit der Anzahl der Abonnenten für jeden Wert. Übergeben Sie den vollständigen Namen des Felds in name, zum Beispiel profile.address.city oder orders.sku.
Abfrageparameter
Anchor link to| Name | Typ | Beschreibung |
|---|---|---|
| application* | string | Anwendungscode, XXXXX-XXXXX. |
| name* | string | Vollständiger Name des Felds. |
| like | string | Nur Werte zurückgeben, die diesen Text an der durch like_op festgelegten Position enthalten. |
| like_op | string | STARTS_WITH (Standard), ENDS_WITH oder CONTAINS. |
| order_by | string | VALUE (Standard) oder COUNT. |
| order_direction | string | ASC (Standard) oder DESC. |
| limit | integer | Anzahl der zurückzugebenden Werte. Standardmäßig 100. |
| offset | integer | Anzahl der zu überspringenden Werte. |
| page | integer | Seitennummer, beginnend bei 0. Wird mit per_page statt limit und offset verwendet. |
| per_page | integer | Anzahl der Werte auf einer Seite. |
GET /api/tags:values?application=XXXXX-XXXXX&name=orders.sku&order_by=COUNT&order_direction=DESC{ "values": [ { "value": "A-1", "count": 120 }, { "value": "B-2", "count": 45 } ], "total": 2, "page": 0, "per_page": 100}Integer- und Price-Felder geben keine Werte zurück, genauso wie reguläre Tags dieser Typen. Ein Objekt-Tag, ein verschachteltes Objekt oder eine verschachtelte Liste selbst hat keine eigenen Werte, daher gibt sein Name HTTP 404 tag not found zurück.
Nach Feldern segmentieren
Anchor link toLegen Sie Segmentbedingungen für Felder fest, nicht für das Objekt-Tag selbst. In der Segmentierungssprache ist ein Feld ein Tag mit einem Namen mit Punkt, und es verwendet die Operatoren seines eigenen Typs:
AT("XXXXX-XXXXX", "order.amount", gte, 100)Ein Feld eines verschachtelten Objekts oder einer verschachtelten Liste wird über seinen vollständigen Namen angegeben, zum Beispiel profile.address.city, profile.visits.code oder orders.meta.color. Eine Bedingung für das Objekt-Tag selbst, ein verschachteltes Objekt oder eine verschachtelte Liste, zum Beispiel profile.address, schlägt mit object tag has no value of its own, use one of its fields fehl.
Ein Feld mit zwei Listen von Objekten darüber, zum Beispiel orders.lines.qty, wird nur gespeichert. Das Segment mit einer solchen Bedingung wird gespeichert, aber seine Berechnung oder ein Versand daran schlägt mit a field inside a list nested in a list is stored only and cannot be searched fehl.
Bedingungen für eine ObjectList
Anchor link toEine Bedingung für ein Feld eines ObjectList-Tags trifft auf einen Benutzer zu, wenn mindestens ein Element der Liste die Bedingung erfüllt. Mit AND verknüpfte Bedingungen für Felder derselben Liste müssen auf dasselbe Element zutreffen:
AT("XXXXX-XXXXX", "orders.amount", gte, 100) * AT("XXXXX-XXXXX", "orders.status", eq, "paid")Dieses Segment enthält Benutzer mit mindestens einer Bestellung, die sowohl 100 oder mehr beträgt als auch bezahlt ist. Ein Benutzer mit einer großen unbezahlten Bestellung und einer kleinen bezahlten Bestellung trifft nicht zu. Für die Felder eines Objekts innerhalb eines Elements wird dasselbe Element geprüft: orders.sku gleich A-1 AND orders.meta.color gleich red trifft auf einen Benutzer mit einer Bestellung zu, die beides hat. Mit OR verknüpfte Bedingungen müssen nicht auf dasselbe Element zutreffen. Bedingungen für zwei verschiedene Listen werden für jede Liste separat geprüft.
Einige Operatoren funktionieren für ein Feld eines ObjectList-Tags anders:
notset. Kein Element der Liste hat einen Wert in diesem Feld. Ein Benutzer ohne die Liste trifft ebenfalls zu.noteq. Mindestens ein Element hat einen Wert in diesem Feld, und dieser Wert unterscheidet sich vom angegebenen. Elemente ohne das Feld zählen nicht. Ein Benutzer mit Bestellungen in den Statuspaidundnewtrifft aufnoteq "paid"zu.notinfür ein List-Feld. Kein Element enthält einen der angegebenen Werte.notinfür ein Feld eines anderen Typs. Mindestens ein Element hat in diesem Feld einen Wert, der nicht unter den angegebenen Werten ist.
notset und notin für ein List-Feld sind nicht an dasselbe Element gebunden wie die anderen mit AND verknüpften Bedingungen. Diese Regeln gelten auch für verschachtelte Listen wie profile.visits.
Werte in Nachrichten verwenden
Anchor link toFügen Sie Felder von Objekt-Tags mit Liquid-Vorlagen in Push-Benachrichtigungen, E-Mails, SMS und Messenger-Nachrichten wie WhatsApp ein. Liquid funktioniert nur, wenn Inhaltsvorlagen für Ihr Konto aktiviert sind. Geben Sie ein Feld auf jeder Ebene über seinen vollständigen Namen an:
Your city is {{ profile.address.city }}.Greifen Sie über seinen Index, beginnend bei 0, auf ein Element einer Liste von Objekten zu:
Your first order is {{ orders[0].sku }}, quantity {{ orders[0].lines[0].qty }}.Ein Index hinter dem Ende der Liste oder eine Liste, die der Benutzer nicht hat, wird als leere Zeichenfolge ausgegeben. Prüfen Sie zuerst das Element oder legen Sie mit default einen Fallback fest:
{% if orders[0] %}Your first order is {{ orders[0].sku }}.{% endif %}Your first order is {{ orders[0].sku | default: "on its way" }}.Durchlaufen Sie eine Liste von Objekten, auch eine Liste innerhalb eines Elements:
{% for o in orders %}{{ o.meta.color }}{% for l in o.lines %}{{ l.qty }}{% endfor %}{% endfor %}Nur gespeicherte Felder wie orders.lines.qty funktionieren in Vorlagen genauso wie andere Felder.
Segmente mit Objekt-Tags exportieren
Anchor link to/exportSegment exportiert die Felder von Objekt-Tags:
- CSV. Jedes Feld mit einem Wert ist eine separate Spalte, benannt nach seinem vollständigen Namen, zum Beispiel
order.amountoderprofile.address.city. Objekt-Tags, verschachtelte Objekte und verschachtelte Listen selbst erhalten keine Spalte. Ein Feld innerhalb einer Liste von Objekten enthält auf jeder Ebene die unterschiedlichen Werte aus allen Elementen als JSON-Array, genauso wie ein List-Tag:["A-1","B-2"]. Das Array ist sortiert und zeigt nicht, aus welchem Element ein Wert stammt, daher bleibt auch die Reihenfolge der Elemente nicht erhalten. Um die Elemente vollständig zu erhalten, exportieren Sie injsonoderjson_each_line. jsonundjson_each_line. Objekt-Tags werden verschachtelt ausgegeben, in derselben Form, in der/getTagssie zurückgibt. EinObject-Tag ist ein Eintrag intagsmit seinen Feldern unterobject.fields, und ein verschachteltes Objekt darin trägt seine eigenen Felder ebenfalls unterobject.fields, auf jeder Ebene. EinObjectList-Tag ist ein Eintrag mit seinen Elementen inobject_list.items, ebenso eine verschachtelte Liste. Felder haben kurze Namen, sind nach Namen sortiert und tragen ihren Wert unter einem Schlüssel, der nach dem Typ benannt ist:integer,string,list,date,boolean,priceoderversion:
{ "name": "profile", "object": { "fields": [ { "name": "address", "object": { "fields": [{ "name": "city", "string": "Berlin" }] } }, { "name": "visits", "object_list": { "items": [{ "fields": [{ "name": "code", "string": "v1" }] }] } } ] }}Ein ObjectList-Tag sieht so aus. Integer-Werte werden als Zeichenfolgen ausgegeben:
{ "name": "orders", "object_list": { "items": [ { "fields": [{ "name": "amount", "integer": "120" }, { "name": "status", "string": "paid" }] }, { "fields": [{ "name": "amount", "integer": "50" }] } ] }}Ein Element mit einem verschachtelten Objekt und einer verschachtelten Liste sieht so aus:
{ "fields": [ { "name": "meta", "object": { "fields": [{ "name": "color", "string": "red" }] } }, { "name": "lines", "object_list": { "items": [{ "fields": [{ "name": "qty", "integer": "2" }] }] } } ]}Wenn tagsList ein Objekt-Tag nennt, werden alle seine Felder exportiert, einschließlich verschachtelter.