Vyer i webbtillägg

NOTE
Adobe Experience Platform Launch har omklassificerats som en serie datainsamlingstekniker i Adobe Experience Platform. Som ett resultat av detta har flera terminologiska förändringar införts i produktdokumentationen. Se följande dokument för en konsoliderad hänvisning till terminologiska förändringar.

Varje händelse, villkor, åtgärd eller dataelementtyp kan innehålla en vy som gör att användaren kan ange inställningar. Tillägget kan också ha en översta nivå tilläggskonfigurationsvy som gör att användare kan ange globala inställningar för hela tillägget. Processen att skapa en vy är identisk för alla typer av vyer.

Inkludera en dokumenttyp

Var noga med att inkludera en doctype -taggen i din HTML-fil. Vanligtvis innebär det att du börjar din HTML-fil med följande:

<!DOCTYPE html>

Inkludera taggarnas iframe-skript

Inkludera taggar i iframe-skript i HTML i vyn:

<script src="https://assets.adobedtm.com/activation/reactor/extensionbridge/extensionbridge.min.js"></script>

Skriptet innehåller ett kommunikations-API som gör att vyn kan kommunicera med taggprogrammet.

Registrering med tilläggsbryggans kommunikations-API

När iframe-skriptet har lästs in måste du ange några metoder för taggar som det ska använda för kommunikation. Utlysning window.extensionBridge.register och skicka ett objekt enligt följande:

window.extensionBridge.register({
  init: function(info) {
    // Populate view with info.settings which will exist if the user is editing something
    // that was previously saved.
    if (info.settings) {
      document.getElementById('name').value = info.settings.name;
    }
  },
  validate: function() {
    // Return whether the view is valid.
    return document.getElementById('name').value.length > 0;
  },
  getSettings: function() {
    // Return user-provided settings.
    return {
      name: document.getElementById('name').value
    };
  }
});

Innehållet i varje metod måste ändras för att passa dina visningsbehov.

init

The init -metoden anropas av -taggar så snart vyn har lästs in i iframe-elementet. Det kommer att få ett argument (info) som måste vara ett objekt som innehåller följande egenskaper:

Egenskap
Beskrivning
settings
Ett objekt som innehåller inställningar som tidigare sparats från den här vyn. If settings är nullanger det att användaren skapar de ursprungliga inställningarna i stället för att läsa in en sparad version. If settings är ett objekt, bör du använda det för att fylla i vyn eftersom användaren väljer att redigera de tidigare beständiga inställningarna.
extensionSettings
Inställningar som har sparats från tilläggskonfigurationsvyn. Det här kan vara användbart för att komma åt tilläggsinställningar i vyer som inte är tilläggskonfigurationsvyn. Om den aktuella vyn är tilläggskonfigurationsvyn använder du settings.
propertySettings
Ett objekt som innehåller inställningar för egenskapen. Se turbinobjektguide om du vill ha information om vad som finns i det här objektet.
tokens
Ett objekt som innehåller API-token. Om du vill få åtkomst till Adobe-API:er inifrån vyn måste du vanligtvis använda en IMS-token under tokens.imsAccess. Den här variabeln blir bara tillgänglig för tillägg som utvecklats av Adobe. Om du är anställd i Adobe som representerar ett tillägg som skrivits av Adobe, vänligen skicka e-postmeddelanden till datainsamlingsteamet och ange namnet på tillägget så att det kan läggas till tillåtelselista.
company
Ett objekt som innehåller en enda egenskap, orgId, som i sin tur representerar ditt Adobe Experience Cloud-ID (en 24-siffrig alfanumerisk sträng).
schema
Ett objekt i JSON-schema format. Objektet kommer från tilläggsmanifest och kan vara till hjälp vid validering av formuläret.

Vyn bör använda den här informationen för att återge och hantera formuläret. Det är troligt att du bara behöver ta itu med info.settings, men övriga uppgifter lämnas om det skulle behövas.

validate

The validate -metoden anropas när användaren har kommit till knappen Spara. Den ska returnera något av följande:

  • Ett booleskt värde som anger om användarens indata är giltiga.
  • Ett löfte att senare matchas med ett booleskt värde som anger om användarens indata är giltiga.

Det är upp till dig som tilläggsutvecklare att avgöra vad som är giltiga indata eftersom din biblioteksmodul kommer att reagera på dessa indata.

Om användarens indata är ogiltiga, visa en indikation på detta i din vy så att användarna vet vad som behöver korrigeras.

getSettings

The getSettings -metoden anropas när användaren har kommit till knappen Spara och vyn har validerats. Funktionen ska returnera något av följande:

  • Ett objekt som innehåller inställningar baserade på användarindata.
  • Ett löfte att senare lösas med ett objekt som innehåller inställningar som baseras på användarindata.

