---
title: 機能フラグ
description: 自分のアプリに限定機能を作る。
---

機能フラグは自分のアプリに限定機能を作るための商品の種類です。Cozeni はアプリの画面を持たず、購入の有無と設定値を返します。アプリはその結果で機能を出し分けます。

## 使いどころ

購入の有無で機能を開くだけでなく、設定値で機能の中身も変えられます。設定値には文字列・数値・真偽値を入れられるので、次のように使えます。

- 購入したお客様にだけ、アプリの有料機能を開きます。
- 数値の設定値で、1日に使える回数などの上限を商品ごとに切り替えます。
- 真偽値の設定値で、商品に含めるかどうかを機能ごとに切り替えます。
- 文字列の設定値にアプリ側で使うプランの名前を入れ、プランを見分けます。

機能フラグの商品には、購入者限定ページのURLはありません。機能フラグは購入者ポータルと、Cozeni の商品を開くページ（`/access/{productId}`）には表示されません。

## 管理画面で設定する

1. 商品を登録するときに、商品の種類で「機能フラグ」を選びます。
2. 「機能フラグ」の欄の「設定値」に、キーと値を入れます。行は追加・削除できます。

### 設定値

設定値はアプリに渡すキーと値の組です。設定値は無くても構いません。たとえば次のように入れると、照会の結果の `metadata` に同じキーと値が入ります。

| キー | 値 | アプリでの使い方の例 |
| --- | --- | --- |
| `daily_messages` | `500`（数値） | 1日に送れるメッセージの上限 |
| `export_csv` | `true`（真偽値） | CSV の書き出しを開くかどうか |

設定値には次の制約があります。

- 件数は0〜50件です。
- キーは1〜40字の英数字・`_`・`-` です。`__proto__` は使えません。
- 値は文字列（1〜500字。空の文字列は不可）・数値・真偽値のいずれかです。

:::warning
API キーなどの秘密情報は設定値に入れないでください。設定値は管理画面と API の応答に平文で出ます。
:::

## お客様から見た流れ

1. お客様はアプリの画面のボタンから購入を始めます。
2. アプリのサーバーが購入画面を作ります。購入画面のメールアドレスは、アプリにログインしている人のものが入り、変更できません。
3. お客様がカードで支払います。
4. 完了画面に、アプリへ戻って使うよう案内する文が表示されます。ボタンはありません。
5. アプリに戻ると、機能が開きます。

決済が成立すると、Cozeni はお客様に購入完了メールを1通送ります。メールには商品名・販売者名と、「（販売者名）のサービスで、このメールアドレスのアカウントからご利用いただけます。」という案内が載ります。購入者ポータルを開くボタンはありません。

購入直後は、購入の記録が照会にすぐ出ないことがあります。お客様が完了画面からアプリに戻ったら、数秒おきに数回照会し直してください。

## サイトに組み込む（SDK・API）

アプリのサーバーで購入画面を作り、お客様の機能フラグを確かめます。どちらも API キーを使います。

### 1. APIキーを発行する

管理画面の「開発者設定」で、APIキーを発行します。次の2つの権限を選びます。

- 「購入画面を作る」（`checkouts:write`）
- 「購入者の機能フラグを確かめる」（`customers:read`）

キーの全文は発行時の1回だけ表示されます。CLI のキーや、初期設定の導入用のキーには、これらの権限は含まれません。

APIキーはサーバー専用の環境変数 `COZENI_API_KEY` に置きます。サンドボックスのキーを使うときは、`COZENI_ENVIRONMENT=sandbox` も設定します。`NEXT_PUBLIC_COZENI_API_KEY` は設定しないでください。`NEXT_PUBLIC_` を付けた環境変数はブラウザに渡るため、SDK はこの変数を検出するとエラーにします。

### 2. 購入画面を作る

ログインしている人のメールアドレスで、購入画面を作ります。

