ガイド付きツアー - クライアント

  • リリースバージョン: Xanadu
  • 更新日 2024年08月01日
  • 所要時間：12分

    • ガイド付きツアー API は、ガイド付きツアーを開始および停止するためのメソッドを提供します。

    この API には 、ガイド付きツアーデザイナーで使用されるメソッドが含まれています。

    Guided Tours - applyListFilter(関数 filter_func)

    getAllTours() メソッドが呼び出されたときにフィルタリングされたツアー結果を取得する関数を設定します。

    完全な署名には、メソッド名の前に top.NOW.guided_tours.api が含まれています。

    表 : 1. パラメーター
    名前 タイプ 説明
    filter_func 関数 getAllTours() メソッドから返された tours[] アレイから単一の tour オブジェクトを取得するフィルター関数。
    表 : 2. 返される内容
    タイプ 説明
    なし

    次の例は、基本的な API を使った場合を示しています。

    //create a filter function
var filtFunction = function(tour) {
   //only return those tours whose name starts with 'my'
   return tour.name.indexOf('my') === 0);
}

//apply the filter 
top.NOW.guided_tours.api.applyListFilter (filtFunction);

//call the getAllTours method to observe the filtered tours
top.NOW.guided_tours.api.getAllTours (function(er, tours) {
  if(!er) {
    console.log('The filtered tours are: ');
    console.log(tours);
  }
});

    次の例は、ツアーオブジェクトの options フィールドを使用して、ツアーを読み取ってフィルタリングするためのカスタムのツアー識別子を含む JSON を filter_func() 関数内に追加する方法を示しています。

    top.NOW.guided_tours.api.applyListFilter(function(tour) {
       var options = (tour.options)? JSON.parse(tour.options): null;
       return (options && options.my_param) ? (options.my_param == my_value) : false;
});

    Guided Tours - endTour()

    現在再生中のツアーを停止します。再生中のツアーがない場合、このメソッドはメッセージなしで終了します。

    完全な署名には、メソッド名の前に top.NOW.guided_tours.api が含まれています。

    表 : 3. パラメーター
    名前 タイプ 説明
    なし
    表 : 4. 返される内容
    タイプ 説明
    Null 
    //create a callback function to end the tour if it starts correctly
var cbFunction = function(err) {
	if (err) {
   console.log('Error Occurred');
}
	else {
	   // tour has started so we can call endTour
	   top.NOW.guided_tours.api.endTour();
}
}

//calling the startTour method so that we can end the tour as soon as it starts
top.NOW.guided_tours.api.startTour('a297e04b732313007077edcc5ef6a780', 2, cbFunction);

    Guided Tours - events.off(文字列 event_name, 関数 listener_function)

    既存のイベントリスナーを削除します。

    完全な署名には、メソッド名の前に top.NOW.guided_tours.api が含まれています。

    表 : 5. パラメーター
    名前 タイプ 説明
    event_name 文字列 リスナーから削除するイベント名。
    有効なイベント名：
    • tourStarted
    • tourEnded
    • tourCompleted
    • tourFailed
    • tourAbandoned
    • tourDismissed
    • stepStarted
    listener_function 関数 オプション。指定した場合、指定されたリスナー関数が、そのイベントに添付されている残りのイベントリスナーから削除されます。指定しない場合、そのイベントに添付されているすべてのリスナー関数が削除されます。
    表 : 6. 返される内容
    タイプ 説明
    なし 
    //create a callback function to handle the result of the api call
var eventListenerTourStarted = function() {
   console.log('The tour has started'); 
}
var eventListenerTourEnded = function() {
   console.log('The tour has ended'); 
}

//attaching event listeners for tourStarted and tourEnded Events
top.NOW.guided_tours.events.on('tourStarted',eventListenerTourStarted);
top.NOW.guided_tours.events.on('tourEnded', eventListenerTourEnded);

…
//start a tour
top.NOW.guided_tours.api.startTour ('a297e04b732313007077edcc5ef6a780', 2, cbFunction);
//As soon as the tour starts the eventListenerTourStarted gets fired
…
top.NOW.guided_tours.api.endTour();
// eventListenerTourEnded gets fired

….

//removing the event listeners top.NOW.guided_tours.events.off('tourStarted',eventListenerTourStarted);
top.NOW.guided_tours.events.off('tourEnded', eventListenerTourEnded);

    Guided Tours - events.on(文字列 event_name, 関数 listener_function)

    チュートリアルイベントにイベントリスナーを添付します。

    完全な署名には、メソッド名の前に top.NOW.guided_tours.api が含まれています。

    表 : 7. パラメーター
    名前 タイプ 説明
    event_name 文字列 リスナーに添付するイベント名。
    有効なイベント名：
    • stepStarted
    • tourStarted
    • tourEnded
    • tourCompleted
    • tourFailed
    • tourAbandoned
    • tourDismissed
    listener_function 関数 追加するリスナー。
    注:
    目的を解決した後にイベントリスナーをクリアします。
    listener_function.obj オブジェクト 各イベントによって、次の形式で listener_function() に渡されます。
    • stepStarted イベントの場合： 
      {tour: '<tour_sys_id>', step: step_num}
    • 他のすべてのイベントの場合：
      {tour: '<tour_sys_id>'}
    JSON パラメーター：
    • tour_sys_id：文字列。Guided Tours [sys_embedded_tour_guide] テーブルから取得したチュートリアルの ID。
    • step_num：番号。0 (最初のステップ) と n (最後のステップ) の間の値

    次の例は、基本的な API を使った場合を示しています。

    //create a callback function to handle the result of the api call
