ドキュメント

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

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

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

プロパティの仕様

制約と永続性

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

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

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

SDK初期化前の設定

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

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

// Initialize SDK with global properties
var config = new cordova.plugins.SingularCordovaSdk.SingularConfig(
  'YOUR_SDK_KEY',
  'YOUR_SDK_SECRET'
);

// Set app-level global properties before initialization
config.withGlobalProperty('app_version', '1.2.3', true);
config.withGlobalProperty('user_type', 'free', true);

// Initialize SDK with global properties
cordova.plugins.SingularCordovaSdk.init(config);

メソッドのシグネチャ：

withGlobalProperty(key: string, value: string, overrideExisting: boolean): SingularConfig

パラメータ

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

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

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

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

// Set a global property after initialization
function updatePlayerLevel(level) {
  cordova.plugins.SingularCordovaSdk.setGlobalProperty(
    'player_level',
    level.toString(),
    true,
    function(success) {
      if (success) {
        console.log('Global property set successfully');
      } else {
        console.error('Failed to set property - may have reached 5 property limit');
      }
    }
  );
}

メソッドのシグネチャ：

setGlobalProperty(key: string, value: string, overrideExisting: boolean, success: Function): void

パラメータ

キー：プロパティ名（最大200文字）
値：プロパティ値（200文字以内）
overrideExisting：同じキーを持つ既存のプロパティを上書きするかどうか。
success：プロパティが正常に設定された場合はtrue を、そうでない場合はfalse を受け取るコールバック関数。

重要：

重要： 5 個のプロパティがすでに存在していて、新規に追加しようとすると、コールバックはfalseを受け取ります。
overrideExisting パラメータは、既存のプロパティ値を置き換えるかを決定します。
必ず戻り値をチェックして、プロパティが正常に設定されたことを確認してください。

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

現在設定されているすべてのグローバル・プロパティとその値をオブジェクトとして取得します。

// Retrieve all global properties
function displayGlobalProperties() {
  cordova.plugins.SingularCordovaSdk.getGlobalProperties(function(properties) {
    // Iterate through properties
    for (var key in properties) {
      if (properties.hasOwnProperty(key)) {
        console.log('Property: ' + key + ' = ' + properties[key]);
      }
    }
  });
}

メソッドのシグネチャ：

getGlobalProperties(success: Function): void

パラメータ：

成功：すべてのグローバル・プロパティのキーと値のペアを含むオブジェクトを受け取るコールバック関数。

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

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

// Remove a specific global property
cordova.plugins.SingularCordovaSdk.unsetGlobalProperty('player_level');

メソッドのシグニチャ：

unsetGlobalProperty(key: string): void

パラメータ：

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

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

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

// Remove all global properties
cordova.plugins.SingularCordovaSdk.clearGlobalProperties();

メソッドの署名：

clearGlobalProperties(): void

ベスト・プラクティス：ユーザがログアウトしたときや、すべてのカスタムトラッキングプロパティをデフォルト状態にリセットする必要があるときに、clearGlobalProperties()。

実装例

完全な使用パターン

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

document.addEventListener('deviceready', initializeApp, false);

function initializeApp() {
  // Set app-level global properties before initialization
  var config = new cordova.plugins.SingularCordovaSdk.SingularConfig(
    'YOUR_SDK_KEY',
    'YOUR_SDK_SECRET'
  );
  
  config.withGlobalProperty('app_version', '1.2.3', true);
  config.withGlobalProperty('platform', 'cordova', true);
  
  // Initialize SDK
  cordova.plugins.SingularCordovaSdk.init(config);
}

// Set user-specific properties on login
function handleUserLogin(userId, userTier) {
  // Set third-party identifier
  cordova.plugins.SingularCordovaSdk.setGlobalProperty(
    'third_party_id',
    userId,
    true,
    function(success) {
      if (success) {
        // Set user tier property
        cordova.plugins.SingularCordovaSdk.setGlobalProperty('user_tier', userTier, true, function(tierSuccess) {
          if (tierSuccess) {
            console.log('User properties set successfully');
          }
        });
      } else {
        console.error('Failed to set user properties');
      }
    }
  );
}

// Update dynamic properties during gameplay
function handleLevelUp(newLevel) {
  cordova.plugins.SingularCordovaSdk.setGlobalProperty(
    'player_level',
    newLevel.toString(),
    true,
    function(success) {
      if (success) {
        // Track level up event
        cordova.plugins.SingularCordovaSdk.eventWithArgs('level_up', {
          new_level: newLevel
        });
      }
    }
  );
}

// Clear user-specific properties on logout
function handleUserLogout() {
  // Remove user-specific properties
  cordova.plugins.SingularCordovaSdk.unsetGlobalProperty('third_party_id');
  cordova.plugins.SingularCordovaSdk.unsetGlobalProperty('user_tier');
  cordova.plugins.SingularCordovaSdk.unsetGlobalProperty('player_level');
  
  console.log('User properties cleared');
}

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

プロパティの上限管理：最大5つのグローバルプロパティで、アナリティクスのために最も価値のあるトラッキングディメンションを優先します。上限に達したら、新しいプロパティを追加する前に、重要度の低いプロパティを削除することを検討してください。上記の例では、戻り値をチェックすることで、5 プロパティの制限を優雅に処理する方法を示しています。

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

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

プロパティの仕様

制約と永続性

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

SDK初期化前の設定

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

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

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

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

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

実装例

完全な使用パターン