Extension manifest

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:

Appendix

Naming rules naming-rules

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

These are consistent with npm package name rules.

Configuration object properties config-object

The configuration object should be structured as follows:

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

Type definitions 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:

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

Transforms transforms

For certain specific use cases, extensions need the settings objects saved from a view to be transformed by 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 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"
    ]
  }
}

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

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

Function transform

The function transform allows code written by 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 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"]
    }
  ]
}

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 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"
    }
  ]
}

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"
    }
  ]
}

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.