Guide d'Intégration du SDK Web

Ce document est le guide d'intégration standard du SDK Web MA.

Description du Produit

Le SDK Web MA fournit des fonctions de collecte et de remontée de données, utilisées dans des scénarios tels que la génération d'EUID, la définition de propriétés utilisateur et la remontée d'événements.

Choix du Mode d'Intégration

Le SDK Web MA prend en charge 2 modes d'intégration : avec WebPush, ou le SDK Web MA utilisé seul.

• Avec WebPush : activez la fonction MA lors de l'intégration du module EngageLab WebPush, le SDK MA est alors chargé automatiquement.
• SDK Web MA seul : intégrez directement l'adresse du SDK MA dans votre site web, sans les fonctions WebPush.

Avec WebPush

Préparatifs avant l'Intégration

• Vous devez également intégrer le module WebPush.
• Préparez un nom de domaine de service web HTTPS accessible. Après l'intégration, les pages doivent être testées et déboguées sous ce nom de domaine. La notification push hors ligne web ne prend pas en charge le débogage local ni le HTTP.
• Accédez à EngageLab WebPush, puis sur la page [Paramètres d'Intégration] - [Nom de Domaine du Site Web], renseignez le nom de domaine du service web HTTPS.

Obtenir les Informations de l'Application

Vous devez créer une application sur la console WebPush. Après création, une AppKey est générée automatiquement pour identifier cette application. Pour plus de détails, consultez le Document des Paramètres de l'Application.

Configuration de la Source de Données MA

Dans le projet MA, accédez à Sources de données - Ajouter une source de données - Web, sélectionnez « Utiliser avec WebPush », choisissez dans la liste déroulante l'application créée dans WebPush, puis enregistrez.

Accès au SDK

Rendez-vous sur la Console, téléchargez le SDK et incluez le JavaScript sur chaque page :

              
              <script type="text/javascript" src="./WebSDK.3.3.4.js"></script>

            

Astuces

Après avoir importé ce JavaScript, transmettez la propriété maOpen avec la valeur true pour activer la configuration MA, ce qui vous permet d'utiliser les API et fonctions associées à MA.

Initialisation du SDK

              
                  //  Initialisation (activer MA)
  MTpushInterface.init({
    appkey: "", // Obligatoire, voir ci-dessus « Obtenir les Informations de l'Application »
    user_str: "adminDemo", // Obligatoire, identifiant utilisateur servant à marquer l'utilisateur
    swUrl: "url", // Par défaut : "/sw.min." + sdkEnv.version + ".js". Cette option correspond à l'adresse du fichier service worker. Le domaine doit être le domaine actuel, et le chemin détermine la portée du service worker.
    debugMode: true,// Définit si le mode debug est activé. true affichera plus d'informations de log ; false n'affichera que les logs de niveau w et e.
    channel: "default-channel",// Nom du canal, valeur par défaut : default-channel
    appName: "string",// Sert à définir le nom du site web, utilisé pour la remontée
    maOpen: true, // Active l'interrupteur pour utiliser la fonction MA
    userIdentity: { user_id: "1234567890", anonymous_id: "anonymous123" },// Définit l'identification de l'utilisateur lors de l'initialisation de MA. Pris en charge depuis la version 3.3.4, applicable aux entreprises fournissant des services MA exclusivement aux membres connectés
    maDataCollectionEnabled: false, // État initial de la collecte de données MA ; activée par défaut si omis. Pris en charge depuis WebPush SDK 3.3.9
    maCompletion: (code, msg) => {// Callback d'initialisation de MA
                if (code === 0) {
                    console.log("✅SDK MA initialisé avec succès !");
                } else {
                    console.error("❌Échec de l'initialisation du SDK MA :", msg);
                }
    }
  });

            

Interrupteur de collecte de données (avec WebPush)

Pris en charge depuis : MA Web SDK 2.2.0, WebPush SDK 3.3.9

• Lors de l'initialisation via MTpushInterface.init, transmettez dynamiquement la valeur de maDataCollectionEnabled selon l'état de consentement de l'utilisateur ; le SDK WebPush la transmet telle quelle au SDK MA. Veillez à ne pas coder la configuration en dur, afin d'éviter que chaque initialisation ne réinitialise l'état à la valeur codée en dur.
• Lorsque l'état de collecte de données de l'utilisateur change, appelez window.MAInterface.setDataCollectionEnabled(true/false) après le déclenchement du callback maCompletion. maCompletion est le signal indiquant que le SDK MA est disponible ; avant celui-ci, window.MAInterface peut ne pas être encore chargé.
• Pendant la désactivation, les notifications WebPush peuvent toujours être délivrées et cliquées, mais l'attribution des conversions liées aux clics sur les notifications n'est plus comptabilisée.

Pour plus de détails, consultez Interrupteur de collecte de données.

SDK Web MA Seul

Configuration de la Source de Données MA

Dans le projet MA, accédez à Sources de données - Ajouter une source de données - Web, sélectionnez « Ne pas utiliser » dans « Utiliser avec WebPush », saisissez le nom de la source de données et le nom de domaine du site web ; après enregistrement, vous obtenez l'AppKey de la source de données Web.

• Préparez un nom de domaine de service web HTTPS accessible. Après l'intégration, les pages doivent être testées et déboguées sous ce nom de domaine.

Accès au SDK

Incluez le JavaScript suivant sur chaque page :

              
              <script type="text/javascript" src="https://websdk-res.engagelab.com/lib/ma-web.min.js"></script>
        

            

Après avoir importé ce JavaScript, vous pouvez utiliser l'objet global MAInterface disponible sur Window.

Remarque importante : utilisez directement ce lien et ne téléchargez pas ce fichier dans votre projet ; sinon, les statistiques risquent de ne plus fonctionner après une mise à jour de nos structures de données ou de nos interfaces API.

Initialisation du SDK

              
                window.MAInterface.init({
    appKey: "7ccf93e0950b5e22f4ca2124",  // Obligatoire, voir ci-dessus « Obtenir les Informations de l'Application »
    debugMode: true,
    channel: "default-channel22",// Nom du canal, valeur par défaut : default-channel
    appName: "EngageLab-MA test-appName", // Nom du site web, utilisé comme app_name dans les propriétés de l'appareil et la remontée d'événements
    userIdentity: { user_id: "1234567890", anonymous_id: "anonymous123", email: "user@example.com", phone: "+8613800000000" }, // Définit l'identification de l'utilisateur lors de l'initialisation de MA ; prend en charge user_id, anonymous_id, email et phone
      completion: (code, msg) => {
        if (code === 0) {
            console.log("✅ SDK initialisé avec succès !");
        } else {
            console.error("❌ Échec de l'initialisation du SDK :", msg);
        }
    }
  })
        

            

À propos de l'identification de l'utilisateur

• userIdentity prend en charge 4 types d'identification de l'utilisateur : user_id, anonymous_id, email et phone (email et phone sont pris en charge depuis la version 2.1.0). Fournissez-en au moins un ; pour les règles de chaque champ, consultez Définir l'identification de l'utilisateur.
• Lors de l'initialisation, les champs non conformes aux règles sont ignorés et un avertissement est affiché dans la console ; les autres champs valides restent en vigueur.
• email et phone servent à la correspondance de l'identité de l'utilisateur et ne sont pas des moyens de contact ; pour l'adresse e-mail et le numéro de téléphone utilisés pour l'envoi de messages, utilisez l'interface « Définir les informations de contact de l'utilisateur » (setUserContact).

Réinitialisation et Changement d'AppKey

Pris en charge depuis : 2.1.0

Une fois le SDK initialisé, vous pouvez appeler de nouveau init sans rafraîchir la page :

• Même AppKey : le SDK récupère de nouveau l'EUID. Si un nouveau userIdentity est transmis en même temps, le SDK récupère de nouveau l'EUID avec la nouvelle identification de l'utilisateur, ce qui convient au changement de compte après déconnexion au sein de la même page.
• AppKey différente : le SDK bascule vers la source de données MA correspondant à la nouvelle AppKey, et les données suivantes sont remontées vers la nouvelle source de données ; les données générées avant le changement sont toujours remontées vers la source de données d'origine.
• Plusieurs appels à init sont exécutés successivement dans l'ordre d'appel, et chaque appel renvoie son résultat via completion ; référez-vous au résultat du callback de l'appel concerné.
• Le changement d'AppKey n'est pris en charge que lorsque le SDK Web MA est utilisé seul ; le mode d'intégration « avec WebPush » ne le prend pas en charge.

              
                // Basculer vers une autre source de données MA
  window.MAInterface.init({
    appKey: "AppKey d'une autre source de données",
    completion: (code, msg) => {
      console.log(code, msg)
    }
  })

            

Définir l'ID de contact du canal

Pris en charge depuis : 2.1.0

Pour définir le RID ou le Token d'un canal WebPush ou d'un canal Push tiers, appelez l'interface suivante après l'initialisation réussie du SDK :

              
                window.MAInterface.setChannelValue(136, ["push rid or token"], (code, message) => { })

            

• channelId : ID du canal Push configuré dans la console MA, doit être supérieur à 0.
• values : tableau de RID ou de Token ; ni le tableau ni ses éléments ne peuvent être vides. Lorsque le RID ou le Token change, appelez de nouveau l'interface pour le mettre à jour.

Pour plus de détails, consultez Définir l'ID de contact du canal.

Interrupteur de collecte de données

Pris en charge depuis : 2.2.0

L'application contrôle, selon le résultat du consentement de l'utilisateur, si le SDK MA collecte des données. Une fois désactivé, le SDK ne génère, ne met en cache et ne remonte plus les événements, les propriétés utilisateur, les UTM et les informations de l'appareil ; l'initialisation, l'identification de l'utilisateur, les informations de contact et l'ID de contact du canal restent utilisables normalement. L'état est enregistré localement dans le navigateur et conservé après rafraîchissement.

              
                // Lors de l'initialisation, transmettez dynamiquement la valeur de dataCollectionEnabled selon l'état de consentement de l'utilisateur ; ne codez pas la configuration en dur, afin d'éviter que chaque initialisation ne réinitialise l'état à la valeur codée en dur
  window.MAInterface.init({
    appKey: "your appKey",
    dataCollectionEnabled: false, // Activée par défaut si omis
    completion: (code, msg) => {}
  })

  // Après que l'utilisateur a donné / retiré son consentement
  window.MAInterface.setDataCollectionEnabled(true, (code, msg) => {})
  window.MAInterface.setDataCollectionEnabled(false, (code, msg) => {})

            

• Définir une valeur identique à l'état actuel ne déclenche pas de traitement de bascule ; synchroniser le choix de l'utilisateur à chaque chargement de page n'a donc aucun effet supplémentaire.
• Pendant la désactivation, l'appel des interfaces de propriétés utilisateur renvoie -8 via completion ; les interfaces sans callback, comme les événements et les UTM, rejettent silencieusement les données.
• En cas de dégradation du stockage (localStorage indisponible), l'état de l'interrupteur n'est valable que dans l'onglet actuel.

Pour plus de détails, consultez Interrupteur de collecte de données.

Autres Interfaces API

Pour l'utilisation des autres API, consultez la documentation d'interface : API SDK Web.