Compartir por

Capturar formularios en Customer Insights - Journeys

  • Artigo

A captura de formularios utilízase para obter envíos de formularios existentes que non se crearon mediante o Customer Insights - Journeys editor de formularios. Recoméndase a captura de formularios se o formulario existente tamén envía envíos a sistemas distintos de Dynamics 365 ou se o formulario existente contén lóxica complexa que non se pode recrear facilmente no Customer Insights - Journeys editor de formularios. Se se pode recrear o formulario existente usando Customer Insights - Journeys editor de formularios, non se recomenda utilizar a función de captura de formularios.

A captura de formularios usa a mesma API que os formularios estándar para procesar os envíos. O mesmo aviso de seguridade aplícase á captura de formularios.

Importante

A captura de formularios require asistencia do programador. Sempre é máis doado crear un formulario usando o Customer Insights - Journeys editor de formularios e incorporalo na túa páxina existente.

Importante

A captura de formularios require a versión da solución de DynamicsMKT_Forms 1.1.35355 ou superior. Ao aprovisionar unha instancia de proba, non sempre terá a versión máis recente automaticamente. Asegúrate de ter actualizado Customer Insights - Journeys antes de tentar capturar formularios.

Activa a captura de formularios

A función de captura de formularios está desactivada por defecto. Podes activar a Captura de formularios activar Configuración>Conmutadores de funcións>Formularios.

Activa a captura de formularios nos interruptores de funcións.

Como funciona a captura de formularios

A captura de formularios imita o envío dun Customer Insights - Journeys formulario estándar. Para vincular os envíos do teu formulario existente a Customer Insights - Journeys, tes que crear un formulario usando o Customer Insights - Journeys editor de formularios. Unha vez que publiques ese formulario, podes obter un script de captura de formularios, que debes inserir na páxina web que contén o teu formulario existente. O script inclúe a definición da asignación de campos de formulario existentes nos atributos da entidade de contacto ou cliente potencial. Podes ver todos os envíos e análises dentro de Customer Insights - Journeys. Tamén podes usar este formulario na orquestración de viaxes co activador Formulario de marketing enviado . Este formulario tamén pode crear ou actualizar o consentimento do punto de contacto e os fins ou temas relacionados.

Guía paso a paso para capturar formularios

Creando a captura de formulario no Customer Insights - Journeys editor de formularios

  1. Para crear un novo script de formulario de captura, vai a Customer Insights - Journeys>Canles>Formularios e selecciona Novo na barra de comandos.

  2. Nomea o formulario e escolle o público axeitado. A elección do público obxectivo é importante. O campo do script de captura de formulario->asignación de atributos só está dispoñible para os atributos do público obxectivo escollido (entidade).

  3. Engade todos os campos que queres asignar aos teus campos de formulario existentes. Este paso non é obrigatorio; a campo > a asignación de atributos defínese no código de captura do formulario. Engadir os campos correctos ao formulario xera marcadores de posición para a asignación de atributos no script de captura de formularios, facilitando a definición da asignación.

  4. Engade elementos de consentimento como Propósito ou Tema para formalos e configuralos. Obtén máis información sobre como xestionar o consentimento das mensaxes de correo electrónico e de texto en Customer Insights - Journeys.

    Importante

    A definición de consentimento debe facerse no editor de formularios. Ignoraranse os cambios realizados na configuración de consentimento no formulario de captura fragmento de código.

  5. Engade un botón Enviar . O botón enviar é necesario para a validación exitosa do formulario antes de publicalo.

  6. Publica o formulario mediante o botón Publicar , situado na esquina superior dereita da pantalla. Copia a captura de formulario fragmento de código e incrusta o fragmento de código na túa páxina web co formulario existente ou entrégalle o fragmento de código ao teu programador. O fragmento de código xa inclúe unha ligazón á documentación para guiar ao teu programador.

    Engade o elemento de consentimento ao formulario.

    Importante

    O nome de dominio onde está aloxado o formulario existente ten que estar habilitado para aloxamento externo de formularios, se non, o envío do formulario non se capturará. Obtén máis información sobre a autenticación de dominios.

Incorporando o script de captura na súa páxina e definición de mapeo

O fragmento de código copiado no paso anterior é un modelo e debe axustarse ao caso de uso específico. Debe substituír todos os elementos marcados como ***Please fill*** no modelo xerado e axustar a lóxica ao seu escenario.

