Capturer des formulaires dans Customer Insights - Journeys

La capture de formulaire est utilisée pour obtenir des soumissions à partir de formulaires existants qui n’ont pas été créés à l’aide de l’éditeur de formulaires Customer Insights - Journeys. La capture de formulaire est recommandée si votre formulaire existant envoie également des soumissions à des systèmes autres que Dynamics 365 ou si le formulaire existant contient une logique complexe qui ne peut pas être facilement recréée dans l’éditeur de formulaires Customer Insights - Journeys. Si le formulaire existant peut être recréé à l’aide de l’éditeur de formulaires Customer Insights - Journeys, il n’est pas recommandé d’utiliser la fonctionnalité de capture de formulaire.

La capture de formulaire utilise la même API que les formulaires standard pour traiter les soumissions. Le même avis de sécurité s’applique à la capture de formulaire.

Activer la capture de formulaire

La fonctionnalité de Capture formulaire est désactivée par défaut. Vous pouvez activer la bascule Capture de formulaire dans Paramètres>Commutateurs de fonctionnalités>Formulaires.

Comment fonctionne la capture de formulaire

La capture de formulaire imite la soumission d’un formulaire Customer Insights - Journeys standard. Pour lier les soumissions de votre formulaire existant dans Customer Insights - Journeys, vous devez créer un formulaire en utilisant l’éditeur de formulaires Customer Insights - Journeys. Une fois que vous avez publié ce formulaire, vous pouvez obtenir un script de capture de formulaire, qui doit être intégré à la page Web contenant votre formulaire existant. Le script inclut la définition des champs de formulaire existants mappés sur les attributs de l’entité prospect ou contact. Vous pouvez voir toutes les soumissions et analyses dans Customer Insights - Journeys. Vous pouvez également utiliser ce formulaire dans l’orchestration du parcours avec le déclencheur Formulaire marketing soumis. Cette soumission de formulaire peut également créer ou mettre à jour le consentement du point de contact et les objectifs ou sujets associés.

Guide pas à pas de capture de formulaires

Création de la capture de formulaire dans l’éditeur de formulaires Customer Insights - Journeys

1. Pour créer un script de formulaire de capture, accédez à Customer Insights - Journeys>Canaux>Formulaires et sélectionnez Nouveau sur la barre de commande.

2. Nommez le formulaire et choisissez l’audience adéquate. Le choix de l’audience cible est important. Le champ du script de capture de formulaire-> le mappage d’attributs est disponible uniquement pour les attributs de l’audience cible choisie (entité).

3. Ajoutez tous les champs que vous souhaitez mapper à vos champs de formulaire existants. Cette étape n’est pas obligatoire ; le mappage du champ > attribut est défini dans le code de capture du formulaire. L’ajout des bons champs dans le formulaire génère des espaces réservés pour le mappage d’attributs dans le script de capture de formulaire, ce qui facilite la définition du mappage.

4. Ajoutez des éléments de consentement comme Objectif ou Rubrique pour les former et les configurer. Apprenez-en plus sur comment gérer le consentement pour le courrier électronique et les SMS dans Customer Insights - Journeys.

   Important

   La définition du consentement doit se faire dans l’éditeur de formulaires. Les modifications apportées aux paramètres de consentement dans l’extrait de code de capture du formulaire seront ignorées.

5. Ajoutez un bouton Soumettre. Le bouton Soumettre est requis pour une validation réussie du formulaire avant la publication.

6. Publiez le formulaire avec le bouton Publier dans le coin supérieur droit de l’écran. Copiez l’extrait de code de capture du formulaire et intégrez l’extrait de code à votre page Web avec le formulaire existant ou remettez l’extrait de code à votre développeur. L’extrait de code comprend déjà un lien vers la documentation pour guider votre développeur.

   

   Important

   Le nom de domaine sur lequel votre formulaire existant est hébergé doit être activé pour l’hébergement de formulaire externe, sinon la soumission du formulaire ne sera pas capturée. En savoir plus sur l’authentification de domaine.

Intégration du script de capture dans votre page et définition de mappage

L’extrait de code copié à l’étape précédente sert de modèle et doit être ajusté au cas d’utilisation spécifique. Vous devez remplacer tous les éléments marqués comme ***Please fill*** dans le modèle généré et ajuster la logique à votre scénario.

Votre soumission de formulaire existante est envoyée à Customer Insights - Journeys en utilisant une API JavaScript, définie dans le fichier FormCapture.bundle.js et est incluse dans l’extrait.

La configuration de la capture de formulaire comprend les étapes suivantes :

