グローバルプロパティの設定

アプリから送信されるすべてのセッションとイベントに自動的に付加されるカスタムプロパティを定義することで、レポートでの詳細なデータセグメンテーションが可能になります。

グローバルプロパティを使用すると、必要な任意のユーザー、アプリモード、コンテキスト情報を追跡できます。たとえば、ゲームアプリで「Level」プロパティを「0」に初期化し、ユーザーの進行に応じて更新できます。すべてのセッションとイベントにこのプロパティが含まれるため、ユーザーレベル別のセッション、イベント数、収益を分析できます。

プロパティの仕様

制限と永続性

グローバルプロパティの制約と永続性の動作を理解してください。

• 最大プロパティ数: アプリのインストールごとに最大5個のグローバルプロパティを定義できます
• 永続性: プロパティは明示的に解除されるか、アプリがアンインストールされるまで、最新の値でアプリの起動間で保持されます
• 文字数制限: プロパティ名と値は最大200文字まで指定できます。長い値は自動的に200文字に切り詰められます
• データの利用可能性: グローバルプロパティはユーザーレベルのエクスポートとポストバックでアクセスできます。集計レポートのサポート更新については、Singularのカスタマーサクセスマネージャーにお問い合わせください

初期化時にグローバルプロパティを設定

SingularConfigを使用した構成

Singular.init() を呼び出す前に、 withGlobalProperty メソッドを使用して、SDK初期化中にグローバルプロパティを設定します。

グローバルプロパティはアプリの起動間で永続化されるため、異なる値のプロパティが既に存在する場合があります。新しい値が既存の値を上書きするかどうかを制御するには、 overrideExisting パラメータを使用してください。

// Set global properties during initialization
val config = SingularConfig("SDK_KEY", "SDK_SECRET")
    .withGlobalProperty("MyProperty", "MyValue", true)
    .withGlobalProperty("AnotherProperty", "AnotherValue", true)

Singular.init(applicationContext, config)

// Set global properties during initialization
SingularConfig config = new SingularConfig("SDK_KEY", "SDK_SECRET")
    .withGlobalProperty("MyProperty", "MyValue", true)
    .withGlobalProperty("AnotherProperty", "AnotherValue", true);

Singular.init(getApplicationContext(), config);

メソッドシグネチャ:

public SingularConfig withGlobalProperty(String key, String value, boolean overrideExisting)

パラメータ:

• key: プロパティ名（最大200文字）
• value: プロパティ値（最大200文字）
• overrideExisting: 同じキーを持つ既存のプロパティを上書きするかどうか

初期化後のプロパティ管理

グローバルプロパティの設定

アプリのランタイム中のいつでもグローバルプロパティを追加または更新できます。

// Set a global property after initialization
val result = Singular.setGlobalProperty("MyProperty", "MyValue", true)
if (result) {
    Log.d("Singular", "Property set successfully")
} else {
    Log.e("Singular", "Failed to set property")
}

// Set a global property after initialization
boolean result = Singular.setGlobalProperty("MyProperty", "MyValue", true);
if (result) {
    Log.d("Singular", "Property set successfully");
} else {
    Log.e("Singular", "Failed to set property");
}

メソッドシグネチャ:

public static boolean setGlobalProperty(String key, String value, boolean overrideExisting)

戻り値: true プロパティが正常に設定された場合、それ以外の場合は false

グローバルプロパティの取得

現在設定されているすべてのグローバルプロパティとその値をMapとして取得します。

// Retrieve all global properties
val properties: Map<String, String> = Singular.getGlobalProperties()

// Iterate through properties
properties.forEach { (key, value) ->
    Log.d("Singular", "Property: $key = $value")
}

// Retrieve all global properties
Map<String, String> properties = Singular.getGlobalProperties();

// Iterate through properties
for (Map.Entry<String, String> entry : properties.entrySet()) {
    Log.d("Singular", "Property: " + entry.getKey() + " = " + entry.getValue());
}

メソッドシグネチャ:

public static Map<String, String> getGlobalProperties()

戻り値: すべてのグローバルプロパティのキーと値のペアを含むMap

グローバルプロパティの解除

キーで特定のグローバルプロパティを削除します。

// Remove a specific global property
Singular.unsetGlobalProperty("MyProperty")

// Remove a specific global property
Singular.unsetGlobalProperty("MyProperty");

メソッドシグネチャ:

public static void unsetGlobalProperty(String key)

パラメータ:

• key: 削除するプロパティの名前

すべてのグローバルプロパティをクリア

すべてのグローバルプロパティを一度に削除します。

// Remove all global properties
Singular.clearGlobalProperties()

// Remove all global properties
Singular.clearGlobalProperties();

メソッドシグネチャ:

public static void clearGlobalProperties()

実装例

完全な使用パターン

アプリケーションのライフサイクル全体を通して、アプリレベルおよびユーザー固有のプロパティをトラッキングしてください。

// Initialize SDK with app-level global properties
val config = SingularConfig("SDK_KEY", "SDK_SECRET")
    .withGlobalProperty("app_version", BuildConfig.VERSION_NAME, true)

Singular.init(applicationContext, config)

// Set third-party identifier on login
fun onUserLogin(thirdPartyUserId: String) {
    val success = Singular.setGlobalProperty("third_party_identifier", thirdPartyUserId, true)
    if (success) {
        Log.d("Singular", "Third-party identifier set")
    }
}

// Clear third-party identifier on logout
fun onUserLogout() {
    Singular.unsetGlobalProperty("third_party_identifier")
    Log.d("Singular", "Third-party identifier cleared")
}

// Initialize SDK with app-level global properties
SingularConfig config = new SingularConfig("SDK_KEY", "SDK_SECRET")
    .withGlobalProperty("app_version", BuildConfig.VERSION_NAME, true);

Singular.init(getApplicationContext(), config);

// Set third-party identifier on login
public void onUserLogin(String thirdPartyUserId) {
    boolean success = Singular.setGlobalProperty("third_party_identifier", thirdPartyUserId, true);
    if (success) {
        Log.d("Singular", "Third-party identifier set");
    }
}

// Clear third-party identifier on logout
public void onUserLogout() {
    Singular.unsetGlobalProperty("third_party_identifier");
    Log.d("Singular", "Third-party identifier cleared");
}