How to integrate a Mobi application into a Web App-Low-Code Development Platform(Mobi)-阿里云帮助中心

This document explains how to integrate Mobi applications into web applications using the Mobi Web software development kit (SDK).

The Mobi platform provides Web SDKs for React, Vue, and JavaScript. These SDKs enable you to easily integrate Mobi applications into your existing web applications. You can choose the integration method that best fits your application.

Logon access

For integrated applications, you must use JWT token authentication as described in the following section. You cannot use an Alibaba Cloud account to log on.

When you browse in incognito mode, the browser's same-origin policy may restrict identity verification for some logon methods.

React SDK

Installation

npm install @mobi-aliyun/runtime-embed-react

Basic usage

import Mobi from '@mobi-aliyun/runtime-embed-react';

const App = () => {
  return (
    <div style={{ height: '100vh', width: '100vw'}}>
      <Mobi src="The URL of the Mobi application, such as 'https://runtime-stage.mobiapp.cloud/xxx/apps/xxx/'" />
    </div>
   )
}

export default App;

Inject dynamic data into the Mobi application

To share data from the host application with the Mobi application, follow these steps:

In the Mobi designer, create host application data. For more information, see Host application data.

In the host application, pass the data property as an object to the SDK and set a value for the key.

import { useState } from 'react';
import Mobi from '@mobi-aliyun/runtime-embed-react';

const App = () => {
  const [value, setValue] = useState<string>('init');
  return (
    <div style={{ height: '100vh', width: '100vw'}}>
      <Mobi
        src="The URL of the Mobi application, such as 'https://runtime-stage.mobiapp.cloud/xxx/apps/xxx/'"
        data={{ sampleKey1: value}}
      />
    </div>
   )
}

export default App;

The globalHostAppData1.value in the Mobi application then changes whenever the value in the host application changes.

Send messages to the host application

To send messages from the Mobi application to the host application, follow these steps:

In the Mobi application, use the mobi.hostApp.postMessage method to construct a message.
1. The mobi.hostApp.postMessage method accepts a required data parameter and an optional origin parameter. If you configure the origin parameter, messages are sent only to targets that match the specified origin.
2. The mobi.hostApp.postMessage method returns a Promise<any>. This promise resolves with the return value from the messageHandler of the host application.

In the host application, pass the messageHandler property as a function to the SDK. This function accepts a data parameter of any type and can return a value of any type.

import { useState } from 'react';
import Mobi from '@mobi-aliyun/runtime-embed-react';

const App = () => {
  const [value, setValue] = useState<string>('init');
  return (
    <div style={{ height: '100vh', width: '100vw'}}>
      <Mobi
        src="The URL of the Mobi application, such as 'https://runtime-stage.mobiapp.cloud/xxx/apps/xxx/'"
        data={{ sampleKey1: value}}
        messageHandler={(data) => {
          if(data.type === 'UPDATE_VALUE'){
            setValue(data.newValue);
          }
          return data.newValue;
        }}
      />
    </div>
   )
}

export default App;

Silent logon

Change the logon configuration of the Mobi application to "JWT token authentication".

Refer to Identity Source Management to obtain the auth_code, refresh_token, and expires_in values. Then, pass these values to the SDK as the auth property.

import { useState } from 'react';
import Mobi from '@mobi-aliyun/runtime-embed-react';
const App = () => {
  const [value, setValue] = useState<string>('init');
  return (
    <div style={{ height: '100vh', width: '100vw'}}>
      <Mobi
        src="The URL of the Mobi application, such as 'https://runtime-stage.mobiapp.cloud/xxx/apps/xxx/'"
        data={{ sampleKey1: value}}
        messageHandler={(data) => {
          if(data.type === 'UPDATE_VALUE'){
            setValue(data.newValue);
          }
          return data.newValue;
        }}
        auth={{
          auth_code: 'xxxxx',
          refresh_token: 'xxxxx',
          expires_in: xxxxx
        }}
      />
    </div>
   )
}
export default App;

