設定値を利用する

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

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

設定値配信は、variables モジュールを導入することで利用可能です。

導入手順

アプリの build.gradle (app) を任意のエディタで開き、dependencies ブロックに variables モジュールを追加します。

dependencies {
  implementation 'io.karte.android:variables:2.2.0'
}

実装手順

変数参照の実装

1. 変数を取得する

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

  1. SDKのインポート宣言を追加
import io.karte.android.variables.Variables
import io.karte.android.variables.Variable
import io.karte.android.variables.Variables;
import io.karte.android.variables.Variable;
  1. 変数の取得
    変数を取得するには Variables クラスの fetch() メソッドを呼び出します。
    fetch() は任意のタイミングで呼び出すことが可能ですが、基本的にはアプリケーション起動時(SDKの初期化直後)に呼び出すことを推奨しております。
override fun onCreate() {
  super.onCreate()
  KarteApp.setup(this, "アプリケーションキー")
  Variables.fetch()
}
@Override
public void onCreate() {
  super.onCreate();
  KarteApp.setup(this, "アプリケーションキー");
  Variables.fetch();
}

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

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

📘

変数名の重複

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

📘

キャッシュのリセット

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

2. 変数を参照する

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

// 数値型で参照
variable.long(100)
// 文字列型で参照
variable.getString("foo");

// 数値型で参照
variable.getLong(100L);

📘

デフォルト値

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

効果測定の実装

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

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

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

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

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

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

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

// バナーが表示されたタイミングで、下記処理を実行
val imgVar = Variables.get("TOP_BANNER_IMAGE_URL")
val linkVar = Variables.get("TOP_BANNER_LINK_URL")
Variables.trackOpen(listOf(imgVar, linkVar))
// バナーが表示されたタイミングで、下記処理を実行
Variable imgVar = Variables.get("TOP_BANNER_IMAGE_URL");
Variable linkVar = Variables.get("TOP_BANNER_LINK_URL");
Variables.trackOpen(Arrays.asList(imgVar, linkVar));

クリックを計測する

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

// バナーがクリックされたタイミングで、下記処理を実行
val imgVar = Variables.get("TOP_BANNER_IMAGE_URL")
val linkVar = Variables.get("TOP_BANNER_LINK_URL")
Variables.trackClick(listOf(imgVar, linkVar))
// バナーがクリックされたタイミングで、下記処理を実行
Variable imgVar = Variables.get("TOP_BANNER_IMAGE_URL");
Variable linkVar = Variables.get("TOP_BANNER_LINK_URL");
Variables.trackClick(Arrays.asList(imgVar, linkVar));

Updated about a year ago

設定値を利用する


Suggested Edits are limited on API Reference Pages

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