Documentation API

Documentation API

Comment utiliser notre API?

Notre API est constituée de plusieurs composants:

 

I – API de recommandation

L’API de recommandation est extrêmement simple et vous permet d’effectuer des requêtes sur nos serveurs de recommandation, à l’aide de vos identifiants et informations à propos de l’utilisateur et du produit en cours de visualisation.

Voici un exemple très simple d’appel:

http://reco.ezako.com/reco/?idsite=MY_IDSITE&t=MY_PRIVATE_TOKEN_KEY

Cet appel contient 2 paramètres:

  • idsite: Votre idsite personnel. Par exemple: ezako.com
  • t: Votre clé privée (privatekey).

Ces paramètres sont obligatoires et le minimum nécessaire pour effectuer un appel. Ils sont disponible dans votre page de profil: 

Paramètres additionnels (et optionnels):

  • id: L’identifiant client. Ce paramètre est obligatoire pour effectuer des recommandations personnalisées. Si vous utilisez notre solution de tracking, ce paramètre sera dans le cookie et appelé _pk_id*
  • pid: Le produit en cours de visualisation (si applicable, par ex. sur une page produit).
  • type: Le type de recommandation (par défaut ALL), les valeurs possibles sont: HOME, PRODUCT, ALL, OFFER, TOP, RANDOM
  • nb: Le nombre de résultats attendus. Ce paramètre est une indication et le nombre de résultats peut être supérieur ou inférieur à l’attendu.

Et voici un exemple plus évolué:

http://reco.ezako.com/reco/?idsite=MY_IDSITE&t=MY_PRIVATE_TOKEN_KEY&pid=657&nb=15&id=abr43254c543

 

Le résultat attendu est un document JSON très simple, contenant une liste d’identifiants produits:

{ "ids": [6,2,1,5,8,7,4,9,3], "count":9 }



II – API de collecte

Dans la même logique que Google Analytics ou Yahoo! Analytics, notre système de collecte permet de transférer les informations de navigation directement depuis le browser du client vers nos serveurs de collecte. Cela se fait de façon asynchrone, pour garantir qu’il n’y a pas d’impact sur le temps de chargement de la page.

A) Introduction

L ‘ API de collecte doit être intégrée sur l’ensemble des pages du site marchand. Cette intégration est extrêmement simple.

Exemple d’utilisation de l’API sur une page produit :

<script type="text/javascript"> var _ezaq = _ezaq ||[]; _ezaq.push(['setSiteId', 'MY_IDSITE']); _ezaq.push(['setTrackerUrl', 'http://reco.ezako.com/pixel/pixel.png']); _ezaq.push(['setProductView', 42, 'Robe rouge', ['Femmes', 'Robe'], 'Rouge', '40', 'Brand1', 19.99, null]); _ezaq.push(['trackPageView']); (function(){ var u=('https:' == document.location.protocol ? 'https://yourserverurl:449' : 'http://yourserverurl') + /chemin/vers/votre/copie/de/ez-analytics-min.js'; var d=document, g=d.createElement('script'), s=d.getElementsByTagName('script')[0]; g.type='text/javascript'; g.defer=true; g.async=true; g.src=u; s.parentNode.insertBefore(g,s); })(); </script>

B) Mise en place

Téléchargez le tracker javascript et rendez le accessible sur vos serveurs: download page

Créez une variable le plus tôt possible dans le script (utile pour agréger les différentes informations), et configurez le siteId et l’url de collecte : var _ezaq = _ezaq || []; _ezaq.push(['setSiteId', 'MY_IDSITE']); _ezaq.push(['setTrackerUrl', 'http://reco.ezako.com/pixel/pixel.png']);

Mettez en place le tracking : // Function loading asynchronously tracking, as google analytics // Specify site url and path to the javascript in variable u (function(){ var u=('https:' == document.location.protocol ? 'https://yourserver.url:449' : 'http://yourserver.url') + /chemin/vers/votre/copie/de/ez-analytics-min.js'; var d=document, g=d.createElement('script'), s=d.getElementsByTagName('script')[0]; g.type='text/javascript'; g.defer=true; g.async=true; g.src=u; s.parentNode.insertBefore(g,s); })();

C) Configurez le suivi vos pages vues

Pour suivre les différentes pages vues, vous ajoutez des appels à des méthodes en javascript, en fonction du contenu de la page (page d’accueil, page produit, page de panier, …). Par exemple pour une page vue d’un produit :

_ezaq.push(['setProductView', 42, 'Robe rouge', ['Femmes', 'Robe'], 'Rouge', '40', 'Brand1', 19.99, null]); _ezaq.push(['trackPageView']);

Il est important de faire appel à trackPageView pour que la vue soit comptabilisée. Ceci donne la possibilité de configurer d’autres variables avant l’appel, comme nous le verrons dans la section avancée. La liste complète des méthodes est résumée dans le tableau suivant.

