워크스페이스 준비하기

워크스페이스가 없다면 01.software에서 가입하고 온보딩을 완료하세요. 온보딩은 프로젝트(Project)와 LIVE 환경을 만듭니다. 사용할 실제 환경과 그 환경의 키를 확인하세요. 프로젝트 이름은 자격 증명이 아닙니다. 로컬 개발용 키가 데이터를 격리하거나 Sandbox를 자동으로 만들지는 않습니다. 이 예제에는 Ecommerce를 선택합니다. 다른 선택지는 기능 계획을 참고하세요. 다른 사람이 워크스페이스를 관리한다면 관리자에게 새 앱 승인을 요청하거나 기존 앱에 필요한 애플리케이션 키를 전달받으세요.

앱 연결하기

새 앱

스타터 명령을 실행하고 등록된 Next.js 스타터 중 하나를 고르세요.

npm create 01-software-app@0.2.5

브라우저 승인으로 이미 만들어진 워크스페이스를 연결합니다. 명령은 자격 증명 없이 프로젝트 파일을 만들고 의존성을 설치한 뒤, 인증을 마친 워크스페이스 관리자에게 개발 앱 승인을 요청합니다. 승인이 성공하면 워크스페이스의 Publishable Key와 새 개발용 Secret Key가 담긴 .env.local을 만듭니다. 이 경로에서는 env 파일을 따로 다운로드할 필요가 없습니다.

기존 앱

package.json이 있는 기존 프로젝트에서 다음을 실행하세요.

npx @01.software/init@0.14.3

생성된 대상별 설정 안내를 따르세요. Init은 질문을 통해 애플리케이션 키 직접 입력이나 키 없이 건너뛰기를 제공합니다. 새 앱의 브라우저 승인 흐름은 열지 않습니다. 자동 설정을 지원하지 않는 프레임워크에서는 SDK 설치와 client/server 예제를 출력합니다. 대상별 동작과 설치를 건너뛴 경우의 복구 방법은 빌드 옵션을 참고하세요.

수동 설정에 쓸 키는 온보딩에서 복사하거나 워크스페이스 관리자에게 요청하세요. 키 발급이 실패하면 완료 화면에서 다시 시도하거나 Console에서 발급하세요. 애플리케이션 키는 init의 질문에 입력합니다. 직접 연결한다면 다음과 같은 환경 변수를 사용하세요.

NEXT_PUBLIC_SOFTWARE_PUBLISHABLE_KEY=pk01_...
SOFTWARE_PUBLISHABLE_KEY=pk01_...
# Only for privileged server operations; not needed for this product count
SOFTWARE_SECRET_KEY=sk01_...

SOFTWARE_SECRET_KEY는 서버 작업에 필요한 경우에만 설정하세요. 앱이 읽는 파일 이름을 사용하세요. Next.js에서는 .env.local입니다. 새 앱의 브라우저 승인이 성공해 만든 파일을 덮어쓰지 마세요. Secret Key는 한 번만 표시됩니다. 잃어버렸다면 Console의 API 키에서 교체 키를 발급하세요.

첫 결과 표시하기

아래는 Next.js App Router의 Server Component 예제입니다. 새 앱에서는 app/page.tsx에 넣고 /를 여세요. 기존 App Router 앱에서는 홈페이지를 보존하세요. app/catalog-example/page.tsx처럼 사용하지 않는 별도 경로에 예제를 추가하고 /catalog-example을 열거나, 기존 Server Component의 내용을 대체하지 않고 호출 부분을 통합하세요. 아래 코드 제목은 새 앱의 위치입니다. 프로젝트의 개발 실행 명령으로 앱을 시작하세요. Pages Router나 다른 프레임워크에서는 이 페이지를 그대로 복사하지 말고 해당 설정에 맞춰 같은 SDK 함수를 적용하세요.

이 서버 호출에는 브라우저 Origin이 없습니다. 브라우저 코드에서 호출한다면 먼저 연동과 키에서 해당 origin을 등록하세요.

아래 동적 렌더링 설정은 next build 중 상품 개수를 미리 생성하는 대신 페이지 요청마다 상품을 조회합니다. 빌드 환경에 NEXT_PUBLIC_SOFTWARE_PUBLISHABLE_KEY를 설정하세요. Production 빌드 후 이 공개 값을 바꾸려면 앱을 다시 빌드해야 합니다.

import { createClient } from '@01.software/sdk'

export const dynamic = 'force-dynamic'

export default async function Page() {
  const client = createClient({
    publishableKey: process.env.NEXT_PUBLIC_SOFTWARE_PUBLISHABLE_KEY!,
  })
  const { cards } = await client.commerce.product.listingPage({ limit: 10 })

  return (
    <main>
      <h1>Catalog</h1>
      <p>{cards.length} published products loaded.</p>
    </main>
  )
}

화면에 Catalog와 상품 개수가 표시됩니다. 0 published products loaded.는 호출에 성공했지만 공개 상품이 없다는 뜻입니다. 상품을 만들지 않고 다음 단계로 넘어가도 됩니다. 공개 상품이 있으면 0보다 큰 개수가 표시됩니다. 이 호출에는 Publishable Key만 필요합니다.

권한 있는 서버 작업은 SDK 가이드와 인증을 참고하세요.