Guide de l’API

Définir l'identification de l'utilisateur

Versions prises en charge

Identifications email et phone prises en charge depuis : 2.1.0

Définition de l'interface

• identifyAccount(user);
  • Description de l'interface :
    • Définit l'identification de l'utilisateur, comme un numéro de carte de membre.
  • Description des paramètres
    • identity : ID d'identification de l'utilisateur. La clé prend en charge 4 valeurs : user_id, anonymous_id, email et phone ; fournissez-en au moins une, il n'est pas nécessaire de toutes les renseigner
    • completion : le callback
  • Règles d'identification de l'utilisateur
    • user_id : non vide après suppression des espaces de début et de fin, 255 caractères maximum, ne peut pas être 0, null, undefined ou nan (insensible à la casse)
    • anonymous_id : non vide après suppression des espaces de début et de fin, 256 caractères maximum
    • email : adresse e-mail de l'utilisateur, non vide après suppression des espaces de début et de fin, 256 caractères maximum, doit être au format d'e-mail valide, par exemple user@example.com
    • phone : numéro de téléphone de l'utilisateur, doit être au format E.164 incluant l'indicatif du pays ou de la région, par exemple +8613800000000
    • Si l'un des champs ne respecte pas les règles, cet appel n'envoie aucune requête, completion renvoie -1 et message indique la raison précise

Exemple d'appel

              
                  let user = {completion: (code, message)=>{}, identity:{"user_id":"value","anonymous_id":"value","email":"user@example.com","phone":"+8613800000000"}}
    window.MAInterface.identifyAccount(user)

            

Ici, email et phone servent à la correspondance de l'identité de l'utilisateur et peuvent renvoyer un nouvel EUID ; ils ne sont pas interchangeables avec les moyens de contact définis via « Définir les informations de contact de l'utilisateur » (setUserContact).

Obtenir l'EUID

Définition de l'interface

• + EUID()
  • Description de l'interface :
    • Obtient l'EUID de EngageLab MA

Exemple d'appel

              
                  window.MAInterface.EUID((code,euid)=>{
        console.log(code, euid)
    })

            

Définir les informations de contact de l'utilisateur

Définition de l'interface

• setUserContact(user)
  • Description de l'interface :
    • Permet de définir plusieurs moyens de contact simultanément. La clé représente le nom du moyen de contact, et la valeur représente sa valeur. Actuellement, 4 types de moyens de contact sont pris en charge : email, mobile_phone, landline_phone et whatsapp_phone
  • Description des paramètres
    • contacts : les informations de contact de l'utilisateur
    • completion : le callback

Exemple d'appel

              
                    let user = {
          completion: (code, message)=>{ },
          contacts: {}
       }
      user.contacts["Nom du moyen de contact"] = "Valeur du moyen de contact"   // Par exemple : mobile_phone=18800000000
      window.MAInterface.setUserContact(user)

            

Définir l'ID de contact du canal

Versions prises en charge

Pris en charge depuis : 2.1.0

Définition de l'interface

• setChannelValue(channelId, values, completion)
  • Description de l'interface :
    • Définit le RID ou le Token d'un canal Push configuré dans la console MA (par exemple WebPush ou un Push tiers).
    • Doit être appelée après l'initialisation réussie du SDK, sinon completion renvoie -1.
    • Lorsque le RID ou le Token change, appelez de nouveau l'interface pour le mettre à jour.
  • Description des paramètres
    • channelId : ID du canal Push configuré dans la console MA, doit être un entier supérieur à 0
    • values : tableau des valeurs de l'ID de contact du canal (par exemple RID ou Token), ne peut pas être vide, et ses éléments ne peuvent pas être des chaînes vides
    • completion : le callback, code 0 signifie succès

Exemple d'appel

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

            

Interrupteur de collecte de données

Versions prises en charge

Pris en charge depuis : 2.2.0

Description de la fonctionnalité

L'application active ou désactive la collecte de données du SDK MA selon le résultat du consentement de l'utilisateur, afin de répondre aux exigences de conformité interdisant la remontée de données comportementales après le refus ou le retrait du consentement de l'utilisateur.

• Désactivé : arrête la génération, la mise en cache et la remontée des événements, des propriétés utilisateur, des UTM et des informations de l'appareil. L'initialisation, l'obtention de l'EUID/RID, la définition de l'identification de l'utilisateur, la définition des informations de contact et la définition de l'ID de contact du canal restent utilisables normalement.
• Activé : reprend la collecte, sans rattraper les données de la période de désactivation.
• Activé par défaut : si non défini, la collecte est activée par défaut, conformément au comportement antérieur à la mise à niveau.
• Enregistré localement : l'état est enregistré localement dans le navigateur (localStorage) et conservé après rafraîchissement ou réouverture de la page. La suppression des données du site rétablit la valeur par défaut.
• Interrupteur décidé par l'application : le SDK ne détermine pas la région de l'utilisateur, n'affiche pas de fenêtre de consentement et ne lit pas de plateforme de gestion du consentement (CMP).

