---
title: "CLIからリテンションメッセージングを管理する"
description: "Adapty CLIを使ってターミナルからAppleリテンションメッセージングをセットアップします：リアルタイムURLの接続、パフォーマンステストの実行、リテンションメッセージの作成・変更・有効化・無効化、指標の確認が可能です。"
---

> **AI agents**: to search Adapty docs faster and with fewer tokens, install the Adapty skills: `npx adapty skills install --yes`

Adapty CLI は、`adapty retention-messaging` トピックの下で、ターミナルから [Apple Retention Messaging](retention-messaging)（サブスクライバーが **Cancel Subscription** 画面で目にするメッセージ）を設定します。アプリのセットアップ状況の確認、Apple のリクエストに応答するメッセージ用 Adapty リアルタイム URL への Apple の接続、Apple のパフォーマンステストの実行、リテンションメッセージの作成・変更、有効化・無効化、各メッセージの指標の確認などが可能です。

AIエージェントを使ってリテンションメッセージングを設定したり、複数のアプリにまたがるメッセージをスクリプト化したり、ダッシュボードを開かずにメッセージの指標を確認したりすることができます。コマンドは、ダッシュボードの **Retention Messaging** ページと同じ操作を行い、ダッシュボードにも同じメッセージが表示されます。

## 始める前に \{#before-you-start\}

`retention-messaging` トピックのインストールとログインは、CLI の他の部分と共通です。まだセットアップしていない場合は、[クイックスタートガイド](developer-cli-quickstart)のステップ 1 と 2 に従ってください。CLI にこのトピックが含まれているか確認するには、次を実行してください：

```bash
adapty retention-messaging --help
```

すべてのコマンドは `--app` にアプリの UUID を指定します。確認するには、次を実行してください：

```bash
adapty apps list
```

各ステップでアプリに必要なもの：

