Guide d intégration. technique Lucky Cart

Transcription

1 Guide d intégration technique Lucky Cart v2.7 Guide d intégration technique Lucky Cart v2.7-1/32

2 1. Introduction 1.1. A propos de ce guide Ce document a pour but de donner les informations techniques nécessaires pour intégrer la solution Lucky Cart sur un site marchand. Il est principalement destiné aux équipes techniques et vient en complément du document d Aperçu d intégration technique Lucky Cart, plus général. Il s accompagne en outre du Kit d intégration Lucky Cart mis à disposition par nos équipes sur demande. De plus, un support technique Lucky Cart est disponible en écrivant à l'adresse suivante : support@luckycart.com 1.2. Table des matières 1. Introduction 1.1. A propos de ce guide 1.2. Table des matières 1.4. Principe de fonctionnement 2. Processus d intégration 2.1. Note importante à propos de l'intégration Lucky Cart 2.2. Préparation Choix de la méthode d intégration Préparation des données 2.3. Intégration en pré-production 2.4. Intégration en production 2.5. Finalisation Redirection automatique de la page de paiement Mise en avant de la promotion 3. Intégration du plugin Lucky Cart 3.1. Intégrations "clé en main" (framework ecommerce) Magento Description du module Remontée des paniers et affichage du jeu Annulation des paniers Prestashop Description du module Remontée des paniers et affichage du jeu Annulation des paniers 3.2. Intégrations "natives" (modules Lucky Cart) Guide d intégration technique Lucky Cart v2.7-2/32

3 PHP Description du module Remontée des paniers et affichage du jeu Annulation des paniers Récupération d'informations sur un jeu Java Description du module Remontée des paniers et affichage du jeu ASP.NET Description du module Remontée des paniers et affichage du jeu Annulation des paniers 3.3. Intégrations "légères" (tag Javascript) Avertissement important Javascript natif Description du module Remontée des paniers et affichage d'un jeu Google Tag Manager Remontée des paniers et affichage d'un jeu Annulation des paniers Eulerian Remontée des paniers et affichage d'un jeu Annulation des paniers Tag Commander Remontée des paniers et affichage d'un jeu Annulation des paniers 4. Intégration d'éléments de mise en avant 4.1. Page "En savoir plus" 4.2. Tableau simple de gagnants (HTML) Description du module Installation Configuration Customisation 4.3. Informations avancées sur les gagnants (Json) 1.4. Principe de fonctionnement Le diagramme ci-dessous résume les communications établies entre le navigateur de l acheteur, le site du marchand et les serveurs Lucky Cart. Il s applique dans le cas simple d un jeu directement proposé sur la page de confirmation d achat du marchand. Guide d intégration technique Lucky Cart v2.7-3/32

4 1. L acheteur confirme le paiement de sa commande. A la génération de la page de confirmation, le site marchand envoie une requête authentifiée aux serveurs Lucky Cart pour demander les bootstraps Lucky Cart. Cette demande reçoit en paramètres des données de transaction (identification de l acheteur, identification de la transaction, montant du panier, etc...) et des données d identification (key, secret). 2. Les serveurs Lucky Cart répondent à cette requête en effectuant les tâches suivantes : - Vérification des informations d'authentification pour valider que la demande provient bien d un marchand Lucky Cart connu. - Analyse et filtrage des données passées en paramètre pour localiser la campagne active spécifique à la transaction. - Création d un jeu et d un identifiant unique associé. - Construction et envoi des bootstraps Lucky Cart contenant les appels à effectuer pour afficher le plugin Lucky Cart associé au jeu. 3. Pendant l affichage de la page de confirmation de commande, le navigateur de l acheteur exécute les appels contenus dans les bootstraps pour récupérer le plugin Lucky Cart. Ces appels se font directement sur les serveurs Lucky Cart sans passer par le site marchand. 4. Les serveurs Lucky Cart renvoient le script correspondant au plugin Lucky Cart à exécuter par le navigateur sur la page de confirmation de paiement. Guide d intégration technique Lucky Cart v2.7-4/32

