Frame Link is a promise-based API built on window.postMessage. It allows a two-way communication between a parent page and a child iframe.

• Features
• Installing
• Glossary
• Usage
• API

Features

• Promise-based API for elegant and simple communication.
• Two-way parent <-> child handshake, with message validation.
• Provides capability to invoke aiWARE functionality from the child frame

Installing

npm install aiware-frame-link

Glossary

• Parent: The top level aiWARE Desktop application that embeds an onboarded application in an <iframe ... />, creating a Child.
• Child: The bottom level web page loaded within the <iframe ... />.
• Handshake: The process of initialization of the FrameLink inside both Parent and Child by the end of which both instances exchange initiation packets and kick off heartbeat sending/monitoring process that allows Parent to handle scenarios when the Child frame cannot be loaded (e.g.: 503) or its application freezes.

Usage

• Child is expected to have headers that allow porting the application via iframe. This means that potential attackers can port the onboarded app anywhere posting messages to the child frame at any rate. Implement throttling and rate-limiting mechanisms to prevent abuse and excessive message sending.
• The Child begins communication with the Parent. A handshake is started when the Child sends a heartbeat and requests the initial context.
• Upon receiving request for initial context Parent completes its initialization and sends a response with the context requested
• Parent validates messages from the Child by checking sender's URL against registry of known applications. Child does not have means to validate messages from the Parent since Parent can be deployed on multiple domains and such domains can change without or on a short notice.
• It is strongly advised that Child does not provide any sensitive information such as authentication tokens, etc to the message sender.

Example

desktop.us-1.veritone.com

// create FrameLink instance in the top-level component
const [frameLink, setFrameLink] = useState(null);

// error action that will be invoked in the Desktop Application
const errorAction = (message: string) => {
  dispatch(
    showMessage({
      content: message,
      severity: MessageSeverity.Error,
    })
  );
};

// listen to the child application URL changes
useEffect(() => {
  if (childApplicationUrl) {
    // initiate FrameLink if a child app was selected from the App Switcher
    AiwareFrameLink.init({
      origin: childApplicationUrl, // pass the URL of the child app as the 'origin'
      errorAction, // pass a function that will take error message string as a param if you wish to handle errors
    }).then(link => {
      setFrameLink(link); // set FrameLink instance in the state
    });
  } else {
    // if the child application was closed, reset FrameLink instance to 'null'
    setFrameLink(null);
  }
}, [childApplicationUrl]);

child-app.com

import { isIFrame, TContext, AiwareFrameLink } from 'aiware-frame-link'
...
const TopLevelComponent = () => {

  const [link, setLink] = useState<typeof AiwareFrameLink>();

  // subscriber functions will receive argument of type TContext
  const subscriberFunc = (context: TContext) => {
      // do something with aiWARE context
  }


  useEffect(() => {
  // when component renders for the first time
    if (isIFrame()) { // check if the app is running inside the iframe using provided helper function
      AiwareFrameLink.init({
        // pass subscriber functions
        subscribers: [subscriberFunc]
      })
      .then((link: typeof AiwareFrameLink) => {
        setLink(link) // set FrameLink instance in the component state
      }
      )
    }
  }, [])
}

This library exports AiwareFrameLinkContext: React.Context<AiwareFrameLink> to allow passing FrameLink instance down the component tree in applications that use React library

API

AiwareFrameLink.init

// Parent
AiwareFrameLink.init({
  origin: 'https://child-app.com',
  errorAction,
  intl,
  store,
});

// Child
AiwareFrameLink.init({
  subscribers,
  errorAction,
});

| Name | Type | Description | | -------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | | origin? | string | Child application URL. This parameter is only passed when initiating in Parent | | errorAction? | (errorMessage: String) => unknown) | Function that is invoked when error occurs | | subscribers? | ((context: TContext) => unknown)[] | Array of functions that are invoked when a child app receives aiWARE context. Passed only in Child initialization | | intl? | IntlShape | Instance of 'react-intl' to support. Passed only in parent initialization as Child apps are expected to handle their own error message translations if any | | store? | IModuleStore<unknown> | Parent application store for scenarios where its data is needed to communicate with a Child. Passed only in parent initialization |

