Widget APIでアクションをカスタマイズする
Widgetについて
Widgetでは、KARTEでエンドユーザーにアクションを表示するための標準的な機能が提供されています。
- 表示タイミングの制御
- 動的変数
- 表示ステート管理
- テンプレート構文
- Web Storageへのアクセス
Vue.jsライクなWidget APIで、Widgetの挙動をシンプルに記述することができます。チャットやスクリプト配信など一部のテンプレートを除くほぼ全てのアクションテンプレートで、Widget APIを使うことができます。
WidgetAPIと基本的な使用例
詳細はWidget APIリファレンスをご覧ください。
動的変数の表示
動的変数は widget.setVal(’変数名’) で値を動的にセットし、 widget.getVal('変数名') にて値を取得します。
HTMLから参照したい場合は、{{変数名}} の形で指定してください。
// 動的変数に値をセット
widget.setVal("cnt", 0);
// 動的変数に値を取得
widget.getVal("cnt");
<p>{{cnt}}</p>
動的変数の注意点
属性内で動的変数を参照する場合は、テンプレート構文ではなく、後述する
krt-bindをお使いください。
<!--悪い例-->
<img src="{{img_url}}">
<div style="background-image: url({{image_url}}"></div>
<!--良い例-->
<img krt-bind:src="img_url">
<div krt-bind:style="'background-image: url(' + image_url + ')'"></div>
Widgetのメソッド定義
イベントハンドラとして利用する関数は、 widget.method('関数名', function() {...}) で定義します。
widget.method('customClick', function() {
console.log('did custom click');
});
// widgetのステートを次に進めるメソッド例
widget.method('nextState', function() {
widget.setState(widget.getState() + 1);
});
DOM要素のイベントハンドラとして登録するには、 krt-on:click="関数名" のように krt-on ディレクティブを使います。
<div krt-on:click="customClick"></div>
<div krt-on:click="nextState"></div>
widgetの表示制御
表示する場合は widget.show() 、非表示するときは widget.hide() を利用します。
// widgetの表示
widget.show();
widget.method('closeBtnClick', function() {
// widgetを非表示化
widget.hide();
});
複数の表示ステートがあるWidgetについては、 widget.setState(ステート番号) で表示ステートを切り替えることができます。
widget.method('btnClick', function() {
// widgetの表示ステートを2に設定
widget.setState(2);
});
HTML側では、 krt-if ディレクティブを使ってステートに対応する表示要素を定義します。
<div class="wrapper">
<section krt-if="state === 1">
<div>...</div>
</section>
<section krt-if="state === 2">
<div>...</div>
</section>
</div>
なお、ステートが 0 の状態が非表示状態です。
前述した widget.show() は widget.setState(1) のエイリアス、 widget.hide() は widget.setState(0) のエイリアスになっています。
Web Storageへのアクセス
ページをまたいだデータの保存がしたい場合には、localStorageを使用することもできます。
Widget API経由でlocalStorageにアクセスすることで、keyにKARTE専用のprefixが付与されます。
var cnt = 0;
widget.storage.local.store("cnt", cnt, {
expire: 1000
});
cnt = widget.storage.local.restore("cnt");
Widget内からのイベント発火
Widget内からイベントを発火させる場合は、 tracker.track('イベント名') を利用します。発生させたイベントは、アクションの効果測定だけではなく、配信先ユーザーに紐付くユーザーデータとしても利用できます。Widget内から発生させたイベントには、デフォルトで接客サービスID（campaign_id）とアクションID（shorten_id）がフィールド内に追加されます。
widget.method('clicked', function(){
var timer = setTimeout(function() {
timer = null;
transition();
}, 3000);
tracker.track("message_click", {}, function() {
if (timer) {
clearTimeout(timer);
timer = null;
}
transition();
});
// 画面遷移の処理を記述
function transition() {
window.location.href = '/hoge';
}
});
定義済みイベント
なお下記のイベントは、実装しなくても自動で発生します。
message_open- Widget表示時に発生
message_click- リンククリック時に発生
message_close- 閉じるボタン押下時に発生
定義済みイベントを tracker.track で明示的に発火させることも可能です。
HTMLディレクティブ
Widgetでは、Widget側の動的変数やメソッドをDOM要素と紐付けるためのHTMLディレクティブが用意されています。
状態に応じた表示切り替え
krt-if を使うことで、動的変数の値に応じて表示する要素を切り替えることができます。
<div krt-if="isLoading">ロード中です...</div>
<div krt-if="!isLoading">コンテンツ</div>
イベントハンドラの登録
krt-on を使うことで、イベントハンドラを登録することができます。
<button krt-on:click="setState(1)">最小化する</button>
配列の展開
krt-for に配列が格納された動的変数を渡すことで、配列要素の数だけリストアイテムを繰り返し表示することができます。
var items = [
{name: "name0", url: "http://example.com/#0"},
{name: "name1", url: "http://example.com/#1"},
];
widget.setVal("items", items);
<div krt-for="item in items">
<a href={{item.url}}>
<div>{{item.name}}</div>
</a>
</div>
フォーム入力を動的変数にバインディングする
krt-model を使うと、フォーム部品の入力と動的変数とを双方向にバインディングすることができます。
widget.setVal('email', '');
widget.method('submit', function(){
var email = widget.getVal('email');
// submit処理
});
<input type="text" krt-model="email"/>
<button krt-on:click="submit">登録</button>
なお、入力内容の変更を検知するためには、 widget.onChangeVal('変数名', 関数) を利用します。
// 動的変数の値変更検知
widget.onChangeVal("email", function(v){
validate(v.newVal);
});
Updated 5 months ago