Guides

設定値を利用する

Suggest Edits

🚧

このドキュメントは古いバージョンのAndroid SDK v1について記載しています

Android SDK v1は 2021/05/11でサポート終了となります。
SDK v1 からのアップグレードについては、まず SDK v1からv2のアップグレード方法 をご覧ください。

KARTE の管理画面上で設定値した変数を、アプリで利用することができます。
これによりアプリをリリースすることなく、挙動をコントロールすることが可能です。

接客の設定

接客の新規作成を行ない、設定値を変更する を選択してください。

作成した接客は、対象イベントが 変数取得 (_fetch_variables) となるように自動で設定されます。

カスタマイズエディタで設定した静的変数をアプリで利用できます。

アプリ側の実装

変数の更新

fetch() を実行することで管理画面で設定した変数を取得できます。
fetch() は任意のタイミングで実行できますが、アプリ起動後必ず立ち上がる画面のonCreate() で呼び出すことを推奨します。起動時に一度変数を取得すれば、その後いつでも変数が参照可能です。（Application.onCreate()では呼び出さないでください。通知受信時等に変数取得イベントが発行され、意図せず計測イベント数が増える可能性があります。）

import io.karte.android.tracker.Tracker
import io.karte.android.tracker.Variables

class MainActivity : Activity() {
  
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        Variables.getInstance(this).fetch()
    }
}

import io.karte.android.tracker.Tracker;
import io.karte.android.tracker.Variables;

public class MainActivity extends AppCompatActivity {
  
  @Override
  protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    Variables.getInstance(this).fetch();
  }
}

fetch() は 変数取得 (_fetch_variables) イベントを発行し、これをトリガーに配信された1つまたは複数の接客の変数を全てキャッシュします。
また、該当する接客が返却された時に表示準備 (_message_ready) を発行します。

📘

変数名の重複

配信された複数の接客間で同名の変数が定義されていた場合、接客の 配信優先度 が高いものが優先されます。 配信優先度 が等しい場合は 接客の最終更新日時 が最近のものが優先されます。

📘

キャッシュのリセット

fetch() による _fetch_variables イベントのトラッキングに成功した時、過去にキャッシュされていた変数値は全てリセットされます。該当する接客が1つもない場合も同様です。
キャッシュには特に有効期限はありませんが、アプリデータ削除（アンインストール等）および renewVisitorId() によるユーザ紐付け解除時に、全ての変数値の削除が行われます。

キャッシュされた変数は次の方法で利用できます。

変数の参照

変数名を指定して変数を取得し、任意の型と変数未定義時のデフォルト値を指定して値を取得できます。

// 変数値を文字列型で参照する
val userName = Variables.getInstance(context).getVariable("user_name").getString("John Doe")
  
// 変数値をJSONArray型で参照する
val jsonArray = Variables.getInstance(context).getVariable("image_names").getJSONArray(JSONArray())
  
// 変数値をJSONObject型で参照する
val jsonObject = Variables.getInstance(context).getVariable("dict_key").getJSONObject(JSONObject())

// 変数値を文字列型で参照する
String userName = Variables.getInstance(context).getVariable("user_name").getString("John Doe");

// 変数値をJSONArray型で参照する
JSONArray array = Variables.getInstance(context).getVariable("image_names").getJSONArray(new JSONArray());
  
// 変数値をJSONObject型で参照する
JSONObject jsonObject = Variables.getInstance(context).getVariable("dict_key").getJSONObject(new JSONObject());

String long double boolean JSONArray JSONObject で参照可能です。

管理画面上で指定したタイプに関わらず、内部的に変数値は文字列として扱われ、参照メソッドは指定した型に変換した値を返します。数値フォーマットではない変数を long で参照した場合等、変換に失敗するとデフォルト値を返します。

  • 管理画面上で 画像 カラー URL タイプとした変数も文字列型として取得できます。
  • 日付型として送られたユーザ情報変数は UNIX 時間の数値として扱われます。

効果測定

変数をバナー表示等に利用した時、接客の効果測定のために表示イベント message_open やクリックイベント message_click をトラッキングしたい場合があります。
表示に利用した変数のインスタンスのリストを Variables クラスのトラックメソッドに渡して計測できます。

val variables = Variables.getInstance(context)
val bannerImageUrlVar = variables.getVariable("top_banner_image_url")
val bannerClickLinkVar = variables.getVariable("top_banner_image_click_link")

val bannerImageUrl = bannerImageUrlVar.getString(null)
val bannerClickLink = bannerClickLinkVar.getString(null)

if (bannerImageUrl != null && bannerClickLink != null) {
  // bannerImageUrlとbannerClickLinkを利用してバナー表示
  // ...

  val bannerVariables = mutableListOf<Variable>()
  bannerVariables.add(bannerImageUrlVar)
  bannerVariables.add(bannerClickLinkVar)

  // 表示イベントを計測
  variables.track(bannerVariables, Tracker.EventName.MESSAGE_OPEN JSONObject().apply {
  put("KEY", "VALUE")
})

  // バナークリック時はeventNameにTracker.EventName.MESSAGE_OPENを渡す
  // variables.track(bannerVariables, Tracker.EventName.MESSAGE_CLICK JSONObject().apply { 
  //  put("KEY", "VALUE")
  // })
}

Variables variables = Variables.getInstance(context);
Variable bannerImageUrlVar = variables.getVariable("top_banner_image_url");
Variable bannerClickLinkVar = variables.getVariable("top_banner_image_click_link");

String bannerImageUrl = bannerImageUrlVar.getString(null);
String bannerClickLink = bannerClickLinkVar.getString(null);

if (bannerImageUrl != null && bannerClickLink != null) {
  // bannerImageUrlとbannerClickLinkを利用してバナー表示
  // ...
    
  List<Variable> bannerVariables = new ArrayList<>();
  bannerVariables.add(bannerImageUrlVar);
  bannerVariables.add(bannerClickLinkVar);
  
  // 表示イベントを計測
  variables.track(bannerVariables, Tracker.EventName.MESSAGE_OPEN);
    
  // バナークリック時はeventNameにTracker.EventName.MESSAGE_OPENを渡す
  // variables.track(bannerVariables, Tracker.EventName.MESSAGE_CLICK);
}

📘

同一接客に複数の設定値が配信されている場合

一つの接客で複数の設定値が配信されている場合、どの変数により対象のバナーが配信されているかを識別するには、第三引数に任意の値を送信することで識別可能になります。
実装方法に関しては、こちらをご参照ください。

ユーザ情報変数

ユーザデータを利用したい場合は、ユーザ情報変数を追加した後、追加したユーザ情報変数を参照する静的変数を設定してください。

例：ユーザの名前を利用したい場合

  1. _user_name という名前のユーザ情報変数を 全ての期間 | ユーザタグ | 名前 | 最新の値 として設定します。
  2. 静的変数 user_name を値 #{_user_name} で設定します。
  3. アプリ側で getVariable("user_name").getString(null) のように参照できます。

ユーザ情報変数に指定されたデフォルト値は、参照メソッドに渡されたデフォルト値よりも優先されます。

Updated 12 months ago

What’s Next