JavaScript SDK リファレンス

スタートアップガイド

• JavaScript SDK (以下JS SDK )は Sprocket の接客情報をブラウザで利用するための関数群です。
• JS SDK を用いることで、接客にサイト独自の機能を組み合わせるなどの柔軟なカスタマイズを行うことが可能になります。
• 本ガイドは、HTML、CSS そして JavaScript が理解できる程度のフロントエンドの知識を前提にしています。

📘

サンプルコードの動作を試すには

Sprocket タグの入っているページにて、ブラウザの開発者ツールなどのコンソールから手軽に動作確認を行えます。

例えば、 SPSDK.gears.navigation.on('shown', function() { console.log('Hello'); }) の動作を確認したい場合、コンソールからこのコードを実行した後、Sprocket プレビューツール にてシナリオを開始します。ステップ表示のタイミングでコンソールに 'Hello' が表示されることが確認できればOKです。

JS SDK の最上位オブジェクト「SPSDK」について

SPSDK は JS SDK の関数群を提供する、オブジェクト型のグローバル変数です。
Sprocket タグによって Sprocket を読み込む場合、ブラウザのグローバル変数として SPSDK が生成されます。
JS SDK が提供する全ての関数は、基本的に SPSDK 以下のメソッド、もしくは下位オブジェクトのメソッドとして定義されており、SPSDK によって JS SDK の関数を利用できます。
関数の詳しい利用法を下記にてご説明します。

リファレンス

SPSDK.ready( callback )

JS SDK の初期化完了を待ってコールバックを実行します。

サンプル

var handler = function() {
  console.log('ready');
}
SPSDK.ready(callback);

引数

• callback function() { ... }
  コールバック関数を指定します。
  SPSDK.ready を複数回実行すると複数のコールバックが登録されます。
  登録されたコールバックは登録順に実行されます。

  • 戻り値 void

戻り値

• void

詳細

• JS SDK の初期化完了前に ready が実行された場合は、初期化の完了を待って callback を遅延実行します。
• JS SDK 初期化の完了後に ready が実行された場合は callback を即時実行します。

SPSDK.userReady( callback )

［Sprocket ユーザー ID］のセット完了を待ってコールバックを実行します。

サンプル

var handler = function() {
  console.log('userReady');
}
SPSDK.userReady(callback);

引数

• callback function() { ... }
  コールバック関数を指定します。
  SPSDK.userReady を複数回実行すると複数のコールバックが登録されます。
  登録されたコールバックは登録順に実行されます。

  • 戻り値 void

戻り値

• void

詳細

• ［Sprocket ユーザー ID］がセットされる前に userReady が実行された場合は、完了を待って callback を遅延実行します。
• ［Sprocket ユーザー ID］がセットされた後にuserReadyが実行された場合は callback を即時実行します。

SPSDK.registerHook( event, handler )

セッションやトラッキングの開始に関連して発生するイベントに対してイベントハンドラーを追加します。

サンプル

var handler = function() {
  console.log('beforeSessionStart');
}
SPSDK.registerHook('beforeSessionStart', handler);

引数

• event string
  イベントの名前を文字列で指定します。
  指定できるイベントは 'beforeSessionStart' 'afterSessionStart' 'beforePageViewTracker' 'afterPageViewTracker' のいずれかです。

• handler function() { ... }
  イベントハンドラーを指定します。
  SPSDK.registerHook を複数回実行すると複数のイベントハンドラーが登録されます。
  登録されたイベントハンドラーは登録順に実行されます。
  コールバック関数が Promise を返す場合はそれが resolve するまで次のコールバック関数が呼ばれません。

  • 戻り値 void

戻り値

• void

詳細

• handler の実行タイミングは event の値によって下記の様に変動します。

  • 'beforeSessionStart'
    Sprocket セッションの開始直前に handler を実行します。

  • 'afterSessionStart'
    Sprocket セッションの開始直後に handler を実行します。

  • 'beforePageViewTracker'
    行動データの計測開始直前に handler を実行します。

  • 'afterPageViewTracker'
    行動データの計測開始直後に handler を実行します。

SPSDK.gears.navigation.on( events , handler )

シナリオ発動に関連して発生するイベントに対してイベントハンドラーを追加します。

サンプル

handler =  function(e, info) {
  console.log('start');
}
SPSDK.gears.navigation.on('start', handler);

引数

• event string
  イベントの名前を文字列で指定します。
  指定できるイベントは 'start' 'show' 'close' 'end' 'shown' 'click' のいずれかです。
  複数の場合はスペースで区切ります。

• handler function(e, info) { ... }
  イベント発生時に実行されるイベントハンドラーを指定します。
  SPSDK.gears.navigation.on を複数回実行すると複数のイベントハンドラーが登録されます。
  登録されたイベントハンドラーは登録順に実行されます。
  コールバック関数が Promise を返す場合はそれが resolve するまで次のコールバック関数が呼ばれません。

  • 戻り値 void

• handler の引数

  • e JQuery.Event
    jQuery イベントオブジェクトです。
    詳細は jQuery API Documentation/Event Objectを参照してください。

  • info {group: string, scenario: string, phase: string, pattern: string, step: string}
    シナリオの情報が格納されたオブジェクトです。
    プロパティはeventの値によらず同じです。
    データ例: {group: "target", scenario: "scenario1", phase: "phase1", pattern: "pattern1", step: "step_01"}

詳細

• event の値によって handler の実行タイミングが変化します。

  • 'start'
    シナリオの開始時に handler を実行します。

  • 'show'
    ステップの表示直前をフックして handler を実行します。

  • 'shown'
    ステップの表示直後をフックして handler を実行します。

  • 'close'
    ステップの×ボタンの押下をフックして handler を実行します。

  • 'end'
    シナリオの終了をフックして handler を実行します。

  • 'click'
    ステップに標準で設定されるボタンのクリックをフックして handler を実行します。

トラブルシューティング

• SPSDK オブジェクトの生成前に SPSDK を呼び出すと変数が存在せずエラーになる
  Sprocket タグの読み込みより後に SPSDK オブジェクトを呼び出す様にしてください。

• Sprocket ユーザーを扱う処理が失敗する
  ユーザー情報の初期化前にユーザー情報にアクセスしたために処理が失敗している可能性があります。
  userReady 以降に実行されるコールバックやイベントハンドラー内で、ユーザー情報へのアクセスを実行してください。

📘

ユーザーIDのセット処理について

ページ来訪者が［Sprocket ユーザー ID］を持っているかどうかで、ユーザー ID のセット処理の内容は分岐します。

ページ来訪者が［Sprocket ユーザー ID］を持っている：ユーザー情報の取得を行う
ページ来訪者が［Sprocket ユーザー ID］を持っていない：ユーザーの作成を行う

いずれの場合にも処理が完了したタイミングで userReady が呼び出されます。