Anyflow SDK

自社プロダクトにAnyflowを組み込む際に使用するフロント SDK のドキュメントです。

SDK をインストールする

npm を使用して SDK をインストールするには次のコマンドを実行します。

npm install @anyflowinc/embed-sdk

npm を使用していない場合はこちらの Google ドライブからダウンロードして JavaScript ファイルを直接使用することも出来ます。参考：npm を使用していない場合の使用方法

SDK を初期化する

AnyflowSDK のインスタンスを取得する前に、 AnyflowSDK を init 関数で初期化する必要があります。

init 関数の引数には、 AnyflowSDK が JWT を取得するために使用する非同期関数を指定します。 ./path/to/your/jwt/endpoint には、自社プロダクトに実装したJWTエンドポイントを設定します。 （参考： JWTを生成する）

TypeScript

const fetchJwt = async () => {
  const res = await fetch("./path/to/your/jwt/endpoint");
  const json = await res.json();
  return json["token"];
};

AnyflowSDK.init(fetchJwt);

JavaScript

セキュリティ上の理由から、JWT生成関数は必ず実行ごとに異なる JWT を返却する必要があります。 具体的には、JWTのPayloadの中のjti（ユニークID）が毎回異なるようにしてください。 逆に、anyflow_team_idやanyflow_user_idなどの値は同一ユーザーの中では変わらないようにしてください。（参考：サンプルコード）

自動的なトークンリフレッシュ

SDKの内部では、JWTはアクセストークンに交換して使用されます。

アクセストークンが有効期限切れとなった場合等には、SDKはinit時に引数に与えられたJWT生成関数を自動で呼び出して新しいJWTを取得してから、再度アクセストークンを発行しリフレッシュを行います。

そのため、init時の引数にはJWTそのもの（固定値）を与えるのではなくJWTの生成関数を与えるようにしてください。

注意

SDK の初期化は、後述する destroy を呼び出すまで、2回実行することはできません。すでに初期化している状態でもう一度初期化しようとすると、 sdk_already_initialized エラーがスローされます。

オプション

init 関数の第2引数にオプションを指定できます。全てのオプションの指定は任意です。

TypeScript

AnyflowSDK.init(fetchJwt, {
  env: "staging"
});

JavaScript

オプション	説明	デフォルト値
env	デプロイ環境のユニーク名を指定します。指定しなければデフォルトデプロイ環境が使用されます。	undefined

SDK インスタンスを取得する

AnyflowSDK では、有効なインスタンスは1つのみ存在します。 SDK を初期化すると、 instance プロパティから有効な AnyflowSDK のインスタンスを取得することができるようになります。

TypeScript

const sdk = AnyflowSDK.instance;

JavaScript

注意

SDK を初期化する前に instance プロパティにアクセスすると、 sdk_not_initialized エラーがスローされます。

SDK インスタンスを破棄する

AnyflowSDK を初期化すると、ソリューションウィザードを表示するための iframe と通信するために window にメッセージハンドラが設定されます。

SDK インスタンスが不要になれば、これらのメッセージハンドラが残ったままにならないように、 SDK インスタンスを破棄することができます。

SDK インスタンスを破棄するには、 AnyflowSDK の destroy 関数を実行します。

注意

destroy を実行すると、それまでに使用していた SDK インスタンスはもう使用できなくなります。破棄した SDK インスタンスを使用しようとすると、 sdk_already_destroyed エラーがスローされます。 SDK インスタンスの isDestroyed プロパティによって、SDK インスタンスが破棄されているかどうかを確認できます。

もう一度 SDK インスタンスが必要になった場合は、改めて init 関数で AnyflowSDK を初期化してください。

ソリューションを取得する

getSolution メソッドを使用して特定のソリューションの情報 (Solution) を取得するか、 getSolutions メソッドを使用して現在使用可能なすべてのソリューションをリストで取得することができます。デプロイされていないソリューションは使用可能ではないため取得できません。

TypeScript

// 特定のソリューションの情報のみ取得する
const solution: Solution = await sdk.getSolution("solution_id");

// リストで取得する
const solutions: Solution[] = await sdk.getSolutions();

JavaScript

取得した Solution オブジェクトは不変です。 SDK を使用してソリューションの有効状態を変更しても、すでに取得してあった Solution オブジェクトの値が変更されることはありません。最新の値を取得するには、もう一度 getSolution メソッドで取得し直してください。

ソリューションの状態を確認する

ソリューションの状態を取得することで、エンドユーザーのソリューションの利用状況に応じて UI の表示を変更する等を実現できます。

ソリューションの状態は、取得した Solution オブジェクトの state プロパティからアクセスできます。

TypeScript

const state: SolutionState = solution.state;

JavaScript

SolutionState の値は、次のいずれかです：

state	説明
not_installed	まだソリューションがインストールされていません。
enabled	ソリューションが有効です。
disabled	ソリューションはインストールされていますが、有効にされていません。

