Захват форм в Customer Insights - Journeys

Статья
04/30/2024

Захват формы используется для получения данных из существующих форм, которые не были созданы с помощью редактора форм Customer Insights - Journeys. Захват формы рекомендуется использовать, если существующая форма также отправляет данные в системы, отличные от Dynamics 365, или если существующая форма содержит сложную логику, которую невозможно легко воссоздать в редакторе форм Customer Insights - Journeys. Если существующую форму можно воссоздать с помощью редактора форм Customer Insights - Journeys, не рекомендуется использовать функцию захвата формы.

Захват форм использует тот же API, что и стандартные формы для обработки отправок. То же уведомление о безопасности применяется и к захвату форм.

Важно

Для захвата форм требуется помощь разработчика. Всегда проще создать форму с помощью редактора форм Customer Insights - Journeys и встроить ее в существующую страницу.

Внимание

Для захвата формы требуется решение DynamicsMKT_Forms версии 1.1.35355 или выше. При подготовке пробного экземпляра вы не всегда будете получать последнюю версию автоматически. Прежде чем пытаться захватить форму, убедитесь, что вы обновили Customer Insights - Journeys.

Включите захват форм

По умолчанию функция захвата форм выключена. Вы можете включить переключатель Захват форм в Параметры>Переключатели функций>Формы.

Включите захват формы в переключателях функций.

Как работает захват формы

Захват формы имитирует отправку стандартной формы Customer Insights - Journeys. Чтобы связать отправку существующей формы с Customer Insights - Journeys, вам необходимо создать форму, используя редактор форм Customer Insights - Journeys. Опубликовав эту форму, вы можете получить сценарий захвата формы, который необходимо внедрить в веб-страницу, содержащую существующую форму. Сценарий включает определение сопоставления существующих полей формы с атрибутами сущности интереса или контакта. Вы можете просмотреть все отправленные данные и аналитику внутри Customer Insights - Journeys. Вы также можете использовать эту форму для координации взаимодействия с триггером Маркетинговая форма отправлена. С помощью отправки этой формы также можно создавать или обновлять согласие контактного лица и связанные с ним цели или темы.

Пошаговое руководство по захвату форм

Создание захвата формы в редакторе форм Customer Insights - Journeys

Чтобы создать новый сценарий захвата формы, перейдите к Customer Insights - Journeys>Каналы>Формы и выберите Создать на панели команд.
Назовите форму и выберите правильную аудиторию. Выбор целевой аудитории важен. Сопоставление "поле сценария захвата формы->атрибут" доступно только для атрибутов выбранной целевой аудитории (сущности).
Добавьте все поля, которые вы хотите сопоставить с существующими полями формы. Этот шаг не является обязательным; сопоставление поле > атрибут определяется в коде захвата формы. Добавление правильных полей в форму создает заполнители для сопоставления атрибутов в сценарии захвата формы, что упрощает определение сопоставления.
Добавьте в форму элементы согласия, такие как Цель или Тема, и настройте их. Узнайте, как управлять согласием на сообщения электронной почты и текстовые сообщения в Customer Insights - Journeys.

Внимание

Определение согласия должно быть сделано в редакторе форм. Изменения, внесенные в настройки согласия, сделанные во фрагменте кода захвата формы, будут игнорироваться.
Добавьте кнопку Отправить. Кнопка отправки необходима для успешной проверки формы перед публикацией.
Опубликуйте форму с помощью кнопку Опубликовать в правом верхнем углу экрана. Скопируйте фрагмент кода захвата формы и вставьте его на свою веб-страницу с существующей формой или передайте фрагмент кода своему разработчику. Фрагмент кода уже содержит ссылку на документацию с рекомендациями для разработчика.

Внимание

Доменное имя, на котором размещена существующая форма, должно быть разрешено для внешнего хостинга форм, иначе отправка формы не будет зафиксирована. Узнайте больше о проверке подлинности домена.

Встраивание сценария захвата на вашу страницу и определение сопоставления

Фрагмент кода, скопированный на предыдущем шаге, является шаблоном, и его необходимо адаптировать к конкретному варианту использования. Вам необходимо заменить все элементы, отмеченные как ***Please fill*** в сгенерированном шаблоне, и настроить логику в соответствии с вашим сценарием.

Отправка существующей формы передается в Customer Insights - Journeys с помощью API-интерфейса JavaScript, который определен в файле FormCapture.bundle.js и включен в фрагмент.

Настройка захвата формы состоит из следующих шагов:

Получите ссылку на элемент формы на странице.
Определите сопоставление полей формы с полями (атрибутами сущности) в Customer Insights - Journeys.
Определите сопоставление полей согласия в модели согласия в Customer Insights - Journeys.
Отправьте отправку формы в Customer Insights - Journeys.

1. Получите ссылку на элемент формы

Чтобы получить ссылку на элемент формы, вы можете использовать вспомогательную функцию waitForElement. Она также работает с динамически отображаемыми элементами и возвращает обещание, которое разрешается, как только элемент с данным селектором будет найден на странице. Для ссылки на селекторы CSS см. эту документацию.

