CX オプション

# Embedded (実装ガイド)

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

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

# はじめに

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

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

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

# 設定パラメータ

パラメータ名	種類	値の例	説明
ベンダーオリジン	必須	`https://vendor.com`	ベンダーの Web アプリのオリジン (`<url_schema>://<url_host>`)。複数のベンダーオリジンを指定することもできます。複数のオリジンを指定する場合は、JWT のペイロードでオリジンを指定する必要があります。
埋め込み URL の接頭辞	必須	`/integration`	最高のユーザーエクスペリエンスを提供するには、iFrame の Workato URL とベンダーの Web アプリの URL を同期する手段が必要です。そのためには、`<embedding_url_prefix>/<workato_url>` というパターンを使って Workato URL からベンダー URL を生成する際に使用する埋め込みパスの接頭辞をベンダーが選択する必要があります。たとえば、接頭辞が `/integration` で Workato URL が `/foo?a=1#hash` である場合、対応するベンダー URL は `/integration/foo?a=1#hash` になります。
スタイルプロパティ	任意	スタイルを参照	Workato をカスタマイズしてベンダーのデザインに合わせるためのプロパティのリスト。詳細については、スタイルのセクションを参照してください。

# 用語の説明

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

# リンク

ベンダー : 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 (opens new window) を介して行います。

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

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

# Workato Embedding Client

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

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

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

以下の点に注意してください。
- 埋め込み iFrame の前に追加する必要があります。
- iFrame が読み込まれる前に同期的に読み込む必要があるため、async 属性と defer 属性のどちらも使えません。
[[EmbeddingClient]] クラスのインスタンスである、グローバルな Workato オブジェクトが作成されます。

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

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

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

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

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

# スタイル

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

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

名前	値の種類	デフォルト値
`brand-color`	16進数のカラーコード	`#108291`
`brand-hover-color`	16進数のカラーコード	`#065f69`
`brand-pending-color`	16進数のカラーコード	`#c7eded`
`page-background-color`	16進数のカラーコード	`#f7f9fa`
`container-max-width`	寸法	`1296px`
`container-margin-left`	寸法	`auto`
`container-margin-right`	寸法	`auto`
`container-padding-left`	寸法	`8px`
`container-padding-right`	寸法	`8px`

# 値の種類

種類	指定可能な値
16進数のカラーコード	3桁または6桁の16進数形式の CSS カラー (`#108291` や `#ccc`)
寸法	ピクセル単位の値または `auto`

Last updated: 2024/1/12 16:26:53