```ts app/api/checkout/route.ts
import { CozeniError, createCheckout } from "@nulogic/cozeni-sdk/next";

// 機能フラグの商品ID（秘密ではない）
const PRODUCT_ID = "prd_...";

export async function POST() {
  // アプリのログイン情報から取る。リクエストの本文からは受け取らない
  const email = await loginEmail(); // アプリ側のログイン処理に置き換える
  try {
    const { url } = await createCheckout({ productId: PRODUCT_ID, email });
    // 返った URL は本人にだけ渡す。有効期限は30分
    return Response.redirect(url, 303);
  } catch (error) {
    if (error instanceof CozeniError && error.code === "already_purchased") {
      // 購入済み。購入画面へ進めず、アプリで利用してもらう
      return Response.json({ purchased: true });
    }
    throw error;
  }
}
```

購入画面の URL の有効期限は30分です。期限が切れたら、もう一度この処理で作り直してください。

### 3. 購入者の機能フラグを確かめる

機能を開く前に、サーバーで照会します。

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

const PRODUCT_ID = "prd_...";

export async function GET() {
  // アプリのログイン中のメールアドレスで照会する
  const email = await loginEmail(); // アプリ側のログイン処理に置き換える
  const { granted, metadata } = await hasFeatureFlag({
    email,
    productId: PRODUCT_ID,
  });
  // 付与されていなければ、機能を開かない
  if (!granted) return Response.json({ enabled: false });
  // metadata は設定値（例：プランの上限など）
  return Response.json({ enabled: true, metadata });
}
```

`hasFeatureFlag()` はお客様がその商品の機能フラグを持つかを返し、付与されていなければ `{ granted: false, metadata: {} }` を返します。照会に失敗したときは例外を投げます。失敗を「付与されていない」と読み替えるかどうかは、アプリ側で決めてください。

お客様が持つ機能フラグの一覧が必要なときは、`getCustomerState()` を使います。

### 他のフレームワークの場合

Next.js 以外のサーバーでは、`@nulogic/cozeni-sdk` の `createManagementClient()` を使います。手順は [JavaScript / TypeScript の SDK](/integrate/sdk/javascript) を参照してください。

## 守ること

- ログインのメールアドレスの本人確認を済ませてください。未確認のメールアドレスでアカウントを作れると、そのアカウントを作った人が、他人の購入した機能を使えてしまいます。
- 画面で隠すだけにせず、サーバーでも判定してください。機能の API（Route Handler など）でも照会してください。
- API キーはサーバーの環境変数に置いてください。ブラウザ・リポジトリ・ログに出さないでください。
- 照会の結果は最大60秒キャッシュしてよいです。購入直後はキャッシュを使わずに照会し直してください。
- ログや分析に、お客様のメールアドレスを残さないでください。

## 付与と取り消し

- 決済が成立すると、Cozeni がお客様に機能フラグを付けます。購入の記録が反映されるまで、数秒かかることがあります。
- 全額返金が確定すると、機能フラグは外れます。照会の結果は付与されていない状態（`granted: false`）になります。
- 部分返金では、機能フラグは残ります。
- 設定値を変えると、既存のお客様にも次の照会から反映されます。

返金の詳しい扱いは [返金](/features/refunds) を参照してください。

## よくある質問

**設定値を変えると、購入済みのお客様にも反映されますか**

反映されます。設定値を変えると、既存のお客様にも次の照会から反映されます。

**設定値に API キーを入れてもよいですか**

入れないでください。設定値は管理画面と API の応答に平文で出ます。

**機能フラグの商品は購入者ポータルに出ますか**

出ません。機能フラグは購入者ポータルと、Cozeni の商品を開くページ（`/access/{productId}`）には表示されません。お客様は自分のアプリで機能を使います。

**照会に失敗したときは、付与されていないものとして扱えばよいですか**

アプリ側で決めてください。`hasFeatureFlag()` は照会の失敗を例外として投げます。「付与されていない」と読み替えるかどうかは、アプリの事情に合わせて選びます。

## 次に読むページ

**[購入画面の API](/features/checkout/session)**

自分のサーバーで購入画面を作る方法の詳細です。

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

メールアドレスから、お客様に付いている機能フラグを照会します。

**[購入者の状態を取得（API）](/api-reference/customer/external-get-customer-state)**

購入者の状態を照会する API の仕様です。

**[購入画面を作成（API）](/api-reference/checkout/external-create-checkout-session)**

購入画面を作る API の仕様です。
