Passer au contenu

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 to

Un 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 exemple order.amount. Vous segmentez selon les champs, et vous pouvez écrire un champ d’un tag Object par 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 OBJECT avec ses propres champs, par exemple profile.address avec le champ profile.address.city.
  • Liste imbriquée. Un champ de type OBJECT_LIST, un tableau d’objets à l’intérieur d’un tag d’objet, par exemple profile.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 to

Un 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 INTEGER

Champs consultables et champs uniquement stockés

Anchor link to

Ce 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.code ou orders.meta.color et 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.qty est uniquement stocké. Utilisez-le dans les messages, mais pas dans les segments.

Pushwoosh applique ces limites aux tags d’objet, objets et listes imbriqués compris :

LimiteValeurEn cas de dépassement
Profondeur d’imbrication3 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 objetDe 1 à 20, pour le tag et pour chaque objet imbriqué ou liste imbriquéeLa méthode de schéma renvoie HTTP 400, voir Erreurs
Champs avec des valeurs dans un tag d’objet50, champs imbriqués compris. Les champs de type OBJECT et OBJECT_LIST ne comptent pasLa méthode de schéma renvoie HTTP 400, voir Erreurs
Nom complet du champ64 caractères, comme profile.address.cityLa méthode de schéma renvoie HTTP 400, voir Erreurs
Éléments dans une liste d’objets100, pour le tag et pour chaque liste imbriquéeToute la valeur écrite est rejetée
Taille d’une valeur écrite64 Ko de JSONToute 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 to

Pushwoosh 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 : Amount et amount dé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 type OBJECT ou OBJECT_LIST a besoin de ses propres fields. 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.note existe, l’ajout du champ note à order échoue avec tag 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 to

Créez un tag d’objet sans objets ni listes imbriqués dans le Panneau de Contrôle :

  1. Sur la page Tags de votre Panneau de Contrôle, cliquez sur Créer un tag.
  2. Saisissez le Nom du tag.
  3. Dans Type de valeur, choisissez Objet ou Liste d’objets.
  4. Sous Champs, saisissez le nom du premier champ.
  5. Choisissez le type du champ.
  6. Pour ajouter un autre champ, cliquez sur Ajouter un champ.
  7. 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 to

Cré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 to
https://rpc-api.svc-nue.pushwoosh.com

Authentification

Anchor link to

Chaque 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_TOKEN

Points de terminaison

Anchor link to

Ces méthodes gèrent le schéma des tags d’objet et lisent les valeurs de leurs champs :

MéthodeCheminDescription
POST/api/tagsCréer un tag d’objet avec ses champs
GET/api/tags/{name}Obtenir un tag d’objet avec ses champs
GET/api/tagsLister 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}/fieldsAjouter 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:valuesLister 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 to

POST /api/tags

Corps de la requête
Anchor link to
NomTypeDescription
name*stringNom du tag d’objet.
type*stringOBJECT pour un objet ou OBJECT_LIST pour une liste d’objets.
fields*arrayChamps de l’objet, de 1 à 20.
fields[].name*stringNom du champ. Le champ devient le tag <name>.<fields[].name>.
fields[].type*stringType du champ : INTEGER, STRING, LIST, DATE, BOOLEAN, PRICE, VERSION, OBJECT ou OBJECT_LIST.
fields[].fieldsarrayChamps 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.
Exemple
{
"name": "orders",
"type": "OBJECT_LIST",
"fields": [
{ "name": "amount", "type": "INTEGER" },
{ "name": "status", "type": "STRING" }
]
}
Réponse
{
"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 :

Exemple : le tag profile de « Objets et listes imbriqués »
{
"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 to

POST /api/tags/{name}/fields

Exemple : POST /api/tags/orders/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 :

Exemple : POST /api/tags/profile/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 to

DELETE /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.

Les 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 HTTPMessageCause
400object tag and field names must contain only letters, digits and underscoresUn 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.
400an object has at most 20 fieldsL’objet auquel vous ajoutez un champ a déjà 20 champs.
400<object>.<field>: objects nest at most 3 levels deepUn champ OBJECT ou OBJECT_LIST serait au quatrième niveau.
400an object tag holds at most 50 fields with values, nested ones includedLe tag d’objet aurait plus de 50 champs avec des valeurs.
400field <name> is given twiceDeux 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 charactersLe nom complet du champ est trop long.
400<object>.<field>: field type must be INTEGER, STRING, LIST, DATE, BOOLEAN, PRICE, VERSION, OBJECT or OBJECT_LISTType de champ non pris en charge.
400an object needs at least one field; delete the object insteadVous avez tenté de supprimer le dernier champ d’un objet.
400field 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.
403object tags are not enabled for the accountLes tags d’objet ne sont pas activés pour le compte.
403a device API token cannot call this method, use an account API tokenLa requête utilise un jeton API Appareil.
404tag not foundGET 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.
404object tag not found, field not foundMé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.
409tag already existsUn tag portant le nom du tag d’objet existe.
409tag <object>.<field> already existsUn 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 :

Exemple : /json/1.3/setTags
{
"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 :

Exemple : valeurs imbriquées dans /json/1.3/setTags
"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 champExemple de valeur
INTEGER120
STRING"paid"
LIST["gift", "express"]
DATE"2026-10-02 22:11" (UTC), "2026-10-02" ou un timestamp Unix en secondes
BOOLEANtrue ou false
PRICE19.95
VERSION"1.0.0"

L’écriture remplace toute la valeur

Anchor link to

Chaque écriture remplace la valeur stockée du tag d’objet :

  • Un champ absent de la nouvelle valeur est supprimé. Un champ envoyé avec null est également supprimé.
  • null, [] ou "" supprime toute la valeur.
  • {} supprime tous les champs d’un tag Object.
  • 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 to

Un 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 to

Une 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 to

Avec 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ésultatCause
object tags are stored on the user onlyLe tag d’objet n’est pas User-specific.
cannot load the fields of the objectPushwoosh 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 mapsLa 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 listLa 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 :

Réponse
{
"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 to

GET /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
NomTypeDescription
application*stringCode d’application, XXXXX-XXXXX.
name*stringNom complet du champ.
likestringRenvoyer uniquement les valeurs qui contiennent ce texte, à la position définie par like_op.
like_opstringSTARTS_WITH (par défaut), ENDS_WITH ou CONTAINS.
order_bystringVALUE (par défaut) ou COUNT.
order_directionstringASC (par défaut) ou DESC.
limitintegerNombre de valeurs à renvoyer. 100 par défaut.
offsetintegerNombre de valeurs à ignorer.
pageintegerNuméro de page, à partir de 0. S’utilise avec per_page à la place de limit et offset.
per_pageintegerNombre de valeurs par page.
Exemple
GET /api/tags:values?application=XXXXX-XXXXX&name=orders.sku&order_by=COUNT&order_direction=DESC
Réponse
{
"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 to

Dé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 to

Une 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 statuts paid et new correspond à noteq "paid".
  • notin sur un champ List. Aucun élément ne contient l’une des valeurs indiquées.
  • notin sur 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 to

Insé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.amount ou profile.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 en json ou json_each_line.
  • json et json_each_line. Les tags d’objet sont renvoyés imbriqués, sous la même forme que celle renvoyée par /getTags. Un tag Object est une seule entrée dans tags avec ses champs sous object.fields, et un objet imbriqué à l’intérieur porte lui aussi ses propres champs sous object.fields, à chaque niveau. Un tag ObjectList est une seule entrée avec ses éléments dans object_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, price ou version :
{
"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.