Croct SDK 통합하기
Croct SDK를 앱에 연결하여 슬롯 콘텐츠를 렌더링하고, CQL을 평가하며, 사용자를 식별합니다. 콘텐츠와 대상(Audience)은 Croct 대시보드에 있으며, 코드는 슬롯을 ID와 버전으로 참조하고 폴백을 제공하기만 하면 됩니다.
워크플로
- [ ] 1. 스택(Stack)을 감지하고 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}) 한 번 | @croct/plug/api에서 apiKey와 함께 독립형 fetchContent/evaluate 사용 | javascript.md |
| React (SPA, Vite, Next가 아닌 모든 SSR) | @croct/plug-react | 루트에서 <CroctProvider appId="..."> | 클라이언트 훅은 initial 필요; 저수준 @croct/plug-react/api 사용 | react.md |
| Next.js (App 또는 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은 초기 값 필요 | 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. 설치
PHP, Laravel, Symfony, Drupal 및 Hydrogen을 포함한 모든 SDK의 통합 페이지는 CLI를 권장합니다. init은 대화형이며 로그인 세션이 필요하므로 사용자에게 프로젝트 루트에서 자신의 터미널에서 실행하도록 요청하십시오:
npx croct@latest init
croct init은 프레임워크를 감지하고, 로그인하고, 조직/워크스페이스/애플리케이션을 선택하고, 일치하는 SDK를 설치하고, 설정(Provider, 미들웨어, 환경 변수)을 연결합니다. 사용자가 이미 세션이 있고 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를 의미합니다. - 항상 버전을 고정(pin)하십시오. 고정되지 않은 슬롯은 주요 스키마 변경이 즉시 적용됩니다. 대시보드에서 새 메이저 버전을 생성하면 코드가 업데이트될 때까지 앱은 계속 이전 버전을 수신합니다.
SlotContent<'home-hero@1'>및ComponentContent<'card@1'>(@croct/plug,@croct/plug-react,@croct/plug-next에서 내보내짐)으로 콘텐츠에 타입을 지정하십시오. 유니온 슬롯은_type에 대한 판별 유니온으로 확인됩니다.
폴백(Fallback), 기본(Default), 및 초기(Initial) 콘텐츠
| 용어 | 설명 | 출처 |
|---|---|---|
| 기본 콘텐츠 | 일치하는 경험이 없거나, 로케일에 콘텐츠가 없거나, 정적 콘텐츠가 요청되거나, 검색에 실패할 때 표시되는 슬롯 콘텐츠 | 대시보드 |
| 폴백(Fallback) | 요청이 실패할 때 렌더링되는 값 | 코드의 fallback 옵션, 또는 CLI에서 다운로드한 기본 콘텐츠 (@croct/content) |
| 초기(Initial) (React/Next 클라이언트 훅) | SSR/프리렌더링 중 및 클라이언트에서 로딩 중에 렌더링되는 값 | initial 옵션; CLI가 자동으로 추가 |
SDK에서의 해결 순서: 동적 콘텐츠 → 명시적 fallback → CLI 기본 콘텐츠 → 오류. 폴백이 없고 CLI 콘텐츠가 없으면 실패한 fetch는 오류를 발생시킵니다 (JS croct.fetch는 거부). @croct/content의 getSlotContent(slotId, locale?) / loadSlotContent(slotId, locale?)을 사용하여 CLI 콘텐츠를 직접 읽으십시오 (코드 분할과 함께 비동기 버전 선호).
클라이언트 vs 서버 렌더링
| 필요 | 작업 |
|---|---|
| 최종 콘텐츠가 첫 HTML에 포함되어야 하고, 깜빡임이 없으며, 크롤링 가능해야 함 | 서버에서 fetch (Next @croct/plug-next/server의 fetchContent, 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 테스트하는 콘텐츠, 대상(Audience) 또는 롤아웃 | 슬롯 및 경험 (Experience) (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 옵션 / prop | 서버 측 독립형 함수 전용 |
- 앱 ID는 애플리케이션의 통합 페이지에서 찾을 수 있습니다. API 키는 API 키 페이지에서 생성하십시오.
- 사용자 토큰을 발급하는 서버 SDK (Next.js)의 경우 API 키에 사용자 토큰 발급(Issue user tokens) 권한이 필요합니다.
- 각 환경에는 고유한 애플리케이션이 있습니다. 로컬호스트에서 프로덕션 앱 ID를 사용하거나 그 반대의 경우 잘못된 자격 증명으로 실패합니다.
식별 및 익명화
- 로그인/가입 시
identify(userId)를 호출하고 로그아웃 시anonymize()를 호출하십시오. ID 변경은 현재 세션을 종료하고 새 세션을 시작합니다. - 페이지 로드 시 사용자가 이미 로그인되어 있으면 초기화 시 ID를 전달하여 (
croct.plug의userId/<CroctProvider>) SDK가 추가 익명 세션을 생성하지 않도록 하십시오. userId는 문자열이어야 합니다. 숫자 ID는 (가급적 서버 측에서) 변환하십시오. 이메일이나 순차 번호보다는 임의 ID (UUID v4)를 선호하십시오.- 애플리케이션 설정에서 서명된 토큰 필요(Require signed token) 가 켜져 있으면
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를 로드하는 모든 도메인을 애플리케이션의 신뢰할 수 있는 출처(Trusted origins) 에 추가하십시오.
- 문제가 발생하면 먼저 디버그 모드를 켜고 (
debug: true,NEXT_PUBLIC_CROCT_DEBUG=true), 그 다음 네트워크 탭을 확인하십시오.
하지 말아야 할 일:
croct.plug를 두 번 호출하지 마십시오 (먼저unplug()호출) 또는plug전에 메서드를 호출하지 마십시오 ("Croct is not plugged in" 오류 발생).- API 키를 클라이언트 코드나
NEXT_PUBLIC_*변수에 넣지 마십시오. - 앱 ID를 스크립트 태그
?appid=와plug모두에 지정하지 마십시오 (충돌하는 앱 ID 오류 발생). - 정적으로 유지하려는 라우트에서 Next
fetchContent를 호출하지 마십시오. 이 함수는 라우트를 동적 렌더링으로 전환합니다. 해당 라우트에서는 클라이언트 훅을 사용하십시오. - Next.js App Router 외부에서
cql태그를 사용하지 마십시오.route와 함께evaluate를 사용하십시오.
일반적인 오류
| 오류 | 해결 방법 |
|---|---|
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을 추가하거나 서버에서 fetch하십시오 |
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, identity, 패치, 독립형@croct/plug/api, 테스트, 오류. - references/react.md —
@croct/plug-react: Provider,useContent,<Slot>,useEvaluation,<Personalization>,useCroct, SSR 초기 값, 테스트. - references/nextjs.md —
@croct/plug-next: 미들웨어withCroct, 서버fetchContent/evaluate, 클라이언트 훅 (훅은@croct/plug-react),cql템플릿 태그, App Router vs Pages Router, 액세스 토큰, 환경 변수, 빌드 오류, 엣지 런타임. - references/vue.md —
@croct/plug-vue: 플러그인,useContent,useEvaluation컴포저블,Slot/Personalization컴포넌트, SSR 초기 값. - references/nuxt.md — Nuxt 모듈, 서버
useCroctServer, 컴포저블, 자동 가져오기,runtimeConfig. - references/hydrogen.md — Vite 플러그인, 서버 미들웨어 및 컨텍스트, Hydrogen 컴포저블 (
useContent,useEvaluation,useSession), Hydrogen 스토어프론트. - references/php.md —
croct/plug-php: 정적 팩토리, 서버 측 슬롯 / CQL, 사용자 세션, 대시보드 동기화. - references/laravel.md — Laravel 서비스 프로바이더, Blade 지시문, 사용자 식별자 리졸버.
- references/symfony.md — Twig 확장 (
slot,evaluate), Symfony 번들,PlugController, 이벤트 구독자. - references/drupal.md — Drupal 모듈, Twig 함수 (
slot,cql), 사용자 동기화, 캐시. - croct-use-cli.md — CLI:
croct init,install,add slot,update,upgrade,logout; 자격 증명; CI;croct.json. - croct-cql.md — CQL: 조건 연산자,
context,user,session,location, 날짜/시간, 집계, 부울, 문자열 보간(personalisations). - croct-personalize-and-test.md — 경험, A/B/n 테스트, 개인화, 타겟팅, 예약, 스케줄, 게재중지(
holdout), 전환 추적, 통계. - croct-track-events.md — 이벤트: 표준 이벤트 카탈로그, 커스텀 이벤트, 속성, 스키마,
track(), 이벤트 로그. - croct-integrate-platforms.md — Storyblok 필드 타입, 콘텐츠 동기화.
- croct-use-api.md — Croct HTTP API: 인증, 슬롯, 평가, 사용자, 이벤트, 조직, 워크스페이스, 애플리케이션.
- croct-design-and-token.md — 스타일링:
@croct/plug의TokenProvider, CSS 사용자 정의 속성(CSS custom properties), 디자인 토큰, Croct JSON, 웹폰트(Webfont).