Webservices liés aux goals

Les "Goals" ACTITO permettent d'identifier les personnes qui visitent votre site web et de récupérer des informations concernant leur comportement sur votre site : les visites de page ou les confirmations de commande.

Lorsqu'un profil atteint un goal, ACTITO enregistre une interaction entre le goal et ce profil. En plus de servir de statistiques, les goals peuvent être utilisés pour cibler des profils, les ajouter à un segment ou déclencher des communications.

La création d'un goal n'est pas possible par API. Elle doit obligatoirement se faire via l'interface ACTITO. De plus, une manipulation est nécessaire sur votre site web, sur les pages visées par le goal. Pour plus d'information à ce sujet, nous vous invitons à vous référer au chapitre consacré aux "Goals"

En revanche, les webservices liés aux goals vous permettront de :

  • Récupérer la liste des goals existants

  • Récupérer la définition d'un goal en particulier

  • Récupérer l'ActId pour un profil

  • Créer une interaction avec un goal transactionnel

images/download/attachments/615292320/image2019-5-8_15-10-55.png

Obtenir des informations sur les goals existants

Récupérer la liste des goals existants pour une entité

Vous avez la possibilité de récupérer la liste des goals existants dans une entité, avec leurs caractéristiques. Ceci vous permet de dresser un état des lieux de vos goals sans passer par l'interface ACTITO.

Il faut pour cela utiliser l'opération GET/entity/{e}/goals

L'unique paramètre obligatoire est le nom ou l'identifiant de l'entité à laquelle appartient le goal. Vous pouvez ensuite spécifier des paramètres de recherche pour filtrer les résultats :

  • Filtre sur le type : vous pouvez choisir de ne récupérer que les goals transactionnels ou les goals de visite de site web

  • Filtre sur le statut : vous pouvez choisir de ne récupérer que les actifs, inactifs ou encore en définition

images/download/attachments/615292320/image2019-4-29_9-58-27.png

Vous obtiendrez la liste des goals existants dans l'entité, avec le détail des éléments suivants :

  • L'identifiant technique du goal : il s'agit d'un numéro auto-généré

  • Le nom du goal : il s'agit du nom d'affichage que vous avez défini à la création du goal. Il est modifiable via l'interface ACTITO

  • L'identifiant de la table de profil ciblée par le goal

  • L'identifiant de l'entité à laquelle appartient le goal

  • Le type de goal : s'il s'agit d'un goal de transaction ou de visite de site web

  • Le statut du goal : selon que le goal actif, inactif ou encore en définition

  • Le momentde la création du goal et le moment de sa dernière mise à jour

Exemple de requête et de réponse : GET/entity/{e}/goals.docx

GET/entity/{e}/goals
Curl call
 
curl -X GET --header "Accept: application/json" "https://test.actito.be/ActitoWebServices/ws/v4/entity/actito/goals?status=ACTIVE"
 
Response body
{
"items": [
{
"id": "9",
"name": "DocGoalTransac",
"profileTableId": 45,
"entityId": 1,
"type": "TRANSACTION",
"status": "ACTIVE",
"createdAt": "06-03-2019 09:40:14",
"updatedAt": "06-03-2019 09:40:14"
},
{
"id": "8",
"name": "DocGoalVisit",
"profileTableId": 45,
"entityId": 1,
"type": "WEBSITE_VISIT",
"status": "ACTIVE",
"createdAt": "06-03-2019 09:39:41",
"updatedAt": "29-04-2019 09:42:50"
},
{
"id": "5",
"name": "Visit homepage webshop",
"profileTableId": 17,
"entityId": 1,
"type": "WEBSITE_VISIT",
"status": "ACTIVE",
"createdAt": "20-06-2018 13:30:19",
"updatedAt": "20-06-2018 13:30:19"
}
]
}

Récupérer la définition d'un goal

Vous avez la possibilité de récupérer les caractéristiques d'un goal en particulier via l'opération GET/entity/{e}/goals/{g}

Les paramètres à renseigner sont :

  • Le nom ou l'identifiant de l'entité à laquelle appartient le goal.

  • L'identifiant auto-généré ou le nom d'affichage du goal

images/download/attachments/615292320/image2019-4-29_10-30-43.png

La réponse obtenue comprendra les mêmes éléments et la même structure que pour l'opération précédente.

Enregistrer des goals via un système externe

Le moyen principal d'enregistrer des goals est dû à l'interaction entre le script inséré sur vos pages web et le cookie généré quand un profil clique sur un lien présent dans un e-mail ACTITO pour lequel le suivi des goals a été activé.

