SDK 初期化¶

このドキュメントでは、Cocos Creator SDK の基本設定、初期化の順序、ユーザーバインド、ライフサイクルについて説明します。

基本設定¶

import { guanceSdk } from '@cloudcare/cocos-sdk/creator3';

guanceSdk.start({
  sdk: {
    datakitUrl: 'https://your-datakit.example.com',
    serviceName: 'cocos-game',
    env: 'prod',
    debug: true,
    globalContext: {
      game_channel: 'app-store',
    },
  },
});

次のいずれかの条件を満たす必要があります。満たさない場合、初期化時に Configure datakitUrl or datawayUrl with clientToken がスローされます。

• 空でない datakitUrl を設定する。
• 空でない datawayUrl と clientToken を併せて設定する。

両方の方式を同時に設定した場合、Bridge は datakitUrl を優先して使用します。環境切り替え時にあいまいさが生じないよう、どちらか一方のみを設定することを推奨します。

SDK は基本グローバルタグに自動的に sdk_package_cocos を追加します。値は現在の Cocos npm パッケージのバージョンです。同名のカスタムタグを使用しないでください。

完全な初期化と順序¶

guanceSdk.start() は次の順序で初期化します：

1. 基本 SDK
2. RUM
3. Log
4. Trace
5. Session Replay（Replay パッケージを組み込んで replay 設定を渡した場合）
6. Cocos の自動収集

対応する設定オブジェクトを渡した場合のみ、該当モジュールが初期化されます：

以下は Replay を含む独立した完全な例です。事前に同バージョンの @cloudcare/cocos-session-replay をインストールし、インストーラーを --replay オプション付きで実行する必要があります。詳細はアプリ導入を参照してください。withSessionReplay() は、最初の start() または attach() の前に呼び出す必要があります。基本パッケージのみを使用する場合は、上記の基本設定を使用し、replay は渡しません。

import { guanceSdk as baseSdk } from '@cloudcare/cocos-sdk/creator3';
import { withSessionReplay } from '@cloudcare/cocos-session-replay/creator3';

export const guanceSdk = withSessionReplay(baseSdk);
guanceSdk.start({
  sdk: {
    datawayUrl: 'https://open.dataway.url',
    clientToken: 'client-token',
    serviceName: 'cocos-game',
    env: 'prod',
  },
  rum: {
    androidAppId: 'android-rum-app-id',
    iosAppId: 'ios-rum-app-id',
  },
  logger: {
    enableCustomLog: true,
  },
  trace: {
    traceType: 'ddTrace',
  },
  replay: {
    captureFps: 1,
  },
  autoTrack: {
    scenes: true,
  },
});

最初の収集シーンが読み込まれる前に初期化してください。また、アプリのライフサイクル全体で一度だけ呼び出されるようにしてください。初期化を繰り返すと、Native SDK または自動リスナーで状態が重複する可能性があります。

ユーザー情報のバインド¶

ユーザー ID のみを渡すこともできます：

guanceSdk.mobile.bindUser('user-123');

完全なユーザー情報を渡すこともできます：

guanceSdk.mobile.bindUser({
  userId: 'user-123',
  userName: '玩家昵称',
  userEmail: 'player@example.com',
  extra: {
    membership: 'gold',
    region: 'cn-east',
  },
});

ユーザーがログアウトするときにバインドを解除します：

guanceSdk.mobile.unbindUser();

SDK のシャットダウン¶

guanceSdk.shutdown();

このメソッドを実行すると、次の処理が行われます：

• Cocos の自動収集リスナーを削除します。
• Session Replay の定期的なフレームキャプチャを停止します。
• Native SDK をシャットダウンします。

シャットダウン後は、収集 API を呼び出し続けないでください。再度有効にする場合は、アプリを再起動して初期化を一度実行することを推奨します。

現在の Cocos API では、キャッシュの手動クリアや即時アップロードを行うメソッドは公開されていません。データのキャッシュと送信タイミングは Native SDK によって管理されます。

実行プラットフォーム¶

ブラウザプレビューと Web ビルドはサポート対象外のプラットフォームです。TypeScript の呼び出しは Native Bridge に到達せず、レポートデータも生成されません。導入の検証には、Android または iOS のネイティブビルドを使用する必要があります。

関連トピック¶

• RUM 設定
• Log 設定
• Trace 設定
• Cocos Creator セッションリプレイ（実験的）
• カスタムタグの使用