Définition de l'interface

• init({ dataCollectionEnabled })

  • Description de l'interface : définit l'état de l'interrupteur au premier lancement lors de l'initialisation.
  • Description des paramètres : true pour activer ; false pour désactiver ; activée par défaut si omis.

• setDataCollectionEnabled(enabled, completion)

  • Description de l'interface : active ou désactive la collecte de données, avec effet immédiat et enregistrement local.
  • Description des paramètres :
    • enabled : true pour activer, false pour désactiver
    • completion : le callback, code 0 signifie succès ; renvoie -1 si le paramètre n'est pas un booléen
  • Remarques d'appel :
    • 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.
    • Lors du passage d'activé à désactivé, le SDK tente immédiatement d'envoyer une fois les données générées avant la bascule (accompagnées de l'événement de fin de la session en cours), sans nouvelle tentative en cas d'échec, puis efface le cache local.
    • Lors du passage de désactivé à activé, le SDK remonte les informations de l'appareil et démarre une nouvelle session (remontée de el_session_start et du el_page_view de la page actuelle).
    • Pendant la désactivation, l'attribution des conversions liées aux clics sur les notifications WebPush n'est plus comptabilisée.

• isDataCollectionEnabled()

  • Description de l'interface : renvoie l'état actuel de l'interrupteur ; lit uniquement l'état local, sans lancer de requête réseau.
  • Description de la valeur de retour : true activé, false désactivé ; renvoie true si aucun état n'a encore été enregistré. La valeur de retour reflète l'état de l'interrupteur du SDK et n'indique pas que l'utilisateur a consenti.

Comportement des interfaces pendant la désactivation

Exemple d'appel

              
                // 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,
    completion: (code, msg) => {}
  })

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

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

  // Interroger l'état
  const enabled = window.MAInterface.isDataCollectionEnabled()

            

Définir les propriétés UTM

Définition de l'interface

• setUtmProperties(attrs:any)
  • Description de l'interface :
    • Les propriétés UTM sont des propriétés d'événement standard. Si les développeurs peuvent identifier quelle publicité a dirigé l'utilisateur vers l'App, il est recommandé de définir les informations UTM ; ce paramètre sera transmis lors de la remontée des événements. Actuellement, les propriétés UTM pouvant être définies sont :
      • utm_source : la source de la campagne publicitaire
      • utm_medium : le support de la campagne publicitaire
      • utm_term : le terme de la campagne publicitaire
      • utm_content : le contenu de la campagne publicitaire
      • utm_campaign : le nom de la campagne publicitaire
      • utm_id : l'ID de la campagne publicitaire

Exemple d'appel

              
                 window.MAInterface.setUtmProperties({"utm_source":"value1"})

            

Définir les propriétés utilisateur

Définissez les valeurs des propriétés utilisateur. Si une propriété utilisateur n'existe pas, elle sera automatiquement créée en arrière-plan.

Écraser et mettre à jour les propriétés utilisateur

• setProperty(user, completion)
  • Description de l'interface :
    • Écrase et met à jour les valeurs des propriétés utilisateur.
    • Seules les dernières données remontées sont conservées, remplaçant les données historiques, comme le niveau d'adhésion de l'utilisateur.
    • Le contenu de ces propriétés utilisateur est stocké dans un object. La clé est le nom de la propriété utilisateur et doit être une string ; la valeur est le contenu de la propriété utilisateur et prend en charge les types string, number, Array, object et object_array.
    • Actuellement, les éléments d'une valeur de type Array doivent uniquement être des string ; un tableau dont tous les éléments sont des object est traité comme object_array ; un tableau mélangeant des object avec d'autres types est invalide.
    • Si une propriété utilisateur existait déjà auparavant, elle sera écrasée ; si elle n'existe pas, elle sera créée. Les règles de mise à jour d'object et d'object_array sont décrites ci-dessous.
  • Exemple d'appel :

              
                 window.MAInterface.setProperty({key:"value"}, (code, message)=>{})

            

Règles object / object_array

Pris en charge depuis : 2.1.0