5 2. Processus d intégration 2.1. Note importante à propos de l'intégration Lucky Cart La technologie Lucky Cart permettant de remonter les informations d'achat depuis le site marchand vers nos serveurs est conçue pour être intégrée une fois pour toute et pour supporter tous les types d'opération de Promogaming prévues ou à venir. Au cours de l'intégration initiale et pour éviter d'engendrer des délais et coûts supplémentaires lors d'opérations ultérieures, il convient que le marchand respecte les deux règles suivantes : - Pas de filtrage coté marchand : l'intégralité des paniers éligibles ou non à l'opération est envoyée à Lucky Cart qui se chargera de son coté de distribuer et d'afficher un ou plusieurs jeux à l'acheteur sur la page de confirmation de commande. - Ne pas couper le flux des paniers après la fin d'une campagne : après la date de fin d'opération prévue, la distribution et l'affichage des jeux sera automatiquement désactivée par notre système sans qu'aucune action spécifique ne soit nécessaire coté marchand. Dans le cas où ces règles ne seraient pas respectées et qu'une intervention technique devait être nécessaire pour refaire ou ajuster une intégration préalablement effectuée, les contrats signés entre les parties stipulent que Lucky Cart facturera cette intervention HT. De plus, Lucky Cart doit avoir accès à un environnement de pré-production pour faire des achats de test. Il convient donc que le marchand anticipe les démarches en interne ou auprès de ses prestataires pour fournir : - un accès à l'environnement de pré-production aussi fidèle que possible à celui de la production (éventuellement sécurisé si besoin, par exemple via l'utilisation d'un portail ou la mise en place d'un filtrage IP). - des comptes ou numéro de cartes de test pour les paiements CB ou paypal Préparation En amont de toute intégration, Lucky Cart recommande de valider en interne et avec nos équipes les points techniques suivants au moins 10 jours avant le début de la campagne de Promogaming : Guide d intégration technique Lucky Cart v2.7-5/32

6 Choix de la méthode d intégration Trois types d intégration sont possibles: Les intégrations "clé en main" via les modules Magento et Prestashop édités par notre partenaire WebInColor. Les intégrations "natives" qui s appuient sur l utilisation de modules propriétaires Lucky Cart (Php, Java, ASP.NET). C'est la méthode recommandée par Lucky Cart si la première ne convient pas. Les intégrations "légères" basées sur l'utilisation d'une librairie Javascript en direct ou via un gestionnaire de tag (Google Tag Manager, Eulerian, Tag Commander). A noter que cette méthode d'intégration, bien qu'elle paraisse plus rapide et facile, comporte un certain nombre de limitations expliquées dans la section correspondante à prendre en considération. Préparation des données Quelque soit la méthode d intégration utilisée, un certain nombre de données doivent être fournies par le site marchand lors des appels aux serveurs Lucky Cart. Il convient donc de s assurer que ces données seront disponibles depuis la page concernée. 1. Données obligatoires : cartid : identifiant unique de la transaction (de l achat) utilisé par le marchand sur le site et dans les s. customerid : identifiant unique de l acheteur utilisé par le marchand sur le site et dans les s. ttc : montant total TTC du panier tel qu'il apparait sur la page de confirmation de commande. Ce montant prend en compte les éventuelles variations appliquées sur le panier de base (frais de port et assurances à ajouter, code de réduction à soustraire, etc...) mais reste invariant selon la méthode de paiement. Par exemple la partie d'un panier payée en bon(s) d'achat, et donc soustraite du montant à payer par CB, doit figurer dans le montant total TTC envoyé. ht : montant total HT du panier. C'est l'équivalent HT du montant total TTC ci-dessus. country :pays de facturation nécessaire pour filtrer les achats hors France, qui ne sont pas légalement éligibles à un jeu. de l acheteur utilisé pour les s transactionnels suite à l'achat. payment : mode de paiement utilisé lors de la commande afin d'exclure systématiquement ceux qui pourraient permettre au consommateur d'accéder à un jeu sans engagement financier préalable (par ex Chèque, Virement) et d'être tenté de refaire des achats jusqu'à l'obtention d'un ticket gagnant. Guide d intégration technique Lucky Cart v2.7-6/32

7 2. Données fortement recommandées firstname, lastname : nom et prénom de l acheteur utilisés pour personnaliser les s transactionnels et le tableau des gagnants. codepromo : code de réduction utilisé dans le cas où la promotion est conditionnée à la présence d un code spécifique. currency : devise des montants envoyés (EUR par défaut) dans le cas ou le site supporte des achats dans une devise autre que l'euro (norme ISO 4217 ). lang: langue à utiliser (FR par défaut) pour l'affichage du jeu, des pages et des s transactionnels (norme ISO ). shopid : identifiant unique du point de vente depuis lequel l'achat a été réalisé dans le cas ou il en existe potentiellement plusieurs. products : lignes de détails de la commande : sous forme de tableau, chaque ligne comportant des indications de produits (référence, catégorie, quantité, montant TTC, montant HT, etc ). Peut être utilisé pour filtrer les gains mis en jeu en fonction des produits achetés. 3. Données spécifiques cartdate : date d achat. Si elle n est pas précisée, la date par défaut sera celle de réception des données. autres informations sur l acheteur, la transaction ou les produits qui pourraient être utiles pour définir l éligibilité du panier au jeu (catégorie, etc ) Les données de transaction requises sont pour l essentiel spécifiques à chaque marchand et il n y a pas de convention de nommage rigoureuse. Un mapping est établi de toute façon coté serveurs Lucky Cart. Il est cependant recommandé d utiliser les valeurs fournies dans les différents exemples Intégration en pré-production Lucky Cart recommande d effectuer cette étape au moins 4 jours avant le début de la campagne de Promogamin. Elle consiste à réaliser et à valider, conjointement avec notre équipe de support, l intégration technique de la solution dans un environnement de pré-production ou de staging, en utilisant lors de l'initialisation de la librairie exclusivement la clé et le secret de test fournis par Lucky Cart. Guide d intégration technique Lucky Cart v2.7-7/32

8 2.4. Intégration en production Cela consiste à reproduire l'intégration en pré-production sur l'environnement de production en utilisant, lors de l'initialisation de la librairie, exclusivement la clé et le secret de production fournis par Lucky Cart. Lucky Cart recommande d effectuer cette étape dès que l'intégration en pré-production a été validée et au moins 2 jours avant le début de la campagne de Promogaming sans nécessairement attendre le début de l'opération. En effet, il est important de comprendre que l'attribution et l'affichage d'un jeu suite à un achat sont contrôlés du coté Lucky Cart indépendamment de la mise en place de la remontée des paniers. En aucun cas l'acheteur ne se verra proposer l'opération avant sa date de lancement Finalisation En complément de l intégration et pour optimiser l efficacité des campagnes, plusieurs actions sur le site marchand sont fortement recommandées. Redirection automatique de la page de paiement Pour les marchands offrant la possibilité de régler la commande via un prestataire de paiement tiers (CB Paybox, Paypal, Cetelem 3x sans frais, etc...), Lucky Cart les encourage vivement à mettre en place toutes les redirections automatiques nécessaires à l'issue de cette étape de paiement pour retourner vers la page de confirmation de commande du site marchand. Ceci permet de sécuriser au maximum l envoi des achats à Lucky Cart et l affichage des jeux sur la page de confirmation de commande. Mise en avant de la promotion En complément de l intégration "minimale" à effectuer, l équipe Lucky Cart recommande également aux marchands de mener des actions pour mettre en avant la promotion sur leur site, par exemple : Affichage d'informations sur les gagnants (Par ex leader board avec Prénom + Gain) Intégration de la page "En savoir plus" en iframe (page fournie par Lucky Cart) Bannière/habillage de mise en avant de l offre Envoi d s promotionnels Guide d intégration technique Lucky Cart v2.7-8/32

9 3. Intégration du plugin Lucky Cart Pour les marchands qui utilisent Magento ou Prestashop, Lucky Cart recommande de se tourner vers notre partenaire WebInColor qui propose des modules spécifiques ainsi que tout le support nécessaire pour faire une intégration rapide et simplifiée. Nous vous invitons donc à consulter directement les liens et documents Web In Color indiqués ci-dessous Intégrations "clé en main" (framework ecommerce) Magento Description du module Page d'information générale : Exemple d'utilisation : Remontée des paniers et affichage du jeu Il suffit d'installer et de configurer le module pour la production et pour la pré-production selon les instructions fournies par WebInColor : Annulation des paniers L'annulation des paniers via un flux automatique n'est actuellement pas disponible dans le module Prestashop Description du module Page d'information générale : Exemple d'utilisation : Remontée des paniers et affichage du jeu Il suffit d'installer et de configurer le module pour la production et pour la pré-production selon les instructions fournies par Web In Color : Ceci prendra en charge la remontée des paniers et l'affichage du jeu sans plus d'opérations. Annulation des paniers L'annulation des paniers via un flux automatique n'est actuellement pas disponible dans le module. Guide d intégration technique Lucky Cart v2.7-9/32

10 3.2. Intégrations "natives" (modules Lucky Cart) Si le marchand ne dispose pas de framework ecommerce supporté, l intégration du plugin Lucky Cart est aussi possible via un ensemble de modules natifs développés par Lucky Cart. Leur utilisation est recommandée car elle encapsule et rend facilement accessible les APIs et l'algorithme d'authentification qui sécurise les échanges. Les modules sont proposés selon le langage ou la technologie utilisés par le serveur du marchand. Plus de précisions sur l implémentation des modules sont disponibles en contactant les équipes techniques Lucky Cart. Quelque soit le module utilisé par le marchand, son fonctionnement reste globalement identique: 1. Initialisation de la librairie et appel aux services Lucky Cart avec les données de transaction et d identification nécessaires à la création des jeux. 2. La librairie retourne un objet spécifique au jeu dans le langage utilisé, cet objet proposant des accès aux tags HTML à intégrer sur la page de confirmation de commande (ou tout autre page sur laquelle doit s afficher le jeu). 3. Le plugin Lucky Cart Javascript intégré s'occupe du reste des opérations lors du chargement de la page sur le navigateur du client PHP Description du module Le module php se compose de 2 fichiers présents dans le kit d intégration: /Plugin/Php/luckycart.php : la librairie php /Plugin/Php/sample.php : un exemple d utilisation Remontée des paniers et affichage du jeu 1. Installation de la librairie Placez la librairie luckycart.php sur le serveur à un endroit accessible depuis la page de confirmation de commande. 2. Inclusion de la librairie Modifiez la page de confirmation de commande pour inclure la librairie: // IncludeLClibrary require_once ( 'path/to/luckycart.php' ); Guide d intégration technique Lucky Cart v2.7-10/32

11 3. Initialisation de la librairie et envoi des données Toujours sur la page de confirmation de commande: 1. Ajoutez le code d initialisation de la librairie avec la clef et le code secret fournis par Lucky Cart spécifique à l'environnement concerné. 2. Ajoutez le code permettant de créer la structure des données à envoyer (normalement déterminée au préalable entre le marchand et Lucky Cart selon les besoins). 3. Envoyez les données. // Useexceptiontocatcherror try{ // CreateaLuckyCartobjectwithyourkeyandsecret $lucky= new LuckyCart( 'key','secret' ); // Createanarrayofdatatosendtoassociatewiththetoken. // Assumingdatafromthesitearestorein$customerand$cartdata. $postdata= array ( // mandatorydata 'customerid' =>$customer->id, 'cartid' =>$cart->id, 'ttc' =>$cart->ttc, 'ht' =>$cart->ht, 'country' =>$customer->country, ' ' =>$customer-> , 'payment' =>$cart->payment, // stronglyrecommandeddata 'firstname' =>$customer->firstname, 'lastname' =>$customer->lastname, 'codepromo' =>$cart->code, 'currency' =>$cart->currency, 'lang' =>$customer->language, 'shopid' =>$cart->shopid, 'products' => array ( array ( 'id' =>$cart->products[0]->id, 'ttc' =>$cart->products[0]->ttc, 'ht' =>$cart->products[0]->ht, 'qty' =>$cart->products[0]->quantity), array ( 'id' =>$cart->products[1]->id, 'ttc' =>$cart->products[1]->ttc, 'ht' =>$cart->products[1]->ht, 'qty' =>$cart->products[1]->quantity), array ( 'id' =>$cart->products[2]->id, 'ttc' =>$cart->products[2]->ttc, 'ht' =>$cart->products[2]->ht, 'qty' =>$cart->products[2]->quantity), ), // addhereanyotherspecificdata ); // SendstherequesttoLCservers $plugin=$lucky->plugin($postdata); Guide d intégration technique Lucky Cart v2.7-11/32

12 } catch(luckyexception$e) { // Dosomethingwiththeerror... retryorlog // theerrormessageforexample...($e->getmessage()) } 4. Affichage du jeu Il s effectue en positionnant les containers suivants sur la page de confirmation de commande : <body>... <!-- Addthisdivtaganywhereintheorderconfirmationpagetorenderthegameplugin--> <?php echo$plugin->gamediv;?>... <!-- Addthisscripttagatthebottomofthepage(inordernottointerferewithpage loading)--> <?php echo$plugin->script;?> </body> Annulation des paniers Dans le même esprit que précédemment, il est également possible de notifier les serveurs Lucky Cart qu un panier a été annulé/modifié et donc d'annuler/modifier le jeu associé en ajoutant les lignes suivantes dans le code de la page de confirmation d annulation : // IncludeLClibrary require_once ( 'path/to/luckycart.php' ); // Useexceptiontocatcherror try{ // CreateaLuckyCartobjectwithyourkeyandsecret $lucky= new LuckyCart( 'key','secret' ); // Cancelsthespecifiedcart $lucky->cancel($cart->id); } catch(luckyexception$e) { // Dosomethingwiththeerror... retryorlog // theerrormessageforexample...($e->getmessage()) } Récupération d'informations sur un jeu Dans le cas où un panier ne donne lieu qu'à un seul jeu, il est possible de récupérer les informations associées à ce jeu en ajoutant les lignes suivantes sur la page qui en a besoin : Guide d intégration technique Lucky Cart v2.7-12/32

13 // IncludeLClibrary require_once ( 'path/to/luckycart.php' ); // Useexceptiontocatcherror try{ // CreateaLuckyCartobjectwithyourkeyandsecret $lucky= new LuckyCart( 'key','secret' ); // Retrievingplayerinfoforthespecifiedcart $player_info=$lucky->getplayers($cart->id); } catch(luckyexception$e) { // Dosomethingwiththeerror... retryorlog // theerrormessageforexample...($e->getmessage()) } Le format des informations de retour sera un tableau d'objets contenant les propriétés suivantes: cust : identifiant unique de l acheteur utilisé par le marchand. cart : identifiant unique de la transaction (de l achat) utilisé par le marchand. win : booléen indiquant si le jeu a été gagné ou non. gain : gain mis en jeu tel qu'il s'est affiché sur le jeu ou dans les s. value : montant équivalent du gain mis en jeu (dans la devise du panier associé) Java Description du module Le module Java se compose de 4 éléments présents dans le kit d intégration: /Plugin/Java/Luckycart.jar : la librairie Java /Plugin/Java/dependencies : les dépendances de la librairie Lucky Cart /Plugin/Java/sample.jsp : un exemple d utilisation /Plugin/Java/javadoc : la documentation de la librairie Remontée des paniers et affichage du jeu 1. Installation de la librairie Copiez la librairie Luckycart.jar, ainsi que ses dépendances, dans le dossier lib de votre application web ou de votre serveur d application. Attention à ne pas laisser des librairies en doublon. Il est probable que vous ayez déjà une version de log4, commons-logging ou commons-codec installée sur votre serveur d application; Guide d intégration technique Lucky Cart v2.7-13/32

14 2. Inclusion de la librairie Modifiez le code de la page de confirmation de commande pour inclure la librairie : // IncludeLClibrary import com.luckycart.client.luckycart; import com.luckycart.client.domain.*; 3. Initialisation de la librairie et envoi des données Toujours dans le code de la page de confirmation de commande: 1. Ajoutez le code d initialisation de la librairie avec la clef et le secret fournis par Lucky Cart. 2. Ajoutez le code permettant de créer la structure des données à envoyer. 3. Envoyez les données. // CreateaLuckyCartobjectwithyourkeyandsecret LuckyCartluckyCart= LuckyCart.builder().setKey( "key" ).setsecret( "secret" ).createluckycart(); // CreateaLuckyCartTransactionobject //Assumingdatafromthesitearestoreinacustomerandcartobject. LuckyCartTransactiontransaction= new LuckyCartTransaction(); // mandatorydata transaction.setcustomerid(customer.getid()); transaction.setcartid(cart.getid()); transaction.setttc(cart.getttc()); transaction.setht(cart.getht()); transaction.setcountry(customer.getcountry()); transaction.set (customer.get ()); transaction.setpayment(cart.getpayment()); // stronglyrecommandeddata transaction.setfirstname(customer.getfirstname()); transaction.setlastname(customer.getlastname()); transaction.setcodepromo(cart.getcode()); transaction.setcurrency(cart.getcurrency()); transaction.setlang(cart.getlang()); transaction.setproducts(arrays.aslist( new LuckyCartProduct(cart.products[0].getId(), cart.products[0].getttc(), cart.products[0].getht(), cart.products[0].getqty()), new LuckyCartProduct(cart.products[1].getId(), cart.products[1].getttc(), cart.products[1].getht(), cart.products[1].getqty()) ); // YoucanaddmoretransactioninformationbyoverridingtheLuckyCartTransactionclass // SendstherequesttoLCservers LuckyCartPluginResponsepluginResponse=luckyCart.plugin(transaction); Guide d intégration technique Lucky Cart v2.7-14/32

15 4. Affichage du jeu Il s effectue en positionnant les containers suivants sur la page de confirmation de commande: <body>... <!-- Addthisdivtaganywhereintheorderconfirmationpagetorenderthegameplugin--> <% out.println(pluginresponse.getgamediv()); %>... <!-- Addthisscripttagatthebottomofthepage(inordernottointerferewithpage loading)--> <% out.println(pluginresponse.getscript()); %> </body> 5. Envoi de données supplémentaires La classe LuckyCartTransaction contient des attributs obligatoires et optionnels prédéfinis. Si besoin, il est possible d'envoyer pour chaque panier des informations supplémentaires en surchargeant LuckyCartTransaction selon la méthode suivante: publicclass MyCompanyLuckyCartTransaction extends LuckyCartTransaction { privatestring myeextrainfo; publicstring getmyextrainfo(){ returnmyextrainfo; } } publicvoid setmyextrainfo( String myextrainfo){ this.myextrainfo=myextrainfo; } Annulation des paniers L'annulation des paniers se fait via la methode cancel(stringcartid)de la classe LuckyCart. Voici un exemple de code à intégrer sur la page de confirmation d'annulation: // IncludeLClibrary import com.luckycart.client.luckycart; import com.luckycart.client.domain.*; // CreateaLuckyCartobjectwithyourkeyandsecret LuckyCartluckyCart= LuckyCart.builder().setKey( "key" ).setsecret( "secret" ).createluckycart(); // Cancelsthespecifiedcart LuckyCartCancelResponsecancelResponse=luckyCart.cancel(cart.getId()); Guide d intégration technique Lucky Cart v2.7-15/32

16 ASP.NET Description du module Le module ASP.NET se compose de 2 fichiers présents dans le kit d intégration : /Plugin/ASP.NET/Bin/Luckycart.dll : la librairie ASP.NET /Plugin/ASP.NET/Sample.aspx : la page de l exemple d utilisation /Plugin/ASP.NET/Sample.aspx.cs : le code de l exemple d utilisation Remontée des paniers et affichage du jeu 1. Installation de la librairie Placez la librairie luckycart.dlldans un sous-répertoire Binde celui contenant la page de confirmation de commande. 2. Inclusion de la librairie Modifiez le code de la page de confirmation de commande pour inclure la librairie : // IncludeLClibrary Using LuckyCart; 3. Initialisation de la librairie et envoi des données Toujours dans le code de la page de confirmation de commande: 1. Ajoutez le code d initialisation de la librairie avec la clef et le secret fournis par Lucky Cart. 2. Ajoutez le code permettant de créer la structure des données à envoyer (normalement déterminée au préalable entre le marchand et Lucky Cart selon les besoins). 3. Envoyez les données. // Useexceptiontocatcherror try { // CreateaLuckyCartobjectwithyourkeyandsecret LuckyLiblc= new LuckyLib(Key, Secret); // Createanarrayofdatatosendtoassociatewiththetoken. //AssumingdatafromthesitearestoreinCustomerandCartobject. Dictionary <string, object> PostData= new Dictionary <string, object> () { // mandatorydata { "customerid", Customer.Id}, { "cartid", Cart.Id}, { "ttc", Cart.Ttc}, { "ht", Cart.Ht}, Guide d intégration technique Lucky Cart v2.7-16/32

17 { "country", Customer.Country}, { " ", Customer. }, { "payment", Cart.Payment}, // stronglyrecommandeddata { "firstname", Customer.FirstName}, { "lastname", Customer.LastName}, { "codepromo", Cart.Code}, { "payment", Cart.Currency}, { "lang", Customer.Language}, { "shopid", Cart.ShopId}, { "products", newlist<namevaluecollection>(){ new NameValueCollection(){{ "id", Cart.Products[0].Id},{ "ttc", Cart.Products[0].Ttc}, { "ht", Cart.Products[0].Ht},{ "qty", Cart.Products[0].Qty}}, new NameValueCollection(){{ "id", Cart.Products[1].Id},{ "ttc", Cart.Products[1].Ttc}, { "ht", Cart.Products[1].Ht},{ "qty", Cart.Products[1].Qty}}, new NameValueCollection(){{ "id", Cart.Products[2].Id},{ "ttc", Cart.Products[2].Ttc}, { "ht", Cart.Products[2].Ht},{ "qty", Cart.Products[2].Qty}} }} // addhereanyotherspecificdata ); // SendsthecreationrequesttoLCservers varplugin=lc.plugin(postdata); // Injectsthegamecontainerintoadivtag lcgame.innerhtml=plugin.gamediv; // Injectsthescripttorunintoadivtag lcscript.innerhtml=plugin.script; } catch (Exceptionex) { //handleexceptionhere(retry, log,...) throw ex; } 4. Affichage du jeu Il s effectue en positionnant les containers suivants sur la page de confirmation de commande: <body>... <!-- Addthisdivtaganywhereintheorderconfirmationpagetorenderthegameplugin--> <div id= "lcgame" runat= "server" ></div> </div>... Guide d intégration technique Lucky Cart v2.7-17/32

18 <!-- Addthisdivtagatthebottomofthepage(inordernottointerferewithpageloading) --> <div id= "lcscript" runat= "server" ></div> </body> Annulation des paniers Il est également possible de notifier les serveurs Lucky Cart qu un panier a été annulé et donc d'annuler le jeu éventuel associé en ajoutant les lignes suivantes dans le code de la page de confirmation d annulation: // IncludeLClibrary Using LuckyCart; // Useexceptiontocatcherror try { // CreateaLuckyCartobjectwithyourkeyandsecretprovided LuckyLiblc= new LuckyLib(Key, Secret); // SendsthecancelrequesttoLCservers lc.cancel(cart.id); } catch (Exceptionex) { //handleexceptionhere(retry, log,...) throw ex; } Guide d intégration technique Lucky Cart v2.7-18/32

19 3.3. Intégrations "légères" (tag Javascript) Avertissement important L intégration de la technologie Lucky Cart par tag Javascript, via un gestionnaire de tag ou en natif, n est pas recommandée pour des raisons liées à la sécurité des données et à la fiabilité de leur envoi. En effet, le tag Javascript étant déposé sur une page visible du site du marchant, il devient possible pour une tierce personne de l utiliser afin de simuler des envois de données au serveur Lucky Cart, par exemple pour générer des tickets, ou afin de réaliser une attaque sur les serveurs Lucky Cart. En cas d abus identifié lié à cette faille de sécurité, Lucky Cart se réserve le droit de stopper la réception des données provenant du client. De plus, si le tag est exécuté trop lentement ou si la fermeture prématurée de la page empêche la bonne exécution du script, les données ne seront pas reçues par Lucky Cart et aucun jeu ne pourra être généré pour le client. Il faudra alors procéder à une consolidation manuelle des données facturée 100 HT par fichier.csv traité. Enfin, il est à noter qu'à la différence des autres tag qui généralement n'affichent rien, l'utilisation d'un gestionnaire de tag nécessitera quand même la modification de la page de confirmation de commande pour insérer un élément <div>permettant de localiser l'endroit ou le jeu doit s'insérer. Si cela s'avère impossible, l'insertion manuelle par les équipes Lucky Cart du jeu à partir des éléments déjà présents sur la page de confirmation de commande sera facturée 250 HT Javascript natif Description du module Le module Javascript se compose de 2 fichiers présents dans le kit d intégration : /Plugin/Javascript/luckyclient.min.js : la librairie javascript /Plugin/Javascript/sample.html : un exemple d utilisation Remontée des paniers et affichage d'un jeu 1. Installation de la librairie Placez luckyclient.min.js dans un répertoire accessible par votre serveur web. A noter que la librairie est fournie dans le kit dans le but de faire des tests et peut être hébergée sur votre serveur. Il est toutefois recommandé d utiliser lors de l intégration la version hébergée et mise à disposition par Lucky Cart. Guide d intégration technique Lucky Cart v2.7-19/32

20 2. Création des balises scripts Modifiez la page de confirmation de commande pour inclure la librairie ainsi qu une balise script qui contiendra le code d initialisation et d envoi des données: <script type= "text/javascript src= "/path/to/luckyclient.min.js ></script> <script type= "text/javascript > // Coded initialisationetd envoidesdonnées </script> Nous conseillons d intégrer le script en haut de page pour optimiser sa bonne exécution. 3. Initialisation de la librairie et envoi des données Dans la balise script précédemment créée, ajoutez le code d initialisation de la librairie avec la clef et le code secret fournis par Lucky Cart: // CreateaLuckyCartobjectwithyourkeyandsecret var client =new Luckycart( 'key','secret' ); Ajoutez ensuite le code permettant de créer la structure des données à envoyer (normalement déterminées au préalable entre le marchand et Lucky Cart selon les besoins): // Createanarrayofdatatosendtoassociatewiththetoken. //Assumingdatafromthesitearestoreincustomerandcartdata. var data={ // mandatorydata customerid: customer.getid(), cartid: cart.getid(), ttc: cart.getttc(), ht: cart.getht(), country: customer.getcountry(), customer.get (), payment: cart.getpayment(), // stronglyrecommandeddata firstname: customer.getfirstname(), lastname: customer.getlastname(), codepromo: cart.getcode(), currency: cart.getcurrency(), lang: customer.getlanguage(), shopid: cart.getshopid(), products:[ {uid: cart.products[0].getid(), ttc: cart.products[0].getttc(), ht: cart.products[0].getht(), qty: cart.products[0].getqty(), cat:[6]}, {uid: cart.products[1].getid(), ttc: cart.products[1].getttc(), Guide d intégration technique Lucky Cart v2.7-20/32

21 ht: cart.products[1].getht(), qty: cart.products[1].getqty(), cat:[]}, {uid: cart.products[2].getid(), ttc: cart.products[2].getttc(), ht: cart.products[2].getht(), qty: cart.products[2].getqty(), cat:[1,5]}, ] // addhereanyotherspecificdata }; client.init( function (){ client.plugin(data, 1, function (res){ // Callbackcalledoncedatahavebeensent if (!res.script) return; res.script=res.script.replace(/\<[^<>]+\>/g,""); var lc_script=document.createelement( 'script' ); lc_script.innerhtml+=res.script; document.body.appendchild(lc_script); }) }); 4. Affichage du jeu Il s effectue en positionnant le container suivant sur la page de confirmation de commande: <div id= "luckygame" > <!-- Luckycartpluginwillbedisplayedhere--> </div> Annulation des paniers Pour annuler un panier spécifique et le jeu qui lui est éventuellement associé, il suffit d'appeler la méthode cancel(id) de la class LuckyCart sur la page de confirmation d'annulation: <script type= "text/javascript src= "/path/to/luckyclient.min.js ></script> <script type= "text/javascript > // CreateaLuckyCartobjectwithyourkeyandsecret var client =new Luckycart( 'key','secret' ); // Cancelsthespecifiedcart client.init( function (){ client.cancel(cart.getid()); }); </script> Guide d intégration technique Lucky Cart v2.7-21/32

