Marquage de propriétés personnalisées

Ce guide n'est disponible que pour des analyses sur Piano Analytics

Veuillez vérifier le tableau de compatibilité

 

Avant-propos

Le Tracker dispose de méthodes techniques de marquage avancé utiles pour compléter la collecte de données. Ces méthodes utilitaires servent principalement à la manipulation de paramètres destinés à l’enrichissement des hits et permettent ainsi d’étendre les fonctionnalités de base des SDK.

Ces méthodes sont disponibles pour les SDK :

  • JavaScript à partir de la version 5.21.0
  • Android à partir de la version 2.17.0
  • Apple à partir de la version 2.18.0
 

Typage des propriétés

Afin de typer une propriété, vous pouvez utiliser un préfixe :

  • s: → chaîne de caractères
  • f: → flottant
  • n: → entier
  • b: → booléen
  • d: → date
  • a:X: → tableau de type X (e.g: a:s: signifie tableau de chaînes de caractères)

Les propriétés se terminant par _date, _utc, _timestamp et _ts sont automatiquement typées comme date si le format :

  • est de type Timestamp en secondes
  • respecte la norme RFC 3339 YYYY-MM-DDTHH:mm:ssZ

Si vous utilisez des méthodes events, si le préfixe n’est pas renseigné, le type JSON sera assigné à la propriété :

  • chaîne de caractères
  • flottant (tout nombre sera considéré comme flottant)
  • booléen
  • objet (objet JSON)
 

Méthodes de marquage

Le Tracker fournit une série de fonctions utiles pour la manipulation de propriétés.

Une propriété se compose d’une clé et d’une valeur :

  • La clé d’une propriété est utilisée comme paramètre de hit. Elle doit correspondre exactement à une entrée de votre Data Model.
  • La valeur d’une propriété est transmise encodée dans le hit.

Notion de persistance

Une propriété peut être déclarée comme « persistante ». Dans ce cas, elle est ajoutée automatiquement à tous les hits générés par le Tracker, peu importe le type. Dans le cas contraire, cette dernière est seulement associée au prochain hit ; elle est ensuite supprimée après envoi.

download
 

setProp

setProp(key, value, persistent)

Déclarer une propriété à ajouter au hit.

ParamTypeDescription
keystringNom de la propriété à ajouter – Comment typer une propriété ?
valuestring|numberValeur de la propriété
persistentbooleanPersistance de la propriété (true : tous les hits, false : le prochain hit seulement)

La déclaration d’une propriété entraîne la création d’une entrée ayant pour clé principale le nom de la propriété et pour valeur un objet composé des clés value (la valeur de la propriété) et persistent (l’option de persistance).

Exemple d’une propriété « key1 » ajoutée à la liste des propriétés :

var properties = {
    "key1": {
        "value": "val1",
        "persistent": true
    }
};

Exemples de marquage

tag.setProp('custom1', 'val1', true); // Persistent
tag.setProp('custom2', 'val2', false); // Non-persistent
tag.page.send({'name': 'page_name'}); // Will get both 'custom1' and 'custom2' properties
tag.page.set({'name': 'page_name_set'});
tag.dispatch(); // Will only get 'custom1' property
setProp(key, value, persistent) ⇒ Tracker

Déclarer une propriété à ajouter au hit.

ParamTypeDescription
keyStringNom de la propriété à ajouter – Comment typer une propriété ?
valueStringValeur de la propriété
persistentBoolPersistance de la propriété (true : tous les hits, false : le prochain hit seulement)

Exemples de marquage

tracker.setProp("custom1", value: "val1", persistent: true) // Persistent
tracker.setProp("custom1", value: "val1", persistent: false) // Non-persistent
setProp(key, value, persistent) ⇒ Tracker

Déclarer une propriété à ajouter au hit.

ParamTypeDescription
keyStringNom de la propriété à ajouter – Comment typer une propriété ?
valueStringValeur de la propriété
persistentbooleanPersistance de la propriété (true : tous les hits, false : le prochain hit seulement)

Exemples de marquage

tracker.setProp("custom1", "val1", true); // Persistent
tracker.setProp("custom2", "val2", false); // Non-persistent
 

setProps

setProps(props, persistent)

Déclarer un ensemble de propriétés à ajouter au hit.

ParamTypeDescription
propsObjectObjet contenant les propriétés à ajouter – Comment typer une propriété ?
persistentbooleanPersistance des propriétés (true : tous les hits, false : le prochain hit seulement)

