設定値を利用する

Suggest Edits

🚧

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

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

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

接客の設定

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

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

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

アプリ側の実装

変数の更新

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

import KarteTracker

@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate {
  
  func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
    KarteTracker.setup(appKey: "YOUR_APP_KEY")
    KarteVariables.fetch()
    ...
  }
}

#import "AppDelegate.h"
#import <KarteTracker/KarteTracker.h>

@implementation AppDelegate

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
  [KarteTracker setupWithAppKey:@"YOUR_APP_KEY"];
  [KarteVariables fetch];
  ...
}

@end

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

📘

変数名の重複

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

📘

キャッシュのリセット

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

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

変数の参照

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

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

// String, Array, Dictionaryは、変数未定義時にnullを返すプロパティとしても参照可能
let userName = KarteVariables.variable(forKey: "user_name").string

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

// 変数値をDictionary型として参照する。jsonが {"hoge":"fuga"}の場合
let dictionary = KarteVariables.variable(forKey: "dict_key").dictionary(defaultValue: ["default": "value"])
let value = dictionary["hoge"] as! String

NSString *userName = [[KarteVariables variableForKey:@"user_name"] stringWithDefaultValue:@"John Doe"];

// NSString, NSArray, NSDictionaryは、変数未定義時にnullを返すプロパティとしても参照可能
NSString *userName = [KarteVariables variableForKey:@"user_name"].string;

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

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

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

効果測定

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

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

KarteVariable *bannerImageUrlVar = [KarteVariables variableForKey: "top_banner_image_url"];
KarteVariable *bannerClickLinkVar = [KarteVariables variableForKey: "top_banner_image_click_link"];

if (bannerImageUrlVar.string && bannerClickLinkVar.string) {
    // bannerImageUrlVar.stringとbannerClickLinkVar.stringを利用してバナー表示
    // ...
    
    // 表示イベントを計測
    [KarteVariables trackWithVariables: @[bannerImageUrlVar, bannerClickLinkVar] withEventName: KarteEventMessageOpen]
    
    // バナークリック時はeventNameにKarteEventMessageClickを渡す
    // [KarteVariables trackWithVariables: @[bannerImageUrlVar, bannerClickLinkVar] withEventName: KarteEventMessageClick]
}

📘

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

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

ユーザ情報変数

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

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

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

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

Updated 5 months ago

What’s Next