Extension manifest

Last update: April 2, 2025

Topics:
Tags

CREATED FOR:

Developer

NOTE

Adobe Experience Platform Launch has been rebranded as a suite of data collection technologies in Adobe Experience Platform. Several terminology changes have rolled out across the product documentation as a result. Please refer to the following document for a consolidated reference of the terminology changes.

In your extension’s base directory you must create a file called extension.json. This contains critical details about your extension that allows Adobe Experience Platform to properly consume it. Some of the contents are formed after the manner of npm’s package.json.

An example extension.json can be found the Hello World extension GitHub repository.

An extension manifest must consist of the following:

Property	Description
`name`	The name of your extension. It must be unique from all other extensions and must comply with naming rules. This is used by tags as an identifier and should not be changed after you publish your extension.
`platform`	The platform for your extension. The only value accepted at this moment is `web`.
`version`	The version of your extension. It must follow the semver versioning format. This is consistent with npm version field.
`displayName`	The human-readable name of your extension. This will be shown to Experience Platform users. There is no need to mention “tags” or “Extension”; users will already know they are looking at a tag extension.
`description`	The description of your extension. This will be shown to Experience Platform users. If your extension empowers users to implement your product on their website, describe what your product does. There is no need to mention “tags” or “Extension”; users will already know they are looking at a tag extension.
`iconPath` (Optional)	The relative path to the icon that will be displayed for the extension. It should not not begin with a slash. It must reference an SVG file with a `.svg` extension. The SVG should be square and may be scaled by Experience Platform.
`author`	The “author” is an object which should be structured as follows: `name`: The name of the extension author. Alternatively, the company name can be used here. `url` (Optional): A URL where you can find out more about the extension author. `email` (Optional): The email address of the extension author. This is consistent with npm author field rules.
`exchangeUrl` (Required for public extensions)	The URL to your extension’s listing on Adobe Exchange. It must match the pattern `https://www.adobeexchange.com/experiencecloud.details.######.html`.
`viewBasePath`	The relative path to the subdirectory containing all your views and view-related resources (HTML, JavaScript, CSS, images). Experience Platform will host this directory on a web server and load iframe content from it. This is a required field and should not start with a slash. For example, if all your views are contained within `src/view/`, the value of `viewBasePath` would be `src/view/`.
`hostedLibFiles` (Optional)	Many of our users prefer hosting all tags-related files on their own server. This provides users an increased level of certainty regarding file availability at runtime and they can easily scan the code for security vulnerabilities. If the library portion of your extension needs to load JavaScript files at runtime, it is recommended you use this property to list those files. The listed files will be hosted alongside the tag runtime library. Your extension can then load the files via a URL retrieved using the getHostedLibFileUrl method. This option contains an array with relative paths of 3rd party library files that need to be hosted.
`main` (Optional)	The relative path of a library module that should be executed at runtime. This module will always be included in the runtime library and executed. Because the module is always included in the runtime library, we recommend only using a “main” module when absolutely necessary and keeping its code size minimal. This module is not guaranteed to be executed first; other modules may be executed before it.
`configuration` (Optional)	This describes the extension configuration portion of the extension. This is necessary if you need users to provide global settings for the extension. See the appendix for details on how this field should be structured.
`events` (Optional)	An array of event type definitions. See the appendix section on type definitions for the structure of each object in the array.
`conditions` (Optional)	An array of condition type definitions. See the appendix section on type definitions for the structure of each object in the array.
`actions` (Optional)	An array of action type definitions. See the appendix section on type definitions for the structure of each object in the array.
`dataElements` (Optional)	An array of data element type definitions. See the appendix section on type definitions for the structure of each object in the array.
`sharedModules` (Optional)	An array of shared module definition objects. Each shared module object in the array should be structured as follows: `name`: The name of the shared module. Note that this name will be used when referencing shared modules from other extensions as described in Shared Modules. This name is never displayed in any user interface. It should be unique from the names of other shared modules within your extension and must comply with naming rules. This is used by tags as an identifier and should not be changed after you publish your extension. `libPath`: The relative path to the shared module. It should not not begin with a slash. It must reference a JavaScript file with a `.js` extension.

Appendix

Naming rules

The value of any name field within extension.json must comply with the following rules:

Must be less than or equal to 214 characters
Must not start with a dot or an underscore
Must not contain uppercase letters
Must only contain URL-safe characters

