🏗️

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

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

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

概要

本ドキュメントは、STANDSが提供するOnboarding を自社プロダクトへ導入するにあたり、

必要なインテグレーションについて情報をまとめたものです。

対象者

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

💎 Javascriptタグの形式について

以下のJSタグを本番環境に挿入してください。

<script type="text/javascript">
const userAgent = window.navigator.userAgent.toLowerCase();
if (userAgent.indexOf('msie') === -1 && userAgent.indexOf('trident') === -1 ){
 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 = [
    "Onboardingを除外したいパスをカンマ区切りで指定"
 ];
 ONB._custom_functions = {   
  // "Onboardingイベント名" : "お客様CallBack関数"
  "ready": "callback関数名",
  "intro_displayed": "callback関数名",
  "goal_started": "callback関数名",
  "step_displayed": "callback関数名",
  "step_forwarded": "callback関数名",
  "step_aborted": "callback関数名",
  "goal_completed": "callback関数名",
  "hint_displayed": "callback関数名",
  "hint_hidden": "callback関数名"
 };

// 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>

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

#パラメータ名概要
1

aid

アカウントID (顧客ごとに固定)

2

pid

プロダクトID (プロダクトごとに固定)

3

display_mode

preview　の場合、下書き状態のガイドが参照できます。 自社プロダクトの検証環境へこのタグを張り、リリース前の状態を確認したいときにご利用ください。

4

ONB._queryparam

Key:Value の連想配列形式でパラメータを指定。 用途は後述。

5

ONB.black_list

OnboardingのAPIリクエストを行いたくないページURLを指定。

6

ONB._custom_functions

Key:Value の連想配列形式でパラメータを指定。 コールバックイベントを受け取るファンクション名を指定。

イベント一覧

#イベント名引数概要
1

ready

第一引数:初めてのOnboarding起動であればTrue 、2回目以降であればFalse　(boolean型)

Onboardingのスクリプトが初期化され、利用可能な状態。スクリプトタグが発火されるたびにコールされます。

2

intro_displayed

イントロが表示された状態

3

goal_started

goal_id: 開始されたゴールID step_id : 開始されたステップID

ゴールが開始された状態

4

step_displayed

goal_id: 表示されたゴールID step_id : 表示されたステップID

ステップが表示された状態

5

step_forwarded

goal_id: ゴールID step_id : 次に表示されたステップID

ステップが次へ進んだ状態

6

step_aborted

goal_id: 離脱されたゴールID step_id : 離脱されたステップID

ステップから離脱した状態

7

goal_completed

goal_id: 完了されたゴールID step_id : 完了されたステップID

ゴールが完了された状態

8

hint_displayed

hint_id: 表示されたヒントID

ヒントが表示された状態

9

hint_hidden

hint_id: 非表示にされたヒントID

ヒントが非表示にされた状態

※ goal_id step_id はいずれもstring型になります。

検証環境で下書きモードのプレビューを行いたい場合は、以下のようになります。リクエストパラメータにdisplay_mode=preview　を追加します。その他の形式は同じです。

<script type="text/javascript">
const userAgent = window.navigator.userAgent.toLowerCase();
if (userAgent.indexOf('msie') === -1 && userAgent.indexOf('trident') === -1 ){
 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 = [
    "Onboardingを除外したいパスをカンマ区切りで指定"
 ];
 ONB._custom_functions = {   
  // "Onboardingイベント名" : "お客様CallBack関数"
  "ready": "callback関数名",
  "intro_displayed": "callback関数名",
  "goal_started": "callback関数名",
  "step_displayed": "callback関数名",
  "step_forwarded": "callback関数名",
  "step_aborted": "callback関数名",
  "goal_completed": "callback関数名",
  "hint_displayed": "callback関数名",
  "hint_hidden": "callback関数名"
 };

// 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>

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

概要

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

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

サンプル


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

パラメータ一覧

ID項目概要推奨 or 任意
1

user_id

ユーザーID

推奨
2

user_name

ユーザー名

任意
3

user_group_id

ユーザーが紐づく企業ごとのID

推奨
4

user_group_name

ユーザーが紐づく企業名

任意

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

概要

Onboardingに特定のパラメータが渡ってきた場合、表示するガイドを分ける事ができます。

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

下記の例でいえば、

"plan": "free" が渡ってきた際には、特定のガイドを表示させるように分岐する事ができます。

サンプル


ONB._queryparam = {
    "user_id":"ユーザIDを指定してください",
    "user_name":"ユーザ名を指定してください",
    "user_group_id":"企業IDを指定してください",
    "user_group_name":"企業名を指定してください",
    "plan":"free"
}

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

概要

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

ここにパスを指定すると、指定されたページからは、OnboardingのAPIへリクエストを行いません。

サンプル


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

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

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


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" }