React SDK property reference

Property	Type	Description
src	string	Required. The URL of the integrated Mobi application.
data	object	Optional. Shares data with the Mobi application. This property must be used with the host application data in the Mobi application.
messageHandler	function	Optional. Receives messages from the Mobi application. This property must be used with `mobi.hostApp.postMessage` in the Mobi application.
auth	{ auth_code: string; refresh_token: string; expires_in: number; }	Optional. Implements silent logon. You must obtain a JWT token and enable "JWT token authentication" in the Mobi application.
iframeOptions	{ sandbox?: string; allow?: string; }	Optional. Customizes the `sandbox` and `allow` properties of the iframe. To ensure the Mobi application runs correctly, the SDK injects two `sandbox` properties by default: `allow-script` and `allow-same-origin`.
style	object	Optional. Customizes the style of the iframe.
customRouterHandler	{ navigateTo?: (routerKey: string, routerParams: Record<string, any>) => void; onNavigateError?: (routerKey: string, error: any) => void; }	Optional. Serves as a feature routing callback within a Mobi Copilot application. This configuration item is not valid when integrating a Mobi web application.

Vue SDK

Installation

npm install @mobi-aliyun/runtime-embed-vue

Basic usage

<script setup lang="ts">
import Mobi from "@mobi-aliyun/runtime-embed-vue";
</script>

<template>
  <div style="width: 100vw; height: 100vh">
    <Mobi
      src="The URL of the Mobi application, such as 'https://runtime-stage.mobiapp.cloud/xxx/apps/xxx/'"
    />
  </div>
</template>

<style scoped></style>

Inject dynamic data into the Mobi application

In the Mobi designer, create host application data. For more information, see Host application data.

In the host application, pass the data property as an object to the SDK and set a value for the key.

<script setup lang="ts">
import Mobi from "@mobi-aliyun/runtime-embed-vue";
import { ref } from "vue";
const value = ref("init");
</script>

<template>
  <div style="width: 100vw; height: 100vh">
    <Mobi
      src="The URL of the Mobi application, such as 'https://runtime-stage.mobiapp.cloud/xxx/apps/xxx/'"
      :data="{ sampleKey1: value }"
    />
  </div>
</template>

<style scoped></style>

The globalHostAppData1.value in the Mobi application then changes whenever the value in the host application changes.

Send messages to the host application

Configure mobi.hostApp.postMessage in the Mobi application by referring to the React SDK.
In the host application, pass the message-handler property as a function to the SDK. This function accepts a data parameter of any type and can return a value of any type.

<script setup lang="ts">
import Mobi from "@mobi-aliyun/runtime-embed-vue";
import { ref } from "vue";
const value = ref("init");
const messageHandler = (data) => {
  if (data.type === "UPDATE_VALUE") {
    value.value = data.newValue;
  }
  return data.newValue;
};
</script>

<template>
  <div style="width: 100vw; height: 100vh">
    <Mobi
      src="The URL of the Mobi application, such as 'https://runtime-stage.mobiapp.cloud/xxx/apps/xxx/'"
      :data="{ sampleKey1: value }"
      :message-handler="messageHandler"
    />
  </div>
</template>

<style scoped></style>

Silent logon

For information about how to configure JWT authentication in the Mobi application, see the React SDK.
Refer to Identity Source Management to obtain the auth_code, refresh_token, and expires_in values. Then, pass these values to the SDK as the auth property.

<script setup lang="ts">
import Mobi from "@mobi-aliyun/runtime-embed-vue";
import { ref } from "vue";
const value = ref("init");
const messageHandler = (data) => {
  if (data.type === "UPDATE_VALUE") {
    value.value = data.newValue;
  }
  return data.newValue;
};
</script>