FrameLink Context

To allow Child frame communicate with aiWARE API Parent frame provides context: TContext upon establishing handshake. Such context contains the following properties that should be sufficient to authenticate/interact with aiWARE API services:

// example context:
const context = {
  environment: 'us-1',
  baseUrl: 'https://api.us-1.veritone.com/v3/graphql',
  authToken: 'a5c09131-v51a-4991-b830-e5860e0087f2',
  theme: 'light',
  language: 'en',
  userId: 'a5c09131-v51a-4991-b830-e5860e0087f2',
  organizationId: '1',
};

AiwareFrameLink.on

// Parent
AiwareFrameLink.on(event, callback);

| Name | Type | Description | | ---------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | event | EFrameLinkEvents | Name of a supported event | | callback | (payload?: unknown) => unknown | Callback function executed when event is emitted. Function take an optional payload supplied by the event handler logic in the FrameLink |

Supported events

• init - currently Parent event only, emitted when parent is initialized and receives a heartbeat + initial context request from a Child

AiwareFrameLink.postMessage

// Child
AiwareFrameLink.postMessage(message, payload);

| Name | Type | Description | | ---------- | --------------- | -------------------------------------------------------------------------------------------- | | message | EMessageTypes | supported message or event name that invokes respective logic in the AiWareFrameLink class | | payload? | any | optional payload for a message |

Supported messages

enum EMessageTypes {
  getInitContext = 'getInitContext',
  initContext = 'initContext',
  updateContext = 'updateContext',
  reportActivity = 'reportActivity',
  response = 'response',
  utility = 'utility',
  error = 'error',
  heartbeat = 'heartbeat',
}

AiwareFrameLink.useUtility

// Child
AiwareFrameLink.useUtility(Utilities.filePicker, data);

| Name | Type | Description | | --------- | ----------- | ------------------------------------------- | | utility | Utilities | one of the supported utilities | | data? | any | optional payload for a utility invokation |

Supported Utilities

• filePicker - opens File Importer panel allowing to select files to upload. Upon uploading files to the Data Center this utility returns a response with a list of created TDO IDs to the Child frame { requestId: string, data: { tdoIds: string[] } }

AiwareFrameLink.subscribe

// Child
AiwareFrameLink.subscribe(subscriberFunction);

| Name | Type | Description | | -------------------- | -------------------------------- | ----------------------------------------------------------------------------------------------- | | subscriberFunction | (context: TContext) => unknown | Subscriber function that is invoked when a child app receives initial or updated aiWARE context |

Troubleshooting/FAQ

General

The child does not respond to communication from the Parent

Make sure that you have initialized Frame Link in your child page and that your application was onboarded to aiWARE platform.

I want to retrieve information from the parent by the child

By design FrameLink is restrictive in its communication between frames allowing only specific types of messages or requests. Future versions of the Frame Link will have new types of messages and utilities enabled for the Child to send or invoke.

I cannot send a message from Child to Parent

Frame Link comes with a guard around messages that can be sent only one-way. E.g.: initialContext can only be send from Parent to Child.

How do I make sure that incoming message is from a valid parent?

Parent is secured by validating message sender comparing its URL against the list of onboarded applications. Senders from unknown destantions will be ignored. But once Child allows porting itself via iframe it can be technically ported into any application. This is why we strongly advise to avoid sharing any sensitive information in responses to the Parent. Frame Link was intended to allow Child become a consumer of the parent information/methods. Parent does not expect any authentication or other sensitive information from the Child.

How can I secure my application if it's ported via attacker's iframe?

We strongly advise to sanitize data you receive in communication with Parent to prevent injection attacks or other security vulnerabilities.