Guides

[Android]設定値配信を利用する

Suggest Edits

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

設定値配信を利用するには、設定値配信用の接客を管理画面で設定する必要があります。
詳細については設定値配信の概要を参照ください。

🚧

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

KARTEで配信されたポップアップやアプリPUSH通知では表示, クリック時にmessage_open, message_clickイベントが自動送信されますが、設定値配信の場合は自動送信されません。
※これらのイベントが計測されない場合は、接客サービスの効果測定も行われません

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

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

導入手順

設定値配信は、variables モジュールを導入することで利用可能です。
アプリの build.gradle (app) を任意のエディタで開き、dependencies ブロックに variables モジュールを追加します。

dependencies {
  implementation 'io.karte.android:variables:2.+'
}

variablesのリファレンスも合わせてご確認ください。

変数参照の実装

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

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

1-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-2. 変数の取得

変数を取得するには Variables クラスの fetch() メソッドを呼び出します。
fetch() は任意のタイミングで呼び出すことが可能ですが、基本的にはアプリケーション起動時（SDKの初期化直後）に呼び出すことを推奨しております。
fetch()実行のタイミングについての注意事項等は、設定値配信のベストプラクティスも合わせてご確認ください。

override fun onCreate() {
  super.onCreate()
  KarteApp.setup(this, "アプリケーションキー")
  Variables.fetch { isSuccessful ->
    if (isSuccessful) {
        // 成功時の処理
    }
  }
}

@Override
public void onCreate() {
  super.onCreate();
  KarteApp.setup(this, "アプリケーションキー");
  Variables.fetch(isSuccessful -> {
    if (isSuccessful) {
      //成功時の処理
    }
  });
}

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

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

またfetch()完了のハンドラについてはFetchCompletionが利用可能です。
詳細は設定値配信でのFetchCompletionの利用を御覧ください。

📘

fetch失敗の場合

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

📘

変数名の重複

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

📘

キャッシュのリセット

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

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

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

val variable = Variables.get("参照する変数名を指定")

Variable variable = Variables.get("参照する変数名を指定");

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

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

// 文字列型で参照
variable.string("foo")

// 数値型で参照
variable.long(100)

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

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

🚧

キャッシュの更新について

設定値配信では、fetch()の実行によるキャッシュの更新、もしくは意図的なキャッシュの削除のいずれかが行われない限り、キャッシュが保持されます。
fetch()が適切に行われない場合には意図せずキャッシュが残存してしまうこともあるため、接客サービスの配信停止設定等が意図しない挙動になる場合もあります。詳細は接客サービスの配信停止と、キャッシュされた値の関係 等をご確認ください。

📘

デフォルト値

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

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

Variables.getAllKeys()

Variables.getAllKeys()

効果測定の実装

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

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

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

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

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

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

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

バナーが表示されたタイミングで、message_open イベントを送信することでインプレッションを計測することが可能です。
なお message_open は Variables クラスの 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_openイベントに含めて計測したい場合は、第2引数にカスタムオブジェクトを指定することで対応できます。詳細はリファレンス をご確認ください。

// バナーが表示されたタイミングで、下記処理を実行
val imgVar = Variables.get("TOP_BANNER_IMAGE_URL")
val linkVar = Variables.get("TOP_BANNER_LINK_URL")
Variables.trackOpen(listOf(imgVar, linkVar), mapOf(
  "item_id" to "001",
  "position" to 0,
  "item_info" to mapOf(
    "category" to "A",
    "price" to 1000
  )
))

// バナーが表示されたタイミングで、下記処理を実行
Variable imgVar = Variables.get("TOP_BANNER_IMAGE_URL");
Variable linkVar = Variables.get("TOP_BANNER_LINK_URL");
Variables.trackOpen(Arrays.asList(imgVar, linkVar), new HashMap<String, Object>() {{
  put("item_id", "001");
  put("position", 0);
  put("item_info", new HashMap<String, Object>() {{
    put("category", "A");
    put("price", 1000);
  }});
}});

タップを計測する

バナーがクリックされたタイミングで、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));

📘

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

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

また任意の値をmessage_clickイベントに含めて計測したい場合は、第2引数にカスタムオブジェクトを指定することで対応できます。詳細はリファレンス をご確認ください。

// バナーが表示されたタイミングで、下記処理を実行
val imgVar = Variables.get("TOP_BANNER_IMAGE_URL")
val linkVar = Variables.get("TOP_BANNER_LINK_URL")
Variables.trackClick(listOf(imgVar, linkVar), mapOf(
  "item_id" to "001",
  "position" to 0,
  "item_info" to mapOf(
    "category" to "A",
    "price" to 1000
  )
))

// バナーが表示されたタイミングで、下記処理を実行
Variable imgVar = Variables.get("TOP_BANNER_IMAGE_URL");
Variable linkVar = Variables.get("TOP_BANNER_LINK_URL");
Variables.trackClick(Arrays.asList(imgVar, linkVar), new HashMap<String, Object>() {{
  put("item_id", "001");
  put("position", 0);
  put("item_info", new HashMap<String, Object>() {{
    put("category", "A");
    put("price", 1000);
  }});
}});

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

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

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

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

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

📘

再度fetchした場合

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


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

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

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

📘

設定値配信の接客を作成時に配信トリガーの設定が必要です

`fetch()以外のタイミングで設定値配信を利用したい場合、接客作成時に配信トリガーで配信条件を設定する必要があります。
詳しくは 変数取得イベント以外を指定して設定値配信を行う をご確認ください

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

// viewイベント発火時に変数を取得する
Tracker.view("some_view") { isSuccessful ->
    if (isSuccessful) {
        val variable = Variables.get("some_variable")
        // ...
    }
}

// identifyイベント発火時に変数を取得する
Tracker.identify("sign_up") { isSuccessful ->
    if (isSuccessful) {
        val variable = Variables.get("some_variable")
        // ...
    }
}

// 任意のカスタムイベント発火時に変数を取得する
Tracker.track("some_custom_event") { isSuccessful ->
    if (isSuccessful) {
        val variable = Variables.get("some_variable")
        // ...
    }
}

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

設定値配信の接客サービスをご確認ください。

Updated 22 days ago