<template>
  <div style="width: 100vw; height: 100vh">
    <Mobi
      src="The URL of the Mobi application, such as 'https://runtime-stage.mobiapp.cloud/xxx/apps/xxx/'"
      :data="{ sampleKey1: value }"
      :message-handler="messageHandler"
      :auth="{
        auth_code: 'xxxxx',
        refresh_token: 'xxxxx',
        expires_in: xxxxx,
      }"
    />
  </div>
</template>

<style scoped></style>

Vue SDK property reference

Property name	Type	Description
src	string	Required. The URL of the integrated Mobi application.
data	object	Optional. Shares data with the Mobi application. This property must be used with the host application data in the Mobi application.
message-handler	function	Optional. Receives messages from the Mobi application. This property must be used with `mobi.hostApp.postMessage` in the Mobi application.
auth	{ auth_code: string; refresh_token: string; expires_in: number; }	Optional. Implements silent logon. You must obtain a JWT token and enable "JWT token authentication" in the Mobi application.
iframe-options	{ sandbox?: string; allow?: string; }	Optional. Customizes the `sandbox` and `allow` properties of the iframe. To ensure the Mobi application runs correctly, the SDK injects two `sandbox` properties by default: `allow-script` and `allow-same-origin`.
style	object	Optional. Customizes the style of the iframe.
custom-router-handler	{ navigateTo?: (routerKey: string, routerParams: Record<string, any>) => void; onNavigateError?: (routerKey: string, error: any) => void; }	Optional. Serves as a feature routing callback within a Mobi Copilot application. This configuration item is not valid when integrating a Mobi web application.

JavaScript SDK

Installation

Install using NPM

npm install @mobi-aliyun/runtime-embed-javascript

Install using a CDN

<script src="https://cdn.jsdelivr.net/npm/@mobi-aliyun/runtime-embed-javascript/dist/index.global.js"></script>

Basic usage

<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Web SDK</title>
  </head>
  <body>
    <div style="width: 100vw; height: 100vh" id="root"></div>
    <!-- If you install using a CDN -->
    <!-- <script src="https://cdn.jsdelivr.net/npm/@mobi-aliyun/runtime-embed-javascript/dist/index.global.js"></script> -->
    <script type="module">
      import { createMobiEmbed } from "@mobi-aliyun/runtime-embed-javascript";
      // If you install using a CDN
      // const { createMobiEmbed } = MobiEmbed;
      const mobiEmbed = createMobiEmbed({
        src: "The URL of the Mobi application, such as 'https://runtime-stage.mobiapp.cloud/xxx/apps/xxx/'"
      });
      const container = document.querySelector("#root").appendChild(mobiEmbed);
    </script>
  </body>
</html>

Inject dynamic data into the Mobi application

In the Mobi designer, create host application data. For more information, see Host application data.
In the host application, pass the data property as an object to the SDK and set a value for the key.

<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Web SDK</title>
  </head>
  <body>
    <div style="width: 100vw; height: 100vh" id="root"></div>
    <!-- If you install using a CDN -->
    <!-- <script src="https://cdn.jsdelivr.net/npm/@mobi-aliyun/runtime-embed-javascript/dist/index.global.js"></script> -->
    <script type="module">
      import { createMobiEmbed } from "@mobi-aliyun/runtime-embed-javascript";
      // If you install using a CDN
      // const { createMobiEmbed } = MobiEmbed;
      const mobiEmbed = createMobiEmbed({
        src: "The URL of the Mobi application, such as 'https://runtime-stage.mobiapp.cloud/xxx/apps/xxx/'",
        data: { sampleKey1: "init" },
      });
      const container = document.querySelector("#root").appendChild(mobiEmbed);
    </script>
  </body>
</html>

You can change the data by modifying the data property of the SDK.

import { createMobiEmbed } from "@mobi-aliyun/runtime-embed-javascript";

const mobiEmbed = createMobiEmbed({
  src: "The URL of the Mobi application, such as 'https://runtime-stage.mobiapp.cloud/xxx/apps/xxx/'",
  data: { sampleKey1: "init" },
});
setTimeout(() => {
  mobiEmbed.data = { sampleKey1: "updated" };
}, 5000);

