Onboardingインテグレーションガイド
🏗️

Onboardingインテグレーションガイド

💡
このページはWEBで公開されています。2022/8/5 更新。

💎 本ドキュメントについて

概要

本ドキュメントは、STANDSが提供するOnboarding を、お客様サイトへ導入するために必要となる情報をまとめたものです。

対象者

自社プロダクトを管理するプロダクトマネージャー、フロントエンドエンジニアの方々を対象としています。

💎 JavaScriptタグの形式について

※こちらは仕様を確認頂くためのサンプルタグです。実際に設置頂くタグはOnboardingの管理画面内「タグ」から発行できます。

本番環境タグ

以下のJavaScriptタグを本番環境のheadタグ内に設置してください。

<script type="text/javascript">
var userAgent = window.navigator.userAgent.toLowerCase();
if ((userAgent.indexOf('msie') === -1 && userAgent.indexOf('trident') === -1) && !document.querySelector("#stands_onbd_point")) {
  var ONB = ONB || {};
  ONB.ignition_url = "https://api.onboarding-app.io/v1/onboarding-init?aid=xx&pid=xx";

  // Custom Area Start=====================
  ONB._queryparam = {
      "user_id":"ユーザID",
      "user_name":"ユーザ名",
      "user_group_id":"企業ID",
      "user_group_name":"企業名"
  }
  ONB.black_list = [];
  ONB._custom_functions = {};
  // Custom Area End======================

  ONB.embed = function(){for(ONB.item in ONB._queryparam){ONB.ignition_url+="&"+ONB.item+"="+ encodeURIComponent(ONB._queryparam[ONB.item])}for(ONB.d=0;ONB.d<ONB.black_list.length;ONB.d++){if(location.href.indexOf(ONB.black_list[ONB.d])!=-1){return}}if(Object.keys(ONB._custom_functions).length>0){ONB.ignition_url+="&custom_functions="+encodeURIComponent(JSON.stringify(ONB._custom_functions))}ONB.b=document.createElement("script"),ONB.c=document.getElementsByTagName("head")[0];ONB.b.src=ONB.ignition_url;ONB.b.id="stands_onbd_point";ONB.b.charset="utf-8";ONB.b.async="async";ONB.c.appendChild(ONB.b);};
  ONB.embed();
}
</script>

テスト環境タグ

検証環境で下書きモードのプレビューを行う場合、以下のJavaScriptタグを検証環境のheadタグに設置してください。

リクエストパラメータにdisplay_mode=preview が追加されています。

<script type="text/javascript">
var userAgent = window.navigator.userAgent.toLowerCase();
if ((userAgent.indexOf('msie') === -1 && userAgent.indexOf('trident') === -1) && !document.querySelector("#stands_onbd_point")) {
  var ONB = ONB || {};
  ONB.ignition_url = "https://api.onboarding-app.io/v1/onboarding-init?aid=xx&pid=xx&display_mode=preview";

  // Custom Area Start=====================
  ONB._queryparam = {
      "user_id":"ユーザID",
      "user_name":"ユーザ名",
      "user_group_id":"企業ID",
      "user_group_name":"企業名"
  }
  ONB.black_list = [];
  ONB._custom_functions = {};
  // Custom Area End======================

  ONB.embed = function(){for(ONB.item in ONB._queryparam){ONB.ignition_url+="&"+ONB.item+"="+ encodeURIComponent(ONB._queryparam[ONB.item])}for(ONB.d=0;ONB.d<ONB.black_list.length;ONB.d++){if(location.href.indexOf(ONB.black_list[ONB.d])!=-1){return}}if(Object.keys(ONB._custom_functions).length>0){ONB.ignition_url+="&custom_functions="+encodeURIComponent(JSON.stringify(ONB._custom_functions))}ONB.b=document.createElement("script"),ONB.c=document.getElementsByTagName("head")[0];ONB.b.src=ONB.ignition_url;ONB.b.id="stands_onbd_point";ONB.b.charset="utf-8";ONB.b.async="async";ONB.c.appendChild(ONB.b);};
  ONB.embed();
}
</script>