These are consistent with npm package name rules.

Configuration object properties

The configuration object should be structured as follows:

Property Description

viewPath The relative URL to the extension configuration view. It should be relative to viewBasePath and should not begin with a slash. It must reference an HTML file with a .html extension. Query string and fragment identifier (hashes) suffixes are acceptable.

Property	Description
`viewPath`	The relative URL to the extension configuration view. It should be relative to `viewBasePath` and should not begin with a slash. It must reference an HTML file with a `.html` extension. Query string and fragment identifier (hashes) suffixes are acceptable.
`schema`	An object of JSON Schema describing the format of a valid object being saved from the extension configuration view. Since you are the developer of the configuration view, it is your responsibility to ensure that any settings object saved matches this schema. This schema will also be used for validation when users attempt to save data using Experience Platform services. An example schema object is as follows: `{ "$schema": "http://json-schema.org/draft-04/schema#", "type": "object", "properties": { "delay": { "type": "number", "minimum": 1 } }, "required": [ "delay" ], "additionalProperties": false }` We recommend using a tool like JSON Schema validator to manually test your schema.
`transforms` (Optional)	An array of objects where each object represents a transformation that should be performed on every corresponding settings object when it is emitted into the runtime library. See the transforms section for more information on why this may be needed and how it is used.

schema

An object of JSON Schema describing the format of a valid object being saved from the extension configuration view. Since you are the developer of the configuration view, it is your responsibility to ensure that any settings object saved matches this schema. This schema will also be used for validation when users attempt to save data using Experience Platform services.

An example schema object is as follows:

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

We recommend using a tool like JSON Schema validator to manually test your schema.

transforms (Optional) An array of objects where each object represents a transformation that should be performed on every corresponding settings object when it is emitted into the runtime library. See the transforms section for more information on why this may be needed and how it is used.

Type definitions

A type definition is an object used to describe an event, condition, action, or data element type. The object consists of the following:

Property	Description
`name`	The name of the type. This must be a unique name within the extension. The name must comply with naming rules. This is used by tags as an identifier and should not be changed after you publish your extension.
`displayName`	The text that will be used to represent the type within the Data Collection user interface. It should be human-readable.
`categoryName` (Optional)	When provided, the `displayName` will be listed under the `categoryName` within the UI. All types with the same `categoryName` will be listed under the same category. For example, if your extension provided a `keyUp` event type and a `keyDown` event type and they both had a `categoryName` of `Keyboard`, both event types would be listed under the Keyboard category while the user is selecting from the list of available event types when building a rule. The value of `categoryName` should be human-readable.
`libPath`	The relative path to the type's library module. It should not not begin with a slash. It must reference a JavaScript file with a `.js` extension.
`viewPath` (Optional)	The relative URL to the type's view. It should be relative to `viewBasePath` and should not begin with a slash. It must reference an HTML file with a `.html` extension. Query strings and fragment identifiers (hashes) are acceptable. If your type's library module does not use any settings from a user, you may exclude this property and Experience Platform will instead display a placeholder stating that no configuration is necessary.
`schema`	An object of JSON Schema describing the format of a valid settings object that can be saved by the user. Settings are usually configured and saved by a user using the Data Collection user interface. In these cases, the extension's view can take necessary steps to validate user-provided settings. On the other hand, some users choose to use tags APIs directly without the aid of any user interface. The purpose of this schema is to allow Experience Platform to properly validate that settings objects saved by users, regardless of whether a user interface is used, are in a format that is compatible with the library module that will act upon the settings object at runtime. An example schema object is as follows: `{ "$schema": "http://json-schema.org/draft-04/schema#", "type": "object", "properties": { "delay": { "type": "number", "minimum": 1 } }, "required": [ "delay" ], "additionalProperties": false }` We recommend using a tool like JSON Schema validator to manually test your schema.
`transforms` (Optional)	An array of objects where each object represents a transformation that should be performed on every corresponding settings object when it is emitted into the runtime library. See the section on transforms for more information on why this may be needed and how it is used.

Transforms

For certain specific use cases, extensions need the settings objects saved from a view to be transformed by Experience Platform before they are emitted into the tag runtime library. You may request that one or more of these transforms take place by setting the transforms property when defining a type definition within your extension.json. The transforms property is an array of objects where each object represents a transformation that should take place.

