---
title: Next.js
description: Next.js（App Router）用のヘルパー。
---

`@nulogic/cozeni-sdk/next` は Next.js（App Router）で購入者限定ページを守るためのヘルパーです。Next.js 15 と 16 に対応します。お客様が戻ってきたときのコードの交換、ページの認可、入場画面へのリダイレクトを行います。

## インストール

```package-install
npm i @nulogic/cozeni-sdk@0.8.0
```

`next` は peer dependency です。対応するバージョンは `^15.0.0 || ^16.0.0` です。

:::caution
`@nulogic/cozeni-sdk/next` は Next.js のバンドラ（webpack または Turbopack）を通してだけ動きます。Node.js の ESM として直接読み込むと、解決できません。`@nulogic/cozeni-sdk` の本体はこの制約を受けません。
:::

## 最小のコード例

proxy と、保護するページの例です。Route Handler、Server Action、購入者ポータルへのボタンまで含む完成例は、SDK の導入例（[`examples/nextjs`](https://github.com/nulogic-jp/cozeni-sdk/tree/main/examples/nextjs)）にあります。

Next.js 16 では `proxy.ts` に書きます。Next.js 15 では `middleware.ts` に `export { cozeniProxy as middleware } from "@nulogic/cozeni-sdk/next";` と書きます。

```ts title="proxy.ts"
export { cozeniProxy as proxy } from "@nulogic/cozeni-sdk/next";

export const config = {
  matcher: ["/((?!_next/static|_next/image|favicon.ico).*)"],
};
```

```tsx title="app/members/page.tsx"
import { AccessDenied, requireEntitlement } from "@nulogic/cozeni-sdk/next";

export const dynamic = "force-dynamic";

export default async function Page() {
  try {
    // 権利が無ければ入場画面へ redirect する
    await requireEntitlement("prd_...");
  } catch (error) {
    // redirect() の例外は握りつぶさず、投げ直す
    if (!(error instanceof AccessDenied)) throw error;
    return <p>表示できません</p>;
  }
  return <p>限定の内容</p>;
}
```

## サンドボックス

サンドボックスに接続するには、サーバーの環境変数に `COZENI_ENVIRONMENT=sandbox` を設定します。ローカルでは `.env.local` に書きます。`.env.local` は Git に含めないでください。

```sh title=".env.local"
COZENI_SITE_ORIGIN=http://localhost:3000
COZENI_ENVIRONMENT=sandbox
```

サンドボックスで機能フラグを使うときは、`COZENI_API_KEY` にも同じ環境のキーを設定します。環境変数の一覧は下の「主な関数」の「環境変数」を見てください。

## 主な関数

### ハンドオフ

お客様が Cozeni から戻ったときに、`cozeni_code` を交換して Cookie を設定します。

| 関数 | 使う場所 | 振る舞い |
| --- | --- | --- |
| `cozeniProxy(request)` | `proxy.ts` の `proxy`、または `middleware.ts` | `cozeni_code` 付きの GET でコードを交換し、`cozeni_customer` を設定します。コードを除いた同じ URL へ 303 で戻します。 |
| `handleCozeniHandoff(request, options?)` | 既存の proxy、middleware の中 | コードの交換だけを行います。戻り値が `undefined` でなければ、その Response を返します。 |
| `clearCozeniHandoff(request, response)` | 既存の proxy、middleware の中 | 直前のハンドオフの結果を示す Cookie を消し、`Response` を返します。 |

`cozeniProxy` と `handleCozeniHandoff` は非同期で、`Response` または `undefined` を返します。`handleCozeniHandoff` の `options` は次の項目を指定できます。すべて省略できます。

| オプション | 意味 |
| --- | --- |
| `apiOrigin` | API のオリジンです。省略すると環境変数から決まります。 |
| `siteOrigin` | 戻り先のサイトのオリジンです。省略すると `COZENI_SITE_ORIGIN` を使います。 |
| `fetch` | `fetch` の差し替えです。テストに使います。 |
| `timeoutMs` | 通信の待ち時間です。既定は5000（5秒）、範囲は1から120000です。 |

`cozeniProxy` はオプションを受け取りません。

ハンドオフの結果は `cozeni_handoff` という Cookie で次のリクエストに伝えます。値は `ok`、`invalid_code`、`unavailable` のいずれかで、有効期間は60秒です。

既存の認証や middleware がある場合は、`cozeniProxy` で置き換えないでください。`handleCozeniHandoff` と `clearCozeniHandoff` を、既存の処理に組み込みます。

:::caution
購入者の Cookie はアクセスされたホストに付きます。サイトは1つのオリジンで公開してください。例えば `www` の有無はリダイレクトで1つに統一します。お客様が `COZENI_SITE_ORIGIN` と違うホストでアクセスすると、交換されたコードは消費されますが、Cookie は戻り先に届きません。
:::

### ページの認可

| 関数 | 使う場所 | 振る舞い |
| --- | --- | --- |
| `requireEntitlement(productId, options?)` | ページだけ | 権利があれば何も返さず完了します。権利が無く、入場画面の URL があれば redirect します。ハンドオフの直後、判定できないとき、URL が無いときは `AccessDenied` を投げます。 |
| `AccessDenied` | `requireEntitlement` の catch | 拒否の理由（`reason`）と、判定結果（`entitlement`）を持ちます。 |
| `entitlement(productId, options?)` | Route Handler、Server Action | `Promise<Entitlement>` を返します。redirect はしません。 |
| `nextEntitlement(options)` | API の接続先を直接指定するとき | `options.apiOrigin` と `options.productId` は必須です。Cookie から購入者を読み、`Promise<Entitlement>` を返します。接続先の設定不備や通信の失敗では `unavailable` を返します。 |
| `denialStatus(reason)` | 拒否理由からステータスだけを得たいとき | `no_session` は 401、`unavailable` は 503、`no_grant` と `revoked` は 403 を返します。 |
| `denialResponse(result, productId)` | Route Handler | 拒否の JSON を返します。`no_session` は 401、`unavailable` は 503、そのほかは 403 です。入場画面の URL は `enter_url` として本文に含みます。 |

`Entitlement` の形は [JavaScript / TypeScript](/integrate/sdk/javascript#購入者のクライアント) と同じです。`entitlement` と商品IDを渡す形の `requireEntitlement` の `options` は、`fetch` と `timeoutMs` を指定できます。待ち時間の既定は10000（10秒）、範囲は1から120000です。`nextEntitlement` の `options` にも同じ2項目を指定できます。

`requireEntitlement` の戻り値は `Promise<void>` です。入場画面へ送るときは redirect の例外を投げます。`try` の中では `AccessDenied` だけを捕まえ、それ以外の例外（redirect を含む）は投げ直してください。

Server Action では Response を返さず、`entitlement` の理由を通常の戻り値として返します。

### 購入者ポータル

| 関数 | 使う場所 | 振る舞い |
| --- | --- | --- |
| `portalRedirect(creatorId, options?)` | Route Handler の `GET` | 購入者ポータルへのリンクを発行して、302 で送ります。お客様がこのサイトで入場していないときは、コード無しのポータルへ送ります。 |

`portalRedirect` は `Promise<Response>` を返します。`options` は `fetch` と `timeoutMs` で、待ち時間の既定は5000（5秒）、範囲は1から120000です。リンクの発行に失敗したときは 503 を返します。`COZENI_API_ORIGIN` で本番・サンドボックス以外の接続先を指定している場合、未入場のお客様を送るポータルのオリジンを決められないため、302 ではなく 401 を返します。

```ts title="app/portal/route.ts"
import { portalRedirect } from "@nulogic/cozeni-sdk/next";

export const dynamic = "force-dynamic";

// ボタンが押されたときに、購入者ポータルへのリンクを発行して 302 で送る
export function GET() {
  return portalRedirect("cre_...");
}
```

ボタンは `<a href="/portal">購入した商品</a>` の形で置きます。

`creatorId` は `npx cozeni whoami --json` の `data.creator_id` です。秘密ではありません。ボタンは `<a>` で置き、`<Link>` は使わないでください。リンクは60秒で切れ、1回しか使えません。`<Link>` は表示時に先読みしてリンクを作るため、お客様が押す前にリンクが使い切られたり切れたりします。

### 機能フラグ

機能フラグの関数はサーバーの環境変数 `COZENI_API_KEY` を使います。`COZENI_ENVIRONMENT` で接続先を選びます。

| 関数 | 振る舞い |
| --- | --- |
| `createCheckout({ productId, email })` | ログイン中のユーザーのメールアドレスで、機能フラグの購入画面を作ります。URL は本人にだけ渡し、30分で失効します。 |
| `getCustomerState({ email })` | 付いている機能フラグをすべて返します。 |
| `hasFeatureFlag({ email, productId })` | 特定の商品の機能フラグを確かめます。無ければ `{ granted: false, metadata: {} }` を返します。 |

購入画面は Server Action か Route Handler で作り、お客様をそのまま購入画面へ送ります。

```ts title="app/upgrade/actions.ts"
"use server";
import { createCheckout } from "@nulogic/cozeni-sdk/next";
import { redirect } from "next/navigation";

export async function upgrade() {
  // getLoginUser はアプリのログインの処理に置き換える（メールアドレスは本人確認済みのもの）
  const user = await getLoginUser();
  const checkout = await createCheckout({ productId: "prd_...", email: user.email });
  // checkout.expiresAt（作成から30分）を過ぎたら作り直す
  redirect(checkout.url);
}
```

戻り値は `{ checkoutId, url, expiresAt }` です。お客様がすでに購入済みのときは、`CozeniError`（`code` が `already_purchased`）を投げます。

機能の API では呼ばれるたびにサーバーで権利を確かめます。

```ts title="app/api/chat/route.ts"
import { hasFeatureFlag } from "@nulogic/cozeni-sdk/next";

export async function POST(request: Request) {
  // getLoginUser はアプリのログインの処理に置き換える
  const user = await getLoginUser(request);
  const { granted, metadata } = await hasFeatureFlag({
    email: user.email,
    productId: "prd_...",
  });
  if (!granted) return Response.json({ error: "upgrade_required" }, { status: 403 });
  // metadata は商品に設定した値。例：{ daily_messages: 500 }
  // ここから先が機能の本体
}
```

付いている機能フラグをすべて取るときは、`getCustomerState` を使います。

```ts
import { getCustomerState } from "@nulogic/cozeni-sdk/next";

const state = await getCustomerState({ email: user.email });
// => { customerId: string | null, featureFlags: [{ productId, benefitId, grantedAt, metadata }] }
```

SDK の戻り値の名前は camelCase です（`customerId`、`featureFlags`）。API の応答（`customer_id`、`feature_flags`）とは書き方が違います。照会に失敗したとき（認証、レート制限、通信など）は、`CozeniError` を投げます。

キーの発行、結果のキャッシュ、購入直後の再照会については、[購入者の状態](/integrate/customer-state) と [機能フラグ](/features/benefits/feature-flags) を見てください。

### 環境変数

| 変数 | 必要な場面 | 意味 |
| --- | --- | --- |
| `COZENI_SITE_ORIGIN` | 購入者限定ページ（ハンドオフ） | サイトのオリジンです。パスを含まない形で書きます。例：`https://example.com` |
| `COZENI_ENVIRONMENT` | サンドボックスのとき | `production` か `sandbox` です。省略すると本番です。 |
| `COZENI_API_KEY` | 機能フラグを使うとき | API キーです。サーバーだけに置きます。 |
| `COZENI_API_ORIGIN` | Cozeni 自体をローカルで動かす開発用 | API のオリジンを直接指定します。通常は省略し、`COZENI_ENVIRONMENT` で環境を選びます。 |

環境変数から接続先を決めるとき、`COZENI_API_ORIGIN` と `COZENI_ENVIRONMENT` を両方指定する場合は、その環境の API オリジンと一致させてください。一致しなければ API に問い合わせず、権利の確認では `unavailable`、ハンドオフやポータルへの送り出しでは 503 を返します。機能フラグの関数は `CozeniError`（`invalid_input`）を投げます。

`COZENI_API_KEY` が空のとき、または `NEXT_PUBLIC_COZENI_API_KEY` が設定されているときは、機能フラグの関数は失敗します。`NEXT_PUBLIC_` で始まる変数にはキーを入れないでください。

:::note
Next.js 15 でローカル開発するときは、`COZENI_SITE_ORIGIN` とブラウザで開く URL の両方を `localhost` に揃えてください。Next.js 15 の middleware は `127.0.0.1` を `localhost` に書き換えるためです。
:::

:::note
0.3 系の書き方（`requireEntitlement({ apiOrigin, productId, haltRedirect })` や `nextEntitlement({ apiOrigin, productId })`）も引き続き動きます。移行は必須ではありません。`requireEntitlement` にオブジェクトを渡す形では、`apiOrigin` と `productId` が必須です。`fetch` と `timeoutMs` も指定でき、`haltRedirect: true` を渡すと、権利が無いときは redirect せず `AccessDenied` を投げます。
:::

## 次に読むページ

**[Next.js に組み込む](/integrate/guides/nextjs)**

購入リンクと限定ページを、手順に沿って組み込みます。

**[購入者の状態](/integrate/customer-state)**

機能フラグの照会と、結果のキャッシュの仕方を説明します。

**[JavaScript / TypeScript](/integrate/sdk/javascript)**

フレームワークを問わず使う関数と、エラーの扱いを説明します。

**[サンドボックス](/integrate/sandbox)**

テスト購入と、本番への切り替えを説明します。
