Embedding apps in external web pages

You can now embed your business apps in external web pages that run outside an App Engine. This configuration provides you more flexibility on where and how your apps are used. When you embed your app in an external page, you can securely pass information between the external page to your business app.

As an example, let's say that your website has a "Contact us" page, where customers can input personal information, like their name and email, and submit a message. Your embedded app can securely facilitate this communication. Let's see how you can configure this example.

Embedding your app in external pages

To embed your app in an external page:

  1. Open your app in the low-code designer, by using the Advanced view mode.
  2. Switch to the Overview tab.
  3. Under the Advanced settings, click the Allow this app to be embedded in an external site.
  4. Switch to your Application project settings, then click Environment variables.
  5. Click the + sign to add an environment variable.
  6. Name the variable embeddedAppTargetOrigin and set the value to the URL where you want your app to be embedded.
    Note: embeddedAppTargetOrigin is a reserved variable that is only used when embedding apps.

Now your app is ready to be hosted by an external page, but let's configure the input variables for your app.

Creating your input variables

To create your input variables:

  1. Switch from the Application project settings back to your app page.
  2. Click the Variables tab.
  3. Under the Variables section, add three string variables:
    1. Name
    2. Email
    3. Message
  4. Click the page tab to switch to design your app page.
  5. From the components list, select Variables.
  6. Add the variables to the page.
    • Input: Data that can be passed from the external page to your business app.
    • Output: Data that can be passed to the external page from your business app.
    • Data: Data that can be used only in your business app.
  7. Finish designing your Contact page to suit your site's styling.

Sending and receiving information

Configure your external site to communicate information to and from your app. When you call your app, the app opens in a separate browser tab.

Here’s a code example for sending inputs to your app:

var appHostOrigin = 'https://originOfYourApp';
var inputMsg = {
    'input': {
        'name': 'Mike',
        'email': 'example@ibm.com',
        'message': 'I would like to submit a ticket'
    },
    'name': 'cfgInputData'
};

//When opening in a separate window:
var newWindow = window.open('https://baa-env.com/AnApp(AA)'); //open the new window with the app

//add event listener to the window to send the inputs once loaded
newWindow.addEventListener('load', () => {
  newWindow.postMessage(inputMsg, appHostOrigin);
});
Note:
  • When sending inputs to your app, there is a default timeout of 2 seconds. If inputs are not received to the app within the timeout, the app runs without inputs.
  • The name of the message should be cfgInputData, and the input object should be populated with the variable_name and value pairs.
  • You can obtain the URL of your app, which is used for the newWindow.location.href value in the above example, from the REST APIs for DevOps. For more information, see REST APIs for DevOps.

Once the app receives the inputs, and the app completes, the outputs are sent to the embeddedAppTargetOrigin environment variable that you defined in that app. Here’s a code example for receiving outputs from your app:

window.addEventListener('message', (event) => {
    var message = JSON.parse(event.data);
    if (message.name === 'cfgOutputData') {
        //do something with the output data
    }
});
Note: The message.name must be cfgOutputData.