Skip to main content

<iframe> Embedding

The Unito iframe embed is a fully managed micro-app with the following capabilities:

  • Authorization module supporting all connectors in Unito’s catalog, using OAuth, access tokens, username/password, etc.
  • Fully-featured flow editor with rules, mappings and activity logs.
  • Flows define how two sets of work items should sync together.
  • Seamless user login and automatic workspace creation

URL and parameters​

https://app.unito.io/api/embed/<embed-id>

URL Parameters:

  • embed-id: string

    A unique identifier provided by Unito for each embedding application.

  • user_id: string

    The native unique identifier for the user of the embedding app that is accessing the iframe. Used to ensure the correct user is logged into Unito, so this user ID must match that passed by the app’s OAuth process.

    ⚠️ Warning: will soon be replaced with external_user_id

  • account_id: string

    A native unique identifier for the account, organization or group that the user accessing the iframe belongs to. Unito will create a single workspace per such ID, and all users accessing the iframe for the same workspace will get added as workspace members. This ID must match that passed by the app’s OAuth process.

    ⚠️ Warning: will soon be replaced with external_workspace_id

  • container_id (optional): string

    A container is a project, board, sheet, table, or other that forms a set of items to sync. If provided, any flow listed and created in the embed will be limited to that container.

    ⚠️ Warning: will soon be replaced with external_container_id

  • bot_user_id, bot_auth_code (optional): string

    Native ID for a pre-created and pre-authorized bot account, and its OAuth authorization code.

Example:

<https://app.unito.io/api/embed/acme?user_id=111&account_id=222&bot_user_id=333&bot_auth_code=ABC>

<iframe> Specs​

Unito’s UI is responsive, however works best in the following conditions

  • Width:
    • Bare minimum 600px
    • Ideal 1000px
  • Height: less than window or popup innerHeight (see scrolling below)
  • Scrolling: let iframe itself handle scrolling, so make sure the iframe is not higher or wider than it’s container (the browser window or a popup/modal)
  • Quirks: iframes have a lot of quirks with different browsers, and with cookies in particular. Unito detects and handles many of these quirks. For example it can detect blocked third-party cookies and work around them (with Safari and IE in particular, and more recently Chrome).

Example:

<iframe
  height="100%"
  width="100%"
  src="https://app.unito.io/api/embed/acme?user_id=111&account_id=222&bot_user_id=333&bot_auth_code=ABC"
/>

Using a pop-up/modal​

  • You can load the iframe inside your app’s nav, or inside a pop-up or modal dialog.
  • We’re talking about a overlay panel here, not a pop-up browser window
  • The pop-up should not have its own scroll bars, let the iframe handling scrolling (avoid double scrollbars)
  • Avoid padding or margins
  • Escape key handler: none
    • Unito app itself may have pop-ups/modals and it will be unclear to the user what the escape key will close.
    • Unito app will attempt to capture escape key event and prevent bubbling to pop-up, but cross-browser behavior is variable
    • Suggest this event handler be removed/disabled on pop-up when using iframe

OAuth flow​

When the iframe is loaded, here is the standard flow for a new user. This includes a standard OAuth flow for the user to authorize Unito to access its account in the embedding app.

  1. Unito detects user is not logged in
  2. Unito redirects to embedding app’s OAuth page (within iframe)
  3. Embedding app shows OAuth authorization page, asking users to let Unito access their data. Since the user is already signed into the embedding app, no login screen will be shown.
  4. User authorizes
  5. Embedding app redirects back to Unito (within iframe)
  6. Unito fetches and validates user’s info/tokens from embedding app, and creates a Unito account
  7. User can start using Unito

We recommend the embedding app to ensure its OAuth authorization page has minimal nav and chrome. Since the authorization page will load inside the iframe, it must not look like the embedding app is loaded within itself.

Bot pre-authorization​

Unito works best when it can use a bot account to perform its syncs. Users can create and connect those bot accounts themselves, but the best experience comes when the embedding app automatically creates that bot account when users install or access the embed.

  • Bots are standard users and we use standard OAuth for them too
  • Users will basically have both their personal user and bot user “associated” to their Unito account
  • Since we’re going through the full OAuth flow for the personal account (see OAuth flow above), we can skip some OAuth steps for the bot:
    • Through URL parameters on the iframe, pass bot_user_id and bot_auth_code
    • The bot_auth_code parameter is the standard OAuth authorization code, the one you pass back to an app through a redirect url parameter.
    • Unito must then exchange that authorization code with the embedding app for an actual access/refresh token. The exchange is done between Unito’s server and the embedding app’s servers, and requires the Unito app ID and secret. In other words, the authorization code is not security-sensitive.