リクエストパラメータ一覧

以下は、上記JavaScriptタグにパラメータとして設定できるオプションの一覧です。

パラメータ名
値
補足
aid
アカウントID (お客様ごとに固定)
アカウントIDは変更しないでください。
pid
プロダクトID (プロダクトごとに固定)
プロダクトIDは変更しないでください。
display_mode
検証環境での利用の場合はpreview を指定。
本番公開前に、検証環境で下書き状態のガイドを確認したいときにご利用ください。
ONB._queryparam
Key:Value形式でパラメータを指定。
用途は後述。
ONB.black_list
Onboardingを利用しないURLを相対パス形式で指定。
ONB._custom_functions
Key:Value形式でパラメータを指定。
用途は後述。

💎 顧客アカウントごとのレポートを見たい [推奨]

概要

Onboardingにユーザー情報、企業情報を表す特定のパラメータが渡ってきた場合、ログ集計時にユーザー情報を紐付けることができます。それにより、どの企業の、どのユーザーが、どのガイドをどこまで表示したのか、を把握することができます。

ONB._queryparam 内に以下のようにKey:Value形式でパラメータを指定できます。

サンプル

ONB._queryparam = {
    "user_id":"123",
    "user_name":"オンボ太郎",
    "user_group_id":"456",
    "user_group_name":"株式会社STANDS"
}

デフォルトのパラメータ一覧

項目
概要
推奨 or 任意
user_id
ユーザーID
推奨
user_name
ユーザー名
任意
user_group_id
ユーザーが紐づく企業ごとのID
推奨
user_group_name
ユーザーが紐づく企業名
任意

💎 パラメータによって、表示するガイド分けたい [任意]

概要

Onboardingに特定のパラメータをお渡しいただくことで、表示するガイドを分ける事ができます。

ONB._queryparam 内に任意のKey:Value形式でパラメータを指定できます。

利用例

ユーザープランよってOnboardingのガイドを出し分けたい場合の設定例を以下に示します。

  • "plan": "free" のユーザーに対しては無料ユーザー向けガイドを表示
  • "plan": "premium" のユーザーに対してはアップセルを促すガイドを表示
ONB._queryparam = {
    "plan":"free"
}

※ パラメーターが送信できているかの確認は本ドキュメント内の疎通確認についてを参照ください。

設定内容

ガイドの出しわけを行いたい場合、以下2点の設定をお願いします。

💎 特定のページだけOnboardingを表示したくない [任意]

概要

Onboardingを表示したくないページを、URLごとに指定できます。（相対パス指定となります。）

利用例

ログインページではツアーを利用しないので、Onboardingを表示しない。

ONB.black_list = [
    "/login", 
];

💎 Onboardingのツアーをカスタマイズしたい [任意]

カスタムファンクション機能をご利用ください。行いたい処理をONB._queryparam 内に記述することで、既存の機能を拡張するようなカスタマイズが可能です。

詳しくは「カスタムファンクション設定」を参照ください。

💎 疎通確認について [任意]

ブラウザのコンソールから以下を実行してください。

STANDSUnit.custom_query_list.user_id

上記によって、queryParamで与えていたパラメータが返却されていれば、Onboardingに連携が成功となります。以下は返却例となります。

"1"

また、user_id user_group_id などの予約されたパラメータ以外に、

任意のパラメータをqueryParamで与えている場合には、ブラウザコンソールから以下を実行してください。

STANDSUnit.custom_query_list

上記によって、queryParamで与えていたパラメータが返却されていれば、Onboardingに連携が成功となります。以下のJSONは返却例となります。

{ user_group_id: "10", user_group_name: "株式会社テストグループ", user_id: "1234", user_name: "テストユーザー", role: "admin", plan: "premium" }