22 Google Tag Manager Dans le cadre de l'utilisation de la technologie Google Tag Manager pour intégrer Lucky Cart, les étapes détaillées ci-dessous pré-supposent de la part du marchand une connaissance approfondie du gestionnaire de tag. En cas de problème relatif à son utilisation ou à la mise en place de données spécifiques au site marchand, il est recommandé de se tourner en premier lieu vers le support Google Tag Manager. Remontée des paniers et affichage d'un jeu 1. Identification et création des macros Assurez-vous que les macros/variables correspondantes aux données listées chapitre 2. sont disponibles dans GTM et les créer si nécessaire. 2. Mise en place des balises de pré-production et de production Créez deux balises/tags, l'une pour la pré-production (par ex "Lucky Cart - test") et l'autre pour la production (par ex "Lucky Cart - prod") avec les propriétés suivantes: Type : HTML personnalisé/custom Code HTML : calqué sur l'exemple /Plugin/Javascript/GTM.jsfourni dans l'archive d'intégration en utilisant les macros/variables précédemment créées Support "document.write" : Activé Règles de déclenchement : exclusivement sur la page de confirmation de commande de chaque environnement Guide d intégration technique Lucky Cart v2.7-22/32

23 3. Insertion du tag d'affichage du jeu Positionnez le container suivant sur la page de confirmation de commande à l'emplacement choisi pour afficher le jeu: <div id= "luckygame" > <!-- Luckycartpluginwillbedisplayedhere--> </div> 4. Publication des tags Publier sur tous les environnements les tags précédemment crées dans GTM. Annulation des paniers Dans le même esprit que pour la création des paniers, il est possible de mettre en place des tags permettant de les annuler en utilisant dans chacun d'eux le code Javascript d'annulation précédent. Il faudra alors configurer ces tags pour être déclenchés depuis la page de confirmation d'annulation sur chaque environnement cible uniquement Eulerian Dans le cadre de l'utilisation de la technologie Eulerian pour intégrer Lucky Cart, les étapes détaillées ci-dessous pré-supposent une connaissance approfondie du gestionnaire de tag de la part du marchand. En cas de problème relatif à son utilisation ou à la mise en place de données spécifiques au site marchand, il est fortement recommandé de se tourner en premier lieu vers le support Eulerian. Remontée des paniers et affichage d'un jeu 1. Mise en place des tags de pré-production et de production Depuis le gestionnaire de tags partenaires, créez deux tag partenaires "Luckycart v2", l'un pour la pré-production (par ex "Lucky Cart - test") et l'autre pour la production (par ex "Lucky Cart - prod") : Guide d intégration technique Lucky Cart v2.7-23/32