1. Obtenez la référence à l’élément de formulaire sur la page.
2. Définissez le mappage des champs de formulaire sur les champs (attributs d’entité) dans Customer Insights - Journeys.
3. Définissez le mappage des champs de consentement sur le modèle de consentement dans Customer Insights - Journeys.
4. Envoyez la soumission de formulaire à Customer Insights - Journeys.

1. Obtenir une référence à l’élément de formulaire

Pour obtenir une référence à l’élément de formulaire, vous pouvez utiliser la fonction d’assistance waitForElement. Elle fonctionne également avec des éléments rendus dynamiquement et renvoie une promesse qui est résolue une fois que l’élément avec le sélecteur donné est trouvé sur la page. Pour une référence sur les sélecteurs CSS, consultez cette documentation.

Exemple :

<form id="form1">
...
</form>

<script>
d365mktformcapture.waitForElement("#form1").then(form => {
  ...
});
</script>

2. Définir le mappage des champs du formulaire

Les champs du formulaire doivent être mappés aux champs respectifs (attributs d’entité) dans Customer Insights - Journeys. Le mappage est défini dans la fonction d365mktformcapture.serializeForm(form, mappings).

Exemple :

<form id="form1">
  <p>FirstName: <input type="text" name="firstName"/></p>
</form>

<script>
d365mktformcapture.waitForElement("#form1").then(form => {
  const mappings = [
    {
      FormFieldName: "firstName",
      DataverseFieldName: "firstname",
    },
  ];

  ...
  
  const serializedForm = d365mktformcapture.serializeForm(form, mappings);
  // console.log(JSON.stringify(serializedForm)); // NOTE: enable for debugging
  const payload = serializedForm.SerializedForm.build();
});
</script>

Le paramètre form est récupéré par la fonction waitForElement décrite dans la section précédente. Le paramètre mappings est un tableau avec des éléments de la structure suivante :

export interface IFormFieldMapping {
    FormFieldName?: string; // name of form field
    DataverseFieldName: string; // name of field on Dynamics 365 side
    DataverseFieldValue?: string | IFormValueMapping[]; // optional - either a fixed value or a value mapping
}

export interface IFormValueMapping {
    FormValue: string; // form field value
    DataverseValue: string; // mapped value for that form field value that will be sent to Dynamics 365
}

La fonction est synchrone et renvoie le résultat de la sérialisation avec le contrat suivant :

export interface IFormSerializationResult {
    FormFieldMappingResults: IFormFieldMappingResult[]; // Status for each of the defined mappings
    SerializedForm: IFormSerializationBuilder; // The serialized form
}

export interface IFormFieldMappingResult {
    Mapping: IFormFieldMapping; // The defined mapping
    FormFieldMappingStatus: FormFieldMappingStatus; // Status of the mapping (see below for status values)
    Message: string; // Optional - an error/warning message for the mapping
}

export enum FormFieldMappingStatus {
    Success = 0,
    NotFound = 1,
    Error = 2
}

Assurez-vous de gérer toutes les erreurs renvoyées par le FormFieldMappingResults. Vous pouvez créer la charge utile pour Customer Insights - Journeys en appelant serializedForm.SerializedForm.build().

2.1 Mappage des champs OptionSet

Pour les champs OptionSet, vous devez définir le mappage avec la valeur respective qui doit être stockée dans Customer Insights - Journeys. Vous pouvez mapper les valeurs des champs OptionSet de votre formulaire existant dans la propriété DataverseFieldValue.

Exemple :

<form id="form1">
  <p>Radio: <input type="radio" name="radioInput" value="option1"/><input type="radio" name="radioInput" value="option2"/></p>
</form>

<script>
  ...
  const mappings = [
    {
        FormFieldName: "radioInput",
        DataverseFieldName: "dvradioInput",
        DataverseFieldValue: [ 
            { FormValue: "option1", DataverseValue: "1" }, 
            { FormValue: "option2", DataverseValue: "2" },
        ]
    },
  ];
  ...
</script>

2.2 Mappage de champs de recherche

Définir la valeur par défaut pour le champ de recherche

Vous pouvez utiliser uniquement des valeurs statiques (par défaut) dans la logique de mappage pour les champs de recherche. Vous devez définir le nom du champ et la valeur qui doit être stockée dans Customer Insights - Journeys.

Exemple :

<form id="form1">
  ...
</form>

<script>
  ...
  const mappings = [
    {
        DataverseFieldName: "currency",
        DataverseFieldValue: "{\"Id\":\"ffffd6c1-b32d-ee11-bdf3-6045bded6105\",\"LogicalName\":\"transactioncurrency\"}"
    },
  ];
  ...
</script>

Mapper la valeur du champ de recherche sur un champ de votre formulaire

