# \[Cordova]設定値を利用する

Key-Valueで構成される値をKARTE経由で配信したい場合は、設定値配信機能を利用することで実現可能です。

アプリケーションの設定などをKARTEに切り出して管理することで、アプリケーションをリリースすることなく、挙動を変更することが可能になります。

### 変数参照の実装

### STEP1: 変数を取得する

管理画面上で設定した変数は、SDKを初期化しただけでは取得されません。\
変数を利用する前に、事前にリモートから取得する必要があります。

変数を取得するには `KarteVariables` オブジェクトの `fetch()` メソッドを呼び出します。

`fetch()`は要素の表示の直前や、セグメント更新の直後といった任意のタイミングで実行することが一般的です。\
実行のタイミングについての注意事項等は、[設定値配信のベストプラクティス](https://app.developers.karte.io/karte-for-app-best-practices/best-practices-for-variables-module)も合わせてご確認ください。\
※前セッションで配信済みのキャッシュをリセットしたい場合は、アプリケーション起動時（SDKの初期化直後）にも呼び出すことを推奨しております。

{% code overflow="wrap" %}

```javascript
document.addEventListener("deviceready", onDeviceReady, false);

function onDeviceReady() {
	KarteVariables.fetch();
}
```

{% endcode %}

`fetch()` メソッドを呼び出すと、SDKは変数取得（ `_fetch_variables` ）イベントを発行し、これをトリガーに設定値配信の接客サービスが配信されます。

この時、配信された接客サービスに含まれる変数は端末にキャッシュされます。\
加えて、変数を取得した時点で既にキャッシュされた変数がある場合は、キャッシュされた全変数を削除した上で新たに取得した変数をキャッシュします。\
また、これと同時にSDKは表示準備（ `_message_ready` ）イベントを発行します。

{% hint style="info" %}
**変数名の重複**

配信された複数の接客サービスの間で、同名の変数が定義されている場合は、接客サービスの `最終更新日時` が最近のものがキャッシュされます。
{% endhint %}

### STEP2: 変数を参照する

1. 変数オブジェクトを取得

{% code overflow="wrap" %}

```javascript
KarteVariables.getVariable("参照する変数名を指定").then(function(variable) {
  // 変数オブジェクトにアクセスできる
});
```

{% endcode %}

2. 変数オブジェクトから値を取得\
   管理画面上で設定した変数は、変数オブジェクト内で文字列型で保持されています。\
   変数オブジェクトから値を取得して利用する場合は、任意の型にキャストして利用します。

{% tabs %}
{% tab title="Swift" %}
{% code overflow="wrap" %}

```swift
// 文字列型で参照
variable.getString("foo").then(function(value) {
  // 文字列にアクセスできる
});

// プリミティブではない値（String / Array / Object）は、デフォルト値の指定をせず参照することも可能
// 値がない場合は `nil` が返ります。
variable.getArray().then(function(value) {
  // 配列にアクセスできる
});
```

{% endcode %}
{% endtab %}

{% tab title="Objective-C" %}
{% code overflow="wrap" %}

```objectivec
// 文字列型で参照
[variable stringWithDefaultValue:@"foo"];

// プリミティブではない値（String / Array / Dictionary）は、デフォルト値の指定をせず参照することも可能
// 値がない場合は `nil` が返ります。
[variable array];
```

{% endcode %}
{% endtab %}
{% endtabs %}

{% hint style="info" %}
**デフォルト値**

キャッシュされていない変数を参照した場合や、指定した型にキャストできない場合にデフォルト値が返ります。
{% endhint %}

### 効果測定の実装

設定値配信機能では、配信した変数を利用するだけでなく、その変数を利用した接客の効果を測定することが可能です。

ここでは説明のために、配信した変数を利用してバナーを表示するケースを例に話を進めます。

接客サービス名は「トップバナー」とし、配信する変数は下記の2変数とします。

| 変数名                     | 内容                   |
| ----------------------- | -------------------- |
| TOP\_BANNER\_IMAGE\_URL | バナー画像のURL            |
| TOP\_BANNER\_LINK\_URL  | バナー画像をクリックした時の遷移先URL |

なお、ここでは変数を利用してバナーを作成する処理については解説しません。\
変数の参照については、[変数参照の実装](#section-変数参照の実装) を参考にしてください。

### インプレッションを計測する

バナーが表示されたタイミングで、`message_open` イベントを送信することでインプレッションを計測することが可能です。\
なお `message_open` は `KarteVariables` オブジェクトの `trackOpen()` メソッドで送信することが可能です。

{% code overflow="wrap" %}

```javascript
// バナーが表示されたタイミングで、下記処理を実行
var commands = [
  KarteVariables.getVariable("TOP_BANNER_IMAGE_URL"),
  KarteVariables.getVariable("TOP_BANNER_LINK_URL")
];
Promise.all(commands).then(function(variables) {
  return KarteVariables.trackOpen(variables);
});
```

{% endcode %}

### クリックを計測する

バナーがクリックされたタイミングで、`message_click` イベントを送信することでクリックを計測することが可能です。\
なお `message_click` は `KarteVariables` オブジェクトの `trackClick()` メソッドで送信することが可能です。

{% code overflow="wrap" %}

```javascript
// バナーがクリックされたタイミングで、下記処理を実行
var commands = [
  KarteVariables.getVariable("TOP_BANNER_IMAGE_URL"),
  KarteVariables.getVariable("TOP_BANNER_LINK_URL")
];
Promise.all(commands).then(function(variables) {
  return KarteVariables.trackClick(variables);
});
```

{% endcode %}

## 設定値配信の接客サービスの設定

[設定値配信の接客サービス](https://support.karte.io/post/reO1yrya5guq8jPqLIclh)をご確認ください。


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://app.developers.karte.io/cordova-sdk/variables-cordova-sdk.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.