24 Renseignez pour chaque tag la clé et le secret (communiqués pas Lucky Cart) correspondant à l'environnement cible (production/pré-production) et configurez son déclenchement pour s'effectuer exclusivement sur la page de confirmation de commande de l'environnement cible : 2. Mise à jour du pseudo-code des tags Afin de s'assurer que les tags sont à jour, il est conseillé de mettre à jour leurs pseudo-codes à partir de la fenêtre de "Prévisualisation du tag" de l'interface. Ceci peut être fait de deux façons: - en récupérant le format Ad'Hoc du tag - en copiant le pseudo code contenu dans l'archive d'intégration : /Plugin/Javascript/Eulerian.js 3. Paramétrage des tags Dans l'interface d'édition des paramètres de chaque tag, affectez les champs (détaillés précédemment section 2.) aux paramètres génériques, ou personnalisés (saisie libre, passé au EA_collector, etc...) disponibles sur la page de confirmation de commande. Voici un exemple de configuration : Guide d intégration technique Lucky Cart v2.7-24/32

25 4. Insertion du tag d'affichage du jeu Il convient de positionner le container suivant sur la page de confirmation de commande à l'endroit désiré pour afficher le jeu : <div id= "luckygame" > <!-- Luckycartpluginwillbedisplayedhere--> </div> Guide d intégration technique Lucky Cart v2.7-25/32