Пример:

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

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

2. Определите сопоставление полей формы

Поля в форме необходимо сопоставить с соответствующими полями (атрибутами сущности) в Customer Insights - Journeys. Отображение определено в функции d365mktformcapture.serializeForm(form, mappings).

Пример:

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

Параметр form извлекается функцией waitForElement, описанной в предыдущем разделе. Параметр mappings представляет собой массив с элементами следующей структуры:

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
}

Функция синхронна и возвращает результат сериализации со следующим контрактом:

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
}

Убедитесь, что вы обрабатываете все ошибки, возвращаемые FormFieldMappingResults. Вы можете создать полезную нагрузку для Customer Insights - Journeys, вызвав метод serializedForm.SerializedForm.build().

2.1 Сопоставление полей набора параметров OptionSet

Для полей OptionSet вам необходимо определить сопоставление с соответствующим значением, которое должно храниться в Customer Insights - Journeys. Вы можете сопоставить значения полей OptionSet существующей формы в свойстве DataverseFieldValue.

Пример:

<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 Сопоставление полей поиска с подстановкой

Установка значения по умолчанию для поля подстановки

В логике сопоставления для полей поиска можно использовать статические значения (по умолчанию). Вам необходимо определить имя поля и значение, которое должно храниться в Customer Insights - Journeys.

Пример:

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

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

Сопоставление значения поля поиска с подстановкой с полем в форме

Вы также можете сопоставить значение поля поиска с подстановкой с соответствующим значением в существующем поле формы.

Пример:

<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 Сопоставление значений полей с множественным выбором

Для полей multi-select вам необходимо определить сопоставление с соответствующим значением, которое должно храниться в Customer Insights - Journeys. Вы можете сопоставить существующие значения полей с множественным выбором формы в свойстве DataverseFieldValue.

Пример:

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

Поля согласия необходимо настроить в редактор форм в Customer Insights - Journeys. Сопоставления DataverseFieldName и DataverseFieldValue генерируются автоматически соответственно.

Пример:

<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. Отправьте отправку формы в Customer Insights - Journeys

Получив ссылку на форму, определив сопоставления и сериализовав форму, вы можете добавить прослушиватель событий к событию submit и отправить его с помощью функции d365mktformcapture.submitForm(captureConfig, payload). Этот вызов возвращает обещание, а ошибки можно обрабатывать в логике catch.

Внимание

Если у вас есть пользовательская проверка или проверка Captcha, убедитесь, что вы отправляете форму в Customer Insights - Journeys только в случае успешной проверки (например, проверьте isDefaultPrevented на событие submit или явный вызывайте submitForm только после прохождения проверки)

Пример:

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

Устранение неполадок

Вызов конечной точки отправки завершается с ошибкой CORS

Совместное использование ресурсов между источниками (CORS) может привести к сбою захвата отправки формы. Включите свой домен для внешнего размещения форм. Узнайте больше о проверке подлинности домена.

Убедитесь, что вы настроили соответствующие поля согласия в редакторе форм (см. раздел Создание захвата формы в редакторе форм Customer Insights - Journeys) и использовали правильные сопоставления, созданные в процессе публикации.

Поделиться через

Захват форм в Customer Insights - Journeys

Включите захват форм

Как работает захват формы

Пошаговое руководство по захвату форм

Создание захвата формы в редакторе форм Customer Insights - Journeys

Встраивание сценария захвата на вашу страницу и определение сопоставления

1. Получите ссылку на элемент формы

2. Определите сопоставление полей формы

2.1 Сопоставление полей набора параметров OptionSet

2.2 Сопоставление полей поиска с подстановкой

Установка значения по умолчанию для поля подстановки

Сопоставление значения поля поиска с подстановкой с полем в форме

2.3 Сопоставление значений полей с множественным выбором

4. Отправьте отправку формы в Customer Insights - Journeys

Устранение неполадок

Вызов конечной точки отправки завершается с ошибкой CORS

Дополнительные ресурсы

Поделиться через

Захват форм в Customer Insights - Journeys

Включите захват форм

Как работает захват формы

Пошаговое руководство по захвату форм

Создание захвата формы в редакторе форм Customer Insights - Journeys

Встраивание сценария захвата на вашу страницу и определение сопоставления

1. Получите ссылку на элемент формы

2. Определите сопоставление полей формы

2.1 Сопоставление полей набора параметров OptionSet

2.2 Сопоставление полей поиска с подстановкой

Установка значения по умолчанию для поля подстановки

Сопоставление значения поля поиска с подстановкой с полем в форме

2.3 Сопоставление значений полей с множественным выбором

3. Определение сопоставления полей согласия

4. Отправьте отправку формы в Customer Insights - Journeys

Устранение неполадок

Вызов конечной точки отправки завершается с ошибкой CORS

Значения согласия обновляются неправильно

Дополнительные ресурсы