Ceci impliquerait que les goals ne puissent être atteints que par des profils ayant déjà reçu et cliqué dans un e-mail ACTITO. Grâce à la connectivité accrue permise par les webservices ACTITO, vous avez cependant la possibilité d'enregistrer des interactions de goals pour un profil qui auraient atteint ce goal par un système externe.

Vous avez pour cela deux possibilités :

  • Générer vous-même le cookie en récupérant l'ActId d'un profil

  • Créer une interaction de goal transactionnel via API

Récupérer l'ActId d'un profil

Le concept d'ActId désigne l'identifiant unique qui va permettre de faire le lien entre un profil donné et un goal. Il est stocké sur un cookie déposé sur le navigateur de l'utilisateur et c'est son interaction avec le script inséré sur vos pages web qui permettront le bon fonctionnement des goals.

Ce cookie est habituellement transmis par le biais d'un e-mail ACTITO. Cependant, dans un souci de connectivité entre ACTITO et les différentes plateformes partenaires ou les systèmes qui vous sont propres, rien ne vous empêche de créer vous-même ce cookie et de la déposer par un moyen le plus approprié selon votre activité (par exemple, lors de la connexion à un espace client). Cette alternative vous permettra notamment d'enregistrer des goals pour des profils qui n'ont encore jamais cliqué dans un e-mail ACTITO.

Pour créer ce cookie, il est nécessaire de pouvoir récupérer l'identifiant ActId pour chaque profil. Ceci est possible grâce à l'opération GET/entity/{e}/goal/table/{t}/profile{p}

images/download/attachments/615292320/image2019-4-26_17-19-24.png

Les paramètres devant être renseignés pour cette opération sont :

  • e = le nom de l'entité à laquelle appartient le goal

  • t = le nom de la table de profil

  • p = l'ID du profil (profileId) ou un attribut clé (par exemple, l'adresse e-mail). Dans le deuxième cas, il convient d'utiliser le format attributClé=valeur propre au profil (par exemple, emailAddress=mailtest@actito.com).

Exemple de requête et de réponse :

GET/entity/{e}/goal/table/{t}/profile/{p}
Curl call
curl -X GET --header "Accept: application/json" "https://test.actito.be/ActitoWebServices/ws/v4/entity/actito/goal/table/demodoc/profile/1147696"
 
 
Response body
{
"actId": "ebwp0YMB8s0j3CMkbjKAdZJ1bR7khe25PUBhQPbUPoCmZHJC_8wqozAtO_t2OrII"
}

La réponse à cette requête sera l'ActId du profil visé.

Créer une interaction de goal transactionnel

Il est possible de créer une interaction de goal transactionnel pour un profil donné via l'opération POST/entity/{e}/goals/{g}/profile/{p}/transaction

Ceci vous permet d'enregistrer un goal transactionnel quelle que soit la source ayant permis la génération de cette transaction.

images/download/attachments/615292320/image2019-5-7_11-54-34.png

Les paramètres à renseigner pour créer une interaction de goal transactionnel sont :

  • L'entité à laquelle appartient le goal

  • Le goal atteint : vous pouvez soit utiliser le nom du goal tel que vous l'avez défini en le créant ou en le modifiant, soit son id technique qui est un numéro auto-généré

  • Le profil ayant atteint le goal : il est nécessaire d'indiquer son "profileId"

  • "transactionGoalInteraction" : ceci correspond aux paramètres additionnels propres à un goal transactionnel, sous forme de code JSON. Comme pour le script à insérer sur votre site, ces paramètres sont :

    • amountCent : Le montant de la transaction en cents. Dans l'interface ACTITO, ce montant sera converti en €.

    • businessId : La clé d'identification de la transaction.

    • comment : Un commentaire accompagnant la transaction. Vous pouvez définir ce que vous voulez afficher dans ce champ.

    • source : La source de la transaction. Dans le cas d'une création par API, ce champ pourra être paramétré pour indiquer la provenance de la transaction.

Exemple de requête et de réponse : (Téléchargez cet exemple)

POST/entity/{e}/goals/{g}/profile/{p}/transaction
Curl call
 
curl -X POST --header "Content-Type: application/json" --header "Accept: application/json" -d "{
\"amountInCents\": 13502,
\"businessId\": \"Order 55\",
\"comment\": \"Product 1\",
\"source\": \"website\"
}" "https://development.actito.be/ActitoWebServices/ws/v4/entity/actito/goals/DemoDocTransac/profile/28704/transaction"
 
Response body
{
"id": 3629370
}

La réponse à cette requête sera l'identifiant de l'interaction.