Anyflow SDK v0.13.0

自社プロダクトに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

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

AnyflowSDK.init(fetchJwt);

initに指定する関数について

init に指定する関数は、必ず実行ごとに異なる JWT を返却する必要があります。 この JWT は内部でアクセストークンに交換されてから使用されますが、セキュリティ上の理由から、アクセストークンの発行には同じ JWT は2回以上使用できないようになっています。 SDK はアクセストークンの有効期限切れなどの理由によりこの関数を複数回実行することがあります。

注意

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

オプション

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

TypeScript

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

JavaScript

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

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

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

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

TypeScript

const sdk = AnyflowSDK.instance;

JavaScript

const sdk = AnyflowSDK.instance;

注意

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

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

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

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

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

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

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

TypeScript

const state: SolutionState = solution.state;

JavaScript

const state = solution.state;

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

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

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

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

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

TypeScript

solutionWizard.load("your_solution_id");

JavaScript

solutionWizard.load("your_solution_id");

ヒント

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

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

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

TypeScript

solutionWizard.unload();

JavaScript

solutionWizard.unload();

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

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

TypeScript

await sdk.uninstallSolution("your_solution_id");

JavaScript

await sdk.uninstallSolution("your_solution_id");

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

ソリューションウィザードが完了したりユーザーによってキャンセルされた時に処理を実行するには、 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

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

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

TypeScript

solutionWizard.removeListener(listener);

JavaScript

solutionWizard.removeListener(listener);

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

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

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

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

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

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

TypeScript

solutionWizard.load("your_solution_id");

JavaScript

solutionWizard.load("your_solution_id");

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

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

TypeScript

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

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

JavaScript

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

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

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

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

TypeScript

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

JavaScript

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

ヒント

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

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

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

TypeScript

sdk.unobserveJob("your_job_id", callback);

JavaScript

sdk.unobserveJob("your_job_id", callback);

ヒント

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

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

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

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

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

TypeScript

solutionWizard.loadHistory("your_solution_id");

JavaScript

solutionWizard.loadHistory("your_solution_id");

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

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

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

データとして取得するには、SDK の getJobs メソッドを使用します。

TypeScript

const jobs: Job[] = await sdk.getJobs("your_solution_id");

JavaScript

const jobs = await sdk.getJobs("your_solution_id");

getJobs の戻り値の Promise が解決すると、ソリューションの実行インスタンスを表す Job オブジェクトの一覧が得られます。実行履歴は直近の20件まで取得できます。 取得にはタイムラグが発生する場合があります。 連続的にgetJobsを実行する場合は、5~10秒程度の間隔を空けて実行してください。

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

My Event を送信する

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

TypeScript

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

JavaScript

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

この例では、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 を使用するソリューションをエンドユーザーが無効にしている場合