A súa presentación de formulario existente envíase a Customer Insights - Journeys través dunha API de JavaScript, definida no ficheiro FormCapture.bundle.js e incluída no fragmento.

A configuración de captura de forma consta destes pasos:

  1. Obtén a referencia ao elemento formulario na páxina.
  2. Definir a cartografía dos campos de formulario sobre campos (atributos de entidade) en Customer Insights - Journeys.
  3. Definir a cartografía dos campos de consentimento sobre o modelo de consentimento en Customer Insights - Journeys.
  4. Enviar o formulario de envío a Customer Insights - Journeys.

1. Obter unha referencia ao elemento de forma

Para obter unha referencia ao elemento de formulario, pode usar a waitForElement función de axudante. Tamén funciona con elementos renderizados dinámicamente e devolve unha promesa que se resolve unha vez que o elemento co selector dado se atopa na páxina. Para unha referencia de CSS selectores, consulte esta documentación.

Exemplo:

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

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

2. Definir a cartografía dos campos de formulario

Os campos do formulario deben ser mapeados nos respectivos campos (atributos de entidade) en Customer Insights - Journeys. A cartografía está definida na función d365mktformcapture.serializeForm(form, mappings).

Exemplo:

<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>

O parámetro form é recuperado waitForElement pola función descrita no apartado anterior. O parámetro mappings é un conxunto con elementos da seguinte estrutura:

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
}

A función é síncrona e devolve o resultado de serialización co seguinte contrato:

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
}

Asegúrese de xestionar todos os erros devoltos pola mesma FormFieldMappingResults. Podes crear a carga útil a Customer Insights - Journeys través de chamadas serializedForm.SerializedForm.build().

2.1 Mapa dos campos de OptionSet

Para OptionSet os campos, cómpre definir a cartografía ao valor respectivo que se debe almacenar Customer Insights - Journeys. Podes mapear o teu formulario existente OptionSet valores de DataverseFieldValue campos na propiedade.

Exemplo:

<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 Mapa de campos de busca
Configurar o valor predeterminado para o campo de busca

Podes usar valores estáticos (por defecto) na lóxica de mapas para campos de busca. Hai que definir o nome do campo e o valor que se debe almacenar Customer Insights - Journeys.

Exemplo:

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

<script>
  ...
  const mappings = [
    {
        DataverseFieldName: "currency",
        DataverseFieldValue: "{\"Id\":\"ffffd6c1-b32d-ee11-bdf3-6045bded6105\",\"LogicalName\":\"transactioncurrency\"}"
    },
  ];
  ...
</script>
Mapea o valor do campo de busca a un campo da túa forma

Tamén podes mapear o valor de campo de busca a un valor respectivo no teu campo de formulario existente.

Exemplo:

<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 Mapeando valores de campo multiseleccionados

Para multi-select os campos, cómpre definir a cartografía ao valor respectivo que se debe almacenar Customer Insights - Journeys. Podes mapear o teu formulario existente valores de campo multiseleccionados DataverseFieldValue na propiedade.

Exemplo:

  <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>

Os campos de consentimento deben configurarse nos editor de formularios in Customer Insights - Journeys. Os DataverseFieldName mapas e DataverseFieldValue mapas son autoxenerados en consecuencia.

Exemplo:

<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. Enviar o formulario de presentación a Customer Insights - Journeys

Unha vez que obteñas unha referencia ao formulario, definir os mapas e serializar o formulario, podes engadir un oínte de eventos ao submit evento e envialo usando a d365mktformcapture.submitForm(captureConfig, payload) función. Esta chamada devolve unha promesa, e os catch erros pódense manexar na lóxica.

Importante

Se tes unha validación personalizada no lugar ou unha comprobación Captcha, asegúrese de enviar o formulario só en Customer Insights - Journeys caso de validación exitosa (por exemplo, comprobe isDefaultPrevented o submit evento ou chame submitForm explicitamente só despois dos pases de validación)

Exemplo:

<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>

Resolución de problemas

A chamada ao punto final de presentación falla cun erro CORS

A compartición de recursos de orixe cruzada (CORS) pode causar que a captura de envío falle. Habilitar o seu dominio para o aloxamento de formularios externos. Obtén máis información sobre a autenticación de dominios.

Asegúrese de configurar os respectivos campos de consentimento no editor de formularios (consulte Crear a captura do formulario en Customer Insights - Journeys editor de formularios) e que usou os mapas correctos xerados no proceso de publicación.