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 セッションリプレイ（実験的）
• カスタムタグの使用