Dans le cas d’un objet complexe à plusieurs niveaux, les clés doivent être regroupées sur un seul niveau avec un séparateur de type « _ » (underscore). Pour rappel, les clés doivent correspondre à votre Data Model.

Exemple :

// Multi-level object
var props = {
    "key1": {
        "key2": "val2"
    },
    "key3": "val3"
};

// Expected object
var props = {
    "key1_key2": "val2",
    "key3": "val3"
}; 

Exemples de marquage

tag.setProps({
    "key1_key2": "val2",
    "key3": "val3"
}, true); // Persistent
tag.setProps({
    "key4": "val4"
}, false); // Non-persistent
tag.page.send({'name': 'page_name'}); // Will get 'key1_key2', 'key3' and 'key4' properties
tag.page.set({'name': 'page_name_set'});
tag.dispatch(); // Will only get 'key1_key2' and 'key3' properties
setProps(props, persistent) ⇒ Tracker

Déclarer un ensemble de propriétés à ajouter au hit.

ParamTypeDescription
props[String: String]Objet contenant les propriétés à ajouter – Comment typer une propriété ?
persistentBoolPersistance des propriétés (true : tous les hits, false : le prochain hit seulement)

Dans le cas d’un objet complexe à plusieurs niveaux, les clés doivent être regroupées sur un seul niveau avec un séparateur de type « _ » (underscore). Pour rappel, les clés doivent correspondre à votre Data Model.

Exemples de marquage

tracker.setProps([
    "key1_key2": "val2",
    "key3": "val3"
], persistent: true) // Persistent
tracker.setProps([
    "key1_key2": "val2",
    "key3": "val3"
], persistent: false) // Non-persistent
setProps(props, persistent) ⇒ Tracker

Déclarer un ensemble de propriétés à ajouter au hit.

ParamTypeDescription
propsMap<String, String>Objet contenant les propriétés à ajouter – Comment typer une propriété ?
persistentbooleanPersistance des propriétés (true : tous les hits, false : le prochain hit seulement)

Dans le cas d’un objet complexe à plusieurs niveaux, les clés doivent être regroupées sur un seul niveau avec un séparateur de type « _ » (underscore). Pour rappel, les clés doivent correspondre à votre Data Model.

Exemples de marquage

tracker.setProps(new HashMap<String, String>() {{
    put("key1_key2", "val2");
    put("key3", "val3");
}}, true); // Persistent
tracker.setProps(new HashMap<String, String>() {{
    put("key1_key2", "val2");
    put("key3", "val3");
}}, false); // Non-persistent
 

getProp

getProp(key) ⇒ Object

Récupérer le contenu d’une propriété.

ParamTypeDescription
keystringNom de la propriété

Exemple de marquage

var property = tag.getProp('key1');
// property = {"value": "val1", "persistent": true};
getProp(key) ⇒ Param

Récupérer le contenu d’une propriété.

ParamTypeDescription
keyStringNom de la propriété

Exemple de marquage

let property = tracker.getProp("key1")
getProp(key) ⇒ Param

Récupérer le contenu d’une propriété.

ParamTypeDescription
keyStringNom de la propriété

Exemple de marquage

Param property = tracker.getProp("key1");
 

getProps

getProps() ⇒ Object

Récupérer l’ensemble des propriétés.

Exemple de marquage

var properties = tag.getProps();
// properties = {"key1": {"value": "val1", "persistent": true}};
getProps() ⇒ [Param]

Récupérer l’ensemble des propriétés.

Exemple de marquage

let properties = tracker.getProps()
getProps() ⇒ List<Param>

Récupérer l’ensemble des propriétés.

Exemple de marquage

List<Param> properties = tracker.getProps();
 

delProp

delProp(key)

Supprimer une propriété.

ParamTypeDescription
keystringNom de la propriété

Exemple de marquage

tag.delProp('custom2');
delProp(key)

Supprimer une propriété.

ParamTypeDescription
keyStringNom de la propriété

Exemple de marquage

tracker.delProp("custom2")
delProp(key)

Supprimer une propriété.

ParamTypeDescription
keyStringNom de la propriété

Exemple de marquage

tracker.delProp("custom2");
 

delProps

delProps()

Supprimer l’ensemble des propriétés.

Exemple de marquage

tag.delProps();
delProps()

Supprimer l’ensemble des propriétés.

Exemple de marquage

tracker.delProps()
delProps()

Supprimer l’ensemble des propriétés.

Exemple de marquage

tracker.delProps();