Embedded (実装ガイド) ​

Embedded を使用すると、Workato プラットフォームのすべてのページと要素を、Embedded パートナーのプラットフォーム UI に組み込まれた iframe 内に埋め込むことが可能になります。そうすることで、シームレスなエンドユーザーエクスペリエンスを提供するとともに、Workato の最新のローコードによるレシピ作成インターフェイスの機能をプラットフォームにもたらすことができます。

アクティビティ監査ログ、ロールベースのアクセス制御、Workato 管理ダッシュボードのようなツールを使用して、顧客はプラットフォーム内から統合の作成、テスト、監視を行うことができます。

はじめに ​

このガイドでは、プラットフォーム内に Embedded を実装する方法について説明します。

以下のような注意点があります。

• Workato とベンダー間の統合には、iFrame を使用します。これは、ブラウザー内である Web アプリを他の Web アプリに埋め込むネイティブな方法です。
• Embedded パートナーのアプリケーションとページスタイルやデザインを合わせるために、ブランドカラーやページマージンなど、Workato のスタイルプロパティの一部をカスタマイズする手段を用意しています。
• また、Workato の Web アプリ (iFrame で埋め込まれた) とパートナーの Web アプリ間の同期を簡素化する目的で、Workato Embedding Client スクリプトも用意しています。

設定パラメータ ​

用語の説明 ​

このガイドをわかりやすくするために、いくつかの用語の定義を示します。

リンク ​

• ベンダー : Embedded パートナーの Web アプリは ベンダー といいます。
• ベンダー URL - Vendor origin の配下にあるすべての URL (https://vendor.com/*) です。
• 埋め込み URL - Embedding URL prefixから始まるすべてのベンダー URL (https://vendor.com/integration/*) です。
• 埋め込みリンク - 埋め込み URL を指す <a> 要素です。
• 埋め込み iframe または iframe - 埋め込まれた Workato Web アプリを含む <iframe> HTML 要素です。
• 埋め込みページ - 埋め込み URL の配下にあり、 かつ 、埋め込み iframe を含む、ベンダーの Web アプリの任意のページ

パラメータ Vendor origin とパラメータ Embedding URL prefix は、埋め込まれている Workato ウェブアプリ内のすべてのリンクを埋め込みリンクに変換するために必要となります。

たとえば、<a href="/foo?a=1#hash"> は以下のようになります。

<a href="https://vendor.com/integration/foo?a=1#hash">

これにより、ユーザーが新しいタブでリンクを開くときに正しい埋め込みページを開いたり、リンクの URL をコピーするときに正しい URL をコピーしたりすることが可能になります。

アプリ同士の通信 ​

iFrame とパートナーのアプリケーション間の通信は、ブラウザーの PostMessage API を介して行います。

Workato からベンダーの Web アプリに送られるメッセージのリストについては EmbeddingWorkatoMessage を、逆方向に送ることができるメッセージのリストについては EmbeddingVendorMessage を参照してください。

Workato とベンダーの Web アプリ間の通信を簡素化するために、Workato Embedding Client を用意しています。詳細については、直後のセクションで説明します。

Workato Embedding Client ​

Workato Embedding Client は、ベンダーの Web アプリと埋め込み Workato プラットフォーム間の通信を簡素化する小さなスクリプトです。Workato と埋め込み URL との同期に役立つヘルパーメソッドも提供しています。

以下の手順で、Web アプリに組み込むことができます。

1. 以下のスクリプトを、すべての埋め込みページに挿入します。<script src="https://embedding.workato.com/r/embedding-client.js">

   以下の点に注意してください。

   • 埋め込み iFrame の 前 に追加する必要があります。
   • iFrame が読み込まれる前に同期的に読み込む必要があるため、async 属性と defer 属性のどちらも使えません。

   [[EmbeddingClient]] クラスのインスタンスである、グローバルな Workato オブジェクトが作成されます。

2. 最初の設定スクリプトのすぐ下に、次の設定スクリプトを挿入します。

   html

   <script>
     Workato.configure({
       // Value of `Embedding URL prefix` parameter
       embeddingUrlPrefix: '/integration'
     });
   </script>

以上です。これで、EmbeddingClient クラスのプロパティとメソッドを使用できるようになりました。

たとえば、EmbeddingClient.handleNavigation メソッドを使用すると、埋め込み iframe 内の現在の Workato URL をベンダーのウェブアプリの現在の URL と同期できます。また、EmbeddingClient.generateIFrameUrl メソッドを使用すると、iframe の src 属性の値を生成できます。

EmbeddingClient のドキュメントに、使用できるすべてのヘルパーメソッドに関する情報が記載されています。

スタイル ​

Embedded パートナーは、Workato のスタイルパラメータをカスタマイズして、アプリケーションのデザインがよりマッチするように調整できます。すべて省略可能です。指定しなかったプロパティには、デフォルト値が使用されます。

カスタマイズ可能なプロパティとそのデフォルト値は以下のとおりです。

値の種類 ​