Insamlingsformulär i Customer Insights - Journeys

Formulärinsamlingen används för att hämta inskick från befintliga formulär som inte skapades med Customer Insights - Journeys formulärredigerare. Formulärinsamling rekommenderas om ditt befintliga formulär också skickar inlämningar till andra system än Dynamics 365 eller om det befintliga formuläret innehåller komplex logik som inte enkelt kan återskapas i Customer Insights - Journeys formulärredigerare. Om det befintliga formuläret kan återskapas med Customer Insights - Journeys formulärredigerare, är det inte rekommenderat att använda formulärinsamlingsfunktionen.

Formulärinsamling använder samma API som standardformulären för att behandla inlämningar. Samma säkerhetsmeddelande gäller för insamlingsformulär.

Aktivera insamlingsformulär

Funktionen insamlingsformulär inaktiveras som standard. Du kan aktivera växlingen Insamlingsformulär i Inställningar>Funktionsväxlare>Formulär.

Hur formulärinsamling fungerar

Formulärinsamling efterliknar inlämning av ett Customer Insights - Journeys standardformulär. För att länka inlämningar av ditt befintliga formulär till Customer Insights - Journeys måste du skapa ett formulär med Customer Insights - Journeys formulärredigerare. När du har publicerat det formuläret kan du skaffa ett formulärinsamlingsskript, som måste bäddas in på webbsidan som innehåller ditt befintliga formulär. Skriptet inkluderar definitionen av befintliga formulärfältsmappningar på attributen för lead- eller kontaktentiteten. Du kan se alla inlämningar och analyser i Customer Insights - Journeys. Du kan också använda det här formuläret i orkestrering av resan med utlösaren Marknadsföringsformuläret skickat. Detta formulär kan också skapa eller uppdatera samtycke till kontaktpunkt och relaterade syften eller ämnen.

Steg-för-steg-guide till insamling av formulär

Skapar formulärinsamlingen i Customer Insights - Journeys formulärredigerare

1. För att skapa ett nytt skript för insamling av formulär, gå till Customer Insights - Journeys>Kanaler>Formulär och välj Ny på kommandofältet.

2. Namnge formuläret och välj rätt målgrupp. Valet av målgrupp är viktigt. Fältet för skript för insamling av formulär->attributmappning är endast tillgänglig för attribut för den valda målgruppen (entitet).

3. Lägg till alla fält som du vill mappa till de befintliga formulärfälten. Det här steget är inte obligatoriskt; fält > attribut mappning definieras för formulärinhämtning. Om du lägger till de rätta fälten i formuläret genereras platshållare för attributmappning i skriptet för insamling av formulär, vilket gör mappningsdefinitionen enklare.

4. Lägg till samtyckeselement som Purpose eller ämne för att skapa och konfigurera dem. Lär dig hur du hanterar samtycke för e-post och textmeddelanden i Customer Insights - Journeys.

   Viktigt!

   Definitionen av samtycke måste göras i formulärredigerare. Ändringar av samtyckesinställningar som görs i kodavsnittet för formulärinsamling kommer att ignoreras.

5. Lägg till en knapp för Skicka. Skicka-knappen krävs för framgångsrik validering av formuläret innan publicering.

6. Publicera formuläret med hjälp av knappen Publicera i det övre högra hörnet av skärmen. Kopiera kodavsnittet för formulärinsamling och bädda in kodavsnittet på din webbsida med befintligt formulär eller lämna över kodavsnittet till din utvecklare. Kodavsnittet innehåller redan en länk till dokumentation för att ge vägledning till din utvecklare.

   

   Viktigt!

   Domännamnet där ditt befintliga formulär är värd måste vara aktiverat för extern formulärvärd, annars kommer formulärinlämningen inte att samlas in. Läs mer om domän autentisering.

Bädda in insamlingsskriptet på din sida och mappningsdefinition

