Registrer skjemaer i Customer Insights - Journeys

Skjemaregistreringen brukes til å hente innsendinger fra eksisterende skjemaer som ikke ble opprettet ved hjelp av skjemaredigeringsprogram for Customer Insights - Journeys. Skjemaregistrering anbefales hvis det eksisterende skjemaet ditt også sender innsendinger til andre systemer enn Dynamics 365, eller hvis det eksisterende skjemaet inneholder kompleks logikk som ikke enkelt kan gjenskapes i skjemaredigeringsprogrammet for Customer Insights - Journeys. Hvis det eksisterende skjemaet kan gjenskapes ved å bruke skjemaredigeringsprogrammet for Customer Insights - Journeys, anbefales det ikke å bruke skjemaregistreringsfunksjonen.

Skjemaregistrering bruker samme API som standardskjemaene til å behandle innsendinger. Det samme sikkerhetsvarselet gjelder for skjemaregistrering.

Aktiver skjemaregistrering

Funksjonen for skjemaregistrering er deaktivert som standard. Du kan aktivere veksleknappen Skjemaregistrering i Innstillinger>Funksjonsbrytere>Skjemaer.

Slik fungerer skjemaregistrering

Skjemaregistrering etterligner innsending av et standardskjema for Customer Insights - Journeys. Hvis du vil koble innsendinger av det eksisterende skjemaet til Customer Insights - Journeys, må du opprette et skjema ved å bruke skjemaredigeringsprogrammet for Customer Insights - Journeys. Når du har publisert skjemaet, kan du få et skjemaregistreringsskript, som må bygges inn i nettsiden som inneholder det eksisterende skjemaet. Skriptet inkluderer definisjonen av eksisterende skjemafelter som er tildelt attributter til enheten for potensiell kunde eller kontakt. Du kan se alle innsendinger og analyser i Customer Insights - Journeys. Du kan også bruke dette skjemaet i reiseiverksetting med Markedsføringsskjemaet innsendt-utløseren. Denne skjemainnsendingen kan også opprette eller oppdatere kontaktpunktsamtykke og relaterte formål eller emner.

Trinnvise veiledning for registrering av skjemaer

Opprett skjemaregistreringen i skjemaredigeringsprogrammet for Customer Insights - Journeys

1. Du oppretter et nytt registreringsskjemaskript ved å gå til Customer Insights - Journeys>Kanaler>Skjemaer og velg Ny på kommandolinje.

2. Gi skjemaet et navn og velg riktig målgruppe. Valget av målgruppe er viktig. Skjemaregistreringsskriptfeltet->attributtildeling er bare tilgjengelig for attributter til den valgte målgruppen (enhet).

3. Legg til alle felter du vil tilordne til eksisterende skjemafelter. Dette trinnet er ikke obligatorisk. Tilordning av felt > attributt defineres i skjemaregistreringskoden. Ved å legge til de riktige feltene i skjemaet genereres plassholdere for attributtildeling i skjemaregistreringsskriptet, noe som gjør tildelingsdefinisjonen enklere.

4. Legg til samtykkeelementer som Formål eller Emne i skjemaet og konfigurer dem. Finn ut mer om hvordan du administrerer samtykke for e-post og tekstmeldinger i Customer Insights - Journeys.

   Viktig

   Samtykkedefinisjonen må gjøres i skjemaredigeringsprogrammet. Endringer som gjøres i samtykkeinnstillinger som er gjort i kodesnutten for skjemaregistrering blir ignorert.

5. Legg til en Send-knapp. Send-knappen er nødvendig for vellykket validering av skjemaet før publisering.

6. Publiser skjemaet ved hjelp av Publiser-knappen øverst til høyre på skjermen. Kopier kodesnutten for skjemaregistrering og bygg inn kodesnutt på nettsiden med eksisterende skjema eller gi kodesnutten til utvikleren. Kodesnutten inneholder allerede en kobling til dokumentasjon for å gi veiledning til utvikleren.

   

   Viktig

   Domenenavnet der det eksisterende skjemaet er driftet, må være aktivert for ekstern skjemadrift, ellers blir ikke skjemainnsendingen registrert. Finn ut mer om domenegodkjenning.

Bygg inn registreringsskriptet på siden og kartleggingsdefinisjon