All transforms require a type and a propertyPath. The type must be one of function, remove, and file and describes which transform Experience Platform should apply to the settings object. The propertyPath is a period-delimited string that tells tags where to find the property that needs to be modified within the settings object. Here is an example settings object and some propertyPaths:

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

If you set a propertyPath of foo.bar you would transform the "A string" value.
If you set a propertyPath of foo.baz[] you would transform each value in the baz array.
If you set a propertyPath of foo.baz you would transform the baz array.

Property paths can use any combination of array and object notation to apply transforms at any level of the settings object.

WARNING

Using array notation in the propertyPath attribute (e.g. foo.baz[]) is not yet supported in the extension sandbox*tool.

The sections below describe the available transformations and how to use them.

Function transform

The function transform allows code written by Experience Platform users to be executed by a library module within the emitted tag runtime library.

Let’s assume we would like to provide a “custom script” action type. The “custom script” action view might provide a textarea wherein the user can enter some code. Let’s assume a user entered the following code into the textarea:

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

When the user saves the rule, the settings object saved by the view may look like this:

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

When a rule using our action fires within the tag runtime library, we would like to execute the user’s code and pass it a username.

At the point that the settings object is saved from the action type’s view, the user’s code is simply a string. This is good because it can be properly serialized to and from JSON; however, it’s also bad because it would typically be emitted in the tag runtime library as a string as well instead of an executable function. Although you could attempt to execute the code within your action type’s library module using eval or a Function constructor, it is highly discouraged due to content security policies potentially blocking execution.

As a workaround for this situation, using the function transform tells Experience Platform to wrap the user’s code in a executable function when it is emitted in the tag runtime library. To solve our example problem, we would define the transform on the type definition in extension.json as follows:

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

type defines the type of transform that should be applied to the settings object.
propertyPath is a period-delimited string that tells Experience Platform where to find the property that needs to be modified within the settings object.
parameters is an array of parameter names that should be included in the wrapping function’s signature.

When the settings object is emitted in the tag runtime library, it will be transformed to the following:

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

Your library module can then call the function containing the user’s code and pass in the username argument.

File transform

The file transform allows code written by Experience Platform users to be emitted into a file separate from the tag runtime library. The file will be hosted alongside the tag runtime library and can then be loaded as needed by your extension at runtime.

Let’s assume we would like to provide a “custom script” action type. The action type’s view might provide a textarea wherein the user can enter some code. Let’s assume a user entered the following code into the textarea:

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

When the user saves the rule, the settings object saved by the view may look like this:

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

We would like the user’s code to be placed into a separate file instead of included inside in the tag runtime library. When a rule using our action fires within the tag runtime library, we would like to load the user’s code by appending a script element to the document body. To solve our example problem, we would define the transform on the action type definition in extension.json as follows:

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

type defines the type of transform that should be applied to the settings object.
propertyPath is a period-delimited string that tells Experience Platform where to find the property that needs to be modified within the settings object.

When the settings object is emitted in the tag runtime library, it will be transformed to the following:

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

In this case, the value of foo.bar has been transformed to a URL. The exact URL will be determined at the time the library is built. The file will always be given a .js extension and delivered using a JavaScript-oriented MIME type. We may add support for other MIME types in the future.

Remove transform

By default, all the properties of the settings object are emitted in the tag runtime library. If certain properties are only used for the extension view, especially if they contain sensitive information (eg. secret token), you should use the remove transform to prevent the information from being emitted into the tag runtime library.

Let’s assume we would like to provide a new action type. The action type’s view might provide an input wherein the user can enter a secret key that will allow connection to a specific API. Let’s assume a user entered the following text into the input:

ABCDEFG

When the user saves the rule, the settings object saved by the view may look like this:

{
  foo: {
    bar: "ABCDEFG"
  }
}

We would like to not include the property bar inside in the tag runtime library. To solve our example problem, we would define the transform on the action type definition in extension.json as follows:

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

type defines the type of transform that should be applied to the settings object.
propertyPath is a period-delimited string that tells Experience Platform where to find the property that needs to be modified within the settings object.

When the settings object is emitted in the tag runtime library, it will be transformed to the following:

{
  foo: {
  }
}

In this case, the value of foo.bar has been removed from the settings object.

recommendation-more-help