Méthode Description
setHomeView() Page d’accueil
setCategoryView(cat) nom de catégories, séparées par un | de la plus générale à la plus spécifique
setProductView(pid, pname, cat, color, size, brand, price, special_price) Page vue produit.

  • pid: identifiant unique du produit – Obligatoire
  • pname: nom du produit dans sa langue
  • cat: nom de catégorie, ou tableau de nom de catégories et de sous-catégories
  • color: couleur du produit
  • size: taille (par exemple ‘S’ ou ’42’)
  • brand: nom de la marque
  • price: prix du produit
  • special_price: prix en offre spéciale
setAddToBasket(pid, pname, cat, color, size, brand, price, special_price) Ajout au panier.

  • pid: identifiant unique du produit – Obligatoire
  • pname: nom du produit dans sa langue
  • cat: nom de catégorie, ou tableau de nom de catégories et de sous-catégories
  • color: couleur du produit
  • size: taille (par exemple ‘S’ ou ’42’)
  • brand: nom de la marque
  • price: prix du produit
  • special_price: prix en offre spéciale
setViewBasket(pids, total) Visualisation du panier.

  • pids: identifiant unique de produit ou tableau d’id de produits – Obligatoire
  • total: prix total du panier
setOrder(pids, total, quantity) Commande.

  • pids: identifiant unique de produit ou tableau d’id de produits – Obligatoire
  • total: prix total de la commande
  • quantity: nombre de produits achetés, sous forme de tableau si plusieurs produits
setOrderConf(pids, total, quantity, subtotal, tax, shipping, discount) Confirmation de commande.

  • pids: identifiant unique de produit ou tableau d’id de produits – Obligatoire
  • total: prix total de la commande
  • quantity: nombre de produits achetés, sous forme de tableau si plusieurs produits
  • subtotal: prix total de la commande avant charges supplémentaires
  • tax: taxes associées à la vente
  • shipping: coûts de livraison
  • discount: réduction sur la commande
setAddToBasket(pid, pname, cat, color, size, brand, price, special_price) Ajout au panier.

 

D) Configurez le suivi des recommandations. Nous vous encourageons à utiliser un maximum de champs. Néanmoins, il est important de noter que les champs qui ne sont pas obligatoires peuvent être remplacés par la valeur null .

Il est important pour que le système d’apprentissage automatique fonctionne, qu’il soit informé de clics sur les produits recommandés. Pour ce faire, il suffit d’insérer un appel javascript dans le clic.

<a href="#" onclick='javascript:_ezaq.push(["trackRecoClick", 42 ]);'>Product name or image </a>

Méthode Description
trackRecoClick(pid) Suivi de recommandation cliquée.

  • pid: identifiant unique du produit – Obligatoire

E) Configurez le suivi du moteur de recherche

Pour être informé des mots-clés utilisés par vos clients, il est utile de suivre leur usage.

_ezaq.push(['trackSiteSearch', "sport baskets", false, 8]);

Méthode Description
trackSiteSearch(keywords, category, searchCount) Suivi de résultats de recherche.

  • keywords: requête – Obligatoire
  • category: catégorie sélectionnée ou ‘false’ – Obligatoire
  • searchCount: nombre de résultats ou 0 – Obligatoire

G) Fonctionnalités avancées

Si les méthodes décrites jusqu’à présent ne vous conviennent pas, il est possible d’insérer directement des variables custom pour compléter les informations déjà fournies.

_ezaq.push(['setCustomVariable', 100, "testvarname1", "000" ]);

Méthode Description
setCustomVariable(index, name, value) Ajouter une variable custom

  • index: numéro de l’index de la variable, liée au nom – Obligatoire
  • name: nom de la variable – Obligatoire
  • value: valeur – Obligatoire

Les variables disponibles et les index associés sont listés dans le tableau ci-dessous.

Index Nom de la variable Description Obligatoire
1 type type de page: home, category, product, addbasket, viewbasket, order, order_conf, other Obligatoire
2 pid identifiant unique de produit Obligatoire
3 pname nom du produit dans sa langue Obligatoire
4 pid2 autre identifiant de produit Optionnel
5 cat nom de catégories, séparées par un | de la plus générale à la plus spécifique Obligatoire
6 color couleur du produit (si applicable) Optionnel
7 size taille du produit (si applicable) Optionnel
8 brand marque du produit Optionnel
9 price prix du produit Optionnel
10 sprice prix du produit en offre spéciale Optionnel
12 total prix total (page panier ou commande) Optionnel
13 quantity quantité du produit commandé, séparées par un | si plusieurs produits Optionnel
15 sessionid identifiant unique de cet utilisateur, par exemple un id de cookie serveur Optionnel
16 userid identifiant du client s’il est authentifié Optionnel
20 rclicked identifiant du produit sur un lien de recommandation (pour aider à déterminer la conversion) Optionnel
22 subtotal prix total de la commande avant charges supplémentaires Optionnel
23 tax taxes associées à la vente Optionnel
24 shipping coûts de livraison Optionnel
25 discount réduction sur la commande Optionnel

