ドキュメント

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

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

グローバルプロパティを使用すると、必要なユーザー、アプリモード、またはコンテキスト情報を追跡できます。例えば、ゲームアプリでは、"Level "プロパティを作成し、"0 "に初期化します。すべてのセッションとイベントにこのプロパティが含まれ、セッション、イベントカウント、収益をユーザーレベル別に分析できます。

プロパティの仕様

制約と永続性

実装する前に、グローバル・プロパティの制約と永続化の動作を理解してください。

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

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

SDK初期化前の設定

グローバルプロパティが初期セッションに含まれるように、globalProperties 設定プロパティを使用して、SDK の初期化前にグローバルプロパティを設定します。

グローバルプロパティはアプリの起動間で持続するので、プロパティはすでに異なる値で存在している可能性があります。SingularGlobalProperty コンストラクタのoverrideExistingパラメータを使用して、新しい値が既存の値を上書きするかどうかを制御します。

import 'package:flutter/material.dart';
import 'package:singular_flutter_sdk/singular.dart';
import 'package:singular_flutter_sdk/singular_config.dart';
import 'package:singular_flutter_sdk/singular_global_property.dart';

void main() {
  runApp(MyApp());
}

class MyApp extends StatefulWidget {
  @override
  _MyAppState createState() => _MyAppState();
}

class _MyAppState extends State<MyApp> {
  @override
  void initState() {
    super.initState();
    initializeSDK();
  }

  void initializeSDK() {
    // Create configuration with global properties
    SingularConfig config = SingularConfig(
      'YOUR_SDK_KEY',
      'YOUR_SDK_SECRET'
    );

    // Set app-level global properties before initialization
    config.globalProperties = [
      SingularGlobalProperty('app_version', '1.2.3', true),
      SingularGlobalProperty('platform', 'flutter', true)
    ];

    // Initialize SDK with global properties
    Singular.start(config);
  }

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Flutter Demo',
      home: MyHomePage(),
    );
  }
}

構成プロパティ：

List<SingularGlobalProperty> globalProperties

SingularGlobalProperty コンストラクタ：

SingularGlobalProperty(String key, String value, bool overrideExisting)

パラメータ

キー：プロパティ名（最大200文字）
値：プロパティ値（200文字以内）
overrideExisting：既存のプロパティを同じキーで上書きするかどうか。

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

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

setGlobalProperty() を使用して、アプリの実行中に任意の時点でグローバル・プロパティを追加または更新します。

import 'package:singular_flutter_sdk/singular.dart';

// Set a global property after initialization
void updatePlayerLevel(int level) {
  Singular.setGlobalProperty(
    'player_level',
    level.toString(),
    true
  );

  print('Global property set: player_level = $level');
}

メソッドの署名：

static void setGlobalProperty(String key, String value, bool overrideExisting)

重要：

重要： 5つのプロパティが既に存在し、異なるキーで新しいプロパティを追加しようとすると、SDKはそれを追加しません。
overrideExisting パラメタは、既存のプロパティ値を置き換えるかどうかを決定します。
初期化時または実行時に設定されたプロパティは、同じ永続化動作を持ちます。

例ユーザーアクションでのプロパティの更新

import 'package:singular_flutter_sdk/singular.dart';

// Example: Track user subscription tier
void handleSubscriptionChange(String tier) {
  // Update global property
  Singular.setGlobalProperty('subscription_tier', tier, true);

  // Track the subscription event
  Singular.eventWithArgs('subscription_changed', {
    'new_tier': tier,
    'timestamp': DateTime.now().toIso8601String()
  });

  print('Subscription tier updated: $tier');
}

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

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

import 'package:singular_flutter_sdk/singular.dart';

// Retrieve all global properties
Future<void> displayGlobalProperties() async {
  Map<String, String> properties = await Singular.getGlobalProperties();

  // Iterate through properties
  properties.forEach((key, value) {
    print('Property: $key = $value');
  });

  // Check if specific property exists
  if (properties.containsKey('player_level')) {
    print('Current player level: ${properties['player_level']}');
  }
}

メソッドのシグネチャ：

static Future<Map<String, String>> getGlobalProperties()

戻り値：すべてのグローバル・プロパティのキーと値のペアを含むMap<String, String> に解決するFuture を返します。

グローバル・プロパティのアンセット

そのディメンジョンを追跡する必要がなくなった場合に、特定のグローバル・プロパティをそのキーで削除します。

import 'package:singular_flutter_sdk/singular.dart';

// Remove a specific global property
Singular.unsetGlobalProperty('player_level');

メソッドのシグニチャ：

static void unsetGlobalProperty(String key)

パラメータ：

キー：削除するプロパティの名前

例ログアウト時のユーザ・プロパティの消去

import 'package:singular_flutter_sdk/singular.dart';

// Clear user-specific properties on logout
void handleUserLogout() {
  // Remove user-specific properties
  Singular.unsetGlobalProperty('subscription_tier');
  Singular.unsetGlobalProperty('player_level');
  Singular.unsetGlobalProperty('user_segment');

  // Also clear custom user ID
  Singular.unsetCustomUserId();

  print('User properties cleared on logout');
}

すべてのグローバル・プロパティを消去

すべてのグローバル・プロパティを一度に削除します。通常、ユーザがログアウトした場合や、すべてのトラッキング・プロパティをリセットする必要がある場合に使用します。

import 'package:singular_flutter_sdk/singular.dart';

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

メソッドの署名：

static void clearGlobalProperties()

