# \[iOS]設定値配信を利用する

**設定値配信**とは、アプリのアップデートをユーザーが行わなくても、アプリのネイティブの要素であるバナーや文言をKARTE上から変更できる機能になります。 この機能により、KARTEで作成したセグメント別に異なるキャンペーンバナーを表示したり、ボタンの色やテキストのA/Bテストを行うことによりアプリの改善が行えます。

設定値配信を利用するには、設定値配信用の接客を管理画面で設定する必要があります。 詳細については[設定値配信の概要](https://support.karte.io/post/0MTjCYQQZxiaqvsTjSpKb)を参照ください。

{% hint style="warning" %}
**設定値配信でのmessage\_open, message\_clickイベントについて**

KARTEで配信されたポップアップやアプリPUSH通知では表示, クリック時にmessage\_open, message\_clickイベントが自動送信されますが、設定値配信の場合は自動送信されません。

設定値配信で配信された変数の表示, クリック時に、独自でmessage\_open, message\_clickを発生させる実装が必要になります。

詳細は[インプレッションを計測する](#インプレッションを計測する)、[クリックを計測する](#クリックを計測する)を御覧ください。
{% endhint %}

## 導入手順

設定値配信は、`KarteVariables` モジュールを導入することで利用可能です。 [Variablesのリファレンス](https://plaidev.github.io/karte-sdk-docs/ios/latest/KarteVariables/Classes/Variables.html)も合わせてご確認ください。

1. Podfile の編集 プロジェクトディレクトリにある `Podfile` を任意のエディタで開き、`KarteVariables` の Pod を追加します。

{% code title="Podfile" overflow="wrap" %}

```ruby
pod 'KarteVariables'
```

{% endcode %}

2. Pod のインストール プロジェクトディレクトリで下記コマンドを実行し、Pod をインストールします。

{% code overflow="wrap" %}

```bash
pod install
```

{% endcode %}

## 変数参照の実装

### 1. サーバサイドの変数を取得しキャッシュに格納する

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

#### 1-1. SDKのインポート宣言を追加

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

```swift
import KarteVariables
```

{% endcode %}
{% endtab %}

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

```objc
@import KarteVariables;
```

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

#### 1-2. 変数の取得

変数を取得するには `Variables` クラスの `fetch()` メソッドを呼び出します。

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

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

```swift
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
  KarteApp.setup(appKey: "アプリケーションキー")
  Variables.fetch { isSuccessful in
      if isSuccessful {
          // handle success cases
      }
  }
  ...
}
```

{% endcode %}
{% endtab %}

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

```objc
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
  [KRTApp setupWithAppKey:@"アプリケーションキー" configuration:KRTConfiguration.defaultConfiguration];
  [KRTVariables fetchWithCompletion:^(BOOL isSuccessful) {
    if (isSuccessful) {
      // handle success case
    }
  }];
  ...
}
```

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

`fetch()` メソッドの呼び出し時に、SDKは変数取得（ `_fetch_variables` ）イベントを送信します。

KARTE管理画面側の設定値配信の接客サービスのデフォルト設定では、トリガーに\_fetch\_variablesイベントが設定されているため、このイベントをトリガーに配信が行われます。

任意のイベント発火時に接客サービスを配信したい場合は、[任意のイベント発火時に変数を取得する](#任意のイベント発火時に変数を取得する)に従った実装が推奨されます。

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

また`fetch()`完了のハンドラについては[FetchCompletion](https://plaidev.github.io/karte-sdk-docs/ios/latest/KarteVariables/Typealiases.html#/s:14KarteVariables15FetchCompletiona)が利用可能です。 詳細は[設定値配信でのFetchCompletionの利用](https://app.developers.karte.io/app-faq/implementing-fetch-completion)を御覧ください。

{% hint style="info" %}
**fetch失敗の場合**

ネットワークエラー等でfetchが失敗した場合、以前fetch成功した時のデータが存在する場合は、そちらが保持されます。
{% endhint %}

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

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

{% hint style="info" %}
**キャッシュのリセット**

キャッシュには特に有効期限はありませんが、変数の新規取得時以外に、アプリデータ削除（アンインストール等）および `renewVisitorId()` によるユーザ紐付け解除時に、同様に全ての変数値の削除が行われます。

* 参考: [アプリケーションのログアウトに対応する](https://app.developers.karte.io/ios-sdk-appendix/appendix-logout-ios-sdk)
  {% endhint %}

### 2. キャッシュにある変数を参照する

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

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

```swift
let variable = Variables.variable(forKey: "参照する変数名を指定")
```

{% endcode %}
{% endtab %}

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

```objc
KRTVariable *variable = [KRTVariables variableForKey:@"参照する変数名を指定"];
```

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

#### 2-2. 変数オブジェクトから値を取得

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

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

```swift
// 文字列型で参照
variable.string(default: "foo")

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

{% endcode %}
{% endtab %}

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

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

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

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

{% hint style="warning" %}
**キャッシュの更新について**

設定値配信では、fetch()の実行によるキャッシュの更新、もしくは意図的なキャッシュの削除のいずれかが行われない限り、キャッシュが保持されます。 fetch()が適切に行われない場合には意図せずキャッシュが残存してしまうこともあるため、接客サービスの配信停止設定等が意図しない挙動になる場合もあります。詳細は[接客サービスの配信停止と、キャッシュされた値の関係](https://app.developers.karte.io/karte-for-app-best-practices/best-practices-for-variables-module#接客サービスの配信停止と、キャッシュされた値の関係) 等をご確認ください。
{% endhint %}

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

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

なお、`Variables`クラスの`getAllKeys()`を呼ぶことで、現在配信されている設定値のキーの一覧をリスト形式で確認することができます。

{% code overflow="wrap" %}

```swift
Variables.getAllKeys()
```

{% endcode %}

## 効果測定の実装

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

[リファレンス](https://plaidev.github.io/karte-sdk-docs/ios/latest/KarteVariables/Extensions/Tracker.html)も合わせてご覧ください。

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

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

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

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

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

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

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

```swift
// バナーが表示されたタイミングで、下記処理を実行
let imgVar = Variables.variable(forKey: "TOP_BANNER_IMAGE_URL")
let linkVar = Variables.variable(forKey: "TOP_BANNER_LINK_URL")
Tracker.trackOpen(variables: [imgVar, linkVar])
```

{% endcode %}
{% endtab %}

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

```objc
// バナーが表示されたタイミングで、下記処理を実行
KRTVariable *imgVar = [KRTVariables variableForKey:@"TOP_BANNER_IMAGE_URL"];
KRTVariable *linkVar = [KRTVariables variableForKey:@"TOP_BANNER_LINK_URL"];
[KRTTracker trackOpenWithVariables:@[imgVar, linkVar]];
```

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

また任意の値をmessage\_openイベントに含めて計測したい場合は、第2引数にカスタムオブジェクトを指定することで対応できます。詳細は[リファレンス](https://plaidev.github.io/karte-sdk-docs/ios/latest/KarteVariables/Extensions/Tracker.html#/s:9KarteCore7TrackerC0A9VariablesE9trackOpen9variables6valuesySayAD8VariableCG_SDySSAA15JSONConvertible_pGtFZ) をご確認ください。

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

```swift
// バナーが表示されたタイミングで、下記処理を実行
let imgVar = Variables.variable(forKey: "TOP_BANNER_IMAGE_URL")
let linkVar = Variables.variable(forKey: "TOP_BANNER_LINK_URL")
Tracker.trackOpen(variables: [imgVar, linkVar], values: [
  "item_id": "001",
  "position": 0,
  "item_info": [
    "category": "A",
    "price": 1000
  ]
])
```

{% endcode %}
{% endtab %}

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

```objc
// バナーが表示されたタイミングで、下記処理を実行
KRTVariable *imgVar = [KRTVariables variableForKey:@"TOP_BANNER_IMAGE_URL"];
KRTVariable *linkVar = [KRTVariables variableForKey:@"TOP_BANNER_LINK_URL"];
[KRTTracker trackOpenWithVariables:@[imgVar, linkVar] values:@{
  @"item_id": @"001",
  @"position": @0,
  @"item_info": @{@"category": @"A", @"price": @1000}
}];
```

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

### タップを計測する

バナーがタップされたタイミングで、`message_click` イベントを送信することでタップを計測することが可能です。 なお `message_click` は `Tracker` クラスの `trackClick(variables:)` メソッドで送信することが可能です。

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

```swift
// バナーがタップされたタイミングで、下記処理を実行
let imgVar = Variables.variable(forKey: "TOP_BANNER_IMAGE_URL")
let linkVar = Variables.variable(forKey: "TOP_BANNER_LINK_URL")
Tracker.trackClick(variables: [imgVar, linkVar])
```

{% endcode %}
{% endtab %}

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

```objc
// バナーがタップされたタイミングで、下記処理を実行
KRTVariable *imgVar = [KRTVariables variableForKey:@"TOP_BANNER_IMAGE_URL"];
KRTVariable *linkVar = [KRTVariables variableForKey:@"TOP_BANNER_LINK_URL"];
[KRTTracker trackClickWithVariables:@[imgVar, linkVar]];
```

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

{% hint style="info" %}
**タップ数の計測について**

タップ数は配信数を母数にして集計されます。 message\_clickイベントのみ送信しても、タップ数には反映されません。 効果計測を行う際には、必ずmessage\_openイベントも送信してください。
{% endhint %}

また任意の値をmessage\_clickイベントに含めて計測したい場合は、第2引数にカスタムオブジェクトを指定することで対応できます。詳細は[リファレンス](https://plaidev.github.io/karte-sdk-docs/ios/latest/KarteVariables/Extensions/Tracker.html#/s:9KarteCore7TrackerC0A9VariablesE10trackClick9variables6valuesySayAD8VariableCG_SDySSAA15JSONConvertible_pGtFZ) をご確認ください。

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

```swift
// バナーが表示されたタイミングで、下記処理を実行
let imgVar = Variables.variable(forKey: "TOP_BANNER_IMAGE_URL")
let linkVar = Variables.variable(forKey: "TOP_BANNER_LINK_URL")
Tracker.trackClick(variables: [imgVar, linkVar], values: [
  "item_id": "001",
  "position": 0,
  "item_info": [
    "category": "A",
    "price": 1000
  ]
])
```

{% endcode %}
{% endtab %}

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

```objc
// バナーが表示されたタイミングで、下記処理を実行
KRTVariable *imgVar = [KRTVariables variableForKey:@"TOP_BANNER_IMAGE_URL"];
KRTVariable *linkVar = [KRTVariables variableForKey:@"TOP_BANNER_LINK_URL"];
[KRTTracker trackClickWithVariables:@[imgVar, linkVar values:@{
  @"item_id": @"001",
  @"position": @0,
  @"item_info": @{@"category": @"A", @"price": @1000}
}];
```

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

## 変数オブジェクトのキャッシュ削除

一度 `fetch` メソッドで取得した変数オブジェクトのキャッシュは、`clearCache`や`clearCacheAll`のメソッドを用いて削除することが可能です。

キャンペーンバナーなどのユースケースにて一度見せたバナーを確実に表示できないようにしたい場合などにご利用ください。

{% code overflow="wrap" %}

```swift
// 特定のKeyに紐ずく設定値のキャッシュを削除
Variables.clearCache(forKey: "key_to_clear")

// 今ローカルにある設定値のキャッシュをすべて削除
Variables.clearCacheAll()
```

{% endcode %}

{% hint style="info" %}
**再度fetchした場合**

再度`fetch`をした際に、一度削除した`key`に対応する変数オブジェクトが存在する場合は、その変数オブジェクトは新しくキャッシュされます。
{% endhint %}

## 任意のイベント発火時に変数を取得する

設定値配信の変数の取得には、通常は `fetch()` メソッドを使いますが、以下の場合においては任意のイベント発火時に変数を取得する方法を推奨します。

* アプリから送信した任意のイベントに基づいて設定値を配信したい
* `fetch()`メソッドによって発生する変数取得（ `_fetch_variables` ）イベントの送信数を増やしたくない

{% hint style="info" %}
**設定値配信の接客を作成時に配信トリガーの設定が必要です**

fetch()以外のタイミングで設定値配信を利用したい場合、接客作成時に配信トリガーで配信条件を設定する必要があります。詳しくは[変数取得イベント以外を指定して設定値配信を行う](https://support.karte.io/post/reO1yrya5guq8jPqLIclh#1-2)をご確認ください
{% endhint %}

実装方法は以下になります。

{% code overflow="wrap" %}

```swift
// viewイベント発火時に変数を取得する
Tracker.view("some_view").completion = { isSuccessful in
    if isSuccessful {
        let variable = Variable(name: "some_variable")
        //...
    }
}

// 任意のカスタムイベント発火時に変数を取得する
Tracker.track("some_custom_event").completion = { isSuccessful in
    if isSuccessful {
        let variable = Variable(name: "some_variable")
        //...
    }
}
```

{% endcode %}

{% hint style="info" %}
**イベント完了時のcompletionハンドラについて**

上述以外のすべてのイベント送信メソッドには、completionハンドラを設定可能です。各メソッドの詳細は[KarteCore Reference](https://plaidev.github.io/karte-sdk-docs/ios/latest/KarteCore/Classes/Tracker.html)を参照ください。
{% endhint %}

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

[設定値配信の接客サービス](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/ios-sdk/variables-ios-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.