ソリューションをインストールする

ソリューションをインストールするには、ソリューションウィザードと呼ばれる画面を表示し、ユーザーに各種設定項目を入力してもらう必要があります。

ソリューションウィザードを作成する

ソリューションウィザードの UI は Anyflow によって提供されるため、まずは createWizard メソッドを使用して SolutionWizard をインスタンス化します。 createWizard にはソリューションウィザードを表示させたい iframe を指定します。

TypeSctipt

const iframe = document.getElementById("solution_wizard");
const solutionWizard: SolutionWizard = sdk.createWizard(iframe);

JavaScript

iframe や SolutionWizard のインスタンスはソリューションごとに別々のものを使用することも、複数のソリューションで一つのものを共有して使用することもできます。

ウィザードを翻訳する

createWizard の第2引数にIETF言語タグを指定することで、ウィザードの内容を翻訳することができます。

sdk.createWizard(iframe, "en");

現在対応しているIETF言語タグは次の通りです

• en : 英語

• zh-Hans : 簡体中文

• zh-Hant : 繁体中文

• ja : 日本語(デフォルト)

ソリューションウィザードを iframe に読み込む

ソリューションウィザードを指定した iframe に表示させるには、 SolutionWizard オブジェクトの load メソッドを使用します。 load メソッドにはソリューションウィザードを表示したいソリューションの ID を指定します。

TypeScript

solutionWizard.load("your_solution_id");

JavaScript

ヒント

iframeのスタイルは自社プロダクト側で調整する必要があります。

ソリューションウィザードにデフォルト値を与える

ソリューションウィザードを iframe に読み込ませる際に、ウィザードで採用するデフォルト値を与えることができます。

TypeScript

solutionWizard.load("solution_id", {
  defaultInputs: [
    {
      type: "value",
      key: "...",
      value: "...",
    },
  ],
});

JavaScript

ソリューションウィザードを破棄する

iframe 内に表示したソリューションウィザードを破棄するには、 unload メソッドを実行します。ソリューションウィザードが完了またはキャンセルされたタイミングで unload することを推奨します。

TypeScript

solutionWizard.unload();

JavaScript

ソリューションをアンインストールする

ソリューションをアンインストールにするには、 sdk の uninstallSolution メソッドを実行します。ソリューションは再度インストールされるまで実行できなくなります。

TypeScript

await sdk.uninstallSolution("your_solution_id");

JavaScript

ソリューションウィザードの状態を監視する

ソリューションウィザードが完了したりユーザーによってキャンセルされた時に処理を実行するには、 SolutionWizard オブジェクトに対して addListener メソッドで SolutionWizardListener を設定します。

TypeScript

const listener: SolutionWizardListener = (event: SolutionWizardEvent, solutionId: string, solutionInstanceId?: string) => {
  if (event === "loaded") {
    // ソリューションウィザードが読み込まれたとき
  }
  if (event === "completed") {
    // ソリューションウィザードが完了したとき（ソリューションがインストールされたとき）
    // 完了したときのみ、リスナの第三引数 solutionInstanceId が渡ってきます
  }
  if (event === "canceled") {
    // ソリューションウィザードがキャンセルされたとき
  }
}
solutionWizard.addListener(listener);

JavaScript

リスナが不要になった場合は removeListener メソッドで削除できます。

TypeScript

solutionWizard.removeListener(listener);

JavaScript

ソリューションインスタンスIDについて

エンドユーザーがソリューションをインストールすると、completedのイベントが呼び出され、リスナの第三引数 solutionInstanceId が渡ってきます。 solutionInstanceId はベンダーサーバーAPIでも取得できます。

ソリューションの設定を変更する

インストールしたソリューションの設定を変更するには、ソリューションをインストールした時と同様、ソリューションウィザードを使用します。

インストール済みの状態でソリューションウィザードを表示すると、ユーザーが以前に設定した内容が入った状態のソリューションウィザードが表示されます。もう一度ウィザードを完了させることで、ソリューションの設定が変更できます。

ソリューションウィザードを iframe に読み込むには、インストール時と同じように、 SolutionWizard オブジェクトの load メソッドを実行します。

TypeScript

solutionWizard.load("your_solution_id");

JavaScript

ソリューションの有効状態を変更する

ソリューションを有効にするには sdk の enableSolution メソッドを、無効にするには disableSolution メソッドを実行します。

TypeScript

// 有効にする
await sdk.enableSolution("your_solution_id");

// 無効にする
await sdk.disableSolution("your_solution_id");

JavaScript

ソリューションを手動実行する

ユーザーの操作に応じてソリューションを手動実行するには、 SDK の runSolution メソッドを実行します。

TypeScript

const job = await sdk.runSolution("your_solution_id");

JavaScript

ヒント