• object est un objet simple non vide, par exemple { city: "Singapore", score: 100 } ; object_array est un tableau dont tous les éléments sont des objets simples non vides.
• Les noms des sous-champs doivent être des string non vides et ne peuvent pas contenir . ni $ ; les valeurs des sous-champs prennent en charge string, number et les tableaux de string, sans imbrication supplémentaire d'object ou d'object_array.
• object utilise une sémantique de fusion des sous-champs : lors d'une nouvelle définition, seuls les sous-champs transmis cette fois sont mis à jour, les sous-champs non transmis restent inchangés ; transmettre null comme valeur d'un sous-champ supprime ce sous-champ.
• object_array utilise une sémantique de remplacement intégral : lors d'une nouvelle définition, le nouveau tableau remplace intégralement l'ancien, en conservant l'ordre du tableau. Lors de la première création d'un object_array, transmettez un tableau d'objets non vide.
• Le type des sous-champs doit correspondre à la définition de cette propriété utilisateur dans la console MA ; en cas de non-conformité, le serveur renvoie un échec.

              
                 window.MAInterface.setProperty({
       profile: { city: "Singapore", score: 100 },
       addresses: [
           { id: "home", city: "Singapore" },
           { id: "office", city: "Tokyo" }
       ]
   }, (code, message)=>{})

   // Met à jour uniquement profile.score, profile.city reste inchangé
   window.MAInterface.setProperty({ profile: { score: 200 } }, (code, message)=>{})

            

Incrémenter et mettre à jour les propriétés utilisateur

• increaseProperty(user, completion)
  • Description de l'interface :
    • Définit une incrémentation pour les valeurs des propriétés utilisateur.
    • Ajoute des valeurs à plusieurs propriétés utilisateur de type numérique. Toutes les données remontées sont cumulées, comme le montant de consommation cumulé.
    • Cette interface ne peut être appelée que pour des propriétés utilisateur de type number, sinon elle sera ignorée. Si cette propriété utilisateur n'existait pas auparavant, la valeur initiale est considérée comme 0.
  • Exemple d'appel :

              
               window.MAInterface.increaseProperty({key:1}, (code, message)=>{})

            

Ajouter des propriétés utilisateur

• addProperty(key, content completion)
  • Description de l'interface :
    • Ajoute des valeurs aux propriétés utilisateur.
    • Permet d'ajouter continuellement des éléments à cet ensemble. Les doublons sont supprimés lors du stockage en base de données. Si ABC existe déjà et que CD est ajouté, le résultat final sera ABCD, comme les actualités aimées par l'utilisateur.
    • Ajoute des valeurs à une propriété de type Array. Les éléments de cet Array doivent être des string, sinon ils seront ignorés. De même, si la propriété utilisateur à compléter n'existait pas auparavant, un Array vide sera initialisé.
  • Exemple d'appel :

              
               window.MAInterface.addProperty("key",["value1", "value2"], (code, message)=>{})

            

Retirer des propriétés utilisateur

• removeProperty(key, content completion)
  • Description de l'interface :
    • Supprime une ou plusieurs valeurs d'une propriété de type tableau.
    • Supprime certaines valeurs d'une propriété de type Array. Les éléments de cet Array doivent être des string, sinon ils seront ignorés. De même, si la propriété utilisateur visée par removeEventListAttrValue n'existait pas auparavant, il n'y aura aucun effet.
  • Exemple d'appel :

              
               window.MAInterface.removeProperty("key",["value1", "value2"], (code, message)=>{})

            

Opérer sur les éléments d'object_array

Versions prises en charge

Pris en charge depuis : 2.1.0

Les usages suivants s'appliquent uniquement aux propriétés utilisateur de type object_array et localisent un élément du tableau via un sous-champ d'identifiant unique. Lorsque addProperty et removeProperty reçoivent un tableau de chaînes, ils continuent d'opérer sur des tableaux de chaînes et leur comportement reste inchangé.

• addProperty(key, object, completion)
  • Description de l'interface :
    • Lorsque le deuxième paramètre est un seul object (et non un tableau), ajoute un élément à la fin de l'object_array sans affecter les éléments existants.
    • L'object doit être un objet non vide ; les règles des sous-champs sont identiques à celles du type object, sans prise en charge de l'imbrication d'object ou d'object_array.
    • Si cette propriété n'est pas encore définie dans la console MA, le serveur la crée automatiquement comme propriété de type object_array et y écrit cet élément ; si la propriété est définie mais que l'utilisateur actuel n'a pas encore de valeur, le tableau est créé avec cet unique élément.
  • Exemple d'appel :

              
               window.MAInterface.addProperty("addresses", { id: "school", city: "Osaka" }, (code, message)=>{})

            

