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 Launch 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 in our Hello World extension.

An extension.json must consist of the following:

  • name (required)

    The name of your extension. It must be unique from all other Reactor extensions and must comply with naming rules. This is used by Launch as an identifier and should not be changed after you publish your extension.

  • platform (required)

    The platform for your extension. The only value accepted at this moment is web.

  • version (required)

    The version of your extension. It must follow the semver versioning format. This is consistent with npm version field.

  • displayName (required)

    The human-readable name of your extension. This will be shown to users of Launch. There is no need to mention “Launch” or “Extension”; users will already know they are looking at a Launch extension.

  • description (required)

    The description of your extension. This will be shown to users of Launch. If your extension empowers users to implement your product on their website, describe what your product does. There is no need to mention “Launch” or “Extension”; users will already know they are looking at a Launch extension.

  • iconPath

    The relative path to the icon that will be displayed for the extension within Launch. 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 Launch.

  • author (required)

    The “author” is an object which should be structured as follows:

    • name (required)

      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 (optional)

    The URL to your extension’s listing on Adobe Exchange. It must match the pattern https://www.adobeexchange.com/experiencecloud.details.######.html.

  • viewBasePath (required)

    The relative path to the subdirectory containing all your views and view-related resources (HTML, JavaScript, CSS, images). Launch 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 Launch-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 Launch 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. The configuration object should be structured as follows:

    • viewPath (required)

      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 (required)

      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 Launch 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.

  • events (optional)

    An array of event type definitions. See the type definition section for the structure of each object in the array.

  • conditions (optional)

    An array of condition type definitions. See the type definition section for the structure of each object in the array.

  • actions (optional)

    An array of action type definitions. See the type definition section for the structure of each object in the array.

  • dataElements (optional)

    An array of data element type definitions. See the type definition section 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 (required)

      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 Launch as an identifier and should not be changed after you publish your extension.

    • libPath (required)

      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.

Type Definition

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

  • name (required)

    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 Launch as an identifier and should not be changed after you publish your extension.

  • displayName (required)

    The text that will be used to represent the type within the Launch user interface. It should be human-readable.

  • categoryName (optional)

    When provided, the displayName will be listed under the categoryName within the Launch 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 (required)

    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 Launch will instead display a placeholder stating that no configuration is necessary.

  • schema (required)

    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 Launch 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 Launch APIs directly without the aid of any user interface. The purpose of this schema is to allow Launch 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 Transforming Settings Objects section for more information on why this may be needed and how it is used.

Transforming Settings Objects

For certain specific use cases, extensions need the settings objects saved from a view to be transformed by Launch before they are emitted into the Launch runtime library. You may request that one or more of these transformations 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. Below are the available transformations and how to use them.

Function Transform

The function transform allows code written by Launch users to be executed by a library module within the emitted Launch 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 Launch 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 Launch 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 Launch to wrap the user’s code in a executable function when it is emitted in the Launch 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 Launch 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 Launch 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 Launch users to be emitted into a file separate from the Launch runtime library. The file will be hosted alongside the Launch 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 Launch runtime library. When a rule using our action fires within the Launch 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 Launch where to find the property that needs to be modified within the settings object.

When the settings object is emitted in the Launch 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.

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.