Kodesnutten som ble kopiert i forrige trinn, fungerer som en mal og må justeres til den spesifikke brukssaken. Du må erstatte alle elementer merket som ***Please fill***, i den genererte malen og justere logikken til scenarioet.

Den eksisterende skjemainnsendingen sendes til Customer Insights - Journeys ved hjelp av en JavaScript-API, som er definert i filen FormCapture.bundle.js og er inkludert i snutten.

Oppsettet for skjemaregistrering består av disse trinnene:

1. Få referansen til skjemaelementet på siden.
2. Definer tildelingen av skjemafelter på felter (enhetsattributter) i Customer Insights - Journeys.
3. Definer tildelingen av samtykkefelter på samtykkemodellen i Customer Insights - Journeys.
4. Send skjemainnsending til Customer Insights - Journeys.

1. Få en referanse til skjemaelementet

Hivs du få en referanse til skjemaelementet, kan du bruke waitForElement-hjelpefunksjon. Det fungerer også med dynamisk gjengitte elementer og returnerer et løfte som er løst når elementet med den gitte velgeren er funnet på siden. Hvis du vil ha en referanse av CSS-velgere, kan du se denne dokumentasjonen.

Eksempel:

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

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

2. Definer tildelingen av skjemafelter

Felter i skjemaet må tildeles de respektive feltene (enhetsattributter) i Customer Insights - Journeys. Tildelingen er definert i funksjonen d365mktformcapture.serializeForm(form, mappings).

Eksempel:

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

Parameteren form hentes av waitForElement-funksjonen beskrevet i forrige avsnitt. Parameteren mappings er en matrise med elementer av følgende 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
}

Funksjonen er synkron og returnerer serialiseringsresultatet med følgende 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
}

Pass på at du håndterer alle feil som returneres av FormFieldMappingResults. Du kan opprette nyttelasten til Customer Insights - Journeys ved å kalle opp serializedForm.SerializedForm.build().

2.1 Tildeling av OptionSet-felter

For OptionSet-felter må du definere tildelingen til den respektive verdien som skal lagres i Customer Insights - Journeys. Du kan tildele de eksisterende OptionSet-feltverdiene i DataverseFieldValue-egenskapen.

Eksempel:

<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 Tildeling av oppslagsfelter

Angi standardverdien for oppslagsfeltet

Du kan bare bruke statiske (standard) verdier i tilordningslogikken for oppslagsfelter. Du må definere navnet på feltet og verdien som skal lagres i Customer Insights - Journeys.

Eksempel:

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

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

Tilordne verdien av oppslagsfeltet til et felt i skjemaet ditt

Du kan også tilordne oppslagsfeltverdien til en respektiv verdi i det eksisterende skjemafeltet.

Eksempel:

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

For multi-select-felter må du definere tildelingen til den respektive verdien som skal lagres i Customer Insights - Journeys. Du kan tilordne flervalgsfeltverdier for eksisterende skjema i DataverseFieldValue-egenskapen.

Eksempel:

  <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. Definere felttilordning for samtykke

Samtykkefelter må konfigureres i skjemaredigeringsprogrammet i Customer Insights - Journeys. DataverseFieldName- og DataverseFieldValue-tildelingene blir automatisk generert tilsvarende.

Eksempel:

<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. Send skjemainnsending til Customer Insights - Journeys

Når du får en referanse til skjemaet, definerer tildelingene og serialiserer skjemaet, kan du legge til en hendelseslytter til submit-hendelsen og sende den ved hjelp av d365mktformcapture.submitForm(captureConfig, payload)-funksjonen. Dette oppkallet returnerer et løfte, og feil kan håndteres i catch-logikken.

Eksempel:

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

Feilsøking

Oppkallet til innsendingsendepunktet mislykkes med en CORS-feil

Cross-Origin Resource Sharing (CORS) kan føre til at skjemainnsending mislykkes. Aktiver domenet for ekstern skjemavertstjeneste. Finn ut mer om domenegodkjenning.

Samtykkeverdier er ikke oppdatert på riktig måte

Sørg for at du har konfigurert de respektive samtykkefeltene i skjemaredigeringsprogram (se Opprett skjemaregistreringen i skjemaredigeringsprogrammet for Customer Insights - Journeys) og at du har brukt de riktige tildelingene som er generert i publiseringsprosessen.