Power Apps Native Mobile Code Apps 開発スキル

Microsoft 公式 microsoft/power-platform-skills/plugins/mobile-apps を upstream として、 Expo + React Native + TypeScript の Native Mobile Code App を作成する。

[!CAUTION] Private Preview であり、本番利用は禁止。 スキル開始時、計画承認時、最終結果でこの制約を明示する。 ユーザーが Preview 利用を明示承認するまで scaffold、環境変更、Wrap 登録、push を開始しない。

Web Code App との境界

「モバイル対応」の依頼では、最初にどちらを求めているか確認する。

選択肢	ランタイム	選ぶ条件	スキル
レスポンシブ Web Code App	React + Vite、ブラウザ／Power Apps player	PC とモバイルで同じ Web UI、ネイティブ機能が不要	code-apps
Native Mobile Code App	Expo + React Native、Power Apps Developer app／Wrap	カメラ、バーコード、位置情報等の端末機能が必要	本スキル

Native 経路は Preview 承認に加え、対象 OS、必要な端末機能、オンライン要件、実機テスト端末を確認する。

ワークフロー

Step 0: Preview 利用を確認する

次を説明し、明示承認を得る。

1. Private Preview で本番利用できない。
2. iOS / Android のローカル native build や App Store / Google Play 配布は v0 の対応範囲外。
3. 公式対応は Power Apps Developer app による実機 preview と、pa app push 後の Wrap 導線まで。
4. Preview の破壊的変更に備え、upstream commit と依存セットを固定する。

承認がない場合は code-apps のレスポンシブ Web 案を提示して停止する。 承認後の scaffold は mobile-preview-approval.json を生成する。検証器はこの記録がなく、または productionAllowed: true のプロジェクトを拒否する。

Step 1: 要件とネイティブ機能を設計する

対象 OS、画面、データ、コネクタ、認証、端末機能、オンライン／オフライン要件を整理する。 端末機能は公式テンプレートの package.json に存在する module だけを候補にする。

• Phase 1: Dataverse／connector、基本画面、camera／location／barcode、実機 preview、push
• Phase 2: PDF、pen／signature、File／Image、sharing、生体認証
• Phase 3: Offline Profile の authoring／assignment／drift check

オフライン runtime store／sync queue は upstream 対応を確認できるまで実装済みと扱わない。

Step 2: 公式テンプレートを生成する

Windows PowerShell 7 で、記録済み upstream commit から生成する。

python .github/skills/mobile-apps/scripts/scaffold_mobile_app.py `
  --target ./my-mobile-app `
  --preview-approved `
  --install
Set-Location ./my-mobile-app

依存は upstream-template.json の互換性セットを使う。 Expo、React Native、Tamagui、native host、Power Apps SDK を個別に latest へ上げない。

Step 3: MobileApp として初期化する

公式 template は Power Apps CLI を依存に含まないため、検証済み CLI を明示して実行する。

npx --yes --package @microsoft/power-apps-cli@1.0.1 pa app init `
  -t MobileApp `
  --display-name "$env:MOBILE_APP_DISPLAY_NAME" `
  --environment-id "$env:ENVIRONMENT_ID" `
  --non-interactive

power.config.json は生成物であり、別アプリからコピーしない。

Step 4: Wrap app registration を設定する

Wrap UIで観測したMicrosoft Graph v1.0 contractを承認付きで実行する。まずplanとSHA-256を確認する。

python scripts/register_wrap_application.py plan --tenant-id $env:TENANT_ID `
  --name $env:MOBILE_APP_DISPLAY_NAME --output .mcp/wrap-registration-plan.json

python scripts/register_wrap_application.py apply `
  --plan .mcp/wrap-registration-plan.json --expected-hash <SHA256> `
  --report-file .mcp/wrap-registration-result.json

applyはtokenのtenant一致と同名registration不存在を確認し、Graph POST /v1.0/applications後に redirect URI、audience、全resource/scopeをread-backする。reportのApplication (client) ID とtenant IDを auth.config.json の msal.clientId / msal.tenantId に設定する。client secret は不要で、保存しない。 OAuth consent、MFA、policy acceptanceは自動化しない。 観測contractとcleanup境界はWrap registrationリファレンスを参照する。

検証用registrationを削除する場合は、report内のcleanupHashを別途承認して実行する。

