設定値を利用する

Suggest Edits

🚧

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

Native SDK v1に依存する旧React Native SDKは 2021/05/11でサポート終了となります。

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

🚧

制限事項

この機能は React Native SDK v0.2.1 から対応しています。

接客の設定

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

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

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

アプリ側の実装

変数の更新

fetch() を実行することで管理画面で設定した変数を取得できます。
fetch() は任意のタイミングで実行できますが、アプリケーション起動時に呼び出すことを推奨します。起動時に一度変数を取得すれば、その後いつでも変数が参照可能です。

import {KarteVariables} from 'react-native-karte-tracker'

await KarteVariables.fetch()

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

📘

変数名の重複

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

📘

キャッシュのリセット

fetch() による _fetch_variables イベントのトラッキングに成功した時、過去にキャッシュされていた変数値は全てリセットされます。該当する接客が1つもない場合も同様です。

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

変数の参照

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

// 文字列型の変数値をデフォルト値を指定して参照する
let variable1 = await KarteVariables.variable("user_name")
let userName = await variable1.string("John Doe")

// 変数値をArray型として参照する。jsonが["a.png","b.png"]の場合
let variable2 = await KarteVariables.variable("image_names")
let array = await variable2.array(["a.png"])

// 変数値をObject型として参照する。jsonが {"hoge":"fuga"}の場合
let variable3 = await KarteVariables.variable("dict_key")
let object = await variable3.object({"default": "value"})
let value = object["hoge"]

String Integer Double Bool Array Object で参照可能です。

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

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

効果測定

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

let bannerImageUrlVar = await KarteVariables.variable("top_banner_image_url")
let bannerClickLinkVar = await KarteVariables.variable("top_banner_image_click_link")

let imageUrl = await bannerImageUrlVar.string()
let clickLink = await bannerClickLinkVar.string()
if (imageUrl && clickLink) {
  // imageUrlとclickLinkを利用してバナーを表示
  // ...
  
  // 表示イベントを計測
  KarteVariables.track([bannerImageUrlVar, bannerClickLinkVar], "message_open", {key: value})
  
  // ...
  // バナークリック時はeventNameにmessage_clickを渡す
  KarteVariables.track([bannerImageUrlVar, bannerClickLinkVar], "message_click", {key: value})
}

📘

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

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

ユーザ情報変数

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

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

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

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

Updated 5 months ago