Croct SDK の統合
Croct SDK をアプリケーションに組み込み、スロットコンテンツのレンダリング、CQL の評価、ユーザーの識別を行います。 コンテンツとオーディエンスは Croct ダッシュボードで管理され、コードは ID とバージョンでスロットを参照し、フォールバックを提供するだけです。
ワークフロー
- [ ] 1. 使用しているスタックを検出し、SDK を選択する（以下の表を参照）
- [ ] 2. CLI でインストールする（`croct init`、ユーザーが実行）。手動でのインストールは、ユーザーから依頼があった場合、または CLI が実行できない場合のみ行う
- [ ] 3. CLI でスロットを追加する（`npx croct@latest add slot home-hero@1 --example`）。タイプ定義とフォールバックが生成される
- [ ] 4. レンダリングする：フレームワークが許可する場合はサーバーサイド、それ以外はクライアントサイド
- [ ] 5. ログイン/ログアウト時にユーザーを識別/匿名化する（または初期化時にユーザー ID を渡す）
- [ ] 6. 確認する：統合ページに「過去 24 時間のトラフィックを受信しました」と表示されることを確認する。表示されない場合はデバッグモードを有効にする
1. SDK を選択する
最初に package.json / composer.json を読み込んでください。フレームワークに最も特化した SDK を選択し、React、Next.js、Vue、Nuxt、Hydrogen の内部でプレーンな JavaScript SDK を決して使用しないでください。
| スタック | パッケージ | 初期化方法 | サーバーレンダリング | リファレンス |
|---|---|---|---|---|
プレーン JS、任意のバンドラー、または <script> タグ | @croct/plug（または https://cdn.croct.io/js/v1/lib/plug.js） | 起動時に croct.plug({appId}) を 1 回実行 | apiKey を使用して @croct/plug/api から fetchContent/evaluate をスタンドアロンで実行 | javascript.md |
| React（SPA、Vite、Next 以外の SSR） | @croct/plug-react | ルートで <CroctProvider appId="..."> を使用 | クライアントフックは initial が必要。低レベル API は @croct/plug-react/api | react.md |
| Next.js（App Router または Pages Router） | @croct/plug-next | ミドルウェア（15 以下）/ プロキシ（16 以上）+ @croct/plug-next/CroctProvider の <CroctProvider> | はい： @croct/plug-next/server | nextjs.md |
| Vue | @croct/plug-vue | app.use(createCroct({appId})) | コンポーザブル/コンポーネント。SSR では initial 値が必要 | vue.md |
| Nuxt | @croct/plug-nuxt | nuxt.config に modules: ['@croct/plug-nuxt'] を追加 | はい | nuxt.md |
| Shopify Hydrogen（React Router 7 または Remix） | @croct/plug-hydrogen | Vite プラグイン + @croct/plug-hydrogen/server の createCroctMiddleware / createCroctContext | はい | hydrogen.md |
| プレーン PHP | croct/plug-php（+ PSR-18 クライアント、例：guzzlehttp/guzzle nyholm/psr7） | 出力前に Croct::fromDotenv() を実行し、その後 Croct::emitCookies() を実行 | はい（サーバーファースト） | php.md |
| Laravel | croct/plug-laravel | .env に認証情報を設定 | はい | laravel.md |
| Symfony | croct/plug-symfony symfony/twig-bundle | config/bundles.php にバンドルを登録 + .env に認証情報を設定 | はい（Twig） | symfony.md |
| Drupal | croct/plug-drupal | モジュールを有効化。settings.php に認証情報を設定。キャッシュを再構築 | はい | drupal.md |
| Storyblok（JS または PHP） | — | croct-integrate-platforms スキルを使用 | — | — |
| サポート外の言語または生の HTTP | — | croct-use-api スキルを使用 | — | — |
2. インストール
すべての SDK の統合ページ（PHP、Laravel、Symfony、Drupal、Hydrogen を含む）では、CLI が推奨されています。init はインタラクティブで、ログインセッションが必要です。そのため、ユーザー自身のターミナルでプロジェクトルートから実行するよう依頼してください：
npx croct@latest init
croct init はフレームワークを検出し、ログインし、組織/ワークスペース/アプリケーションを選択し、一致する SDK をインストールし、セットアップ（プロバイダー、ミドルウェア、環境変数）を配線します。ユーザーがすでにセッションを持っており、ID を把握している場合は、非インタラクティブ形式を自分で実行することもできます：
npx croct@latest --no-interaction init --sdk next --org <org> --wor <workspace> --dev-app <dev-app> --prod-app <prod-app>
（--sdk は javascript、react、vue、next、nuxt のみを受け付けます。省略すると自動検出されます）。フラグ、CI での使用、croct.json については croct-use-cli スキルを参照してください。フレームワークのリファレンスファイルにある手動の手順は、ユーザーから依頼があった場合、または CLI が実行できない場合のみフォールバックとして使用してください。
3. スロットを追加する
必ずスロット ID とバージョンを渡してください。これらがない場合、CLI はスロットの入力を求めますが、あなたはそれに答えることができません：
npx croct@latest add slot home-hero@1 --example
これにより、TypeScript の型定義（useContent('home-hero@1') / fetchContent('home-hero@1') が型付けされるようになります）が生成され、スロットのデフォルトコンテンツが自動フォールバックとしてダウンロードされ、動作するサンプルコードが作成されます。ダッシュボードで変更があった後は、croct install / croct update を再実行して再同期してください（croct-use-cli を参照）。
コアコンセプト（全 SDK 共通）
スロット ID とバージョン
- スロットを
<id>@<version>として参照します。例：home-hero@1。バージョンなし（home-hero）はhome-hero@latestを意味します。 - 常にバージョンを固定してください。 固定されていないスロットは、破壊的なスキーマ変更を即座に受け取ってしまいます。ダッシュボードで新しいメジャーバージョンが作成されても、コードのバージョンが更新されるまで、アプリは古いバージョンを受け取り続けます。
- コンテンツを
SlotContent<'home-hero@1'>とComponentContent<'card@1'>で型付けします（@croct/plug、@croct/plug-react、@croct/plug-nextからエクスポートされます）。ユニオンスロットは_typeで差別化されたユニオンに解決されます。
フォールバック、デフォルト、初期コンテンツ
| 用語 | 説明 | 取得元 |
|---|---|---|
| デフォルトコンテンツ | 一致するエクスペリエンスがない、ロケールのコンテンツがない、静的コンテンツがリクエストされた、または取得に失敗した場合に表示されるスロットコンテンツ | ダッシュボード |
| フォールバック | リクエストが失敗した場合にレンダリングされる値 | fallback オプション（コード内）、または CLI でダウンロードされたデフォルトコンテンツ（@croct/content） |
| 初期コンテンツ（React/Next クライアントフック） | SSR/プリレンダリング中およびクライアントでの読み込み中にレンダリングされる値 | initial オプション。CLI が自動的に追加 |
SDK 内での解決順序：動的コンテンツ → 明示的な fallback → CLI デフォルトコンテンツ → エラー。フォールバックがなく、CLI コンテンツもない場合、取得に失敗するとエラーがスローされます（JS croct.fetch は拒否します）。CLI コンテンツは、@croct/content の getSlotContent(slotId, locale?) / loadSlotContent(slotId, locale?) を使用して直接読み取ります（コード分割を備えた非同期の方を推奨します）。
クライアント vs サーバーレンダリング
| 要件 | 対応方法 |
|---|---|
| 最初の HTML に最終コンテンツを含め、ちらつきをなくし、クロール可能にする | サーバーで取得する（Next の fetchContent（@croct/plug-next/server から）、Nuxt、Hydrogen、PHP ファミリー） |
ページを静的ファイル / CDN / output: 'export' のままにしておく必要がある | initial 値を指定したクライアントフック/コンポーネント、または <Suspense> バウンダリを使用する |
| スケルトンで問題ない、スクロールしないと見えないセクション | クライアントサイドで問題ない |
| プレーンな React / カスタム SSR でのサーバーレンダリング | apiKey を使用して @croct/plug-react/api（または @croct/plug/api）から fetchContent / evaluate を実行し、コンテンツを props として渡す |
サーバーサイドのリクエストは API キーで認証します（これをブラウザに送信してはいけません）。クライアントサイドのリクエストは アプリケーション ID を使用します。スタンドアロン関数に appId と apiKey の両方を渡すことはエラーです。
クエリ評価
CQL を実行時に評価するには、croct.evaluate(query, {attributes})（JS）、useEvaluation / <Personalization>（React/Next クライアント）、または evaluate / cql`...`（Next サーバー）を使用します。クエリは 500 文字に制限されています。結果は任意の JSON にできます（'location' はオブジェクトを返します）。常にフォールバックを指定してください（.catch(() => false) または fallback: false）。CQL の構文については croct-cql スキルを参照してください。
評価かスロットか？ドキュメントでは、スロットはコード変更なしでコンテンツを更新する方法として提示されています。評価されたクエリはコード内に存在し、デプロイによってのみ変更されます。
| 要件 | 使用するもの |
|---|---|
| マーケターが変更、スケジュール、A/B テストするコンテンツ、オーディエンス、またはロールアウト | スロットとエクスペリエンス（croct-personalize-and-test を参照） |
| エンジニアリングによって修正されるロジック（ウィジェットの表示/非表示、条件による分岐）、編集するコンテンツがない | フォールバック付きの evaluate / useEvaluation |
コンテキスト属性
アプリ固有のデータ（プラン、カートの状態）を attributes（JS/React）または context.attributes（Next サーバー、スタンドアロン関数）として渡し、CQL では context's plan is "premium" として読み取ります。制限：最大 30 エントリ、5 レベルの深さ、キーは 50 文字以下、文字列値は 50 文字以下。
認証情報と環境変数
| スタック | アプリ ID | API キー |
|---|---|---|
| Next.js | NEXT_PUBLIC_CROCT_APP_ID | CROCT_API_KEY |
| Nuxt | NUXT_PUBLIC_CROCT_APP_ID | NUXT_CROCT_API_KEY |
| Hydrogen | PUBLIC_CROCT_APP_ID | CROCT_API_KEY |
| PHP、Laravel、Symfony | CROCT_APP_ID | CROCT_API_KEY |
| Drupal | $settings['croct.app_id'] | $settings['croct.api_key'] |
| JavaScript、React、Vue | appId オプション / プロパティ | サーバーサイドのスタンドアロン関数のみ |
- アプリ ID はアプリケーションの統合ページで確認できます。キーは API キーページで作成します。
- ユーザートークンを発行するサーバー SDK（Next.js）の場合、API キーには ユーザートークンの発行 権限が必要です。
- 各環境には独自のアプリケーションがあります。ローカルホストで本番用アプリ ID を使用すると（またはその逆）、無効な認証情報で失敗します。
識別と匿名化
- ログイン/サインアップ時に
identify(userId)を、ログアウト時にanonymize()を呼び出します。ID が変わると、現在のセッションは終了し、新しいセッションが開始されます。 - ページの読み込み時にユーザーがすでにログインしている場合は、初期化時に ID を渡します（
croct.plug/<CroctProvider>のuserId）。これにより、SDK が余分な匿名セッションを作成するのを防げます。 userIdは 文字列 である必要があります。数値 ID は（できればサーバーサイドで）変換してください。ランダム ID（UUID v4）を、メールや連番よりも推奨します。- アプリケーション設定で 署名付きトークンを要求 がオンの場合、
userId/identify（未署名トークン）は失敗します。代わりに署名付きtokenを渡してください。Next.js はCROCT_API_KEYを使用してトークンに自動的に署名します。 - Next.js：ミドルウェア/プロキシで
withCroct({userIdResolver})を使用して、トークンをすべてのリクエストで認証セッションと同期させることを推奨します。
知っておくと便利なプラグオプション
appId、debug、test、track（自動トラッキング、デフォルト true）、userId / token（相互排他的）、tokenScope（global | isolated | contextual）、defaultFetchTimeout（JS/React 5000 ms、Next 2000 ms）、defaultPreferredLocale、baseEndpointUrl（モックサーバー）、cookie（クライアント ID / ユーザートークン / プレビュートークンをファーストパーティクッキーに保存）、eventMetadata、urlSanitizer、logger。完全なリストは javascript.md を参照してください。
トラッキングとデータ収集
目標を croct.track('goalCompleted', {goalId}) で追跡します。プロファイル/セッションは croct.user.edit().set(...).save() / croct.session.edit() で編集します。イベントカタログ、推奨イベント、属性ルールについては croct-track-events スキルを参照してください。
注意点
以下のことを行ってください：
- スロットのバージョンを固定し（
home-hero@1）、フォールバックを保持する（CLI デフォルトコンテンツまたは明示的）。 - サーバー上でレンダリングされる可能性のあるすべてのクライアント
useContent/useEvaluationにinitial（または<Suspense>）を提供する。 - クライアント専用の
Plugメソッド（useCroct().track、identify、user.edit）は、useEffectまたはイベントハンドラ内でのみ呼び出し、レンダリング中には決して呼び出さない。 - SDK を読み込むすべてのドメインを、アプリケーションの 信頼できるオリジン に追加する。
- 何かがおかしい場合は、まずデバッグモードをオンにし（
debug: true、NEXT_PUBLIC_CROCT_DEBUG=true）、その後ネットワークタブを確認する。
以下のことを行わないでください：
croct.plugを 2 回呼び出す（最初にunplug()を呼び出すこと）。またはplugより前にメソッドを呼び出す（「Croct is not plugged in」エラー）。- API キーをクライアントコードまたは
NEXT_PUBLIC_*変数に配置する。 - アプリ ID をスクリプトタグ
?appId=とplugの両方で指定する（競合するアプリ ID エラー）。 - 静的ファイルとして保持したいルートで Next の
fetchContentを呼び出す。これによりルートが動的レンダリングに変更されます。代わりにクライアントフックを使用してください。 - Next.js App Router の外部で
cqlタグを使用する。その場合はevaluateとrouteを使用してください。
よくあるエラー
| エラー | 修正方法 |
|---|---|
Croct is not plugged in. | 他の呼び出しより前に、起動時に croct.plug を呼び出す |
The app ID must be specified when it cannot be auto-detected. | appId（またはスクリプトタグに ?appId=）を渡す |
The request was not authorized, most likely due to invalid credentials. | アプリ ID が間違っている、環境が間違っている、トークンの有効期限切れ/改ざん（クッキーとローカルストレージをクリア）、または 署名付きトークンを要求 がオンの場合の未署名トークン |
CORS エラー / The origin of the request is not allowed in your application settings. | ドメインを信頼できるオリジンに追加する |
The user ID must be a string. | ID を文字列に変換する |
The request timed out. | timeout / デフォルトタイムアウトを増やす。デバッグログで X-Croct-Timing / X-Croct-Region を確認する |
The query is too complex. | クエリが 500 文字を超えている。簡略化、分割、または属性を介してデータを渡す |
The service is temporarily suspended. | コードのバグではない：ワークスペースが停止されている、またはボットトラフィック（X-Suspension-Reason）。フォールバックを維持する |
The application has exceeded the monthly active users (MAU) quota. | プランをアップグレードするか、次のサイクルを待つ |
useCroct() can only be used in the context of a <CroctProvider> component. | ツリーを <CroctProvider> でラップする |
The initial content/value is required for server-side rendering (SSR). | initial を追加するか、サーバー上で取得する |
Did you forget to configure Croct's middleware? | Next ミドルウェア/プロキシを追加する |
someFunction() requires specifying the route parameter outside app routes. | route: context を渡す（Pages Router/API ルート） |
Did you forget to set the SOME_ENV_VAR environment variable? | NEXT_PUBLIC_CROCT_APP_ID / CROCT_API_KEY を設定する |
| 公開後にコンテンツが更新されない（エラーなし） | クライアントフックは結果を expiration（60 秒、レンダリングのたびに延長）キャッシュします。cacheKey を変更して強制的に再取得します。変更が公開されており、下書きではないことを確認してください。固定されたバージョン（home-hero@1）は新しいメジャーバージョンを取得しません。croct upgrade を実行してください。リクエスト失敗後にフォールバックが古くなっている場合：croct update で CLI デフォルトコンテンツを更新します |
リファレンスインデックス
使用中のスタックに対応するファイルのみを読み込んでください。
- references/javascript.md —
@croct/plug：プラグオプション、fetch、evaluate、test、ID、パッチ、スタンドアロン@croct/plug/api、テスト、エラー。 - references/react.md —
@croct/plug-react：プロバイダー、useContent、<Slot>、useEvaluation、<Personalization>、useCroct、SSR 初期値、テスト。 - references/nextjs.md —
@croct/plug-next：App Router / Pages Router、ミドルウェア、プロキシ、fetchContent、cql、useEvaluation、identify、サーバークライアント、テスト、エラー。 - references/vue.md —
@croct/plug-vue：セットアップ、useContent、useEvaluation、useCroct、SSR。 - references/nuxt.md —
@croct/plug-nuxt：セットアップ、useContent、useEvaluation、SSR。 - references/hydrogen.md —
@croct/plug-hydrogen：Vite プラグイン、ミドルウェア、コンテキスト、useContent、fetchContent、useEvaluation。 - references/php.md —
croct/plug-php：セットアップ、fetchContent、evaluate、identify、認証情報。 - references/laravel.md —
croct/plug-laravel：セットアップ、ブレード、fetchContent、evaluate。 - references/symfony.md —
croct/plug-symfony：セットアップ、Twig、fetchContent、evaluate。 - references/drupal.md —
croct/plug-drupal：セットアップ、Twig、PHP 関数。