Launch – Make an Extension – Principles

I have written a lot about how to make an Extension, including here and here. There are missing pieces, though.

If you have looked at the documentation, you will likely have come across the following illustration regarding Extension flow.

The flow diagram describes how the different parts of Launch and your Extension work together.

Flow

On a very high level, your Extension provides HTML files for configuration, and Javascript files that contain the actual Extension code.

The HTML files are used within the Launch UI, so that a Launch user or admin can configure your Extension. That is their sole purpose. They will never be delivered into your site.

You might remember that within the HTML files, you can provide form fields, and that there are three functions that Launch will call when it displays the HTML: init, getSettings, and validate

When you tell the reactor-scaffold tool to create a configuration view, the three functions look like this:

      window.extensionBridge.register({
        init: function(info) {
          if (info.settings) {
            // TODO Populate form values from persisted settings.
          }
        },

        getSettings: function() {
          // TODO Return settings object from form values.
        },

        validate: function() {
          // TODO Return whether settings are valid.
        }
      });

Launch, on displaying your configuration view HTML, calls init. This is your chance to pull existing settings, or to initialize them, and to setup the form fields accordingly.

When the Launch user hits the “Keep” button, Launch calls validate. You have to code that function so that it only returns true if the user input makes sense. Should there be bad input (like an empty field), you can highlight that, or put some message into the form telling the user what is wrong.

Only if validate returns true, Launch will call getSettings. That function must return a settings object, which Launch will store in the Launch Data Storage.

The format of your settings object is up to you! Launch will store it as it is, and you’ll get it back exactly like you told Launch to store it. Note that the settings object must be serializable.

“At Runtime”?

Oh… yes, that is a good question. The documentation says:

At runtime, Launch will inject the user-defined settings into the library module.

– Launch documentation – Extension flow

What exactly does “at runtime” mean, here?

The settings are compiled into the Library when you build it. It is part of the build process, and there is no direct link from a site visitor’s browser to the Launch Data Storage.

Let me repeat that: the only way to update settings is to build (and deploy) a Library.

Yes, if you’re self-hosting, you have to also deploy the newly built Library. Everything you do in Launch ends up in static files in the Libraries, and that is a good thing.

Settings

Apropos settings: Launch knows two different types of settings: there are the settings for each Event Type, Condition Type, Data Element Type, and Action Type that your Extension provides, and there are the Extension settings, which are sort of global.

You can see an example of the former when you create a standard Data Element. The Core Extension provides those, and it is built so that when you create a DE, there will be a configuration view.

An example for Extension settings would be all the configuration of the Analytics Extension, where you set things like the Report Suite IDs on a global level.

In your code, you can access both. Here is an example:

'use strict';

module.exports = function(settings) {
    // output Action Type settings
    if (settings) {
        turbine.logger.info('Action Type settings', settings);
    }
    // output Extension settings
    var extensionSettings = turbine.getExtensionSettings();
    if (extensionSettings) {
        turbine.logger.info('Extension settings', extensionSettings);
    }

    // do the thing you do
    // TODO 
}

As I said, the settings and extensionSettings objects will be of the exact format that you made.

One of the great things about the reactor-sandbox is that it will show you your settings object when you test!

You can also access both types of settings in your HTML configuration views!

The info object passed into the init function gives you access to both: info.settings & info.extensionSettings (and some more, see here)

Javascript

“On the Javascript side”, things are much easier: whatever Javascript you write in your Extension will be part of the Library, and it will therefore end up in your web site.

I have written about Launch load order before, so I’ll keep this to a minimum.

Code in a main module, any dependencies, or code outside your module exports will be executed when Launch loads.

Any code within module.exports is executed when Launch calls it. For Condition Types or Action Types, that would be during the execution of Rules, of course, and for Data Element Types, it would be whenever the value of said Data Element is queried.

By the way: just like DTM, Launch queries Data Elements every time! Even if the DE itself is set to “Remember value”, it will still be queried. The “Remember value” setting is only a backup mechanism, in case the query returns null. If your DE does something complex and you’d like caching, you’ll have to build that into the DE code.

For Event Types, the Javascript runs when Launch loads, i.e. that code is not run as part of any Rules. And that makes sense, since the Event Types trigger the Rules.

Think of Event Types as standalone code, and the Rules as handlers, waiting for the Event Type to call trigger().

If you think of it like that, the “Respecting Rule Order” chapter on the Event Types documentation page makes a lot of sense…

Back into the Flow

So…

When you create an Extension and publish it into Launch, you create that little box at the top left of the flow diagram.

Users can integrate that into their Launch Properties.

Depending on whether there is any configuration in your Extension, Launch may or may not present the user with Configuration Views, and it will store settings into the Launch Data Storage.

When said user decides to build a Library (dev, staging, or production), Launch takes all the Javascript files from your Extension, adds all settings objects from the Launch Data Storage, and drops the result into the Library along with Launch Runtime code.

The resulting Library can be loaded into a web site, and all Javascript code will do its thing there, including yours.

Overall, this thing is pretty simple, isn’t it?