runSolution メソッドで実行することができるのは、Clickトリガー（手動実行トリガー）が指定されているソリューションのみです。手動実行できないソリューションで runSolution を実行すると、 AnyflowError がスローされます。 Solution オブジェクトの runnable プロパティによって、手動実行トリガーが指定されているかどうかを確認できます。

ソリューションの実行状態を確認する

runSolution の戻り値として取得できる Promise を解決すると得られるのは、ソリューションの実行インスタンスを表す Job オブジェクトです。

Job オブジェクトも Solution オブジェクトと同じく不変で、実行状態が変更されてもすでに取得済みの Job オブジェクトの値が変更されることはありません。

ヒント

SDK の getJob メソッドを使用して、最新の Job オブジェクトを取得できます。

ソリューションの実行状態は Job オブジェクトの state プロパティを読み込むことで確認できます。

state	説明
running	この Job はまだ実行中です。
succeeded	この Job の実行は正常に完了しました。
failed	この Job の実行は失敗しました。

ソリューションの実行状態を監視する

Job オブジェクト自体は不変のため、実行状態が変更されてもそのオブジェクトは変更されません。

ソリューションの実行状態が変更された時に新しい Job オブジェクトを取得するには、 SDK の observeJob メソッドを実行してジョブの変更を監視する必要があります。

observeJob に指定する JobCallback はジョブが変更された時に呼び出されます。 JobCallback の第一引数は変更内容を表す JobEvent で、第二引数は変更後の値を持った Job オブジェクトです。

TypeScript

const callback: JobCallback = (event: JobEvent, job: Job) => {
  if (event === "state_changed") {
    // ここで実行状態が変更されたときの処理
  }
}
sdk.observeJob("your_job_id", callback);

JavaScript

監視を終了するには、 SDK の unobserveJob メソッドを実行します。

TypeScript

sdk.unobserveJob("your_job_id", callback);

JavaScript

ヒント

Job.state が succeeded または failed になると、明示的に unobserveJob を実行しなくても、監視は自動的に終了されます。

ソリューションの実行履歴を表示する

ソリューションの実行履歴画面

ソリューションの実行履歴を表示するには、 SolutionWizard オブジェクトの loadHistory メソッドを使用します。 loadHistory メソッドには実行履歴を確認したいソリューションの ID を指定します。

loadHistory メソッドを実行すると、ソリューションウィザードを作成するときに指定した iframe にソリューションの実行履歴が読み込まれます。

TypeScript

solutionWizard.loadHistory("your_solution_id");

JavaScript

iframe 内に表示したソリューションの実行履歴を破棄するには、 SolutionWizard オブジェクトの unload メソッドを実行します。 ソリューションの実行履歴を閉じると canceled イベントが発行されるので、そのタイミングで unload することを推奨します。

ソリューションの実行履歴を取得する

SDK の getJobs メソッドを使用すると、ソリューションの実行履歴を iframe に表示するのではなく、データとして直接 SDK から取得することができます。

TypeScript

const jobs: Job[] = await sdk.getJobs("your_solution_id", { page: 1, perPage: 100 });

JavaScript

第二引数には取得するページや件数を指定できます。 1度に取得できる件数（perPageの最大件数）は100件です。

getJobs の戻り値の Promise が解決すると、ソリューションの実行インスタンスを表す Job オブジェクトの一覧と、ページネーション等に関するメタデータが得られます。

{
  jobs: [Job, ...],
  meta: {
    total: number,
    page: number,
    perPage: number,
  }
}

SDKのバージョンが 0.14.1 以下の場合、ページネーションを行うことはできません。

0.14.1 以下での仕様

• getJobsの第二引数（page, perPage 等）を指定することはできません。

• 実行履歴は直近の20件のみ取得できます。

• Jobオブジェクトの一覧 [Job, ...] のみが返却されます

My Event を送信する

フロントエンドから直接 My Event を送信するには、sendMyEvent メソッドを使用します。

TypeScript

const payload: MyEventPayload = {
  "name": "taro",
  "is_admin": true
};
await sdk.sendMyEvent("user_created", payload);

JavaScript

この例では、user_created というキーを持つ My Event を、 payload 変数の値をペイロードとして送信しています。

payload には送信する My Event で設定済みのスキーマに合う構造のデータを指定してください。 スキーマに合わないペイロードを指定しても、このメソッドはエラーを返しません。

My Event のスキーマが求める値がペイロードに含まれていない場合、ソリューション内ではその変数の値は None になります。 たとえば、この例の My Event に { "email": "[email protected]" } をペイロードとして送信すると、ソリューション内の payload.name や payload.is_admin という変数の値は None になります。

次の場合、このメソッドの返す Promise は my_event_not_triggered エラーで reject されます。

• 指定した My Event が見つからない場合

• 指定した My Event を使用するソリューションが存在しない場合

• 指定した My Event を使用するソリューションをエンドユーザーがインストールしていない場合

• 指定した My Event を使用するソリューションをエンドユーザーが無効にしている場合