Vous pouvez également mapper la valeur du champ de recherche à une valeur respective dans votre champ de formulaire existant.

Exemple :

<form id="form1">
  <p>Radio: <input type="radio" name="currency" value="usd"/><input type="radio" name="currency" value="eur"/></p>
</form>

<script>
  ...
  const mappings = [
    {
        FormFieldName: "currency",
        DataverseFieldName: "transactioncurrencyid",
        DataverseFieldValue: [ 
              { FormValue: "usd", DataverseValue: "{\"Id\":\"cd2cff48-08a3-ea11-a813-000d3a0a82b4\",\"LogicalName\":\"transactioncurrency\"}", }, 
              { FormValue: "eur", DataverseValue: "{\"Id\":\"91f1a052-259c-4719-a3ae-3a1d2987a3ed\",\"LogicalName\":\"transactioncurrency\"}", }, 
        ]
    },
  ];
  ...
</script>

2.3 Mappage des valeurs des champs à sélection multiple

Pour les champs multi-select, vous devez définir le mappage avec la valeur respective qui doit être stockée dans Customer Insights - Journeys. Vous pouvez mapper les valeurs des champs à Sélectionner plusieurs de votre formulaire existant dans la propriété DataverseFieldValue.

Exemple :

  <form id="form1">
    <p>Fieldset: <fieldset name="multiOptionInput">
      <input type="checkbox" name="multiOptionInput" value="100000000">0</input>
      <input type="checkbox" name="multiOptionInput" value="100000001">1</input>
      <input type="checkbox" name="multiOptionInput" value="100000002">2</input>
    </fieldset></p>
  </form>
 
<script>
...
const mappings = [
  {
    FormFieldName: "multiOptionInput",
    DataverseFieldName: "dvmultiOptionInput",
    DataverseFieldValue: [
      { FormValue: "100000000", DataverseValue: "0" },
      { FormValue: "100000001", DataverseValue: "1" },
      { FormValue: "100000002", DataverseValue: "2" },
    ]
  },
];
...
</script>

3. Définir le mappage des champs de consentement

Les champs de consentement doivent être configurés dans le éditeur de formulaires dans Customer Insights - Journeys. Les mappages DataverseFieldName et DataverseFieldValue sont générés automatiquement en conséquence.

Exemple :

<form id="form1">
  <p>Consent: <input type="checkbox" name="consentField"/></p>
</form>

<script>
  ...
  const mappings = [
    {
        FormFieldName: "consentField",
        DataverseFieldName: "msdynmkt_purposeid;channels;optinwhenchecked",
        DataverseFieldValue: "10000000-0000-0000-0000-000000000004;Email;true",
    },
  ];
  ...
</script>

4. Envoyer la soumission de formulaire à Customer Insights - Journeys

Une fois que vous avez obtenu une référence au formulaire, défini les mappages et sérialisé le formulaire, vous pouvez ajouter un écouteur d’événement à l’submitévénement et l’envoyer à l’aide de la fonction d365mktformcapture.submitForm(captureConfig, payload). Cet appel renvoie une promesse et les erreurs peuvent être gérées dans la logique catch.

Exemple :

<form id="form1">
  <p>FirstName: <input type="text" name="firstName"/></p>
</form>

<script>
d365mktformcapture.waitForElement("#form1").then(form => {
  const mappings = [
    {
      FormFieldName: "firstName",
      DataverseFieldName: "firstname",
    },
  ];

  form.addEventListener("submit", (e) => {
    const serializedForm = d365mktformcapture.serializeForm(form, mappings);
    // console.log(JSON.stringify(serializedForm)); // NOTE: enable for debugging
    const payload = serializedForm.SerializedForm.build();

    const captureConfig = {
      FormId: "...", // the form id on Dynamics 365 side
      FormApiUrl: "..." // the API url of the Dynamics 365 backend service where the form will be submitted to
    }
    d365mktformcapture.submitForm(captureConfig, payload)
    .catch(e => {
      // error handling
    });
  }, true);
});
</script>

Résolution des problèmes

L’appel à la soumission point de terminaison échoue avec une erreur CORS

Le partage de ressources cross-origine (CORS) peut entraîner l’échec de la capture de soumission de formulaire. Activez votre domaine pour l’hébergement de formulaire externe. En savoir plus sur l’authentification de domaine.

Les valeurs de consentement ne sont pas mises à jour correctement

Assurez-vous d’avoir configuré les champs de consentement respectifs dans le éditeur de formulaires (voir la section Création de la capture de formulaire dans l’éditeur de formulaires Customer Insights - Journeys) et d’avoir utilisé le bon mappages générés lors du processus de publication.