ベストプラクティス：ユーザがログアウトしたときや、すべてのカスタムトラッキングプロパティをデフォルト状態にリセットする必要があるときに、clearGlobalProperties()。これは、異なるユーザーが同じデバイスでログインするようなマルチユーザーシナリオで特に有用です。

実装例

完全な使用パターン

ログインとログアウトのフロー中に適切な管理を行うことで、アプリケーションのライフサイクル全体を通してアプリレベルとユーザー固有のプロパティを追跡します。

import 'package:flutter/material.dart';
import 'package:singular_flutter_sdk/singular.dart';
import 'package:singular_flutter_sdk/singular_config.dart';
import 'package:singular_flutter_sdk/singular_global_property.dart';

void main() {
  runApp(MyApp());
}

class MyApp extends StatefulWidget {
  @override
  _MyAppState createState() => _MyAppState();
}

class _MyAppState extends State<MyApp> {
  @override
  void initState() {
    super.initState();
    initializeSDK();
  }

  void initializeSDK() {
    // Set app-level global properties before initialization
    SingularConfig config = SingularConfig(
      'YOUR_SDK_KEY',
      'YOUR_SDK_SECRET'
    );

    config.globalProperties = [
      SingularGlobalProperty('app_version', '1.2.3', true),
      SingularGlobalProperty('platform', 'flutter', true)
    ];

    // Initialize SDK
    Singular.start(config);
  }

  // Set user-specific properties on login
  void handleUserLogin(String userId, String userTier) {
    // Set custom user ID
    Singular.setCustomUserId(userId);

    // Set user tier property
    Singular.setGlobalProperty('user_tier', userTier, true);

    // Set initial player level
    Singular.setGlobalProperty('player_level', '1', true);

    print('User properties set successfully');
  }

  // Update dynamic properties during gameplay
  void handleLevelUp(int newLevel) {
    // Update player level property
    Singular.setGlobalProperty('player_level', newLevel.toString(), true);

    // Track level up event
    Singular.eventWithArgs('level_up', {
      'new_level': newLevel.toString(),
      'timestamp': DateTime.now().millisecondsSinceEpoch.toString()
    });

    print('Level updated to $newLevel');
  }

  // Update subscription status
  void handleSubscriptionPurchase(String tier) {
    // Update subscription tier
    Singular.setGlobalProperty('subscription_tier', tier, true);

    // Track subscription event
    Singular.customRevenue('subscription_purchase', 'USD', 9.99);

    print('Subscription tier updated: $tier');
  }

  // Clear user-specific properties on logout
  void handleUserLogout() {
    // Remove user-specific properties
    Singular.unsetGlobalProperty('user_tier');
    Singular.unsetGlobalProperty('player_level');
    Singular.unsetGlobalProperty('subscription_tier');

    // Clear custom user ID
    Singular.unsetCustomUserId();

    print('User properties cleared on logout');
  }

  // Alternative: Clear all properties at once
  void handleCompleteReset() {
    // Remove all global properties
    Singular.clearGlobalProperties();

    // Clear custom user ID
    Singular.unsetCustomUserId();

    print('All properties and user ID cleared');
  }

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Flutter Demo',
      home: MyHomePage(),
    );
  }
}

ベストプラクティスサードパーティのアナリティクス識別子（例：Mixpanel distinct_id、Amplitude user_id）をSingularのグローバルプロパティに同期して、統一されたクロスプラットフォームトラッキングを行う。ログイン時にユーザー固有の識別子を設定し、ログアウト時にunsetGlobalProperty() 。app_version のようなアプリレベルのプロパティは、セッションを超えて持続します。

一般的な使用例

ゲームアプリ

プレーヤーの進行状況、エンゲージメントレベル、収益化層を追跡して、ユーザーをセグメント化し、キャンペーンを最適化します。

player_level：ゲーム内の現在のレベルまたはステージ
vip_status：プレミアム会員レベル（無料、シルバー、ゴールド）
last_purchase_date:最新のアプリ内購入日
engagement_score: エンゲージメントスコア：計算されたエンゲージメント指標

Eコマースアプリ

顧客セグメント、ロイヤリティステータス、ショッピング嗜好を追跡し、マーケティングキャンペーンをパーソナライズします。

loyalty_tier：顧客のロイヤルティプログラムのレベル
preferred_category：最も閲覧された商品カテゴリー
cart_status：カートに商品があるかどうか
ライフタイム・バリュー・バケットカテゴリー別の総消費額（低、中、高）

コンテンツ/メディアアプリ

コンテンツの嗜好、購読状況、エンゲージメントパターンを追跡し、コンテンツの推奨とリテンションを行う。

サブスクリプションの種類無料、プレミアム、ファミリープラン
コンテンツの嗜好主なコンテンツカテゴリーの興味
download_quality：ユーザーの好みのストリーミング品質
watch_time_bucket：カテゴリー分けされた1日の視聴時間

プロパティの上限管理：最大5つのグローバルプロパティで、アナリティクスのために最も価値のあるトラッキングディメンションを優先します。上限に達した場合は、新しいプロパティを追加する前に、重要度の低いプロパティを削除することを検討してください。インサイトを最大化するために、プロパティ戦略を慎重に計画しましょう。

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

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

プロパティの仕様

制約と永続性

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

SDK初期化前の設定

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

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

例ユーザーアクションでのプロパティの更新

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

グローバル・プロパティのアンセット

例ログアウト時のユーザ・プロパティの消去

すべてのグローバル・プロパティを消去

実装例

完全な使用パターン

一般的な使用例

ゲームアプリ

Eコマースアプリ

コンテンツ/メディアアプリ