N.B : Plus vous renseignez de variables, meilleur seront les résultats de nos algorithmes.

H) Exemple avancé

<html> 
<head> 
... 
<script type="text/javascript"> 
// Init the tracking variable to be able to track in the file 
var _ezaq = _ezaq || []; 
_ezaq.push(['setSiteId', 'MY_IDSITE']); 
_ezaq.push(['setTrackerUrl', 'http://reco.ezako.com/pixel/pixel.png']); 
</script> 
... 
</head> 
<body> 
... 
<script type="text/javascript"> 
// Set some variables in the body (these are only sample - not needed) 
_ezaq.push(['setCustomVariable', 100, "testvarname1", "000" ]); 
_ezaq.push(['setCustomVariable', 101, "testvarname2", "rose" ]); 
_ezaq.push(['setCustomVariable', 102, "testvarname3", "18" ]); 
</script> 
... 
// Track click on a recommendation 
<a href="#" onclick='javascript:_ezaq.push(['trackRecoClick', 5000]);'>Product 5000</a> 
... 
<script type="text/javascript"> 
// If the user is logged in, we might match session id with username (optional) 
_ezaq.push(['setCustomVariable', 16, "userid", "julien123" ]); 
// Add a secondary product name 
_ezaq.push(['setCustomVariable', 4, "pid2", "1223" ]); 
// Now push the standard product view variables. 
// on product page: 12000 
// on categories: 122|345|324|765 
_ezaq.push(['setProductView', 1200, 'baskets sport', [122, 345, 324, 765], 'red', '40', 'Brand1', 108.99, 99.99]); 
// Send out the tracking request. 
// Track page views (required) 
_ezaq.push(['trackPageView']); 
// Function loading asynchronously tracking, as google analytics 
// Specify site url and path to the javascript in variable u 
(function(){ 
var u=('https:' == document.location.protocol ? 'https://yourserver.url:449' : 'http://yourserver.url') + 
'/chemin/vers/votre/copie/de/ez-analytics-min.js'; 
var d=document, g=d.createElement('script'), s=d.getElementsByTagName('script')[0]; 
g.type='text/javascript'; g.defer=true; g.async=true; g.src=u; 
s.parentNode.insertBefore(g,s); })(); 
</script> 
... 
</body> 
</html> 

III – Upload du fichier d’inventaire

Notre solution utilise votre inventaire produit pour garantir des recommandations de produits disponibles en stock et fournir les meilleures recommandations. C’est dans ce but que sont utilisées les descriptions produits et autres informations collectées.

Vous pouvez nous envoyer votre inventaire aussi souvent que vous le souhaitez, en fonction de vos variations de stock. Habituellement cette mise à jour se fait entre 1h et 24h.

Nous utilisons le standard feeds google merchant comme format de collecte

L’inventaire doit être envoyé avec la méthode POST à l’url suivante http://reco.ezako.com/pixel/products.txt Les headers suivants devront être configurés avec vos informations: idsite: MY_IDSITE token: MY_PRIVATE_KEY Content-Type: text/plain; charset=UTF-8  Le contenu est dans le corps du POST. Le format est du texte, délimité par des tabulations, avec une ligne pour les noms de colonnes, suivi d’une ligne par produit.

id	title	price	sale_price	condition	link	availability	product_type	image_link	brand	description
1	Matrox G200 MMS	299.9900 USD	new		http://yourserver.url/product_info.php?prod_id=1	in stock	Hardware > Graphics Cards	http://yourserver.url/images/matrox/mg200mms.gif	Matrox  Reinforcing its position as a multi-monitor trailblazer, Matrox Graphics Inc. has once again developed the most flexible and highly advanced solution
2	Matrox G400 32MB	499.9900 USD	new		http://yourserver.url/product_info.php?prod_id=2	in stock	Hardware > Graphics Cards	http://yourserver.url/images/matrox/mg400-32mb.gif	Matrox	Dramatically Different High Performance Graphics Introducing the Millennium G400 Series - a dramatically different, high performance graphics

Les informations à fournir sont listés dans le tableau ci-dessous.

Nom de la colonne Description
id identifiant unique de produit
title nom du produit dans sa langue
price prix du produit, au format: ii.ii USD ou ii.ii EUR. Par exemple: 226.99 EUR
sale_price prix du produit en offre spéciale
condition état du produit: ‘new’, ‘refurbished’ or ‘used’
link lien vers la page produit
availability disponibilité: ‘in stock’, ‘available for order’ ou ‘out of stock’
product_type catégorie du produit, en cas de hiérarchie de catégories, utiliser le séparateur ‘ > ‘
product_type_id identifiant de catégorie du produit, en cas de hiérarchie de catégories, utiliser le séparateur ‘ > ‘
image_link lien vers une image produit
brand marque du produit
description description du produit. Limiter à environ 1024 caractères