26 5. Activation du tag Activez enfin les tags ainsi mis en place en s'assurant que ces derniers seront inclus dans le code de la page de confirmation de commande (sans iframe) : Annulation des paniers Il est possible de mettre en place des tags permettant d annuler des paniers, en utilisant dans chacun d'eux le code Javascript d'annulation précédant. Il vous faudra alors configurer ces tags pour être déclenchés depuis la page de confirmation d'annulation sur chaque environnement cible. Guide d intégration technique Lucky Cart v2.7-26/32

27 Tag Commander Dans le cadre de l'utilisation de la technologie Tag Commander pour intégrer Lucky Cart, les étapes détaillées ci-dessous pré-supposent de la part du marchand une connaissance approfondie du gestionnaire de tag. En cas de problème relatif à son utilisation ou à la mise en place de données spécifiques au site marchand, il est recommandé de se tourner en premier lieu vers le support Tag Commander. Remontée des paniers et affichage d'un jeu 1. Mise en place des tags de pré-production et de production Dans l'interface de gestion Tag Commander du site marchand, créez deux tags, l'un pour la pré-production (par ex "Lucky Cart - test") et l'autre pour la production (par ex "Lucky Cart - prod") et configurer pour chacun: La clé et le secret (communiqués par Lucky Cart) correspondant à l'environnement cible (production/pré-production). Le chemin vers la librarie luckyclient.min.js (communiqué pas Lucky Cart). Les valeurs des différents champs (définis au chapitre 2.) en utilisant les variables Tag Commander ( tc_vars["..."] ) disponibles sur la page de confirmation de commande. Les conditions de déclenchement pour s'effectuer exclusivement sur la page de confirmation de commande de l'environnement cible. Un exemple de pseudo-code de référence du tag Lucky Cart est disponible dans le fichier /Plugin/Javascript/TagCommander.js de l'archive d'intégration. 2. Insertion du tag d'affichage du jeu Positionnez le container suivant sur la page de confirmation de commande à l'endroit choisi pour afficher le jeu : <div id= "luckygame" > <!-- Luckycartpluginwillbedisplayedhere--> </div> Annulation des paniers Il est possible de mettre en place des tags permettant d annuler des paniers, en utilisant dans chacun d'eux le code Javascript d'annulation précédent. Il faudra alors configurer ces tags pour être déclenchés depuis la page de confirmation d'annulation sur chaque environnement cible. Guide d intégration technique Lucky Cart v2.7-27/32

