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

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

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

プロパティ仕様

制限と永続性

グローバルプロパティの制約と永続性の動作を理解しましょう。

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

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

SingularConfigによる構成

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

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

func getConfig() -> SingularConfig? {
    // Create config with API credentials
    guard let config = SingularConfig(apiKey: "SDK_KEY", andSecret: "SDK_SECRET") else {
        return nil
    }

    // Set global properties during initialization
    config.setGlobalProperty("MyProperty", withValue: "MyValue", overrideExisting: true)
    config.setGlobalProperty("AnotherProperty", withValue: "AnotherValue", overrideExisting: true)

    return config
}

// Initialize SDK with config
if let config = getConfig() {
    Singular.start(config)
}

- (SingularConfig *)getConfig {
    // Create config with API credentials
    SingularConfig *config = [[SingularConfig alloc] initWithApiKey:@"SDK_KEY"
        andSecret:@"SDK_SECRET"];

    // Set global properties during initialization
    [config setGlobalProperty:@"MyProperty" withValue:@"MyValue" overrideExisting:YES];
    [config setGlobalProperty:@"AnotherProperty" withValue:@"AnotherValue" overrideExisting:YES];

    return config;
}

// Initialize SDK with config
SingularConfig *config = [self getConfig];
[Singular start:config];

メソッドシグネチャ:

- (void)setGlobalProperty:(NSString *)key withValue:(NSString *)value overrideExisting:(BOOL)overrideExisting;

パラメーター:

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

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

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

アプリの実行中の任意の時点でグローバルプロパティを追加または更新します。

// Set a global property after initialization
let result = Singular.setGlobalProperty("MyProperty",
    andValue: "MyValue",
    overrideExisting: true)

if result {
    print("Property set successfully")
} else {
    print("Failed to set property")
}

// Set a global property after initialization
BOOL result = [Singular setGlobalProperty:@"MyProperty"
    andValue:@"MyValue"
    overrideExisting:YES];

if (result) {
    NSLog(@"Property set successfully");
} else {
    NSLog(@"Failed to set property");
}

メソッドシグネチャ:

+ (BOOL)setGlobalProperty:(NSString *)key andValue:(NSString *)value overrideExisting:(BOOL)overrideExisting;

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

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

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

// Retrieve all global properties
let properties = Singular.getGlobalProperties()

// Iterate through properties
if let properties = properties as? [String: String] {
    for (key, value) in properties {
        print("Property: \(key) = \(value)")
    }
}

// Retrieve all global properties
NSDictionary *properties = [Singular getGlobalProperties];

// Iterate through properties
for (NSString *key in properties) {
    NSString *value = properties[key];
    NSLog(@"Property: %@ = %@", key, value);
}

メソッドシグネチャ:

+ (NSDictionary *)getGlobalProperties;

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

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

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

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

// Remove a specific global property
[Singular unsetGlobalProperty:@"MyProperty"];

メソッドシグネチャ:

+ (void)unsetGlobalProperty:(NSString *)key;

パラメーター:

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

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

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

// Remove all global properties
Singular.clearGlobalProperties()

// Remove all global properties
[Singular clearGlobalProperties];

メソッドシグネチャ:

+ (void)clearGlobalProperties;

実装例

完全な使用パターン

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

// Initialize SDK with app-level global properties
func getConfig() -> SingularConfig? {
    guard let config = SingularConfig(apiKey: "SDK_KEY", andSecret: "SDK_SECRET") else {
        return nil
    }

    // Set app version as a global property
    if let appVersion = Bundle.main.infoDictionary?["CFBundleShortVersionString"] as? String {
        config.setGlobalProperty("app_version", withValue: appVersion, overrideExisting: true)
    }

    return config
}

// Set third-party identifier on login
func onUserLogin(thirdPartyUserId: String) {
    let success = Singular.setGlobalProperty("third_party_identifier",
        andValue: thirdPartyUserId,
        overrideExisting: true)

    if success {
        print("Third-party identifier set")
    }
}

// Clear third-party identifier on logout
func onUserLogout() {
    Singular.unsetGlobalProperty("third_party_identifier")
    print("Third-party identifier cleared")
}

// Initialize SDK with app-level global properties
- (SingularConfig *)getConfig {
    SingularConfig *config = [[SingularConfig alloc] initWithApiKey:@"SDK_KEY"
        andSecret:@"SDK_SECRET"];

    // Set app version as a global property
    NSString *appVersion = [[NSBundle mainBundle] infoDictionary][@"CFBundleShortVersionString"];
    if (appVersion) {
        [config setGlobalProperty:@"app_version" withValue:appVersion overrideExisting:YES];
    }

    return config;
}

// Set third-party identifier on login
- (void)onUserLogin:(NSString *)thirdPartyUserId {
    BOOL success = [Singular setGlobalProperty:@"third_party_identifier"
        andValue:thirdPartyUserId
        overrideExisting:YES];

    if (success) {
        NSLog(@"Third-party identifier set");
    }
}

// Clear third-party identifier on logout
- (void)onUserLogout {
    [Singular unsetGlobalProperty:@"third_party_identifier"];
    NSLog(@"Third-party identifier cleared");
}