API des tags d'objet (bêta)
Les tags d’objet stockent des données structurées sur un utilisateur dans un seul tag. Un tag de type Object contient un objet avec des champs nommés, comme la dernière commande order avec son amount et son status. Un tag de type ObjectList contient un tableau de tels objets, comme toutes les commandes orders. Un champ peut lui-même être un objet ou une liste d’objets, comme l’adresse address d’un profil profile. Vous définissez les champs une seule fois, écrivez et lisez les valeurs via l’API des tags, créez des segments selon les valeurs des champs et insérez les valeurs dans les messages avec Liquid.
Fonctionnement des tags d’objet
Anchor link toUn tag d’objet possède un schéma et une valeur. Le schéma est le nom du tag et une liste de champs, chacun avec son propre type. La valeur est stockée dans les champs, séparément pour chaque utilisateur.
- Champ. Chaque champ est un tag nommé
<object>.<field>, par exempleorder.amount. Vous segmentez selon les champs, et vous pouvez écrire un champ d’un tagObjectpar ce nom. - Valeur
Object. Un objet par utilisateur, par exemple"order": {"amount": 120, "status": "paid"}. - Valeur
ObjectList. Un tableau d’objets avec les mêmes champs, par exemple"orders": [{"amount": 120, "status": "paid"}, {"amount": 50}]. - Objet imbriqué. Un champ de type
OBJECTavec ses propres champs, par exempleprofile.addressavec le champprofile.address.city. - Liste imbriquée. Un champ de type
OBJECT_LIST, un tableau d’objets à l’intérieur d’un tag d’objet, par exempleprofile.visits. Voir Objets et listes imbriqués.
Dans l’API, les types de tags et de champs sont OBJECT et OBJECT_LIST. Dans le Panneau de Contrôle, ce sont Objet et Liste d’objets. Sur cette page, une liste d’objets désigne un tag ObjectList ou une liste imbriquée.
Les tags d’objet sont toujours User-specific : la valeur appartient à l’utilisateur, et non à un seul appareil, et elle est copiée sur tous les appareils de l’utilisateur. Consultez l’API de Tags pour les tags classiques.
Objets et listes imbriqués
Anchor link toUn champ d’un tag d’objet peut contenir ses propres champs au lieu d’une valeur unique. Un objet imbriqué, un champ de type OBJECT, contient un objet. Une liste imbriquée, un champ de type OBJECT_LIST, contient une liste d’objets. Un élément d’une liste peut lui aussi contenir des objets et des listes imbriqués. Chaque champ conserve son nom complet avec des points, comme profile.address.city, et vous segmentez selon ces noms.
Par exemple, un tag profile de type OBJECT et un tag orders de type OBJECT_LIST peuvent avoir cette structure :
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 INTEGERChamps consultables et champs uniquement stockés
Anchor link toCe que vous pouvez faire avec un champ dépend du nombre de listes d’objets au-dessus de lui :
- Aucune liste au-dessus du champ. Vous pouvez segmenter selon un champ comme
profile.address.city, l’écrire seul par son nom complet et l’utiliser dans les messages. - Une liste au-dessus du champ. Vous pouvez segmenter selon un champ comme
profile.visits.codeouorders.meta.coloret l’utiliser dans les messages. Écrivez-le uniquement dans le cadre de la liste entière. - Deux listes au-dessus du champ. Un champ comme
orders.lines.qtyest uniquement stocké. Utilisez-le dans les messages, mais pas dans les segments.
Limites
Anchor link toPushwoosh applique ces limites aux tags d’objet, objets et listes imbriqués compris :
| Limite | Valeur | En cas de dépassement |
|---|---|---|
| Profondeur d’imbrication | 3 niveaux d’objets et de listes. Le tag lui-même est le premier niveau, donc profile.address.geo est l’objet le plus profond autorisé | La méthode de schéma renvoie HTTP 400, voir Erreurs |
| Champs dans un objet | De 1 à 20, pour le tag et pour chaque objet imbriqué ou liste imbriquée | La méthode de schéma renvoie HTTP 400, voir Erreurs |
| Champs avec des valeurs dans un tag d’objet | 50, champs imbriqués compris. Les champs de type OBJECT et OBJECT_LIST ne comptent pas | La méthode de schéma renvoie HTTP 400, voir Erreurs |
| Nom complet du champ | 64 caractères, comme profile.address.city | La méthode de schéma renvoie HTTP 400, voir Erreurs |
| Éléments dans une liste d’objets | 100, pour le tag et pour chaque liste imbriquée | Toute la valeur écrite est rejetée |
| Taille d’une valeur écrite | 64 Ko de JSON | Toute la valeur écrite est rejetée |
Une valeur rejetée est traitée de la même manière qu’une valeur avec un type de champ incorrect, voir L’écriture remplace toute la valeur.
Règles du schéma
Anchor link toPushwoosh vérifie ces règles lorsque vous créez un tag d’objet ou ajoutez un champ :
- Les noms d’objets et de champs ne contiennent que des lettres latines, des chiffres et
_. - Le tag et chaque objet imbriqué ou liste imbriquée comportent de 1 à 20 champs. Les autres limites s’appliquent aussi. Les noms de champs ne sont pas sensibles à la casse :
Amountetamountdésignent le même champ. - Un champ a l’un de ces types :
INTEGER,STRING,LIST,DATE,BOOLEAN,PRICE,VERSION,OBJECT,OBJECT_LIST. Un champ de typeOBJECTouOBJECT_LISTa besoin de ses propresfields. Les champs de fuseau horaire ne sont pas pris en charge. - Un champ ne peut pas prendre un nom déjà porté par un autre tag. Si un tag
order.noteexiste, l’ajout du champnoteàorderéchoue avectag order.note already exists. - Un objet ne peut pas perdre son dernier champ. Supprimez plutôt l’objet.
- Un champ ou un tag d’objet en cours d’utilisation ne peut pas être supprimé. Un objet imbriqué ou une liste imbriquée est considéré comme utilisé lorsqu’un élément à l’intérieur est utilisé. L’erreur indique où il est utilisé, par exemple
field is in use: segment Big buyers, in-app Spring sale. Les segments, les in-apps, les campagnes Customer Journey en cours, les presets, les modèles d’e-mail et les autres éléments qui font référence au tag comptent comme des utilisations.
Gérer les tags d’objet dans le Panneau de Contrôle
Anchor link toCréez un tag d’objet sans objets ni listes imbriqués dans le Panneau de Contrôle :
- Sur la page Tags de votre Panneau de Contrôle, cliquez sur Créer un tag.
- Saisissez le Nom du tag.
- Dans Type de valeur, choisissez Objet ou Liste d’objets.
- Sous Champs, saisissez le nom du premier champ.
- Choisissez le type du champ.
- Pour ajouter un autre champ, cliquez sur Ajouter un champ.
- Cliquez sur Créer.
Sur la page du tag, ajoutez un champ ou cliquez sur Supprimer à côté d’un champ pour le supprimer. Le Panneau de Contrôle ne peut pas créer d’objet imbriqué ni de liste imbriquée, ni modifier leurs champs. Il affiche un objet imbriqué ou une liste imbriquée créé via l’API comme un seul champ de type Objet ou Liste d’objets. La suppression de ce champ le supprime avec tout ce qu’il contient.
Gérer le schéma
Anchor link toCréez et modifiez les tags d’objet avec les méthodes REST ci-dessous. Utilisez /json/1.3/addTag uniquement pour les tags classiques, car cette méthode ne peut pas définir de champs.
URL de base
Anchor link tohttps://rpc-api.svc-nue.pushwoosh.comAuthentification
Anchor link toChaque requête doit inclure un en-tête Authorization avec votre jeton API Serveur. Un jeton API Appareil reçoit HTTP 403 a device API token cannot call this method, use an account API token.
Authorization: Api YOUR_API_TOKENPoints de terminaison
Anchor link toCes méthodes gèrent le schéma des tags d’objet et lisent les valeurs de leurs champs :
| Méthode | Chemin | Description |
|---|---|---|
POST | /api/tags | Créer un tag d’objet avec ses champs |
GET | /api/tags/{name} | Obtenir un tag d’objet avec ses champs |
GET | /api/tags | Lister les tags. Un tag d’objet est renvoyé avec tous ses fields, champs imbriqués compris, et les champs ne sont pas listés comme des tags distincts |
POST | /api/tags/{name}/fields | Ajouter un champ à un tag d’objet, un objet imbriqué ou une liste imbriquée |
DELETE | /api/tags/{name}/fields/{field} | Supprimer un champ, un objet imbriqué ou une liste imbriquée |
DELETE | /api/tags/{name} | Supprimer un tag d’objet avec tous ses champs |
GET | /api/tags:values | Lister les valeurs stockées d’un champ, voir Valeurs stockées d’un champ |
POST /api/tags renvoie le tag d’objet, et les deux méthodes de champs renvoient l’objet nommé dans {name} après la modification, encapsulé dans {"tag": {...}}. DELETE /api/tags/{name} renvoie {}.
Si les tags d’objet ne sont pas activés pour votre compte, POST /api/tags avec un type objet et les deux méthodes de champs échouent avec HTTP 403 object tags are not enabled for the account. GET /api/tags/{name} et DELETE /api/tags/{name} renvoient HTTP 404 tag not found, et GET /api/tags ne liste pas les tags d’objet. Sans les tags d’objet activés, vous ne pouvez pas en créer, il n’y a donc rien dans quoi écrire des valeurs.
Créer un tag d’objet
Anchor link toPOST /api/tags
Corps de la requête
Anchor link to| Nom | Type | Description |
|---|---|---|
| name* | string | Nom du tag d’objet. |
| type* | string | OBJECT pour un objet ou OBJECT_LIST pour une liste d’objets. |
| fields* | array | Champs de l’objet, de 1 à 20. |
| fields[].name* | string | Nom du champ. Le champ devient le tag <name>.<fields[].name>. |
| fields[].type* | string | Type du champ : INTEGER, STRING, LIST, DATE, BOOLEAN, PRICE, VERSION, OBJECT ou OBJECT_LIST. |
| fields[].fields | array | Champs d’un objet imbriqué ou d’une liste imbriquée, de 1 à 20, au même format. Obligatoire pour les types OBJECT et OBJECT_LIST, ignoré pour les autres types. |
{ "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": [] } ] }}Le tag est créé comme User-specific, quelle que soit la valeur de user_specific. GET /api/tags/{name} renvoie le même objet sans l’enveloppe tag. Les champs sont triés par nom, et un champ sans champs imbriqués est renvoyé avec un tableau fields vide.
Pour créer des objets et des listes imbriqués, donnez à un champ le type OBJECT ou OBJECT_LIST et ses propres fields. Une seule requête crée toute la structure :
{ "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" }] } ]}Les champs imbriqués sont renvoyés avec des noms relatifs à leur objet, comme city dans address. GET /api/tags/{name} n’accepte que le nom du tag lui-même. Un nom imbriqué comme profile.address renvoie HTTP 404 tag not found.
Ajouter un champ
Anchor link toPOST /api/tags/{name}/fields
{ "field": { "name": "note", "type": "STRING" }}Pour ajouter un champ à un objet imbriqué ou à une liste imbriquée, indiquez son nom complet dans {name}, par exemple POST /api/tags/profile.address/fields ou POST /api/tags/profile.visits/fields. Le nouveau champ peut être un objet imbriqué ou une liste imbriquée avec ses propres fields :
{ "field": { "name": "company", "type": "OBJECT", "fields": [{ "name": "title", "type": "STRING" }] }}Vous pouvez écrire le nouveau champ immédiatement dans le cadre de la valeur complète du tag. L’ajout d’un champ échoue si l’objet a déjà 20 champs, si le champ enfreint une autre limite ou si un tag portant le nom complet du champ existe, voir Erreurs.
Supprimer un champ
Anchor link toDELETE /api/tags/{name}/fields/{field}
Par exemple, DELETE /api/tags/orders/fields/note supprime le champ orders.note. Pour supprimer un champ d’un objet imbriqué ou d’une liste imbriquée, indiquez son nom complet dans {name} : DELETE /api/tags/profile.address/fields/city.
La suppression d’un objet imbriqué ou d’une liste imbriquée supprime tout ce qu’il contient : DELETE /api/tags/profile/fields/address supprime aussi profile.address.city et profile.address.geo. Vous ne pouvez pas supprimer le dernier champ d’un objet, ni un champ, un objet imbriqué ou une liste imbriquée en cours d’utilisation, voir Erreurs.
Erreurs
Anchor link toLes erreurs sont renvoyées au format {"code": <n>, "message": "...", "details": [...]}. Lorsque vous créez un tag d’objet, un message 400 a la forme validate: rpc error: code = InvalidArgument desc = <message>, où <message> est le texte du tableau. Dans ces messages, <object> est le nom complet de l’objet, comme profile.address.
| Statut HTTP | Message | Cause |
|---|---|---|
| 400 | object tag and field names must contain only letters, digits and underscores | Un nom contient un autre caractère. |
| 400 | <object>: an object needs 1 to 20 fields | À la création, le tag, un objet imbriqué ou une liste imbriquée n’a aucun champ ou plus de 20 champs. |
| 400 | an object has at most 20 fields | L’objet auquel vous ajoutez un champ a déjà 20 champs. |
| 400 | <object>.<field>: objects nest at most 3 levels deep | Un champ OBJECT ou OBJECT_LIST serait au quatrième niveau. |
| 400 | an object tag holds at most 50 fields with values, nested ones included | Le tag d’objet aurait plus de 50 champs avec des valeurs. |
| 400 | field <name> is given twice | Deux champs portent le même nom, sans tenir compte de la casse. |
| 400 | <object>.<field>: object and field names together cannot be longer than 64 characters | Le nom complet du champ est trop long. |
| 400 | <object>.<field>: field type must be INTEGER, STRING, LIST, DATE, BOOLEAN, PRICE, VERSION, OBJECT or OBJECT_LIST | Type de champ non pris en charge. |
| 400 | an object needs at least one field; delete the object instead | Vous avez tenté de supprimer le dernier champ d’un objet. |
| 400 | field is in use: ..., tag is in use: ... | Le champ, un élément à l’intérieur de l’objet imbriqué ou de la liste imbriquée, ou le tag d’objet est utilisé dans des segments, des in-apps, des campagnes Customer Journey ou d’autres éléments. |
| 403 | object tags are not enabled for the account | Les tags d’objet ne sont pas activés pour le compte. |
| 403 | a device API token cannot call this method, use an account API token | La requête utilise un jeton API Appareil. |
| 404 | tag not found | GET ou DELETE /api/tags/{name} : aucun tag de ce nom, le nom est un champ, ou les tags d’objet ne sont pas activés. |
| 404 | object tag not found, field not found | Méthodes de champs : aucun tag d’objet, objet imbriqué, liste imbriquée ou champ de ce nom. Un {name} qui est un champ avec une valeur renvoie aussi object tag not found. |
| 409 | tag already exists | Un tag portant le nom du tag d’objet existe. |
| 409 | tag <object>.<field> already exists | Un tag portant le nom complet du champ existe. |
Écrire des valeurs
Anchor link toÉcrivez les valeurs des tags d’objet avec /setTags et /bulkSetTags. Ces méthodes conservent leur propre authentification : /setTags prend un jeton API Appareil dans l’en-tête Authorization: Token, et /bulkSetTags prend le jeton d’accès API dans auth. Envoyez une valeur Object sous forme d’objet JSON et une valeur ObjectList sous forme de tableau d’objets :
{ "request": { "application": "XXXXX-XXXXX", "userId": "user_42", "tags": { "order": { "amount": 120, "status": "paid" }, "orders": [ { "amount": 120, "status": "paid" }, { "amount": 50 } ] } }}Si vous définissez la valeur par HWID, elle est stockée sur l’utilisateur de cet appareil. POST /api/devices:set_tags sur l’URL de base des méthodes de schéma écrit les tags d’objet selon les mêmes règles. Sa réponse liste les champs des objets sous forme de noms à plat, comme "profile.address.city".
Un objet imbriqué prend un objet JSON, et une liste imbriquée prend un tableau d’objets :
"tags": { "profile": { "address": { "city": "Berlin", "geo": { "lat": "52.5" } }, "visits": [{ "code": "v1" }] }, "orders": [ { "sku": "A-1", "meta": { "color": "red" }, "lines": [{ "qty": 2 }, { "qty": 3 }] } ]}Chaque champ prend une valeur au format de son type :
| Type de champ | Exemple de valeur |
|---|---|
INTEGER | 120 |
STRING | "paid" |
LIST | ["gift", "express"] |
DATE | "2026-10-02 22:11" (UTC), "2026-10-02" ou un timestamp Unix en secondes |
BOOLEAN | true ou false |
PRICE | 19.95 |
VERSION | "1.0.0" |
L’écriture remplace toute la valeur
Anchor link toChaque écriture remplace la valeur stockée du tag d’objet :
- Un champ absent de la nouvelle valeur est supprimé. Un champ envoyé avec
nullest également supprimé. null,[]ou""supprime toute la valeur.{}supprime tous les champs d’un tagObject.- Une clé qui n’est pas un champ de l’objet est ignorée.
- Si la valeur d’un champ, à n’importe quelle profondeur, ne correspond pas au type du champ, toute la valeur du tag est rejetée et la valeur stockée reste inchangée. Il en va de même si la valeur enfreint une limite : une liste de plus de 100 éléments ou plus de 64 Ko de JSON.
/setTags ne signale pas une valeur rejetée dans sa réponse et renvoie HTTP 200. Vérifiez le résultat avec /getTags ou utilisez /bulkSetTags, qui renvoie un résultat pour chaque tag.
Champs masqués
Anchor link toUn champ masqué est un champ que Pushwoosh marque comme masqué pour son propre usage. Les méthodes de schéma de cette page ne permettent ni de créer ni de masquer un champ. /getTags ne renvoie pas les champs masqués, donc une valeur que vous lisez puis réécrivez ne les contient jamais. Ce qu’il advient d’eux lors d’une écriture dépend du type :
Object. Un champ masqué absent de la nouvelle valeur est conservé, à n’importe quelle profondeur. Un objet imbriqué visible absent de la nouvelle valeur est supprimé avec tout son contenu, champs masqués compris. La suppression de toute la valeur supprime aussi les champs masqués.ObjectList. L’écriture de la liste remplace tous ses éléments, et les champs masqués des anciens éléments sont perdus. Un élément n’a pas d’identifiant, donc un nouvel élément ne peut pas être associé à un ancien. Il en va de même pour une liste imbriquée.
Écrire une partie d’un Object
Anchor link toÉcrivez un seul champ, un objet imbriqué ou une liste imbriquée d’un tag Object par son nom complet au lieu de toute la valeur du tag. increment et les autres opérations de /setTags fonctionnent sur les champs :
"tags": { "order.status": "shipped", "order.amount": { "operation": "increment", "value": 5 }}Il en va de même pour un champ d’un objet imbriqué qui n’a que des objets au-dessus de lui, comme "profile.address.city": "Paris".
Un objet imbriqué ou une liste imbriquée qui n’a que des objets au-dessus de lui peut être écrit seul par son nom complet, comme profile.address ou profile.visits. La valeur remplace uniquement cet élément, et le reste de profile reste inchangé. Les limites de 100 éléments et de 64 Ko s’appliquent à partir de cette valeur :
"tags": { "profile.address": { "city": "Paris" }, "profile.visits": [{ "code": "v2" }]}Rien à l’intérieur d’une liste d’objets ne peut être écrit seul, car on ne sait pas quel élément modifier. Cela concerne un champ d’un tag ObjectList, comme orders.sku, et tout ce qui se trouve à l’intérieur d’un élément, comme orders.meta ou profile.visits.code. /setTags ignore une telle valeur. Envoyez plutôt la liste entière.
Les tags d’objet ne sont pas créés automatiquement
Anchor link toUne valeur contenant un objet ou un tableau d’objets pour un tag qui n’existe pas est ignorée. La création automatique de tags ne crée pas de tags d’objet : créez donc d’abord le schéma avec POST /api/tags.
Résultats de bulkSetTags
Anchor link toAvec detailed=true, le statut de /bulkSetTags renvoie l’un de ces résultats pour un tag d’objet, en plus de ok, tag not found et wrong value. expect :<type> :
| Résultat | Cause |
|---|---|
object tags are stored on the user only | Le tag d’objet n’est pas User-specific. |
cannot load the fields of the object | Pushwoosh n’a pas pu lire les champs du tag d’objet. |
wrong value. expect an object (a map) or, for a list of objects, an array of maps | La valeur ne correspond pas au tag d’objet, la valeur d’un champ à n’importe quelle profondeur ne correspond pas à son type, ou la valeur enfreint une limite. |
a field of a list of objects cannot be set on its own, set the whole list | La valeur est définie sur un élément à l’intérieur d’une liste d’objets, comme orders.sku ou orders.meta. |
Lire des valeurs
Anchor link to/getTags renvoie une valeur Object sous forme d’objet JSON et une valeur ObjectList sous forme de tableau d’objets :
{ "status_code": 200, "status_message": "OK", "response": { "result": { "order": { "amount": 120, "status": "paid" }, "orders": [ { "amount": 120, "status": "paid" }, { "amount": 50 } ] } }}Les objets et listes imbriqués sont renvoyés à n’importe quelle profondeur sous la même forme que celle dans laquelle vous les écrivez, par exemple "profile": {"address": {"city": "Berlin"}, "visits": [{"code": "v1"}]}.
Les valeurs des champs sont renvoyées de la même manière que les valeurs des tags classiques dans /getTags : un Date sous forme de timestamp Unix en secondes, un Price sous forme de chaîne, par exemple "120.00", et un Boolean sous forme de 1 ou 0.
Valeurs stockées d’un champ
Anchor link toGET /api/tags:values sur l’URL de base liste les valeurs distinctes d’un champ, avec le nombre d’abonnés pour chaque valeur. Transmettez le nom complet du champ dans name, par exemple profile.address.city ou orders.sku.
Paramètres de requête
Anchor link to| Nom | Type | Description |
|---|---|---|
| application* | string | Code d’application, XXXXX-XXXXX. |
| name* | string | Nom complet du champ. |
| like | string | Renvoyer uniquement les valeurs qui contiennent ce texte, à la position définie par like_op. |
| like_op | string | STARTS_WITH (par défaut), ENDS_WITH ou CONTAINS. |
| order_by | string | VALUE (par défaut) ou COUNT. |
| order_direction | string | ASC (par défaut) ou DESC. |
| limit | integer | Nombre de valeurs à renvoyer. 100 par défaut. |
| offset | integer | Nombre de valeurs à ignorer. |
| page | integer | Numéro de page, à partir de 0. S’utilise avec per_page à la place de limit et offset. |
| per_page | integer | Nombre de valeurs par page. |
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}Les champs Integer et Price ne renvoient aucune valeur, comme les tags classiques de ces types. Un tag d’objet, un objet imbriqué ou une liste imbriquée n’a pas de valeurs propres, donc son nom renvoie HTTP 404 tag not found.
Segmenter selon les champs
Anchor link toDéfinissez les conditions de segment sur les champs, et non sur le tag d’objet lui-même. Dans le langage de segmentation, un champ est un tag dont le nom contient un point, et il accepte les opérateurs de son propre type :
AT("XXXXX-XXXXX", "order.amount", gte, 100)Un champ d’un objet imbriqué ou d’une liste imbriquée est désigné par son nom complet, comme profile.address.city, profile.visits.code ou orders.meta.color. Une condition sur le tag d’objet lui-même, un objet imbriqué ou une liste imbriquée, comme profile.address, échoue avec object tag has no value of its own, use one of its fields.
Un champ avec deux listes d’objets au-dessus de lui, comme orders.lines.qty, est uniquement stocké. Le segment avec une telle condition est enregistré, mais son calcul ou un envoi vers lui échoue avec a field inside a list nested in a list is stored only and cannot be searched.
Conditions sur un ObjectList
Anchor link toUne condition sur un champ d’un tag ObjectList correspond à un utilisateur lorsqu’au moins un élément de la liste remplit la condition. Les conditions sur des champs de la même liste reliées par AND doivent correspondre au même élément :
AT("XXXXX-XXXXX", "orders.amount", gte, 100) * AT("XXXXX-XXXXX", "orders.status", eq, "paid")Ce segment contient les utilisateurs ayant au moins une commande à la fois d’un montant de 100 ou plus et payée. Un utilisateur avec une grosse commande non payée et une petite commande payée ne correspond pas. Le même élément est vérifié pour les champs d’un objet à l’intérieur de cet élément : orders.sku égal à A-1 AND orders.meta.color égal à red correspondent à un utilisateur ayant une commande qui possède les deux. Les conditions reliées par OR n’ont pas à correspondre au même élément. Les conditions sur deux listes différentes sont vérifiées sur chaque liste séparément.
Certains opérateurs fonctionnent différemment sur un champ d’un tag ObjectList :
notset. Aucun élément de la liste n’a de valeur dans ce champ. Un utilisateur sans la liste correspond également.noteq. Au moins un élément a une valeur dans ce champ, et cette valeur diffère de celle indiquée. Les éléments sans ce champ ne comptent pas. Un utilisateur avec des commandes aux statutspaidetnewcorrespond ànoteq "paid".notinsur un champ List. Aucun élément ne contient l’une des valeurs indiquées.notinsur un champ d’un autre type. Au moins un élément a dans ce champ une valeur qui ne figure pas parmi les valeurs indiquées.
notset et notin sur un champ List ne sont pas liés au même élément que les autres conditions reliées par AND. Ces règles s’appliquent aussi aux listes imbriquées, comme profile.visits.
Utiliser les valeurs dans les messages
Anchor link toInsérez les champs des tags d’objet dans les notifications push, les e-mails, les SMS et les messages de messageries comme WhatsApp avec les modèles Liquid. Liquid ne fonctionne que si les modèles de contenu sont activés pour votre compte. Désignez un champ par son nom complet, à n’importe quelle profondeur :
Your city is {{ profile.address.city }}.Accédez à un élément d’une liste d’objets par son index, à partir de 0 :
Your first order is {{ orders[0].sku }}, quantity {{ orders[0].lines[0].qty }}.Un index au-delà de la fin de la liste, ou une liste que l’utilisateur n’a pas, s’affiche comme une chaîne vide. Vérifiez d’abord l’élément ou définissez une valeur par défaut avec default :
{% if orders[0] %}Your first order is {{ orders[0].sku }}.{% endif %}Your first order is {{ orders[0].sku | default: "on its way" }}.Parcourez une liste d’objets, y compris une liste à l’intérieur d’un élément :
{% for o in orders %}{{ o.meta.color }}{% for l in o.lines %}{{ l.qty }}{% endfor %}{% endfor %}Les champs uniquement stockés, comme orders.lines.qty, fonctionnent dans les modèles de la même manière que les autres champs.
Exporter des segments avec des tags d’objet
Anchor link to/exportSegment exporte les champs des tags d’objet :
- CSV. Chaque champ qui a une valeur est une colonne distincte nommée d’après son nom complet, comme
order.amountouprofile.address.city. Les tags d’objet, objets imbriqués et listes imbriquées eux-mêmes n’ont pas de colonne. Un champ à l’intérieur d’une liste d’objets, à n’importe quelle profondeur, contient les valeurs distinctes de tous les éléments sous forme de tableau JSON, de la même manière qu’un tag List :["A-1","B-2"]. Le tableau est trié et n’indique pas de quel élément provient une valeur, il ne conserve donc pas non plus l’ordre des éléments. Pour obtenir les éléments complets, exportez enjsonoujson_each_line. jsonetjson_each_line. Les tags d’objet sont renvoyés imbriqués, sous la même forme que celle renvoyée par/getTags. Un tagObjectest une seule entrée danstagsavec ses champs sousobject.fields, et un objet imbriqué à l’intérieur porte lui aussi ses propres champs sousobject.fields, à chaque niveau. Un tagObjectListest une seule entrée avec ses éléments dansobject_list.items, tout comme une liste imbriquée. Les champs ont des noms courts, sont triés par nom et portent leur valeur sous une clé nommée d’après le type :integer,string,list,date,boolean,priceouversion:
{ "name": "profile", "object": { "fields": [ { "name": "address", "object": { "fields": [{ "name": "city", "string": "Berlin" }] } }, { "name": "visits", "object_list": { "items": [{ "fields": [{ "name": "code", "string": "v1" }] }] } } ] }}Un tag ObjectList se présente ainsi. Les valeurs entières sont renvoyées sous forme de chaînes :
{ "name": "orders", "object_list": { "items": [ { "fields": [{ "name": "amount", "integer": "120" }, { "name": "status", "string": "paid" }] }, { "fields": [{ "name": "amount", "integer": "50" }] } ] }}Un élément avec un objet imbriqué et une liste imbriquée se présente ainsi :
{ "fields": [ { "name": "meta", "object": { "fields": [{ "name": "color", "string": "red" }] } }, { "name": "lines", "object_list": { "items": [{ "fields": [{ "name": "qty", "integer": "2" }] }] } } ]}Si tagsList nomme un tag d’objet, tous ses champs sont exportés, champs imbriqués compris.