Det här inställningsobjektet kommer senare att skickas i taggens körningsbibliotek. Objektets innehåll bestäms av dig. Objektet måste kunna serialiseras och avserialiseras till och från JSON. Värden som funktioner eller RegExp instanser uppfyller inte dessa kriterier och är därför inte tillåtna.

Utnyttja delade vyer

The window.extensionBridge -objektet har flera metoder som gör att du kan dra nytta av befintliga vyer som är tillgängliga via taggar så att du inte behöver återge dem i vyn. Följande metoder är tillgängliga:

openCodeEditor

window.extensionBridge.openCodeEditor().then(function(code) {
  console.log(code);
});

Om den här metoden anropas visas ett modalt kodfragment som gör att användaren kan redigera ett kodfragment. När användaren är klar med redigeringen av koden löses löftet med den uppdaterade koden. Om användaren stänger kodredigeraren utan att välja att spara ändringar kommer löftet aldrig att lösas. The options objektet ska struktureras på följande sätt:

Egenskap
Beskrivning
code
Kod som ska visas i redigeraren. Detta anges vanligtvis när användaren redigerar befintlig kod. Om detta inte anges kommer kodredigeraren att vara tom när den öppnas.
language
Språket för koden som ska redigeras. Giltiga alternativ är javascript, html, css, jsonoch plaintext. Om detta inte anges javascript antas.

openRegexTester

window.extensionBridge.openRegexTester().then(function(pattern) {
  console.log(pattern);
});

Om den här metoden anropas visas ett modalt uttryck som gör att användaren kan testa och ändra ett mönster för reguljära uttryck. När användaren har redigerat det reguljära uttrycket löses löftet med det uppdaterade mönstret för reguljära uttryck. Om användaren stänger regex-testaren utan att välja att spara ändringarna kommer löftet aldrig att lösas. The options ska innehålla följande egenskaper:

Egenskap
Beskrivning
pattern
Det reguljära uttrycksmönstret som ska användas som startvärde för mönsterfältet inuti provaren. Detta anges vanligtvis när användaren redigerar ett befintligt reguljärt uttryck. Om detta inte anges kommer mönsterfältet till att börja med att vara tomt.
flags
De flaggor för reguljära uttryck som ska användas av provaren. Som ett exempel gi skulle visa den globala matchningsflaggan och flaggan för ignorerade fall. Dessa flaggor kan inte ändras av användaren i testaren, men används för att demonstrera de specifika flaggor som tillägget kommer att använda när det reguljära uttrycket körs. Om detta inte anges kommer inga flaggor att användas i provaren. Se MDN:s RegExp-dokumentation om du vill ha mer information om flaggor för reguljära uttryck.

Ett vanligt scenario är ett tillägg som gör att användare kan växla skiftlägeskänslighet för ett reguljärt uttryck. För att detta ska fungera har tillägget vanligtvis en kryssruta i tilläggsvyn som, när den är markerad, aktiverar skiftlägesokänslighet (representeras av i -flagga). Inställningsobjektet som sparas av vyn måste representera om kryssrutan är markerad så att biblioteksmodulen som kör det reguljära uttrycket kan veta om den ska använda i flagga. När tilläggsvyn vill öppna det reguljära uttrycket måste den dessutom godkänna i flagga om kryssrutan för skiftlägeskänslighet är markerad. Detta gör att användaren kan testa det reguljära uttrycket med aktiverad skiftlägeskänslighet.

openDataElementSelector open-data-element

window.extensionBridge.openDataElementSelector().then(function(dataElement) {
  console.log(dataElement);
});

Om den här metoden anropas visas ett modalt element som gör att användaren kan välja ett dataelement. När användaren har valt ett dataelement kommer löftet att lösas med namnet på det valda dataelementet (namnet kommer som standard att omslutas av procenttecken). Om användaren stänger elementväljaren utan att välja att spara ändringar kommer löftet aldrig att lösas.

The options objektet ska innehålla en enda boolesk egenskap, tokenize. Den här egenskapen anger om namnet på det markerade dataelementet ska radbrytas i procent innan löftet löses. Se avsnittet om stödjande dataelement för varför detta är användbart. Standardinställningen är true.

Stöd för dataelement supporting-data-elements

Dina vyer har antagligen formulärfält där användarna vill utnyttja dataelement. Om vyn t.ex. innehåller ett textfält där användaren ska ange ett produktnamn, kan det vara svårt att skriva in ett hårdkodat värde i fältet. I stället kanske de vill att fältets värde ska vara dynamiskt (bestämmas vid körning) och kan uppnå detta genom att använda ett dataelement.