Kodavsnittet som kopierades i föregående steg är en mall och måste anpassas till det specifika användningsfallet. Du måste byta ut alla element markerade som ***Please fill*** i den genererade mallen och anpassa logiken till ditt scenario.

Ditt befintliga formulär skickas till Customer Insights - Journeys med hjälp av ett JavaScript API, som definieras i filen FormCapture.bundle.js och ingår i kodavsnittet.

Inställningen för formulärinsamling består av dessa steg:

1. Hämta referensen till formulärelementet på sidan.
2. Definiera mappningen av formulärfält på fält (entitetsattribut) i Customer Insights - Journeys.
3. Definiera mappningen av samtyckesfält på samtyckesmodellen i Customer Insights - Journeys.
4. Skicka formuläret till Customer Insights - Journeys.

1. Få en referens till formulärelementet

För att få en referens till formulärelementet kan du använda waitForElement hjälparfunktion. Det fungerar också med dynamiskt renderade element och returnerar ett löfte som löses när elementet med den givna väljaren hittas på sidan. För en referens av CSS-väljare, se detta dokumentation.

Exempel:

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

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

2. Definiera mappningen av formulärfält

Fält i formuläret måste mappas till respektive fält (entitetsattribut) i Customer Insights - Journeys. Mappningen definieras i funktionen d365mktformcapture.serializeForm(form, mappings).

Exempel:

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

Parametern form hämtas av waitForElement funktionen som beskrivs i föregående avsnitt. Parametern mappings är en matris med element av följande struktur:

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
}

Funktionen är synkron och returnerar serialiseringsresultatet med följande kontrakt:

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
}

Se till att du hanterar alla fel som returneras av FormFieldMappingResults. Du kan skapa nyttolasten till Customer Insights - Journeys genom att anropa serializedForm.SerializedForm.build().

2.1 Mappning av OptionSet-fält

För OptionSet-fält måste du definiera mappningen till respektive värde som ska lagras i Customer Insights - Journeys. Du kan mappa dina befintliga OptionSet-fältvärden i DataverseFieldValue egenskapen.

Exempel:

<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 Mappning av uppslagsfält

Ställ in standardvärdet för uppslagsfältet

Du kan använda statiska (standard) värden i mappningslogiken för uppslagsfält. Du måste definiera namnet på fältet och värdet som ska lagras i Customer Insights - Journeys.

Exempel:

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

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

Mappa värdet för uppslagsfältet till ett fält i ditt formulär

Du kan också mappa uppslagsfältets värde till ett respektive värde i ditt befintliga formulärfält.

Exempel:

<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 Mappa fältvärden med flera alternativ

För multi-select-fält måste du definiera mappningen till respektive värde som ska lagras i Customer Insights - Journeys. Du kan mappa befintliga fältvärden med flera alternativ i formuläret i DataverseFieldValue-egenskapen.

Exempel:

  <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. Definiera mappning av godkännandefält

Samtyckesfält måste konfigureras i formulärredigerare i Customer Insights - Journeys. Mappningarna DataverseFieldName och DataverseFieldValue är autogenererade i enlighet med detta.

Exempel:

<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. Skicka formuläret till Customer Insights - Journeys

När du har fått en referens till formuläret, definierat mappningarna och serialiserat formuläret kan du lägga till en händelseavlyssnare till submit händelsen och skicka den med funktionen d365mktformcapture.submitForm(captureConfig, payload). Detta anrop returnerar ett löfte och fel kan hanteras i catch-logiken.

Exempel:

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

Felsökning

Anropet till inlämningsslutpunkt misslyckas med ett CORS-fel

Resursdelning med flera ursprung (CORS) kan göra att formulärinlämning misslyckas. Aktivera din domän för extern formulärvärd. Läs mer om domän autentisering.

Samtyckesvärden har inte uppdaterats korrekt

Se till att du har ställt in respektive samtyckesfält i formulärredigerare (se Skapa formulärinsamlingen i Customer Insights - Journeys formulärredigerare) och använd rätt mappningar som genereras i publiceringsprocessen.