Vyer i webbtillägg
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:
settings
settings
är null
anger 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
settings
.propertySettings
tokens
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
orgId
, som i sin tur representerar ditt Adobe Experience Cloud-ID (en 24-siffrig alfanumerisk sträng).schema
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:
code
language
javascript
, html
, css
, json
och 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:
pattern
flags
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 2000
blir 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:
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.