var eventListenerTourStarted = function() {
   console.log('The tour has started'); 
}
var eventListenerTourEnded = function() {
   console.log('The tour has ended'); 
}

//attaching event listeners for tourStarted and tourEnded Events
top.NOW.guided_tours.events.on('tourStarted',eventListenerTourStarted);
top.NOW.guided_tours.events.on('tourEnded', eventListenerTourEnded);

…
//start a tour
top.NOW.guided_tours.api.startTour ('a297e04b732313007077edcc5ef6a780', 2, cbFunction);
//As soon as the tour starts the eventListenerTourStarted gets fired
…
top.NOW.guided_tours.api.endTour();
// eventListenerTourEnded gets fired

….

//removing the event listeners top.NOW.guided_tours.events.off('tourStarted',eventListenerTourStarted);
top.NOW.guided_tours.events.off('tourEnded', eventListenerTourEnded);

    次の例は、引数が obj の listener_function パラメーターを使用する方法を示しています。

    top.NOW.guided_tours.events.on("tourStarted", function (obj){console.log(obj);});

    Guided Tours - getAllTours(関数 cb_function)

    このメソッドが呼び出された現在のページにあるツアーのリストを取得します。このメソッドは非同期であるため、操作の成功を判断してツアーのリストを取得するためのコールバック関数を渡す必要があります。

    完全な署名には、メソッド名の前に top.NOW.guided_tours.api が含まれています。

    表 : 8. パラメーター
    名前 タイプ 説明
    cb_function 関数 getAllTours() メソッドが呼び出された現在のページのすべてのツアーをフェッチしようとした後に、getAllTours() によって呼び出されるコールバック関数。
    cb_function.err オブジェクト 操作中にエラーが発生した場合は、次のエラーオブジェクトを表示します。

    err = {success: false, message: 'エラーオブジェクトを含む文字列' }

    それ以外の場合は Null です。
    cb_function.tours アレイ ページで利用可能なツアーのリスト。

    ページにツアーが存在しない場合、cb_function.tours は undefined を返します。

    if(!tours) console.log('No tour present')
    表 : 9. 返される内容
    タイプ 説明
    なし 
    //create a callback function to handle the result of the API call
var cbFunction = function(err, tours) {
	if (err) {
   console.log('Error Occurred');
}
	else {
	    if(!tours) console.log('No tour present')
   else {
      tours.forEach(function(t) {
               console.log(t);
             });
          }
}
}
//calling the getTours method
top.NOW.guided_tours.api.getAllTours(cbFunction);

    Guided Tours - loadPlayer()

    チュートリアルプレーヤーがデフォルトで存在しないページにチュートリアルプレーヤーをロードします。

    完全な署名： 
    NOW.guided_tours.api.loadPlayer()
    表 : 10. パラメーター
    名前 タイプ 説明
    なし
    表 : 11. 返される内容
    タイプ 説明
    なし

    Guided Tours - startTour(文字列 tour_id, 番号 step_number, 関数 cb_function)

    ツアーを開始します。このメソッドは非同期であるため、操作の成功を判断するためのコールバック関数を渡す必要があります。

    完全な署名には、メソッド名の前に top.NOW.guided_tours.api が含まれています。

    表 : 12. パラメーター
    名前 タイプ 説明
    tour_id 文字列 Guided Tours [sys_embedded_tour_guide] テーブルから取得したツアーのSys ID。
    step_number 番号 オプション。ツアーを開始するステップ。指定しない場合 (またはステップ番号が 0 の場合)、ツアーは最初から開始されます。
    cb_function 関数 オプション。ツアーを開始しようとした後に startTour() メソッドによって呼び出されるコールバック関数。
    cb_function.err オブジェクト 操作中にエラーが発生した場合は、次のエラーオブジェクトを表示します。

    err = {success: false, message: 'エラーオブジェクトを含む文字列' }

    それ以外の場合は Null です。
    表 : 13. 返される内容
    タイプ 説明
    なし 
    //create a callback function to handle the result of the API call
var cbFunction = function(err) {
	if (err) {
   console.log('Error Occurred');
}
	else {
   console.log('The tour with tourid=%s was successfully launched', tourId);
}
}

//calling the startTour method
top.NOW.guided_tours.api.startTour('a297e04b732313007077edcc5ef6a780', 2, cbFunction);