ドキュメント

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

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

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

プロパティの仕様

制約と永続性

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

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

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

SDK初期化前の設定

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

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

// TurboModule direct API (React Native 0.76+ New Architecture)
import React, { useEffect } from 'react';
import NativeSingular from 'singular-react-native/jsNativeSingular';

export default function App() {
  useEffect(() => {
    initializeSDK();
  }, []);

  async function initializeSDK() {
    // Initialize SDK with global properties in config
    const config: SingularConfig = {
      apikey: 'YOUR_SDK_KEY',
      secret: 'YOUR_SDK_SECRET',
      globalProperties: {
        app_version: {
          Key: 'app_version',
          Value: '1.2.3',
          OverrideExisting: true
        },
        user_type: {
          Key: 'user_type',
          Value: 'free',
          OverrideExisting: true
        }
      }
    };

    NativeSingular.init(config);
  }

  return (
    // Your app components
    null
  );
}

import React, { useEffect } from 'react';
import { Singular, SingularConfig } from 'singular-react-native';

export default function App() {
  useEffect(() => {
    initializeSDK();
  }, []);

  async function initializeSDK() {
    // Create configuration with global properties
    const config = new SingularConfig(
      'YOUR_SDK_KEY',
      'YOUR_SDK_SECRET'
    )
      // Set app-level global properties before initialization
      .withGlobalProperty('app_version', '1.2.3', true)
      .withGlobalProperty('user_type', 'free', true);

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

  return (
    // Your app components
  );
}

メソッドのシグネチャ：

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

パラメータ

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

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

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

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

// TurboModule direct API (React Native 0.76+ New Architecture)
import NativeSingular from 'singular-react-native/jsNativeSingular';

// Set a global property after initialization
async function updatePlayerLevel(level) {
  const success = await NativeSingular.setGlobalProperty(
    'player_level',
    level.toString(),
    true
  );

  if (success) {
    console.log('Global property set successfully');
  } else {
    console.error('Failed to set property - may have reached 5 property limit');
  }
}

import { Singular } from 'singular-react-native';

// Set a global property after initialization
async function updatePlayerLevel(level) {
  const success = await Singular.setGlobalProperty(
    'player_level',
    level.toString(),
    true
  );

  if (success) {
    console.log('Global property set successfully');
  } else {
    console.error('Failed to set property - may have reached 5 property limit');
  }
}

メソッドのシグネチャ：

static setGlobalProperty(key: string, value: string, overrideExisting: boolean): Promise<boolean>

戻り値：プロパティが正常に設定された場合はtrue に解決するPromise<boolean> を、そうでない場合はfalse を返します。

重要：

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

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

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

// TurboModule direct API (React Native 0.76+ New Architecture)
import NativeSingular from 'singular-react-native/jsNativeSingular';

// Retrieve all global properties
async function displayGlobalProperties() {
  const properties = await NativeSingular.getGlobalProperties();

  // Iterate through properties
  Object.entries(properties).forEach(([key, value]) => {
    console.log(`Property: ${key} = ${value}`);
  });
}

import { Singular } from 'singular-react-native';

// Retrieve all global properties
async function displayGlobalProperties() {
  const properties = await Singular.getGlobalProperties();

  // Iterate through properties
  Object.entries(properties).forEach(([key, value]) => {
    console.log(`Property: ${key} = ${value}`);
  });
}

メソッドのシグニチャ：

static getGlobalProperties(): Promise<Record<string, any>>

戻り値すべてのグローバル・プロパティのキーと値のペアを含むオブジェクトに解決する Promise。

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

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

// TurboModule direct API (React Native 0.76+ New Architecture)
import NativeSingular from 'singular-react-native/jsNativeSingular';

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

import { Singular } from 'singular-react-native';

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

メソッドのシグニチャ：

static unsetGlobalProperty(key: string): void

パラメータ

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

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

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

// TurboModule direct API (React Native 0.76+ New Architecture)
import NativeSingular from 'singular-react-native/jsNativeSingular';

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

import { Singular } from 'singular-react-native';

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

メソッドの署名：

static clearGlobalProperties(): void

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

実装例

完全な使用パターン

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

// TurboModule direct API (React Native 0.76+ New Architecture)
import React, { useEffect } from 'react';
import NativeSingular from 'singular-react-native/jsNativeSingular';

export default function App() {
  useEffect(() => {
    initializeSDK();
  }, []);

  async function initializeSDK() {
    // Set app-level global properties before initialization
    const config: SingularConfig = {
      apikey: 'YOUR_SDK_KEY',
      secret: 'YOUR_SDK_SECRET',
      globalProperties: {
        app_version: {
          Key: 'app_version',
          Value: '1.2.3',
          OverrideExisting: true
        },
        platform: {
          Key: 'platform',
          Value: 'react-native',
          OverrideExisting: true
        }
      }
    };

    // Initialize SDK
    NativeSingular.init(config);
  }

  // Set user-specific properties on login
  async function handleUserLogin(userId, userTier) {
    // Set third-party identifier
    const success = await NativeSingular.setGlobalProperty(
      'third_party_id',
      userId,
      true
    );

    if (success) {
      // Set user tier property
      await NativeSingular.setGlobalProperty('user_tier', userTier, true);
      console.log('User properties set successfully');
    } else {
      console.error('Failed to set user properties');
    }
  }

  // Update dynamic properties during gameplay
  async function handleLevelUp(newLevel) {
    await NativeSingular.setGlobalProperty('player_level', newLevel.toString(), true);

    // Track level up event
    NativeSingular.eventWithArgs('level_up', {
      new_level: newLevel
    });
  }

  // Clear user-specific properties on logout
  function handleUserLogout() {
    // Remove user-specific properties
    NativeSingular.unsetGlobalProperty('third_party_id');
    NativeSingular.unsetGlobalProperty('user_tier');
    NativeSingular.unsetGlobalProperty('player_level');

    console.log('User properties cleared');
  }

  return (
    // Your app components
    null
  );
}

import React, { useEffect } from 'react';
import { Singular, SingularConfig } from 'singular-react-native';

export default function App() {
  useEffect(() => {
    initializeSDK();
  }, []);

  async function initializeSDK() {
    // Set app-level global properties before initialization
    const config = new SingularConfig(
      'YOUR_SDK_KEY',
      'YOUR_SDK_SECRET'
    )
      .withGlobalProperty('app_version', '1.2.3', true)
      .withGlobalProperty('platform', 'react-native', true);

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

  // Set user-specific properties on login
  async function handleUserLogin(userId, userTier) {
    // Set third-party identifier
    const success = await Singular.setGlobalProperty(
      'third_party_id',
      userId,
      true
    );

    if (success) {
      // Set user tier property
      await Singular.setGlobalProperty('user_tier', userTier, true);
      console.log('User properties set successfully');
    } else {
      console.error('Failed to set user properties');
    }
  }

  // Update dynamic properties during gameplay
  async function handleLevelUp(newLevel) {
    await Singular.setGlobalProperty('player_level', newLevel.toString(), true);

    // Track level up event
    Singular.eventWithArgs('level_up', {
      new_level: newLevel
    });
  }

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

    console.log('User properties cleared');
  }

  return (
    // Your app components
  );
}

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

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

React Native SDK - グローバル・プロパティの設定

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

プロパティの仕様

制約と永続性

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

SDK初期化前の設定

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

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

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

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

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

実装例

完全な使用パターン