Widget APIでアクションをカスタマイズする

Widgetについて

Widgetでは、KARTEでエンドユーザーにアクションを表示するための標準的な機能が提供されています。

  • 表示タイミングの制御
  • 動的変数
  • 表示ステート管理
  • テンプレート構文
  • Web Storageへのアクセス

チャットやスクリプト配信など一部のテンプレートを除くほぼ全てのアクションテンプレートでWidget APIを利用することができます。

なお、詳細はWidget APIリファレンスをご覧ください。

WidgetAPIと基本的な使用例

動的変数の表示

動的変数は 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などのWeb Storageを使用します。

Widget API経由でWeb Storageにアクセスすることで、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 4 months ago

Widget APIでアクションをカスタマイズする


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.