コンテンツにスキップ
Docs
Esc
↑↓移動↵開く⌘Jプレビュー
このページの内容

Next.js

Next.js(App Router)用のヘルパー。

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

インストール

npm install @nulogic/cozeni-sdk@0.8.0
pnpm add @nulogic/cozeni-sdk@0.8.0
yarn add @nulogic/cozeni-sdk@0.8.0
bun add @nulogic/cozeni-sdk@0.8.0
nub add @nulogic/cozeni-sdk@0.8.0
aube add @nulogic/cozeni-sdk@0.8.0

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

最小のコード例

proxy と、保護するページの例です。Route Handler、Server Action、購入者ポータルへのボタンまで含む完成例は、SDK の導入例(examples/nextjs)にあります。

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

export { cozeniProxy as proxy } from "@nulogic/cozeni-sdk/next";

export const config = {
  matcher: ["/((?!_next/static|_next/image|favicon.ico).*)"],
};
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 に含めないでください。

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 を、既存の処理に組み込みます。

ページの認可

関数 使う場所 振る舞い
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 と同じです。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 を返します。

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 で作り、お客様をそのまま購入画面へ送ります。

"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 では呼ばれるたびにサーバーで権利を確かめます。

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 を使います。

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 を投げます。

キーの発行、結果のキャッシュ、購入直後の再照会については、購入者の状態 と 機能フラグ を見てください。

環境変数

変数 必要な場面 意味
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_ で始まる変数にはキーを入れないでください。

次に読むページ

このページは役に立ちましたか?