Getting started

This page walks you through creating an AppLink app, waiting until it is ready, and reading the app and session identifiers. You can use this as a template for any Finqu App that runs inside the Commerce admin.

Create the app

Create an app instance with your app id and the administration origin. The origin is used to validate PostMessage communication: only messages from that origin are accepted. You can fetch the admin URL from the OAuth 2.0 resource when your app is loaded in the admin.

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

• First argument (appName): Your app’s identifier (e.g. the same id used when registering the app in Finqu).
• Second argument (origin): The admin’s origin. Use '*' only for development or when you do not need origin checks; for Commerce admin iframes, set this to your actual admin URL (e.g. https://my-admin-url.myfinqu.com).

If your app is opened in a top-level window (not in an iframe) and you provided an origin, AppLink will redirect the browser to the admin’s app route so the app loads inside the admin (e.g. https://my-admin-url.myfinqu.com/app/my-app-id/...).

Run logic when the app is ready

The host sends an Initialize message to your iframe. Until that message is received, you do not yet have an app instance id or session id. Use ready() to run code once the app is initialized (or immediately if it is already initialized):

app.ready(() => {
  console.log('App ID:', app.getId());
  console.log('Session ID:', app.getSessionId());
});

After ready() runs, app.getId() and app.getSessionId() return the values provided by the host. Use them when you need to identify the app instance or the current session in your UI or when talking to your backend.

Full example

Here is a minimal entry point that creates the app, waits for readiness, and logs the ids:

import { App } from '@finqu/app-link';
 
const adminOrigin = 'https://my-admin-url.myfinqu.com';
const app = App.create('my-app-id', adminOrigin);
 
app.ready(() => {
  console.log('App ID:', app.getId());
  console.log('Session ID:', app.getSessionId());
  // Mount your UI, subscribe to messages, etc.
});

Running inside the admin

Your app is loaded by the Finqu Commerce administration in an iframe. The host page will:

1. Load your app’s URL in the iframe
2. Send an Initialize message with id and sessionId in the payload
3. Optionally use iframe-resizer so the iframe can report its height

Make sure the origin you pass to App.create() matches the admin’s origin (e.g. the origin of the page that embeds your iframe). If it does not match, PostMessage validation will reject the host’s messages and your app will never receive Initialize. Obtain the admin URL from your OAuth 2.0 resource.

Next: App API for the full list of methods, or Messaging to subscribe and dispatch messages.