App API

This page is a reference for the App instance returned by App.create(). All methods are available after you have called App.create(appName, origin).

App.create(appName, origin?)

Creates and initializes an app. Call it once at startup.

Parameters:

• appName (string): Your app’s identifier.
• origin (string, optional): Target origin for PostMessage. Defaults to '*'. For Finqu Commerce admin iframes, set this to your admin URL (e.g. https://my-admin-url.myfinqu.com) so only the admin can communicate with your app.

Returns: An App instance.

Example:

import { App } from '@finqu/app-link';
 
const app = App.create('my-app-id', 'https://my-admin-url.myfinqu.com');

app.ready(fn)

Runs a callback when the app has been initialized by the host (or immediately if the app is already initialized). Use this before relying on getId() or getSessionId().

Parameters:

• fn (function): Callback with no arguments. Called once when the host has sent the Initialize message (or right away if initialization already happened).

Example:

app.ready(() => {
  const id = app.getId();
  const sessionId = app.getSessionId();
  // Safe to use id and sessionId here
});

app.getId()

Returns the app instance id assigned by the host, or null if not yet initialized.

Returns: string | null

Example:

app.ready(() => {
  const appId = app.getId();
  if (appId) {
    console.log('Instance ID:', appId);
  }
});

app.getSessionId()

Returns the current session id from the host, or null if not yet initialized.

Returns: string | null

Example:

app.ready(() => {
  const sessionId = app.getSessionId();
  // Use sessionId for API calls or logging
});

app.dispatch(message)

Sends a message to the host. The app link will set message.clientId and message.sessionId from the current app state, and will ensure message.payload is an object (defaulting to {}).

Parameters:

• message (IMessage): A message object. You must set at least component, action, and typically payload. See Messaging for the IMessage shape.

Returns: boolean (true if the message was sent via PostMessage).

Example:

import { App, ComponentGroup } from '@finqu/app-link';
 
// After building a valid IMessage (e.g. from a component or helper):
app.dispatch(myMessage);

For building messages that the host understands (e.g. Dialog, Resource), you usually use the component APIs on the host side. From the app, you often subscribe to messages and optionally send callbacks. See Messaging and Component groups and resources.

app.subscribe(group?, callback)

Subscribes to messages from the host. You can subscribe to all messages or only those for a specific component group.

Parameters:

• group (ComponentGroup, optional): If provided, only messages whose message.component.group matches this value are passed to the callback. Omit to receive all messages.
• callback (function): Called with one argument, the IMessage object. Signature: (message: IMessage) => void.

Returns: A function that unsubscribes this listener when called.

Examples:

Subscribe to all messages:

const unsubscribe = app.subscribe((message) => {
  console.log('Received:', message.action, message.component.group, message.payload);
});
// Later: unsubscribe();

Subscribe only to Dialog messages:

import { App, ComponentGroup } from '@finqu/app-link';
 
const unsubscribe = app.subscribe(ComponentGroup.Dialog, (message) => {
  if (message.action === 'Confirm') {
    // User confirmed a dialog
  }
});

Subscribe only to Resource messages:

const unsub = app.subscribe(ComponentGroup.Resource, (msg) => {
  console.log('Resource action:', msg.action, msg.payload);
});

app.unsubscribe(fn)

Removes a subscription that was added with subscribe. You can also use the function returned by subscribe() instead.

Parameters:

• fn (function): The same callback function you passed to subscribe.

Example:

const handler = (message) => console.log(message);
app.subscribe(handler);
// Later:
app.unsubscribe(handler);

app.getResizer()

Returns the iframe-resizer API when your app runs inside a resizable iframe (when the host uses iframe-resizer), or null otherwise. You can use this to e.g. send height updates to the parent.

Returns: The parentIFrame object from iframe-resizer, or null.

Example:

app.ready(() => {
  const resizer = app.getResizer();
  if (resizer && typeof resizer.size === 'function') {
    resizer.size(400);
  }
});

Summary

Next: Messaging for the IMessage shape and patterns for subscribing and dispatching.