設定値を利用する

Suggest Edits

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

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

設定値配信は、KarteVariables モジュールを導入することで利用可能です。
Variablesのリファレンスも合わせてご確認ください。

🚧

設定値配信でのmessage_open, message_clickイベントについて

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

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

詳細はインプレッションを計測する、クリックを計測するを御覧ください。

導入手順

  1. Podfile の編集
    プロジェクトディレクトリにある Podfile を任意のエディタで開き、KarteVariables の Pod を追加します。
pod 'KarteVariables'
  1. Pod のインストール
    プロジェクトディレクトで下記コマンドを実行し、Pod をインストールします。
pod install

実装手順

変数参照の実装

1. 変数を取得する

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

  1. SDKのインポート宣言を追加
import KarteVariables

@import KarteVariables;
  1. 変数の取得
    変数を取得するには Variables クラスの fetch() メソッドを呼び出します。
    fetch() は任意のタイミングで呼び出すことが可能ですが、基本的にはアプリケーション起動時（SDKの初期化直後）に呼び出すことを推奨しております。
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
  KarteApp.setup(appKey: "アプリケーションキー")
  Variables.fetch()
  ...
}

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

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

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

またfetch()完了のハンドラについてはFetchCompletionが利用可能です。


📘

fetch失敗の場合

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

📘

変数名の重複

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

📘

キャッシュのリセット

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

2. 変数を参照する

  1. 変数オブジェクトを取得
let variable = Variables.variable(forKey: "参照する変数名を指定")

KRTVariable *variable = [KRTVariables variableForKey:@"参照する変数名を指定"];
  1. 変数オブジェクトから値を取得
    管理画面上で設定した変数は、変数オブジェクト内で文字列型で保持されています。
    変数オブジェクトから値を取得して利用する場合は、任意の型にキャストして利用します。
// 文字列型で参照
variable.string(default: "foo")

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

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

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

📘

デフォルト値

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

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

Variables.getAllKeys()

Variables.getAllKeys()

効果測定の実装

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

リファレンスも合わせてご覧ください。

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

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

変数名内容
TOP_BANNER_IMAGE_URLバナー画像のURL
TOP_BANNER_LINK_URLバナー画像をクリックした時の遷移先URL

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

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

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

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

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

クリックを計測する

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

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

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

📘

クリック数の計測について

クリック数は配信数を母数にして集計されます。
message_clickイベントのみ送信しても、クリック数には反映されません。
効果計測を行う際には、必ずmessage_openイベントも送信してください。


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

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

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

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

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

📘

再度fetchした場合

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

Updated 4 days ago