python scripts/register_wrap_application.py cleanup `
  --report-file .mcp/wrap-registration-result.json --expected-hash <CLEANUP_SHA256>

Step 5: Power Platform データを接続する

外部 API への直接 fetch / axios ではなく connector-first とする。

# Dataverse または Power Platform connector を CLI で追加し、src/generated/ を生成する
npx --yes --package @microsoft/power-apps-cli@1.0.1 pa app add data-source <options>

React Native 画面は src/generated/services/*Service.ts を service／hook 層から呼び出す。 ページから SDK や connector client を直接呼ばない。詳細は build-reference.md。

Step 6: allowlist 内のネイティブ機能を追加する

必要な module が生成済み package.json に存在することを確認してから、src/native/ に typed wrapper を置く。 camera／barcode の標準契約は native-capabilities.md を使う。

wrapper は permission の granted / denied、cancel、unsupported、success を判別可能な union で返し、 画面から Expo module を直接呼ばない。allowlist にない native package を追加したふりをしない。

Step 7: モバイル UI を実装する

Expo Router の Stack／Tabs を要件に応じて選択し、次を品質ゲートにする。

• root を SafeAreaProvider で包み、各画面で safe area を確保
• 入力画面は KeyboardAvoidingView を使用
• touch target は原則 44 x 44 pt 以上
• screen reader label、font scaling、loading／empty／error／retry／refresh を実装
• 一覧は cursor paging を使い、総件数前提のページ番号 UI にしない

詳細は mobile-ui.md。

Step 8: 品質ゲートを実行する

npm run type-check
python ../.github/skills/mobile-apps/scripts/validate_mobile_project.py .

失敗した状態で Metro、build、push へ進まない。

Step 9: 実機 preview を確認する

npm run dev

Metro の QR コードを Power Apps Developer app で読み取り、iOS／Android 実機で認証、safe area、keyboard、 権限拒否、camera／barcode 等を確認する。ストア配布用アプリの検証とは扱わない。

Step 10: build、push、Wrap 導線を確認する

最初に power.config.json の appId を確認する。未発行の場合、最初の push で ID が発行されるが、 その ID は native bundle の build 時に埋め込まれるため、bundle → push を2回実行する。

python ../.github/skills/mobile-apps/scripts/verify_native_package.py preflight .
# exit code 2 (FIRST_DEPLOY) の場合は、以下を2サイクル実行する

npm run generate-schemas
npm run bundle:web
npm run bundle:android
npm run bundle:ios
python ../.github/skills/mobile-apps/scripts/verify_native_package.py verify .
npx --yes --package @microsoft/power-apps-cli@1.0.1 pa app push

各サイクルで connector schema を先に再生成する。1回目の push 後に appId が発行されたことを preflight で確認し、Web bundle、Android／iOS の Hermes bundle と customer assets をすべて再生成してから2回目を push する。片方の native bundle、 manifest、Hermes magic bytes が欠ける場合は停止し、Web-only build を Wrap に渡さない。

push 後は power.config.json の app ID と環境 ID を使い、次の Wrap URL を案内する。

https://make.powerapps.com/environments/{ENVIRONMENT_ID}/wrap?appID={APP_ID}

最終結果に Private Preview／本番利用禁止、実機確認済み範囲、未検証 OS、offline runtime 未対応を明記する。

リファレンス

文書	内容
build-reference.md	init、認証、connector、generated services、preview、push
native-capabilities.md	allowlist と camera／barcode wrapper
mobile-ui.md	Stack／Tabs、safe area、keyboard、accessibility
offline.md	Offline Profile authoring と runtime の境界
upstream-template.json	公式同期元 commit、同期日、依存バージョン
troubleshooting.md	Preview／Expo／Wrap／権限／Metro の異常系

スクリプト

スクリプト	用途
scaffold_mobile_app.py	pinned upstream template を生成し、任意で install／MobileApp init／type-check
validate_mobile_project.py	Preview ガード、依存セット、auth、UI、native wrapper、offline 境界を検証
verify_native_package.py	app ID preflight と Android／iOS native package を検証
test_validate_mobile_project.py	offline runtime 判定の false positive／false negative を回帰テスト
test_verify_native_package.py	app ID／Hermes bundle／asset manifest の回帰テスト
check_upstream.py	公式 mobile-apps HEAD と同期済み commit の差分を検出