28 4. Intégration d'éléments de mise en avant 4.1. Page "En savoir plus" Lucky Cart met à votre disposition une page expliquant la promotion dans le détail. Cette page a vocation à être intégrée directement sur le site du marchand : Pour ce faire, il suffit d'insérer le code html suivant sur la page récapitulant la promotion: <iframe src= " width= "100%" height= "1250" frameborder= "0" ></iframe> en remplaçant le paramètre src par l'url communiquée par les équipes Lucky Cart. Guide d intégration technique Lucky Cart v2.7-28/32

29 4.2. Tableau simple de gagnants (HTML) Le module luckywinners permet d afficher sur le site du marchand une liste paramétrable des gagnants sous la forme d un tableau HTML. Description du module Le module Javascript se compose de 2 fichiers présents dans le kit d intégration : /Leaderboard/luckywinners.min.js : la librairie javascript /Leaderboard/luckywinners.html : un exemple d utilisation Installation 1. Installation de la librairie Placez luckywinners.min.js dans un répertoire accessible par votre serveur web. La librairie est fournie dans le kit dans le but de faire des tests et peut être hébergée sur votre serveur. Il est toutefois recommandé d utiliser lors de l intégration la version hébergée et mise à disposition par Lucky Cart. 2. Modification de la page Ajoutez dans le code HTML de la page: 1. L inclusion à la librairie 2. Le container du tableau des gagnants 3. L appel à la fonction qui retourne le tableau dans le container <head> <!-- includingluckycartleaderboardlibrary--> < script type= "text/javascript" src= "/path/to/luckywinners.js" ></script>... </head> <body>... <!-- addthisanywheretodisplaytheleaderboardinyourpage--> <div id= "lc-winners-container" ></div>... <!-- addthisatthebottomofthepage--> <script type= "text/javascript" > var options={ display: 5, count: 10, order:"date", way:"desc", Guide d intégration technique Lucky Cart v2.7-29/32

30 headers:"joueur;gain" }; luckywinners("client_id","campaign_id", options); </script> </body> </html> Configuration Le configuration du tableau des gagnants se fait à travers les 3 paramètres passés à la fonction luckywinners(). client_id : champ texte fourni par Lucky Cart permettant d identifier le client campaign_id : champ texte fourni par Lucky Cart permettant d identifier la campagne. S il n est pas précisé, les gagnants seront sélectionnés parmi toutes les campagnes de Promogaming mises en place par le client. options : objet optionnel permettant de contrôler le résultat renvoyé. L utilisation de cet objet se fait sous forme de liste dont le détail des paramètres pris en compte est indiqué ci-dessous : nom display description valeur défaut nombre de lignes maximum à afficher entier count nom description type count nombre de gagnants à récupérer périodiquement entier défaut 5 note si la valeur du paramètre count est supérieure à la valeur du paramètre display, les gagnants défileront verticalement dans le tableau créé par le plugin. Arrivé en bas de la liste, le défilement reprendra à partir du premier gagnant Guide d intégration technique Lucky Cart v2.7-30/32

