※このハンズオンは、JavaScriptに慣れた方が読むことを想定して書かれています。

Webサイトやネイティブアプリに配信されるWidgetタイプのアクションのカスタマイズを試してみましょう。この基礎編では、実際のアクションを編集する中で、次のような機能を体験します。

• イベントハンドラの登録
• 動的変数の利用
• Widgetの表示/非表示制御
• Widgetのステート制御
• 静的変数の利用
• ユーザー情報変数の利用

Widget配信の仕組み

まずはKARTEから配信するWidgetと呼ばれるアクションタイプについて、仕組みを学びましょう。

アクション配信の流れ

エンドユーザーがページを閲覧してからKARTEのアクションがクライアントで実行されるまでの流れは、次の記事の通りです。

• WebやNativeアプリへのアクション配信の仕組み

Widget APIとは何か？

WidgetやWidget APIと呼ばれるものの概要については、次の記事の通りです。

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

接客サービスをテスト配信する

まず、題材となるアクションをテスト配信するための接客サービスを作成します。
接客サービスのテスト配信の手順がわからない場合は、こちらの記事を参考にしてください。
「 特定ユーザーにのみテスト配信することはできますか？ 」
（必ず、テストセグメントに限定して配信するようにしてください。）

• 接客サービス名を設定します
  • 例: test_Widgetカスタマイズ基礎編
• [アクションを追加]します
• テンプレート選択画面の検索ボックスで「3商品」と検索します
• [最小化-複数商品（3商品）] というテンプレートを選択します
  • 似たテンプレートが多いので注意してください
    

テスト配信の設定を完了し、Webサイト上でテンプレートがそのまま自分に配信できることを確認します。

表示されない場合は、次の設定を確認します。

• アクションの配信率が100%になっているか？
• 同時配信がOKになっているか？
• 自分がテストセグメントに入っているか？

なお、この記事で実施するカスタマイズの内容の一部は、プレビュー画面でも確認できます。

クリック時イベントハンドラの追加

まずは、簡単なWidgetのカスタマイズを1つ体験してみます。
ポップアップのヘッダに数字を表示し、ヘッダ要素クリック時にカウントアップさせてみましょう。

• アクション編集画面を開きます
• ヘッダ文言を変更します
  • [ベーシック > アクション設定 > 拡大時詳細設定 > 見出し]を次のように変更します
    • クリック回数:

• [カスタマイズ > Script]タブを開きます
• WidgetにcountUp関数を追加します
  • JSの冒頭に次の記述を追加します
  • widget.setVal()で動的変数の値を追加・更新できます
  • widget.getVal()で動的変数の値を取得できます
  • widget.method()で、イベントハンドラに使える関数を登録できます

widget.setVal('cnt', 0);
widget.method('countUp', function() {
    var cnt = widget.getVal('cnt');
    widget.setVal('cnt', cnt+1);
});

• ヘッダクリック時のイベントハンドラとして関数countUpを追加し、動的変数cntを表示します
  • [HTML]タブを開き、該当箇所を次のように変更します
  • krt-on:event名で、イベントハンドラを登録できます
  • {{動的変数名}}で動的変数の値を参照できます

<!-- before -->
<div class="karte-temp-title">#{state2.title}</div>
<!-- after -->
<div class="karte-temp-title" krt-on:click="countUp">#{state2.title} {{cnt}}</div>

• [Script]タブ最下部の[アクション再実行]をクリックします
• プレビュー画面に表示されたポップアップのヘッダをクリックし、数字がカウントアップされることを確認します

• アクションを[保存]します

補足

• HTMLのテキストノードではなく属性値に対して動的変数の値を使う場合は、krt-bindを使用してください

<!--悪い例-->
<img src="{{image_url}}">
<div style="background-image: url({{image_url}}"></div>

<!--良い例-->
<img krt-bind:src="image_url">
<div krt-bind:style="'background-image: url(' + image_url + ')'"></div>

Widgetの表示/非表示制御

Widgetの表示/非表示をJavaScriptで制御できることを確認しましょう。

• [カスタマイズ > Script]を開き、該当箇所を次のように変更します
  • widget.show()で、Widgetを表示できます

// before
widget.show();

// after
setTimeout(function() {
    widget.show();
}, 3000);

• [Script]タブ最下部の[アクション再実行]をクリックします

• 3秒後にアイコンが表示されることを確認します

• さらにJSの最後に次のような処理を追加します

  • widget.hide()で、Widgetを非表示にできます

setTimeout(function() {
    widget.hide();
}, 6000);

• [Script]タブ最下部の[アクション再実行]をクリックします
• 3秒後にアイコンが表示され、6秒後に非表示になることを確認します
• 確認できたら、非表示処理はコメントアウトしておきます