Anta till exempel att vi skapar ett tillägg som skickar en signal för att spåra en konvertering. Låt oss också anta att en av datadelarna som vi skickar är ett produktnamn. Vår tilläggsvy som gör att användaren kan konfigurera beacon har förmodligen ett textfält för produktnamnet. Det skulle vanligtvis inte vara särskilt vettigt för plattformsanvändaren att skriva in ett statiskt produktnamn som "Calzone Oven XL", eftersom produktnamnet troligtvis är beroende av sidan som beacon ska skickas från. Detta är ett bra exempel på ett dataelement.

Om en användare vill använda dataelementet med namnet productname för produktnamnsvärdet kan de skriva namnet på dataelementet med procenttecken på båda sidor (%productname%). Vi kallar ett procenttecken för ett dataelementnamn som en"dataelementtoken". Plattformsanvändare känner ofta till denna konstruktion. Tillägget sparar i sin tur dataelementstoken i settings objekt som exporteras. Inställningsobjektet kan då se ut så här:

{
  productName: '%productname%'
}

Innan inställningsobjektet skickas till biblioteksmodulen skannas inställningsobjektet och alla variabler för dataelement ersätts med deras respektive värden. Om vid körning är värdet för productname dataelementet var Ceiling Medallion Pro 2000blir inställningsobjektet som skulle skickas till din biblioteksmodul följande:

{
  productName: 'Ceiling Medallion Pro 2000'
}

För att ange var det kan vara praktiskt för användarna att använda dataelement och för att göra det enkelt för användarna att ange ett dataelement, rekommenderar vi att du lägger till en ikonknapp bredvid de fält som visas här:

dataelementfält

NOTE
Om du vill hämta rätt ikon går du till ikonsida i Adobe Spectrum och sök efterData".

När knappen bredvid textfältet är markerad av en användare, anropa window.extensionBridge.openDataElementSelector as ovan. Då visas en lista med användarens dataelement som användaren kan välja bland i stället för att tvinga användaren att komma ihåg tecknen för namn och procent. När användaren har valt ett dataelement får du namnet på det markerade dataelementet omgivet av procenttecken (om du inte har angett tokenize alternativ till false). Vi rekommenderar att du sedan fyller i textfältet med resultatet.

Ersätta dataelementstoken

Om ett beständigt inställningsobjekt består av följande:

{
  productName: '%productname%'
}

Vid körning är värdet för productname dataelement var Ceiling Medallion Pro 2000, blir inställningsobjektet som skickas till din biblioteksmodul följande:

{
  productName: 'Ceiling Medallion Pro 2000'
}

När ett värde i ett inställningsobjekt som består av ett procenttecken påträffas, kommer en sträng och sedan ett procenttecken, och inget mer, ersätts det av dataelementvärdet utan att ändra dataelementets värdetyp.

Om till exempel värdet för productname vid körning var i stället talet 538 (inte en sträng) blir inställningsobjektet som skickas till din biblioteksmodul följande:

{
  productName: 538
}

Observera att resultatet 538 är ett tal här och inte en sträng. Om dataelementvärdet vid körning var en funktion (ett sällsynt men möjligt användningsfall) blir det resulterande inställningsobjektet följande:

{
  productName: function() { … }
}

Å andra sidan antar vi att det beständiga inställningsobjektet var följande:

{
  productName: '%productname% - %modelnumber%'
}

I det här fallet beror det på productName är mer än en enda dataelementtoken, kommer resultatet alltid att vara en sträng. Varje dataelementtoken ersätts med sitt respektive värde efter att ha bytt till en sträng. Om vid körning är värdet för productname var Ceiling Medallion Pro (en sträng) och modelnumber var 2000 (ett tal) blir det inställningsobjekt som skickas till biblioteksmodulen:

{
  productName: 'Ceiling Medallion Pro - 2000'
}

Undvik navigering

Kommunikation mellan tilläggsvyn och det innehållande användargränssnittet för datainsamling är beroende av att ingen navigering sker i tilläggsvyn. Undvik därför att lägga till något i tilläggsvyn som skulle göra det möjligt för användaren att navigera bort från tilläggsvyns HTML-sida. Om du till exempel anger en länk i tilläggsvyn måste du se till att den öppnar ett nytt webbläsarfönster (vanligtvis genom att lägga till target="_blank" till ankartaggen). Om du väljer att använda en form i tilläggsvyn, se till att formuläret aldrig skickas. Om du har ett button element i formuläret och inte lägga till type="button" till den. Om du skickar ett formulär i tilläggsvyn kommer HTML-dokumentet att uppdateras, vilket resulterar i en trasig användarupplevelse.

recommendation-more-help
12b4e4a9-5028-4d88-8ce6-64a580811743