> ## Documentation Index
> Fetch the complete documentation index at: https://moengage.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# リッチプッシュとインプレッショントラッキングのための iOS 通知拡張機能の設定

> iOS でプッシュインプレッショントラッキングとリッチメディア通知を有効にするために必要な設定です。この設定を省略すると、インプレッション指標が欠落し、リッチプッシュが正常に動作しません。

このガイドの手順はすべて Xcode で実行します。作業を始める前に、Xcode で `ios/YourApp.xcworkspace` を開いて iOS プロジェクトを開いてください。

このガイドでは、MoEngage のサービス拡張機能とコンテンツ拡張機能を iOS アプリケーションに統合する方法について説明します。これらの拡張機能により、通知インプレッションのトラッキング、リッチメディア（画像、GIF、動画）のサポート、およびリッチプッシュ通知テンプレートの使用が可能になります。

## サービス拡張機能とコンテンツ拡張機能の統合

これらの拡張機能がない場合、MoEngage はプッシュインプレッションをトラッキングできず、[リッチメディア](https://www.moengage.com/docs/user-guide/campaigns-and-channels/mobile-push/notification-features-and-behavior/gifs-in-push-notifications)通知はプレーンテキストにフォールバックし、[リッチプッシュテンプレート](https://www.moengage.com/docs/user-guide/campaigns-and-channels/mobile-push/create/push-templates)はフォールバックテンプレートで表示されます。

| ユースケース | サービス拡張機能（ステップ 2） | コンテンツ拡張機能（ステップ 3） | MoEngageRichNotification（ステップ 4） | Integrator Tool のフラグ |
| :- | :- | :- | :- | :- |
| プッシュインプレッションのトラッキング | ✅ 必須 | — | — | （デフォルト） |
| プッシュでのリッチメディア（画像、GIF、動画） | ✅ 必須 | — | ✅ 必須 | （デフォルト） |
| MoEngage リッチプッシュテンプレート（カルーセル） | ✅ 必須 | ✅ 必須 | ✅ 必須 | `--enable-push-notification-templates` |

### ステップ 1: 前提条件

作業を進める前に、以下が整っていることを確認してください。

* 拡張機能 Integrator Tool を利用するには、MoEngage React Native SDK バージョン [12.6.0](/docs/ja/release-notes/sdks/react-native#core-12-6-0) 以上を使用していることを確認してください。
* **SDK の初期化:** [ファイルベースの初期化](/docs/ja/developer-guide/react-native-sdk/sdk-integration/react-native/sdk-initialization/file-based-initialization/file-based-initialization)を使用して MoEngage SDK を初期化します。
  * **App Group の設定:** `AppGroupName` キーを使用して、設定内で App Group を定義します（例: `group.com.organization.app`）。
    * この App Group を Xcode の **Signing & Capabilities** に追加します。

      ![iOS 1](https://mintcdn.com/moengage/X586_MHJ15DsSG1z/images/iOS-1.png?fit=max\&auto=format\&n=X586_MHJ15DsSG1z\&q=85\&s=a638b4ba039be7ec2f02823f54b5655b)
* 統合が完了すると、コード署名のためにキーチェーンへのアクセスを求められる場合があります。**常に許可（Always Allow）** をクリックしてください。

  ![キーチェーン](https://mintcdn.com/moengage/X586_MHJ15DsSG1z/images/keychain.png?fit=max\&auto=format\&n=X586_MHJ15DsSG1z\&q=85\&s=bba38a4dc7160d9ee9eafc785c9dc5ba)

### ステップ 2: サービス拡張機能の設定

サービス拡張機能は、通知インプレッションをトラッキングし、リッチメディアコンテンツをダウンロードします。

1. [App Identifier を作成します](https://developer.apple.com/help/account/identifiers/register-an-app-id): `[appBundleId].[serviceExtensionName].` の形式を使用します。
   1. `[appBundleId]` をアプリケーション固有のバンドル識別子に置き換えます。
   2. `[serviceExtensionName]` を任意の名前（デフォルトは *MoEngageNotificationService*）に置き換えます。例えば、アプリのバンドル識別子が `com.org.app` で、拡張機能の名前が `NotificationService` の場合、識別子は `com.org.app.NotificationService` になります。

> [!NOTE]
>
> 既存の Notification Service Extension がある場合は、新しく作成せずにそれを再利用できます。[ステップ 5 の Run Script Phase](#step-5-integrate-the-extension-integrator-tool) を設定する際に、`--notification-service-extension-name` フラグでその名前を渡してください。ツールはカスタムコードを上書きすることなく、必要な MoEngage のロジックを挿入します。

2. ステップ 1 で作成したサービス拡張機能の識別子を選択し、**Capabilities** タブを開いて [**App Groups**](https://developer.apple.com/help/account/identifiers/register-an-app-group) を追加します。`AppGroupName` キーと一致する名前を入力します。

   ![App Group](https://mintcdn.com/moengage/zH21h-CNZRwh5gH2/images/Appgroup.png?fit=max\&auto=format\&n=zH21h-CNZRwh5gH2\&q=85\&s=6c3a987a7b37e774991fc361917a5483)
3. **プロビジョニングプロファイルの生成:** [Apple Developer Portal](https://developer.apple.com/account/resources/profiles/list) で、ステップ 1 で作成した識別子用の[新しいプロビジョニングプロファイルを作成](https://developer.apple.com/help/account/provisioning-profiles/create-an-app-store-provisioning-profile)し、ダウンロードします。Xcode でダウンロードするには、メニューバーの **Xcode** をクリックし、**Settings** を選択します。

   ![Xcode の設定 2](https://mintcdn.com/moengage/QRA9mXpKWWsuhfxo/images/Xcodessettings-2.png?fit=max\&auto=format\&n=QRA9mXpKWWsuhfxo\&q=85\&s=692e2bfbe602e73d1d210d7684233c90)
4. **Apple Accounts** セクションに切り替え、Apple デベロッパーアカウントを選択します。Apple Accounts ページで **Download Manual Profiles** を選択します。

   ![プロビジョニングプロファイル 3](https://mintcdn.com/moengage/F4npPBVazsQn0JKX/images/provisioningprofile-3.png?fit=max\&auto=format\&n=F4npPBVazsQn0JKX\&q=85\&s=10bfd0ea76fe58c0d7db0e1b893b60ef)

> [!TIP]
>
> リッチプッシュテンプレートが不要な場合は、ステップ 3 と 4 をスキップして、[ステップ 5: 拡張機能 Integrator Tool の統合](#step-5-integrate-the-extension-integrator-tool)に直接進むことができます。

### ステップ 3: コンテンツ拡張機能の設定（オプション）

コンテンツ拡張機能は、MoEngage のリッチプッシュ通知テンプレートを使用する場合にのみ必要です。

1. [App Identifier を作成します](https://developer.apple.com/help/account/identifiers/register-an-app-id): `[appBundleId].[contentExtensionName].` の形式を使用します。
   1. `[appBundleId]` をアプリケーション固有のバンドル識別子に置き換えます。
   2. `[contentExtensionName]` を任意の名前（デフォルトは *MoEngageNotificationContent*）に置き換えます。例えば、アプリのバンドル識別子が `com.org.app` で、拡張機能の名前が `NotificationContent` の場合、識別子は `com.org.app.NotificationContent` になります。
2. コンテンツ拡張機能の識別子を選択し、**Capabilities** タブを開いて [**App Groups**](https://developer.apple.com/help/account/identifiers/register-an-app-group) を追加します。`AppGroupName` キーと一致する名前を入力します。

   ![App Group](https://mintcdn.com/moengage/zH21h-CNZRwh5gH2/images/Appgroup.png?fit=max\&auto=format\&n=zH21h-CNZRwh5gH2\&q=85\&s=6c3a987a7b37e774991fc361917a5483)
3. **プロビジョニングプロファイルの生成:** [Apple Developer Portal](https://developer.apple.com/account/resources/profiles/list) で、ステップ 1 で作成した識別子用の[新しいプロビジョニングプロファイルを作成](https://developer.apple.com/help/account/provisioning-profiles/create-an-app-store-provisioning-profile)し、ダウンロードします。Xcode でダウンロードするには、メニューバーの **Xcode** をクリックし、**Settings** を選択します。

   ![Xcode の設定 3](https://mintcdn.com/moengage/QRA9mXpKWWsuhfxo/images/Xcodessettings-3.png?fit=max\&auto=format\&n=QRA9mXpKWWsuhfxo\&q=85\&s=fabd1fbda78ca820cbf0bd07323dec5b)
4. **Apple Accounts** セクションに切り替え、Apple デベロッパーアカウントを選択します。Apple Accounts ページで **Download Manual Profiles** を選択します。

![プロビジョニングプロファイル 3](https://mintcdn.com/moengage/F4npPBVazsQn0JKX/images/provisioningprofile-3.png?fit=max\&auto=format\&n=F4npPBVazsQn0JKX\&q=85\&s=10bfd0ea76fe58c0d7db0e1b893b60ef)

### ステップ 4: MoEngageRichNotification の統合（オプション）

以下のいずれかのプッシュ通知機能をサポートする必要がある場合は、`MoEngageRichNotification` を統合します。

* **リッチメディア** — 通知バナーに画像、GIF、または動画を表示します
* **リッチプッシュテンプレート** — カルーセルなどのインタラクティブな通知レイアウトを表示します

> [!NOTE]
>
> ステップ 3 で説明したコンテンツ拡張機能を統合している場合、このステップは必須です。

**Swift Package Manager (SPM)**

SPM を使用して `MoEngageRichNotification` をインストールするには、以下の手順を実行します。

1. **File > Add Package** に移動します。
2. リポジトリ URL を入力します。
   * `https://github.com/moengage/apple-sdk.git`
3. **master** ブランチまたは特定のバージョンを選択し、**Add Package** を選択します。
4. パッケージのターゲットをアプリケーションに設定します。

**CocoaPods**

> [!WARNING]
>
> **情報** CocoaPods は非推奨になる予定です。MoEngage では、すべての新規統合に Swift Package Manager を使用することを推奨しています。詳細については、[こちら](/docs/ja/developer-guide/ios-sdk/sdk-integration/basic/sdk-integration)を参照してください。

1. アプリのターゲット内の `Podfile` に次の行を追加します。

> [!NOTE]
>
> `react-native-moengage` パッケージは autolinking によってすでに `MoEngage-iOS-SDK` を取り込んでいるため、追加が必要なのは `RichNotification` サブスペックのみです。

```ruby lines wrap theme={null}
pod 'MoEngage-iOS-SDK/RichNotification'
```

2. pod install を実行します。

```ruby lines wrap theme={null}
 pod repo update
 pod install
```

### ステップ 5: 拡張機能 Integrator Tool の統合

ビルドプロセスにカスタムスクリプトを追加して、拡張機能の設定を自動化します。

1. Xcode でアプリケーションのターゲットを選択し、**Build Phases** に移動して **+** をクリックし、**New Run Script Phase** を追加します。

![New Run Script Phase](https://mintcdn.com/moengage/F4npPBVazsQn0JKX/images/newrunscriptphase.png?fit=max\&auto=format\&n=F4npPBVazsQn0JKX\&q=85\&s=4c0db98aafc37139866d3cd48765ef80)

2. **Input Files** セクションに次のパスを追加します。

* `$(BUILT_PRODUCTS_DIR)/$(INFOPLIST_PATH)`
* `$(INSTALL_DIR)/$(INFOPLIST_PATH)`

![パス 1](https://mintcdn.com/moengage/F4npPBVazsQn0JKX/images/path-1.png?fit=max\&auto=format\&n=F4npPBVazsQn0JKX\&q=85\&s=e38b6527f2e8dd128e6d1642f12e32ee)

3. 上の画像の **integrate\_extensions** を置き換えて、使用している依存関係マネージャーに対応するコマンドを入力します。

> [!NOTE]
>
> すでにスクリプトフェーズを追加して入力ファイルを設定している場合は、以下で説明するように実行コマンドを更新するだけで済みます。

**Swift Package Manager (SPM)**

```bash Swift Package Manager (SPM) lines wrap theme={null}
case "$ACTION" in
  install) SPM_ROOT="$OBJROOT/../../../../.." ;;   # xcodebuild archive
  *)       SPM_ROOT="$OBJROOT/../.." ;;            # build / run from Xcode
esac
"$SPM_ROOT/SourcePackages/artifacts/apple-sdk/moengage-extensions-integration/moengage-extensions-integration.artifactbundle/moengage-extensions-integration/bin/moengage-extensions-integration" $OPTIONS
```

**CocoaPods**

```bash CocoaPods lines wrap theme={null}
${PODS_ROOT}/MoEngageExtensionsIntegration/moengage-extensions-integration.artifactbundle/moengage-extensions-integration/bin/moengage-extensions-integration $OPTIONS
```

#### 使用可能なオプション

`$OPTIONS` を以下の 1 つ以上に置き換えます。

| オプション | 説明 |
| :- | :- |
| `--enable-push-notification-templates` | ステップ 3 のコンテンツ拡張機能を使用する場合に必須です。 |
| `--notification-service-extension-name $CUSTOM_SERVICE_EXTENSION_NAME` | サービス拡張機能のカスタム名を設定します。カスタムのサービス拡張機能の実装からこのツールに移行する場合に使用します。（デフォルト: `MoEngageNotificationService`） |
| `--notification-content-extension-name $CUSTOM_CONTENT_EXTENSION_NAME` | コンテンツ拡張機能のカスタム名を設定します。カスタムのコンテンツ拡張機能の実装からこのツールに移行する場合に使用します。（デフォルト: `MoEngageNotificationContent`） |

### コマンド例（SPM）

`NotificationService` という名前のサービス拡張機能と `NotificationContent` という名前のコンテンツ拡張機能を統合する場合、SPM の完全なコマンドは次のようになります。

```bash Swift Package Manager (SPM) lines wrap theme={null}
case "$ACTION" in
  install) SPM_ROOT="$OBJROOT/../../../../.." ;;   # xcodebuild archive
  *)       SPM_ROOT="$OBJROOT/../.." ;;            # build / run from Xcode
esac
"$SPM_ROOT/SourcePackages/artifacts/apple-sdk/moengage-extensions-integration/moengage-extensions-integration.artifactbundle/moengage-extensions-integration/bin/moengage-extensions-integration" --enable-push-notification-templates --notification-service-extension-name NotificationService --notification-content-extension-name NotificationContent
```

4. **サンドボックスの無効化:** アプリケーションターゲットの **Build Settings** で、**USER\_SCRIPT\_SANDBOXING** を **No** に設定します。

   ![User Script Sandboxing](https://mintcdn.com/moengage/QRA9mXpKWWsuhfxo/images/UserScriptsandboxing.png?fit=max\&auto=format\&n=QRA9mXpKWWsuhfxo\&q=85\&s=ef743e8cfbf583c85402f754a3fc87e7)

## 拡張機能 Integrator Tool への移行

既存の手動実装から Integrator Tool に移行するには、[こちら](/docs/ja/developer-guide/react-native-sdk/push/basic/integrating-moengage-service-and-content-extensions/migrating-to-the-extension-integrator-tool)を参照してください。

## トラブルシューティングとよくある質問

> **Integrator Tool がエラーを返しました。どのように解決すればよいですか？**
>
> 詳細な情報については、ビルドログを確認してください。
>
> ![エラーログ](https://mintcdn.com/moengage/vfQMdHOXE1Qy6IH-/images/errorlogs.png?fit=max\&auto=format\&n=vfQMdHOXE1Qy6IH-\&q=85\&s=ae6894fc4ff563b7c6f8034df3e84502)
>
> 一般的な原因には次のようなものがあります。
>
> * **不正な統合:** セットアップが [サービス拡張機能とコンテンツ拡張機能の統合](/docs/ja/developer-guide/ios-sdk/push/basic/ios-push-integration-tutorial)ガイドに従っていません。
> * **設定の欠落:** `Info.plist` に必要な MoEngage の設定オプションがありません。
> * **App Group の不一致:** `Info.plist` で指定した `AppGroupName` が、サービス拡張機能およびコンテンツ拡張機能のバンドル識別子の Capabilities、またはアプリケーションの Entitlements に含まれていません。
> * **環境の不一致:** プロビジョニングプロファイルが特定のビルド環境用に作成されていません（例: App Store ビルドの生成時に Development プロファイルを使用している）。
> * **カスタムディレクトリの問題:** プロビジョニングプロファイルがデフォルトの Xcode ディレクトリに保存されていません。[追加設定用のビルド設定](#troubleshooting-and-faqs)を使用してカスタムパスを渡してください。
> * **証明書の問題:** プロビジョニングプロファイルの生成時に、証明書の設定が欠落しているか誤っています。
> * **プロファイルの有効期限切れ:** プロビジョニングプロファイルの有効期限が切れています。プロファイルを再生成して再ダウンロードする必要があります。

> **サービス拡張機能とコンテンツ拡張機能の両方を統合する必要がありますか？**
>
> いいえ。サービス拡張機能は、通知インプレッションのトラッキングとリッチメディア（画像/GIF/動画）のダウンロードに必須です。コンテンツ拡張機能は、MoEngage のインタラクティブな *リッチプッシュテンプレート*（カルーセルやカスタムボタンレイアウトなど）を使用する場合にのみ必要です。

> **「App Group」の設定が必須なのはなぜですか？**
>
> iOS の拡張機能は、メインアプリケーションとは別のサンドボックスで実行されます。**App Group** は共有コンテナを作成し、メインアプリの MoEngage SDK が認証トークン、ユーザーデータ、ローカルストレージを拡張機能と共有できるようにします。これがないと、拡張機能はユーザーを検証したり、インプレッションを正しくトラッキングしたりできません。

> **Build Settings で「User Script Sandboxing」を無効にする必要があるのはなぜですか？**
>
> **Extension Integrator Tool** は、標準の Xcode サンドボックス外のシステムフォルダにあるプロジェクトのビルド成果物とプロビジョニングプロファイルにアクセスする必要があります。`ENABLE_USER_SCRIPT_SANDBOXING` が **Yes** に設定されていると、スクリプトがブロックされ、ビルドフェーズ中に「Permission Denied」エラーが発生します。

> **このツールで複数のビルド環境（Dev/Staging/Prod）を扱うにはどうすればよいですか？**
>
> 追加のビルド設定を使用して、ローカルビルドと CI ビルドの両方で Integrator Tool に特定の設定入力を提供できます。
>
> * **`MOENGAGE_EXTENSION_PROFILES_SEARCH_PATHS`:** プロビジョニングプロファイルを検索する追加のフォルダを指定する場合に使用します。デフォルトでは、ツールは標準の Xcode ディレクトリを検索します。
>   * `~/Library/Developer/Xcode/UserData/Provisioning Profiles`
>   * `~/Library/MobileDevice/Provisioning Profiles` プロビジョニングプロファイルがこれらのフォルダにない場合は、このビルド設定で追加のパスを指定します。
> * **`MOENGAGE_NOTIFICATION_SERVICE_EXTENSION_PROFILE`:** Notification Service Extension のプロビジョニングプロファイルのファイル名を明示的に指定します。ツールはプロビジョニングプロファイルを検索する代わりに、このファイル名を使用します。プロファイルは上記のいずれかのフォルダに存在する必要があります。ツールが正しいプロビジョニングプロファイルを選択できない場合に、このオプションを使用してください。
> * **`MOENGAGE_NOTIFICATION_CONTENT_EXTENSION_PROFILE`:** Notification Content Extension のプロビジョニングプロファイルのファイル名を明示的に指定します。ツールはプロビジョニングプロファイルを検索する代わりに、このファイル名を使用します。プロファイルは上記のいずれかのフォルダに存在する必要があります。ツールが正しいプロビジョニングプロファイルを選択できない場合に、このオプションを使用してください。

> **通知でリッチメディアが表示されません。何が問題ですか？**
>
> これは通常、次の 3 つの技術的なギャップのいずれかに起因します。
>
> 1. **App Group の不一致:** `Info.plist` の `AppGroupName` 文字列が Entitlements ファイルと完全に一致していることを確認してください。
> 2. **ペイロードのタイムアウト:** iOS は拡張機能にメディアのダウンロード時間として約 30 秒を与えます。アセットが大きすぎる場合やネットワークが遅い場合は、失敗してプレーンテキストにフォールバックします。

> **このツールはカスタムの Derived Data パスや CI/CD で動作しますか？**
>
> はい。ステップ 5 のスニペットにある `case "$ACTION"` ブロックはすべてのビルドアクションに対応しているため、記載どおりに使用してください。
>
> CI 環境でカスタムの Derived Data またはビルドディレクトリを使用しており、パスの解決が失敗する場合は、代わりに `moengage-extensions-integration` バイナリへの絶対パスを指定してください。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.