• updateProperty(key, content, completion)
  • Description de l'interface :
    • Localise un élément de l'object_array via un sous-champ d'identifiant unique, puis fusionne et met à jour les sous-champs de cet élément.
    • La structure de content est { $identifier_key, $identifier_value, $new_object } :
      • $identifier_key : nom du sous-champ servant à localiser l'élément ; ce sous-champ doit déjà être défini dans la console MA, de type string ou number
      • $identifier_value : valeur de localisation, de type string ou number ; si plusieurs éléments correspondent, la mise à jour s'applique à tous
      • $new_object : sous-champs à mettre à jour ; doit être un objet non vide et ne peut pas contenir le sous-champ correspondant à$identifier_key ; les sous-champs non transmis restent inchangés, transmettre null comme valeur d'un sous-champ supprime ce sous-champ
    • Si aucun élément ne correspond dans le tableau, ou si les sous-champs ne respectent pas la définition de la propriété, le serveur renvoie un échec et ne modifie pas les autres éléments ; si plusieurs éléments correspondent, la même mise à jour est appliquée à tous les éléments correspondants.
    • Si cette propriété n'est pas encore définie, le serveur renvoie un échec (55004) ; si elle est définie mais que l'utilisateur actuel n'a pas encore de valeur pour cette propriété, le serveur renvoie code=0 sans effectuer de modification.
  • Exemple d'appel :

              
               // Met à jour city de l'élément dont l'id est home avec Tokyo, et supprime le sous-champ zip
 window.MAInterface.updateProperty("addresses", {$identifier_key:"id", $identifier_value:"home", $new_object:{city:"Tokyo", zip:null}}, (code, message)=>{})

            

• removeProperty(key, content, completion)
  • Description de l'interface :
    • Lorsque le deuxième paramètre est { $identifier_key, $identifier_value }, retire intégralement l'élément correspondant de l'object_array (si plusieurs éléments correspondent, tous les éléments correspondants sont retirés) ; content ne peut contenir que ces deux champs.
    • Les exigences relatives à $identifier_key et$identifier_value sont identiques à celles d'updateProperty.
    • Si cette propriété n'est pas encore définie, le serveur renvoie un échec (55004) ; si l'utilisateur actuel n'a pas de valeur pour cette propriété ou si aucun élément ne correspond, le serveur ignore cette requête et renvoie code=0 ; si plusieurs éléments correspondent, tous les éléments correspondants sont supprimés.
  • Exemple d'appel :

              
               // Retire l'élément dont l'id est office
 window.MAInterface.removeProperty("addresses", {$identifier_key:"id", $identifier_value:"office"}, (code, message)=>{})

            

Supprimer des propriétés utilisateur

Définition de l'interface

• deleteProperty(key, completion)
  • Description de l'interface :
    • Supprime tout le contenu des valeurs d'une propriété utilisateur.
    • Si cette propriété utilisateur n'existait pas auparavant, elle sera directement ignorée.

Exemple d'appel

              
               window.MAInterface.deleteProperty("key", (code, message)=>{})

            

Définir le délai d'expiration de la session

Définition de l'interface

• setSessionTimeout(time)
  • Description de l'interface :
    • Définit le délai d'expiration de la session. Lorsque la page passe en arrière-plan, le décompte du délai d'expiration de la session démarre. Si le temps défini (par défaut : 30 minutes) est dépassé, la session prendra fin.

Exemple d'appel

              
               window.MAInterface.setSessionTimeout(60)

            

Définir la durée de consultation de la page

Définition de l'interface

• setPageStayTime(time)
  • Description de l'interface :
    • Définit la durée de consultation de la page.
    • Le chronométrage commence après l'accès à la page. Si l'utilisateur reste sur la page pendant time secondes sans la quitter, cet événement sera remonté.
    • Par défaut, les remontées sont effectuées à 6 points temporels : 5 secondes, 30 secondes, 60 secondes, 2 minutes, 5 minutes et 10 minutes. Les développeurs peuvent appeler cette interface pour ajouter d'autres points temporels.

Exemple d'appel

              
               window.MAInterface.setPageStayTime(60)

            

Remonter des événements

Si un événement n'existe pas, il est remonté directement et il sera automatiquement créé en arrière-plan.

Définition de l'interface

• onEvent(event)
  • Description de l'interface :
    • Remonte un événement.
  • Description des paramètres
    • event : l'événement à remonter. name est le nom de l'événement, et properties contient les informations de propriété de l'événement, où la clé est le nom de la propriété et la valeur est la valeur de la propriété

Exemple d'appel

              
                 let event = {name:"name", properties:{key:"value"}}
    window.MAInterface.onEvent(event)