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

​

Service Extension と Content Extension の統合

​

ステップ 1: 前提条件

• Extension Integrator Tool を利用するには、MoEngage Flutter SDK バージョン 10.6.0 以上を使用していることを確認してください。
• SDK の初期化: ファイルベースの初期化を使用して MoEngage SDK を初期化します。
  • App Group の設定: AppGroupName キー（例: group.com.organization.app）を使用して、設定内で App Group を定義します。
    • この App Group を Xcode の Signing & Capabilities に追加します。
      
• 統合が完了すると、コード署名のためにキーチェーンへのアクセスを求められる場合があります。常に許可 をクリックしてください。
  

​

ステップ 2: Service Extension の設定

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

2. 手順 1 で作成した Service Extension の識別子を選択し、Capabilities タブを開いて App Groups を追加します。AppGroupName キーと一致する名前を入力します。
   
3. プロビジョニングプロファイルの生成: Apple Developer Portal で、手順 1 で作成した識別子用の新しいプロビジョニングプロファイルを作成し、ダウンロードします。Xcode でダウンロードするには、メニューバーの Xcode をクリックし、Settings を選択します。
   
4. Apple Accounts セクションに切り替え、Apple デベロッパーアカウントを選択します。Apple Accounts ページで Download Manual Profiles を選択します。
   

​

ステップ 3: Content Extension の設定（オプション）

1. App Identifier を作成します: [appBundleId].[contentExtensionName]. の形式を使用します。
   1. [appBundleId] をアプリケーション固有のバンドル識別子に置き換えます。
   2. [contentExtensionName] を任意の名前（デフォルトは MoEngageNotificationContent）に置き換えます。例_:_ アプリのバンドル識別子が com.org.app で、拡張機能の名前が NotificationContent の場合、識別子は com.org.app.NotificationContent になります。
2. Content Extension の識別子を選択し、Capabilities タブを開いて App Groups を追加します。AppGroupName キーと一致する名前を入力します。
   
3. プロビジョニングプロファイルの生成: Apple Developer Portal で、手順 1 で作成した識別子用の新しいプロビジョニングプロファイルを作成し、ダウンロードします。Xcode でダウンロードするには、メニューバーの Xcode をクリックし、Settings を選択します。
   
4. Apple Accounts セクションに切り替え、Apple デベロッパーアカウントを選択します。Apple Accounts ページで Download Manual Profiles を選択します。

​

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

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

pod 'MoEngage-iOS-SDK/RichNotification'

 pod repo update
 pod install

​

ステップ 5: Extension Integrator Tool の統合

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

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

• $(BUILT_PRODUCTS_DIR)/$(INFOPLIST_PATH)
• $(INSTALL_DIR)/$(INFOPLIST_PATH)

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

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

${PODS_ROOT}/MoEngageExtensionsIntegration/moengage-extensions-integration.artifactbundle/moengage-extensions-integration/bin/moengage-extensions-integration $OPTIONS

​

利用可能なオプション

​

コマンドの例（SPM）

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 に設定します。
   

​

Extension Integrator Tool への移行

​

トラブルシューティングと FAQ

Integrator Tool がエラーを返しました。どのように解決すればよいですか？

詳細については、ビルドログを確認してください。

一般的な原因は次のとおりです。

• 統合の誤り: セットアップが Service Extension と Content Extension の統合ガイドに従っていません。
• 設定の欠落: Info.plist に必要な MoEngage の設定オプションがありません。
• App Group の不一致: Info.plist で指定された AppGroupName が、Service Extension と Content Extension のバンドル識別子の capabilities、またはアプリケーションの entitlements に含まれていません。
• 環境の不一致: プロビジョニングプロファイルが特定のビルド環境用に作成されていません（例: App Store ビルドの生成時に Development プロファイルを使用している）。
• カスタムディレクトリの問題: プロビジョニングプロファイルがデフォルトの Xcode ディレクトリに保存されていません。カスタムパスを渡すには、追加の設定用ビルド設定を使用してください。
• 証明書の問題: プロビジョニングプロファイルの生成時に、証明書の設定が欠落しているか誤っています。
• プロファイルの有効期限切れ: プロビジョニングプロファイルの有効期限が切れています。プロファイルを再生成して再ダウンロードする必要があります。

Service Extension と Content Extension の両方を統合する必要がありますか？

いいえ。Service Extension は、通知インプレッションのトラッキングとリッチメディア（画像/GIF/動画）のダウンロードに必須です。Content Extension は、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 バイナリへの絶対パスを指定してください。