- **セットアップステータスの確認**: 不要。どのアプリでも動作します。
- **リアルタイム URL の確認**: Adapty での完全な [App Store セットアップ](app-store-connection-configuration)が必要です。アクセスをリクエストする際にこの URL を Apple に送信します。
- **リアルタイム URL の設定とパフォーマンステストの実行**: さらに、アプリ内購入キーと [Retention Messaging API へのアクセス](retention-messaging-setup#request-access-from-apple)（Apple にリクエスト）が必要です。Apple の審査には最大 1 か月かかる場合があるため、早めにアクセスをリクエストしてください。
- **サブスクライバーへのメッセージ表示**: Apple からのアクセス許可、Adapty に設定されたリアルタイム URL、少なくとも 1 つの[プロダクト](create-product)、および各メッセージに対する Apple の承認が必要です。

リテンションメッセージは、Appleの`sandbox`と`production`という2つの環境に存在します。`--mode`フラグで環境を選択します。ダッシュボードの**Sandbox mode**トグルが示すように、各環境にはそれぞれ独自のメッセージがあります。

リテンションメッセージングを最初から最後まで設定するには:

1. [セットアップステータスを確認する](#read-the-setup-status)。
2. [リアルタイムURLを読み取り](#connect-the-realtime-url)、そのURLでAppleにアクセスをリクエストする。
3. `sandbox` 用に[リアルタイムURLを設定する](#connect-the-realtime-url)。
4. [パフォーマンステストを実行し](#run-the-performance-test)、テストが通過するまでセットアップステータスを確認し続ける。
5. `production` 用に[リアルタイムURLを設定する](#connect-the-realtime-url)。
6. [デフォルトメッセージを作成し](#create-a-message)、次にプロモメッセージを作成する。
7. Appleのレビューに対応するために[メッセージを一覧表示する](#list-and-read-messages)。

## セットアップ状況を確認する \{#read-the-setup-status\}

```bash
adapty retention-messaging setup-status --app <app-id>
```

セットアップの状況は、ダッシュボードと同じ手順で表示されます:

| フィールド | 値 |
|---|---|
| `credentials` | `present` または `missing`: アプリが Retention Messaging で使用する App Store キーを持っているかどうか。 |
| `registration_status` | `registered` または `not_registered`: Apple がアプリに Retention Messaging API へのアクセスを許可しているかどうか。 |
| `sandbox.realtime_url_status`、`production.realtime_url_status` | `not_configured`、`configured_to_other_url`、または `configured_to_adapty`: 各環境で Apple がリクエストを送信する先。 |
| `sandbox.performance_test_status` | `not_started`、`running`、`passed`、または `failed`。 |

:::note
一部の読み取り操作は、ダッシュボードと同様に Adapty を更新します：
- パフォーマンステストの実行中、`setup-status` は Apple にテスト結果を問い合わせて保存します。`realtime-url configure` は承認を求める前に同じ読み取りを行うため、その後に拒否した場合でも結果が保存されます。
- `messages list`、`messages get`、および `messages update` が書き込み前に行う読み取りは、各メッセージのレビュー状況を Apple に確認して新しい状態を保存します。Apple がメッセージを承認していた場合、読み取りによって即座に `live` 状態に移行します。Adapty も独自に Apple のレビューを確認するため、読み取りがなくても承認済みメッセージはライブになります。
:::

## リアルタイム URL の接続 \{#connect-the-realtime-url\}

Apple は、サブスクライバーが **Cancel Subscription** 画面を開いたときにリアルタイム URL へリクエストを送信します。Adapty はこのリクエストにあなたのメッセージで応答します。Adapty の URL を確認するには、次のコマンドを実行してください：

```bash
adapty retention-messaging realtime-url get --app <app-id>
```

同じ URL が `sandbox` と `production` の両方に使用されます。この URL は、[アクセスをリクエスト](retention-messaging-setup#request-access-from-apple)する際に Apple へ提供します。

特定の環境向けに Adapty の URL を Apple に設定するには、次のコマンドを実行してください：

```bash
adapty retention-messaging realtime-url configure --app <app-id> --mode sandbox
```

まず `sandbox` を設定してください。[パフォーマンステスト](#run-the-performance-test)に合格するまで、Adapty は `production` を受け付けません。`sandbox` を設定すると、Adapty はパフォーマンステスト用の隠しテストメッセージも作成します。このメッセージはメッセージリストには表示されません。

Apple がこの環境のリクエストを別のサーバー（`configured_to_other_url`）に送信している場合、Adapty の URL が Apple 上でそのサーバーの URL を置き換えます。それ以降、そのサーバーは **Cancel Subscription** 画面からのリクエストを受け取らなくなります。CLI は該当する環境名を示す警告を表示します。置き換えを承認するには：

- **ターミナルで `--json` なしの場合**: 警告を読み、`Apply? [y/N]` プロンプトで `y` と入力します。`--yes` を渡した場合でもプロンプトは表示されます。
- **スクリプト、エージェント、または `--json` ありの場合**: `--replace-other-url --yes` を渡します。`--replace-other-url` がない場合、`--yes` があっても CLI は何も送信せずコード 6 で終了します。

## パフォーマンステストを実行する \{#run-the-performance-test\}

Adapty が `production` のリアルタイム URL を許可する前に、Apple は Adapty の応答速度をテストします。テストを開始する前に、`sandbox` 用の[リアルタイム URL を設定](#connect-the-realtime-url)してください。次に、サンドボックスアカウントまたは TestFlight を通じて、最も長い期間のプロダクトを購入し、サブスクリプションをアクティブな状態に保ち、購入直後にテストを開始します。

```bash
adapty retention-messaging performance-test start --app <app-id>
```

テストは常に`sandbox`で実行され、最大1時間かかる場合があります。結果を確認するには、[セットアップのステータス](#read-the-setup-status)を再度読み取ってください。`sandbox.performance_test_status`が`running`から`passed`または`failed`に変わります。ステータスが`running`の間は、テストを再度開始しないでください。Adaptyは拒否します。テストが失敗する理由については、[パフォーマンステストに合格する](retention-messaging-setup#pass-the-performance-test)を参照してください。

テストに合格したら、本番環境を接続します。

```bash
adapty retention-messaging realtime-url configure --app <app-id> --mode production
```

## メッセージを一覧表示・確認する \{#list-and-read-messages\}

```bash
adapty retention-messaging messages list --app <app-id> --mode production --state live
```

`--mode` は必須です。一覧には各メッセージの名前、タイプ、状態、プロダクト数、開始日、およびメッセージの全期間における以下の指標が表示されます。

| フィールド | ダッシュボードの列 | 値 |
|---|---|---|
| `shown` | **Shown** | カウント |
| `retained` | **Retained users** | カウント |
| `saved_users` | **Saved users** | カウント |
| `retention_rate` | **Retention rate** | パーセント、小数点以下1桁。ビューに結果がない間は `0.0`。 |
| `save_rate` | **Save rate** | パーセント、小数点以下1桁。24時間未経過のビューがない間は `0.0`。 |
| `saved_revenue` | **Saved revenue** | Appleの手数料控除前のUSD、小数点以下2桁 |

各指標のAdaptyによる計算方法については、[メッセージパフォーマンスの追跡](retention-messaging-analytics)を参照してください。

メッセージは `in_review`、`live`、`rejected`、`inactive` のいずれかの状態を持ちます。各状態の意味については、[メッセージの状態](retention-messaging-create#message-states)を参照してください。

テキスト、画像、箇条書き、プロダクト、ロケールを含む1件のメッセージを取得するには、次のコマンドを実行します：

```bash
adapty retention-messaging messages get <message-id> --app <app-id>
```

メッセージには環境フィールドがありません。テキストと箇条書きは `en-US` のソースです。その他の各ロケールには、それぞれのレビュー状態が表示されます。

## メッセージを作成する \{#create-a-message\}

プロモメッセージには、同じプロダクトの同じ環境でのデフォルトメッセージが必要です。まずデフォルトメッセージを作成してください。Apple のレビューを待つ必要はありません。

ファイルに記載するプロダクト ID、プロモオファー、プランの切り替えを調べるには、[suggest コマンド](#find-products-and-offers)を使用してください。メッセージを作成するには、その内容を JSON ファイルに記述します：

```json title="message.json"
{
  "name": "Annual default",
  "type": "default",
  "title": "Before you go",
  "body": "Your plan keeps every feature you use today.",
  "alt_text": "App icon on a purple background",
  "header_position": "above_body",
  "products": [
    { "store_id": "com.example.annual" }
  ],
  "bullet_points": [
    { "image_path": "icons/sync.png", "text": "Sync on all your devices" },
    { "image_path": "icons/offline.png", "text": "Work offline" }
  ],
  "localizations": [
    {
      "locale": "de-DE",
      "title": "Bevor du gehst",
      "body": "Dein Abo behält alle Funktionen, die du heute nutzt.",
      "bullet_points": [
        { "text": "Auf allen Geräten synchronisieren" },
        { "text": "Offline arbeiten" }
      ]
    }
  ]
}
```

Then run:

```bash
adapty retention-messaging messages create --app <app-id> --mode sandbox \
  --file message.json --image header.png
```

The file takes these keys:

- **`name`, `type`, `title`, `body`**: 必須項目。タイトルとボディは`en-US`のソーステキストで、それぞれ最大66文字と144文字です。
- **`type`**: メッセージタイプ。`default`または`promo`を指定します。後から変更はできません。
- **`alt_text`**: スクリーンリーダー向けの画像説明テキスト。最大150文字。
- **`header_position`**: 画像付きデフォルトメッセージにおけるタイトルの表示位置。`above_image`は画像の上にタイトルを表示し、`above_body`は画像の下、ボディの上に表示します。後から変更はできません。
- **`products`**: メッセージを表示するサブスクライバーのプロダクト。App StoreのプロダクトIDを`store_id`で指定します。デフォルトメッセージには`association`がありません。プロモメッセージには少なくとも1つのプロダクトが必要で、各プロダクトには`association`でインセンティブを指定する必要があります（`{"type": "promo_offer", "store_id": "<offer-id>"}`または`{"type": "plan_switch", "store_id": "<product-id>"}`）。1つのプロモメッセージ内のプロダクトはすべて同じインセンティブタイプを使用します（すべて`promo_offer`またはすべて`plan_switch`）。
- **`bullet_points`**: デフォルトメッセージのみで使用できる箇条書き項目（最大5件）。各項目には`text`（1〜66文字）、オプションの`alt_text`、およびJSONファイルが置かれたフォルダからの相対パスでPNGアイコンを指定する`image_path`があります。CLIは`image_index`を受け付けません。
- **`localizations`**: `en-US`以外の各ロケール用のエントリ。`locale`、`title`、`body`、およびメッセージ内の各箇条書き項目に対応する`bullet_points`テキスト（同じ順序）を含みます。

`--image` はデフォルトメッセージの画像を追加します。プロモメッセージには画像もバレットポイントもありません。

承認を求める前に、CLI は各画像ファイルを検証します。その後、[スクリプトとエージェントでの確認](#confirmation-in-scripts-and-agents) で説明されているように、CLI が承認を求めます。Adapty は新しいメッセージのテキストと画像をレビューのために Apple に送信し、メッセージの状態は `in_review` になります。

作成がネットワークエラーまたはサーバーエラーで失敗した場合は、再実行しないでください。[作成または変更が応答を得られない場合](#if-a-create-or-a-change-gets-no-answer) を参照してください。

### 画像の要件 \{#image-requirements\}

| ファイル | 要件 |
|---|---|
| 画像（`--image`） | PNG、幅3840px・高さ160〜2160px、透過なし、10MB以下 |
| 箇条書きアイコン（`image_path`） | PNG、1024×1024px、透過なし、10MB以下 |

CLIは送信前に各ファイルを検証します。アルファチャンネルを持つPNGでも、すべてのピクセルが完全に不透明であれば通過します。破損したPNGは `must be a PNG` エラーで失敗します。ファイルが失敗した場合、CLIは何も送信せずにコード2で終了します。エラーにはファイル名とルールが表示されます（例：`… must be 3840 px wide and 160–2160 px tall`）。

## メッセージを変更する \{#change-a-message\}

:::warning
非アクティブなメッセージを変更すると、名前だけの変更でも再びアクティブになります。Apple がメッセージを承認すると、サブスクライバーに表示されます。
:::

`messages update` は指定した項目のみを変更します。名前を指定しなかったロケール、箇条書き、アイコン、プロダクト、画像はそのまま維持されます:

```bash
adapty retention-messaging messages update <message-id> --app <app-id> --title "Wait, there's more"
```

`--name`、`--title`、`--body`、`--alt-text`、`--image`、`--remove-image` フラグで名前、タイトル、本文、代替テキスト、画像を変更できます。ロケール、箇条書き、プロダクトの変更は `--file` で指定する変更ファイルを使います。変更ファイルでも `name`、`title`、`body`、`alt_text`、`remove_image` を指定できます。変更ファイルが認識しないキーは CLI が拒否します。この変更ファイルは [メッセージの作成](#create-a-message) で作成したメッセージに対して機能します。

```json title="changes.json"
{
  "localizations": [
    { "locale": "de-DE", "title": "Warte kurz", "bullet_texts": { "<bullet-id>": "Auf jedem Gerät synchronisieren" } }
  ],
  "bullet_points": [
    { "bullet_id": "<bullet-id>", "text": "Sync on every device" },
    {
      "image_path": "icons/backup.png",
      "text": "Daily backups",
      "texts": { "de-DE": "Tägliche Backups" }
    }
  ],
  "remove_bullet_points": ["<other-bullet-id>"]
}
```

- **ロケール**: 各ロケールを `locale` のコードで指定し、`title`、`body`、および `bullet_texts` に `bullet_id` ごとの箇条書きテキストを含めます。メッセージに存在しないロケールは追加され、`title`、`body`、および各箇条書きのテキストが必要です。
- **箇条書き**: 箇条書きを変更するには、`messages get` から取得した `bullet_id` で指定し、`text`、`alt_text`、または新しいアイコンの `image_path` を指定します。新しい箇条書きには `bullet_id` がありません。`image_path`、`en-US` の `text`、およびメッセージの各ロケールの `texts` にテキストが必要です。
- **プロダクト**: App Store のプロダクト ID を `store_id` で指定します。メッセージに存在しないプロダクトは追加されます。プロモーションメッセージでは、各プロダクトにインセンティブが必要です。変更するには新しい `association` を渡します。プロダクトのインセンティブ提供を停止するには、`remove_products` でそのプロダクトを削除します。プロモーションメッセージに追加するプロダクトには `association` が必要です。
- **削除**: 削除フィールドを使用します: `remove_localizations`（ロケールコード）、`remove_bullet_points`（箇条書き ID）、`remove_products`（App Store プロダクト ID）、および `remove_image: true` または `--remove-image`。削除された箇条書きはすべてのロケールから消えます。プロモーションメッセージがプロダクトを使用している間は、そのプロダクトをデフォルトメッセージから削除できません。

タイプ、`header_position`、またはプロモメッセージのインセンティブタイプ（`promo_offer` または `plan_switch`）は変更できません。別のものを使用するには、新しいメッセージを作成してください。

CLIは送信前に変更内容を検証します。入力に矛盾がある場合、変更内容がない場合、またはメッセージに存在しない要素の名前指定や削除を行った場合、CLIは何も送信せず、コード2で終了し、エラーに問題の内容が表示されます。既存の箇条書きのロケールテキストは、`texts`ではなくロケールの`bullet_texts`内に指定してください。

CLI は承認を求め、メッセージを読み取り、変更をそこにマージして、メッセージ全体を Adapty に送信します。更新のたびにメッセージ全体が Apple のレビューに送信され、メッセージの状態は `in_review` になります。`messages update` の実行中にダッシュボードでメッセージを変更した場合、その変更は上書きされます。

## メッセージの有効化・無効化 \{#activate-or-deactivate-a-message\}

```bash
adapty retention-messaging messages set-status <message-id> --app <app-id> --action deactivate
```

- **`activate`**: `inactive` 状態のメッセージを `in_review` に移行します。Apple は未承認のロケールのみ再審査を行います。Apple がメッセージを承認すると、サブスクライバーに再び表示されます。
- **`deactivate`**: `live` 状態のメッセージを `inactive` に移行します。サブスクライバーへの表示が停止されます。それまでの表示数は指標に残ります。

Adapty は `inactive` でないメッセージへの `activate` を、`live` でないメッセージへの `deactivate` を拒否します。`in_review` のメッセージは Apple が承認した時点でライブ状態になります。停止するには、その後に deactivate してください。CLI にはメッセージを削除するコマンドはありません。

プロダクトごとに、各環境でデフォルトメッセージとプロモメッセージをそれぞれ 1 つ持つことができます。次の場合、Adapty はアクティベーションを拒否します。

- このメッセージが inactive の間に、同じタイプの別のメッセージがプロダクトに追加された。
- このメッセージがプロモメッセージであり、そのプロダクトのいずれかがこの環境にデフォルトメッセージを持っていない。

プロモーションメッセージがプロダクトを使用している間、Adapty はそのプロダクトのデフォルトメッセージを無効化できません。先にプロモーションメッセージを無効化するか、そこからプロダクトを削除してください。

## プロダクトとオファーを探す \{#find-products-and-offers\}

メッセージに追加できるプロダクトを探すには、次のコマンドを実行します：

```bash
adapty retention-messaging products suggest --app <app-id> --mode production --type default
```

メッセージを変更する場合は、`--message-id` にそのIDを渡すことで、このメッセージのプロダクトが `used` として表示されなくなります。`disabled_reason` があるプロダクトは追加できません：

- **`used`**: 同じ環境内の同じタイプの別のメッセージがそのプロダクトを使用しています。
- **`no_default_message`**: そのプロダクトはこの環境にデフォルトメッセージがないため、プロモーションメッセージを受け取ることができません。

プロモメッセージは、各プロダクトに1つのインセンティブを紐付けます。プロダクトのインセンティブを調べるには、`products suggest` から取得したプロダクトの `id` を渡します。プロダクトのプロモーションオファー一覧を表示するには、次のコマンドを実行します：

```bash
adapty retention-messaging promo-offers suggest <product-id> --app <app-id>
```

サブスクライバーが切り替え可能なプランの一覧を表示するには、次のコマンドを実行します：

```bash
adapty retention-messaging plan-switches suggest <product-id> --app <app-id>
```

`plan-switches suggest`には、アプリ設定に[App Store Connect APIキー](app-store-connect-api-key)が必要です。プロダクトの`association`に、オファーまたはプランの`store_id`を設定してください。

## スクリプトとエージェントでの確認 \{#confirmation-in-scripts-and-agents\}

これらのコマンドは、**Cancel Subscription** 画面でサブスクライバーに表示される内容を変更します。変更を送信する前に、その内容を表示して承認を求めます（`sandbox` と `production` の両方）：

- `realtime-url configure`
- `messages create`
- `messages update`
- `messages set-status`

確認の方法は、コマンドの実行方法によって異なります：

| コマンドの実行方法 | 動作内容 |
|---|---|
| ターミナルで `--yes` と `--json` なしで実行 | CLIはその効果を表示し、`Apply? [y/N]` と確認を求めます。`y` または `yes` と答えると、CLIはリクエストを送信します。それ以外の回答では、CLIはコード1で終了し、何も送信しません。 |
| `--yes` あり（ターミナルの有無を問わず） | CLIは確認なしにリクエストを送信します。`production` 環境でも同様です。 |
| `--yes` なし、`--json` あり、パイプ経由、またはターミナルなし | CLIは何も送信せずにコード6で終了します。エラーにはその効果の説明が含まれます。 |

Appleで別のリアルタイムURLを置き換える場合は、独自のルールがあります。[リアルタイムURLを接続する](#connect-the-realtime-url)を参照してください。

スクリプトやエージェントはコマンドの影響を事前に確認できます。まず `--yes` なしで実行し、出力で影響を確認してから、誰かが承認した後に `--yes` を付けて再実行します。

`setup-status`、`realtime-url get`、`performance-test start`、`messages list`、`messages get`、および `suggest` コマンドは確認なしで実行されます。

## エラー \{#errors\}

| 終了コード | 原因 | 対処法 |
|---|---|---|
| 1 | プロンプトで `y` 以外を入力した。何も送信されていない。 | 意図していた場合は、コマンドを再実行してください。 |
| 2 | CLIが送信前に入力を拒否した：フラグ、画像ファイル、入力の競合、各箇条書きにテキストがないロケール、または解約阻止メッセージにない要素の削除。 | エラーが示す箇所を修正してください。 |
| 3 | ログインしていないか、Adaptyがアプリへのアクセスを拒否した。 | `adapty auth login` でログインし、`adapty apps list` でアプリIDを確認してください。 |
| 4 | Adaptyがリクエストを拒否した。エラーに理由が示されており、`--json` でHTTPステータスと `error_code` を確認できる。作成または変更時のサーバーエラー（5xx）もコード4となり、結果は不明。 | [Adaptyからのメッセージ](#messages-from-adapty)を参照してください。作成または変更時のサーバーエラーの後は、[作成または変更が応答を受け取らなかった場合](#if-a-create-or-a-change-gets-no-answer)を参照してください。 |
| 5 | CLIがAdaptyに到達できなかった。 | オンライン状態を確認してください。作成または変更後は、[作成または変更が応答を受け取らなかった場合](#if-a-create-or-a-change-gets-no-answer)を参照してください。 |
| 6 | 承認を求めるコマンドが `--yes` なしかつ応答者なしで実行されたか、リアルタイムURL置換が `--replace-other-url` なしで実行された。何も送信されていない。 | エラーに示された影響を確認してから、`--yes` を付けてコマンドを再実行し、置換の場合は `--replace-other-url` も付けてください。 |
| 130 | プロンプトでCtrl+Cを押した。何も送信されていない。 | — |

### Adapty からのメッセージ

`--json` を使うと、エラーに `error_code` が含まれます：

| `error_code` | 原因 | 対処方法 |
|---|---|---|
| `app_store_credentials_missing` | AppにAdaptyのApp Storeキーが設定されていない。 | [App Storeのセットアップ](app-store-connection-configuration)を完了してください。 |
| `app_store_connect_credentials_missing` | `plan-switches suggest` にはApp Store Connect APIキーが必要。 | [App Store Connect APIキー](app-store-connect-api-key)を追加してください。 |
| `realtime_url_unavailable` | AdaptyにApp Storeサーバー通知のセットアップがされていない。 | [App Storeのセットアップ](app-store-connection-configuration)を完了してください。 |
| `apple_rm_api_access_denied` | AppleがアプリへのRetention Messaging APIのアクセスを許可していない。 | [Appleにアクセスを申請](retention-messaging-setup#request-access-from-apple)してください。 |
| `performance_test_required` | パフォーマンステストが完了する前に `production` を設定した。 | 先に[パフォーマンステストを実行](#run-the-performance-test)してください。 |
| `performance_test_already_running` | パフォーマンステストが実行中。 | しばらく待ってから、セットアップ状態を再度確認してください。 |
| `active_sandbox_transaction_missing` | 有効なサンドボックスのサブスクリプションがない。 | サンドボックスで最も期間の長いプロダクトを購入し、テストを再開始してください。 |
| `performance_test_request_rejected` | Appleがテストの開始を拒否した。 | 新たにサンドボックス購入を行い、テストを再開始してください。 |
| `retention_product_claimed` | 同じタイプの別のメッセージがそのプロダクトを使用している。 | 別のプロダクトを選ぶか、他のメッセージを無効化してください。 |
| `retention_default_message_missing` | プロモーションメッセージに、デフォルトメッセージのないプロダクトがある。 | 先にそのプロダクトのデフォルトメッセージを作成または有効化してください。 |
| `retention_dependent_promo_messages` | プロモーションメッセージが、変更によってデフォルトメッセージから削除されるプロダクトを使用している。 | 先にプロモーションメッセージを無効化するか、そのプロダクトを削除してください。 |
| `retention_promo_association_invalid` | プロモーションメッセージにプロダクトがない、`association` のないプロダクトがある、または両方のインセンティブタイプが混在している。 | すべてのプロダクトに同じタイプの `association` を設定してください。 |
| `retention_message_type_immutable` | 変更によってプロモーションメッセージのインセンティブタイプが変わってしまう。 | 新しいメッセージを作成してください。 |
| `retention_message_invalid_status_transition` | `inactive` でないメッセージへの `activate`、または `live` でないメッセージへの `deactivate` を実行した。 | `messages get` でメッセージの状態を確認してください。 |
| `retention_message_not_found` | このIDのメッセージがアプリに存在しない。 | `messages list` からIDを確認してください。 |

### 作成または変更への応答がない場合 \{#if-a-create-or-a-change-gets-no-answer\}

ネットワークエラーやサーバーエラー（終了コード 4 または 5）により、CLIが作成または更新への応答を受け取れなかった場合、Adaptyが変更を保存したかどうかを判断できません。CLIはリクエストを再送しません。ご自身でもコマンドを再実行しないでください。

- **作成後**: 同じ環境で `messages list` を実行し、`--search "<name>" --page-size 100` を指定してください。エラーには該当する名前が単独行で表示されます（`--json` の場合は `message_name`）。`meta.pagination.pages` までの全ページを確認し、各候補を `messages get` で開いてください。再度作成すると重複メッセージが生成され、Appleのレビューに送信される可能性があります。自分のメッセージが候補にない場合のみ、再作成してください。
- **更新後**: `messages get` を実行し、メッセージの状態と内容を確認してください。

## コマンドリファレンス \{#command-reference\}

すべてのコマンドは `--app`（`adapty apps list` で取得できるアプリの UUID）を受け取ります。

### `retention-messaging setup-status`

セットアップのステータスを返します。他のフラグは不要です。

### `retention-messaging realtime-url get`

Adapty のリアルタイム URL を返します。その他のフラグはありません。

### `retention-messaging realtime-url configure`

| フラグ | 必須 | 説明 |
|---|---|---|
| `--mode` | はい | `sandbox` または `production`。 |
| `--replace-other-url` | いいえ | Apple 内の別の URL の置き換えを承認します。 |
| `--yes`, `-y` | いいえ | 確認なしで設定します。`--json` 使用時またはパイプ経由の場合は必須。 |

### `retention-messaging performance-test start`

Apple のパフォーマンステストを`sandbox`で開始します。他のフラグは不要です。

### `retention-messaging messages list`

| フラグ | 必須 | 説明 |
|---|---|---|
| `--mode` | はい | `sandbox` または `production`。 |
| `--search` | いいえ | 名前の一部（大文字・小文字不問）、またはメッセージIDの完全一致。 |
| `--type` | いいえ | `default` または `promo`。 |
| `--state` | いいえ | `in_review`、`live`、`rejected`、または `inactive`。 |
| `--ordering` | いいえ | `name`、`type`、`state`、`products_count`、または `started_at`。逆順にするにはフィールド名の前に `-` を付けます。デフォルト: `-started_at`。 |
| `--page` | いいえ | ページ番号。デフォルト: 1。 |
| `--page-size` | いいえ | 1ページあたりのメッセージ数（最大100）。デフォルト: 20。 |

### `retention-messaging messages get`

メッセージ ID を引数として受け取ります。メッセージの全内容を返します。

### `retention-messaging messages create`

| フラグ | 必須 | 説明 |
|---|---|---|
| `--mode` | はい | `sandbox` または `production`。 |
| `--file` | はい | メッセージの JSON ファイル、またはスタンダード入力から読み込む場合は `-`。[メッセージを作成する](#create-a-message) を参照。 |
| `--image` | いいえ | デフォルトメッセージの PNG 画像。 |
| `--yes`, `-y` | いいえ | 確認なしで作成します。`--json` 使用時またはパイプ経由の場合は必須。 |

### `retention-messaging messages update`

メッセージIDを引数として受け取ります。

| フラグ | 必須 | 説明 |
|---|---|---|
| `--name`, `--title`, `--body`, `--alt-text` | いいえ | フィールドの新しい値。 |
| `--image` | いいえ | 新しいPNG画像。 |
| `--remove-image` | いいえ | 画像を削除します。 |
| `--file` | いいえ | 変更ファイル、または標準入力から読み込む場合は `-`。[メッセージの変更](#change-a-message)を参照してください。 |
| `--yes`, `-y` | いいえ | 確認なしで変更します。`--json` 使用時またはパイプ内では必須です。 |

### `retention-messaging messages set-status`

メッセージIDを引数として受け取ります。

| フラグ | 必須 | 説明 |
|---|---|---|
| `--action` | はい | `activate` または `deactivate`。 |
| `--yes`, `-y` | いいえ | 確認なしでステータスを変更します。`--json` 使用時またはパイプ経由の場合は必須です。 |

### `retention-messaging products suggest`

| フラグ | 必須 | 説明 |
|---|---|---|
| `--mode` | はい | `sandbox` または `production`。 |
| `--type` | はい | `default` または `promo`：メッセージのタイプ。 |
| `--search` | いいえ | プロダクトタイトルの一部（大文字・小文字を問わない）。 |
| `--message-id` | いいえ | 変更するメッセージの ID。 |
| `--limit` | いいえ | 返すプロダクト数（最大 100）。デフォルト：10。 |

### `retention-messaging promo-offers suggest`

`products suggest` からプロダクト ID を引数として受け取ります。

| フラグ | 必須 | 説明 |
|---|---|---|
| `--search` | いいえ | オファータイトルの一部（大文字小文字を区別しない）。 |
| `--limit` | いいえ | 返すオファーの件数（最大100件）。デフォルト: 10。 |

### `retention-messaging plan-switches suggest`

`products suggest` からのプロダクト ID を引数として受け取ります。

| フラグ | 必須 | 説明 |
|---|---|---|
| `--search` | いいえ | プラン名の一部（大文字・小文字不問）。 |
| `--limit` | いいえ | 返却するプラン数。最大 100。デフォルト: 10。 |

## AIアシスタントとの連携 \{#work-from-an-ai-assistant\}

[Adapty MCPサーバー](adapty-mcp)は、`retention_messaging_*` ツールと同じ操作を提供します。たとえば、`messages list` に対応する `retention_messaging_messages_list` などです。これらのツールでは、`--type` の代わりに `message_type` を使用します。

- **承認**: アシスタントは、`sandbox` および `production` 環境でリアルタイム URL の設定、メッセージの作成・変更、またはステータスの変更を行う前に確認を求めます。別のサーバーのリアルタイム URL を置き換える前には、個別に確認を求めます。また、会話内で初めてセットアップステータスを読み取る前に 1 回、初めてメッセージを読み取る前に 1 回確認を求めます。これは[これらの読み取り操作が Adapty を更新する可能性がある](#read-the-setup-status)ためです。
- **画像と箇条書き**: MCP ツールでは、画像、箇条書きアイコン、または新しい箇条書き項目を追加できません。`retention_messaging_messages_create` は画像や箇条書きなしでメッセージを作成します。これらを追加するには、CLI から `messages update` を実行するか、ダッシュボードを使用してください。

## 次のステップ \{#whats-next\}

- [リテンションメッセージングのエージェントスキル](retention-messaging-skill) — エージェントにリテンションメッセージングのセットアップとメッセージの作成を任せ、変更のたびに確認できます。
- [リテンションメッセージングのセットアップ](retention-messaging-setup) — ダッシュボードでの同じセットアップ手順です。
- [リテンションメッセージを作成する](retention-messaging-create) — ダッシュボードのメッセージフィールド、ロケール、ステータスについて説明します。
- [メッセージのパフォーマンスを追跡する](retention-messaging-analytics) — 各指標の意味を解説します。