Send messages to the host application

To configure mobi.hostApp.postMessage in the Mobi application, see the React SDK.

In the host application, pass the messageHandler property as a function to the SDK. This function accepts a data parameter of any type and can return a value of any type.

<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Web SDK</title>
  </head>
  <body>
    <div style="width: 100vw; height: 100vh" id="root"></div>
    <!-- If you install using a CDN -->
    <!-- <script src="https://cdn.jsdelivr.net/npm/@mobi-aliyun/runtime-embed-javascript/dist/index.global.js"></script> -->
    <script type="module">
      import { createMobiEmbed } from "@mobi-aliyun/runtime-embed-javascript";
      // If you install using a CDN
      // const { createMobiEmbed } = MobiEmbed;
      const mobiEmbed = createMobiEmbed({
        src: "The URL of the Mobi application, such as 'https://runtime-stage.mobiapp.cloud/xxx/apps/xxx/'",
        data: { sampleKey1: "init" },
        messageHandler: (data) => {
          if (data.type === "UPDATE_VALUE") {
            mobiEmbed.data = { sampleKey1: data.newValue };
          }
          return data.newValue;
        },
      });
      const container = document.querySelector("#root").appendChild(mobiEmbed);
    </script>
  </body>
</html>

Silent logon

Use the React SDK to configure JWT Token Authentication in your Mobi application.
Refer to Identity Source Management to retrieve the auth_code, refresh_token, and expires_in values. Then, pass these values to the SDK as the auth property.

<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Web SDK</title>
  </head>
  <body>
    <div style="width: 100vw; height: 100vh" id="root"></div>
    <!-- If you install using a CDN -->
    <!-- <script src="https://cdn.jsdelivr.net/npm/@mobi-aliyun/runtime-embed-javascript/dist/index.global.js"></script> -->
    <script type="module">
      import { createMobiEmbed } from "@mobi-aliyun/runtime-embed-javascript";
      // If you install using a CDN
      // const { createMobiEmbed } = MobiEmbed;
      const mobiEmbed = createMobiEmbed({
        src: "The URL of the Mobi application, such as 'https://runtime-stage.mobiapp.cloud/xxx/apps/xxx/'",
        data: { sampleKey1: "init" },
        messageHandler: (data) => {
          if (data.type === "UPDATE_VALUE") {
            mobiEmbed.data = { sampleKey1: data.newValue };
          }
          return data.newValue;
        },
        auth: {
          auth_code: "xxxxx",
          refresh_token: "xxxxx",
          expires_in: xxxxx,
        },
      });
      const container = document.querySelector("#root").appendChild(mobiEmbed);
    </script>
  </body>
</html>

JavaScript SDK property reference

Property name	Type	Description
src	string	Required. The URL of the integrated Mobi application.
data	object	Optional. Shares data with the Mobi application. This property must be used with the host application data in the Mobi application.
messageHandler	function	Optional. Receives messages from the Mobi application. This property must be used with `mobi.hostApp.postMessage` in the Mobi application.
auth	{ auth_code: string; refresh_token: string; expires_in: number; }	Optional. Implements silent logon. You must obtain a JWT token and enable "JWT token authentication" in the Mobi application.
iframeOptions	{ sandbox?: string; allow?: string; }	Optional. Customizes the `sandbox` and `allow` properties of the iframe. To ensure the Mobi application runs correctly, the SDK injects two `sandbox` properties by default: `allow-script` and `allow-same-origin`.
style	string	Optional. Customizes the style of the iframe.
customRouterHandler	{ navigateTo?: (routerKey: string, routerParams: Record<string, any>) => void; onNavigateError?: (routerKey: string, error: any) => void; }	Optional. Serves as a feature routing callback within a Mobi Copilot application. This configuration item is not valid when integrating a Mobi web application.