31 nom description valeur défaut order l'ordre de tri "date" ou "gain" "date" nom description valeur défaut way le mode de tri "desc" ou "asc" "desc" nom description headers nom des en-têtes de chaque colonne valeur chaîne de caractère contenant 2 noms séparés par < ; > défaut "Joueur;Gain" nom description valeur défaut container identifiant du div contenant le tableau de retour chaîne de caractère "lc-winners-container" Customisation Pour customiser l affichage des gagnants, il suffit d appliquer des styles CSS sur les différents éléments du tableau retourné par l appel à la librairie dont voici un exemple : <div id= "lc-winners-container" > <table class= "lc-winners-plugin" > <thead> <tr> <th class= "lc-player" > Joueur </th> <th class= "lc-gain" > Gain </th> </tr> </thead> <tbody> <tr> <td class= "lc-player" > LaurentC. </td> Guide d intégration technique Lucky Cart v2.7-31/32

32 <td class= "lc-gain" > 16,00 </td> </tr> <tr> <td class= "lc-player" > StephaneG. </td> <td class= "lc-gain" > 52,00 </td> </tr> <tr> <td class= "lc-player" > NicolasW. </td> <td class= "lc-gain" > 19,30 </td> </tr> <tr> <td class= "lc-player" > AntoineG. </td> <td class= "lc-gain" > 70,00 </td> </tr> </tbody> </table> </div> 4.3. Informations avancées sur les gagnants (Json) De manière étendue par rapport à un simple tableau de gagnants, un flux json des gagnants est également disponible pour accéder à des informations supplémentaires (dates de gain, nombre de gagnants, etc...) ainsi qu'à une mise en forme plus personnalisée. L'URL de ce flux est : avec les paramètres de configuration suivants : client_id : champ texte fourni par Lucky Cart permettant d identifier le client campaign_id : champ texte fourni par Lucky Cart permettant d identifier la campagne count, order et way : paramètres optionnels à utiliser de la même façon qu'en utilisant le module luckywinners (voir ci-dessus) Le rafraîchissement et la personnalisation de l'affichage de ces informations sont laissés à la discrétion du marchand. Guide d intégration technique Lucky Cart v2.7-32/32