// setTimeout(function() {
//     widget.hide();
// }, 6000);

• アクションを[保存]します

補足

• HTMLの特定の要素にkarte-closeというclassを追加すると、クリック時にWidgetが閉じるようになります
  • 「閉じる」ボタンを簡易実装するために使われています

<i class="karte-temp-close1 karte-close karte-temp-hover" krt-if="#{close.use1}"></i>

• 次の条件であれば、[ベーシック > 表示設定 > 表示・非表示タイミング]で、GUIからも設定できます
  • 時間による表示/非表示
    
  • スクロール率による表示/非表示
    

Widgetのステート変更

ステート管理機能を使うことで、Widget内で簡易的なページ遷移を実現できます。ステートは、JavaScriptから変更することができます。

• [ベーシック]タブの左上から、現在のアクションのステート一覧を確認します
  • 今回のテンプレートでは、1（縮小）と2(拡大)の2つのステートがあります

• JSをカスタマイズし、ステート2のヘッダをクリックすると、ステート1に遷移するようにします
  • [カスタマイズ > Script]を開きます
  • countUp関数の実装に1行追加します
  • widget.setState()で、Widgetのステートを変更できます

widget.method('countUp', function() {
    var cnt = widget.getVal('cnt')
    widget.setVal('cnt', cnt+1);
    widget.setState(1); // 追加
});

• [Script]タブ最下部の[アクション再実行]をクリックします
• ステート2のヘッダをクリックすると、ステート1に戻ることを確認します
• アクションを[保存]します

補足

• [ベーシック > 表示設定]から、次のような設定をすることができます
  • ステート名
  • ステート毎の表示位置

• [ベーシック]タブの左上から、ステートを追加できます

• ステートと表示するHTMLとの対応は、krt-ifを使って実現しています
  • ステートは、プリセットの動的変数stateに格納されています

    <div class="karte-temp-state1" krt-if="state==1" krt-on:click="setState(2)">
      <!--中略-->
    </div>
    <div class="karte-temp-state2" krt-if="state==2">
      <!--中略-->
    </div>

静的変数とユーザー情報変数の利用

GUIで設定できる静的変数や、ユーザー毎に異なる値を参照できるユーザー情報変数を追加し、アクションで利用してみましょう。

• [カスタマイズ > 変数 > 静的変数]を開きます
• [変数の追加]をクリックします
• 追加した変数に、次のような設定をします
  • 変数名
    • title2
  • 表示タイプ
    • テキスト（デフォルトのまま）
  • 表示名
    • 見出し2

• ヘッダを2つに複製し、下のヘッダに静的変数title2を表示させます
  • [カスタマイズ>HTML]を開きます
  • HTMLのヘッダに対応する行を直後にコピーし、次のように書き換えます
  • #{静的変数名}で、静的変数の値を参照できます

<div class="karte-temp-title" krt-on:click="countUp">#{state2.title} {{cnt}}</div>
<div class="karte-temp-title">#{title2}</div>

• [ベーシック > アクション設定 > 見出し2]に次のように入力します
  • お使いのブラウザ:
• 次のように表示されることを確認します

• [ベーシック > アクション設定 > データ管理]を開きます
• [ユーザー情報変数]を追加し、次のように設定します
  • 変数名
    • browser
  • 参照するユーザーデータ
    • すべての期間 閲覧(view) アクセス時のブラウザ名 の 最新の値
  • プレビュー値
    • 未計測
    • ※プルダウン選択ではなく直接入力してください

• 追加したユーザー情報変数を、先ほど追加したヘッダに設定します
  • [カスタマイズ > HTML]を開き、次のようにHTMLを編集します
  • #{ユーザー情報変数名}で、ユーザー情報変数の値を参照できます

<div class="karte-temp-title">#{title2} #{browser}</div>

• プレビューのヘッダに お使いのブラウザ: 未計測 と表示されることを確認します

• アクションを[保存]します
• 実配信で表示し、実際に使っているブラウザが表示されることを確認します

補足

• ユーザー情報変数を設定したアクションは、そのユーザー情報を持たないユーザーには配信されません
  • それを回避するために、ユーザー情報変数にデフォルト値を設定することもできます

次のステップ

応用編の用意もあります。ぜひチャレンジしてみてください。

Widgetをカスタマイズしてみよう（応用編） | KARTEサポートサイト

関連ドキュメント

Widgetの主な機能については、下記ガイドでも紹介しています。

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

また今回紹介した機能のリファレンスは、下記の通りです。

• widget.method()
• widget.setVal()
• widget.getVal()
• krt-on
• krt-bind
• widget.show()
• widget.hide()
• karte-close
• widget.setState()
• krt-if
• 静的変数
• ユーザー情報変数