Extension manifest

I tilläggets baskatalog måste du skapa filen extension.json. Detta innehåller viktig information om tillägget som gör att Adobe Experience Platform kan använda det korrekt. En del av innehållet formateras efter sättet för npm:s package.json.

Ett exempel extension.json finns i GitHub-databasen Hello World-tillägget.

Ett tilläggsmanifest måste bestå av följande:

Bilaga

Namngivningsregler naming-rules

Värdet för alla name-fält i extension.json måste följa följande regler:

Dessa är kompatibla med reglerna för npm-paketnamnet.

Egenskaper för konfigurationsobjekt config-object

Konfigurationsobjektet ska struktureras på följande sätt:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "delay": {
      "type": "number",
      "minimum": 1
    }
  },
  "required": [
    "delay"
  ],
  "additionalProperties": false
}

Typdefinitioner type-definitions

En typdefinition är ett objekt som används för att beskriva en händelse, ett villkor, en åtgärd eller en dataelementtyp. Objektet består av följande:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "delay": {
      "type": "number",
      "minimum": 1
    }
  },
  "required": [
    "delay"
  ],
  "additionalProperties": false
}

Omformningar transforms

För vissa specifika användningsområden behöver tillägg inställningsobjekten som har sparats från en vy omvandlas av plattformen innan de skickas till taggens körtidsbibliotek. Du kan begära att en eller flera av dessa omformningar äger rum genom att ange egenskapen transforms när du definierar en typdefinition i extension.json. Egenskapen transforms är en array med objekt där varje objekt representerar en omformning som ska utföras.

Alla omformningar kräver en type och en propertyPath. type måste vara en av function, remove och file och beskriver vilken transformeringsplattform som ska användas för inställningsobjektet. propertyPath är en periodavgränsad sträng som anger var taggar ska hitta den egenskap som behöver ändras i inställningsobjektet. Här är ett exempel på inställningsobjekt och några propertyPaths:

{
  foo: {
    bar: "A string",
    baz: [
      "A",
      "B",
      "C"
    ]
  }
}

Egenskapssökvägar kan använda valfri kombination av array- och objektnotation för att tillämpa omformningar på alla nivåer i inställningsobjektet.

Avsnitten nedan beskriver de tillgängliga omformningarna och hur de används.

Funktionsomformning

Funktionstransformeringen gör att kod som skrivits av plattformsanvändare kan köras av en biblioteksmodul i det utsända taggbiblioteket.

Låt oss anta att vi vill tillhandahålla en"anpassad manusåtgärd". Åtgärdsvyn för anpassade skript kan innehålla ett textområde där användaren kan ange kod. Låt oss anta att en användare har angett följande kod i textområdet:

console.log('Welcome, ' + username +'. This is ZomboCom.');

När användaren sparar regeln kan inställningsobjektet som sparas av vyn se ut så här:

{
  foo: {
    bar: "console.log('Welcome, ' + username +'. This is ZomboCom.');"
  }
}

När en regel som använder vår åtgärd utlöses i taggens körtidsbibliotek, vill vi köra användarens kod och skicka den till ett användarnamn.

När inställningsobjektet sparas från åtgärdstypens vy är användarens kod bara en sträng. Detta är bra eftersom det kan serialiseras till och från JSON, men det är också dåligt eftersom det vanligtvis skulle ha släppts som en sträng i taggens körningsbibliotek i stället för som en körbar funktion. Även om du kan försöka köra koden i åtgärdstypens biblioteksmodul med eval eller en funktionskonstruktor , rekommenderas det inte eftersom skyddsprofiler eventuellt blockerar körningen.

Som en tillfällig lösning på den här situationen kan du använda funktionsomformningen för att få Platform att kapsla in användarens kod i en körbar funktion när den släpps ut i taggens körningsbibliotek. För att lösa vårt exempelproblem definierar vi transformeringen för typdefinitionen i extension.json enligt följande:

{
  "transforms": [
    {
      "type": "function",
      "propertyPath": "foo.bar",
      "parameters": ["username"]
    }
  ]
}

När inställningsobjektet skickas i taggens körningsbibliotek omvandlas det till följande:

{
  foo: {
    bar: function(username) {
      console.log('Welcome, ' + username +'. This is ZomboCom.');
    }
  }
}

Din biblioteksmodul kan sedan anropa funktionen som innehåller användarens kod och skicka argumentet username.

Filomvandling

Med filtransformeringen kan kod som skrivits av plattformsanvändare skickas till en fil som är separat från taggens körningsbibliotek. Filen lagras tillsammans med taggens körtidsbibliotek och kan sedan läsas in efter behov av tillägget vid körning.

Låt oss anta att vi vill tillhandahålla en"anpassad manusåtgärd". Åtgärdstypens vy kan innehålla ett textområde där användaren kan ange kod. Låt oss anta att en användare har angett följande kod i textområdet:

console.log('This is ZomboCom.');

När användaren sparar regeln kan inställningsobjektet som sparas av vyn se ut så här:

{
  foo: {
    bar: "console.log('This is ZomboCom.');"
  }
}

Vi vill att användarens kod ska placeras i en separat fil i stället för att inkluderas i taggens körningsbibliotek. När en regel som använder vår åtgärd utlöses i taggens körtidsbibliotek, vill vi läsa in användarens kod genom att lägga till ett skriptelement i dokumentets brödtext. För att lösa vårt exempelproblem definierar vi transformeringen för åtgärdstypdefinitionen i extension.json enligt följande:

{
  "transforms": [
    {
      "type": "file",
      "propertyPath": "foo.bar"
    }
  ]
}

När inställningsobjektet skickas i taggens körningsbibliotek omvandlas det till följande:

{
  foo: {
    bar: "//launch.cdn.com/path/abc.js"
  }
}

I det här fallet har värdet foo.bar omvandlats till en URL. Den exakta URL:en bestäms när biblioteket skapas. Filen får alltid tillägget .js och levereras med en JavaScript-orienterad MIME-typ. Vi kan lägga till stöd för andra MIME-typer i framtiden.

Ta bort omformning

Som standard skickas alla egenskaper för inställningsobjektet i taggens körtidsbibliotek. Om vissa egenskaper bara används för tilläggsvyn, särskilt om de innehåller känslig information (t.ex. hemlig token) bör du använda omformningen remove för att förhindra att informationen skickas till taggens körningsbibliotek.

Låt oss anta att vi vill tillhandahålla en ny åtgärdstyp. Åtgärdstypens vy kan innehålla en inmatning där användaren kan ange en hemlig nyckel som tillåter anslutning till ett visst API. Låt oss anta att en användare har angett följande text i indata:

ABCDEFG

När användaren sparar regeln kan inställningsobjektet som sparas av vyn se ut så här:

{
  foo: {
    bar: "ABCDEFG"
  }
}

Vi vill inte inkludera egenskapen bar i taggens körningsbibliotek. För att lösa vårt exempelproblem definierar vi transformeringen för åtgärdstypdefinitionen i extension.json enligt följande:

{
  "transforms": [
    {
      "type": "remove",
      "propertyPath": "foo.bar"
    }
  ]
}

När inställningsobjektet skickas i taggens körningsbibliotek omvandlas det till följande:

{
  foo: {
  }
}

I det här fallet har värdet foo.bar tagits bort från inställningsobjektet.