パーミッション要求詳細 Permission requests

OS ネイティブ許可（user_device_permissions）とユーザーの同意の意思（user_consents）は 別概念です。本ページではそれぞれの意味、要求タイミング、プラットフォーム差分、 サーバー同期 API、および拒否時のフォールバック動作を定義します。

OS-level native permission (user_device_permissions) and the user's expressed consent (user_consents) are distinct concepts. This page defines their meaning, request timing, platform differences, server-sync APIs, and fallback behaviour when denied.

6.1 OS 許可 vs 同意 — 概念整理 6.1 OS permission vs consent — concept overview

OS が許可していてもユーザーが同意していない場合、アプリは機能を使いません。 逆に OS が拒否していれば、同意の有無に関わらず機能は動作しません。 両テーブルを組み合わせて判断します。

Even if the OS has granted a permission, the app will not use it unless the user has also given consent. Conversely, if the OS has denied it, the feature will not work regardless of consent. Both tables must be consulted together.

6.2 要求タイミング 6.2 Request timing

パーミッション要求は、オンボーディングの第 2 段階（認証完了直後）に集約します。 ユーザーが目的を理解した後に要求することで許可率を高めます。

Permission requests are concentrated at onboarding stage 2 (immediately after authentication completes). Requesting after the user understands the purpose increases grant rates.

6.3 位置情報 (Location) 6.3 Location

6.3.1 初期要求 — When In Use 6.3.1 Initial request — When In Use

Permission.locationWhenInUse.request() を呼び出します。 OS ダイアログ完了後、結果に関わらず以下の 2 API を順次呼び出します：

Calls Permission.locationWhenInUse.request(). After the OS dialog completes, regardless of result, the following 2 APIs are called in sequence:

• POST /v1/mobile/actions/permissions/record — OS が返したネイティブ許可状態と同意の意思を 1 リクエストで記録（{ code, granted, recorded_at }、Idempotency-Key 必須）Records both the native permission state and consent intent in one request ({ code, granted, recorded_at }, Idempotency-Key required)

6.3.2 昇格要求 — Always (駐車開始時) 6.3.2 Elevation request — Always (at parking start)

ユーザーが初めて駐車を開始しようとしたとき、 Permission.locationAlways.request() を呼び出します（iOS / Android 10+ 必須）。 既に Always 許可済みの場合はスキップします。

When the user starts parking for the first time, Permission.locationAlways.request() is called (required for iOS / Android 10+). Skipped if Always is already granted.

6.3.3 プラットフォーム差分 6.3.3 Platform differences

6.3.4 拒否時 degraded mode 6.3.4 Degraded mode on denial

• 住所テキスト検索: Mapbox Geocoding API で住所入力から座標取得
• Address text search: Obtain coordinates from address input via Mapbox Geocoding API
• マニュアル選択: マップをドラッグして中心座標を指定
• Manual selection: Drag the map to set the center coordinate
• 周辺一覧 UI: 現在地ボタンを非表示にし、「位置情報が無効です」バナーを表示
• Nearby list UI: Hide the current-location button and show a "Location is disabled" banner
• Live Activity は位置情報なしでも動作するが精度が低下する
• Live Activity operates without location but with reduced precision

6.4 プッシュ通知 (Push Notification) 6.4 Push notification

6.4.1 iOS 6.4.1 iOS

iOS では Permission.notification.request() を明示的に呼ばないと OS ダイアログが表示されません（デフォルトで通知は無効）。 FCM の getToken() 呼び出し前に許可を得ておく必要があります。

On iOS, Permission.notification.request() must be called explicitly; the OS dialog does not appear by default (notifications are off by default). Permission must be obtained before calling FCM's getToken().

6.4.2 Android 6.4.2 Android

6.4.3 拒否時 degraded mode 6.4.3 Degraded mode on denial

• in-app 通知: user_notifications テーブルに蓄積し、アプリ内通知センターで表示
• In-app notifications: Accumulated in user_notifications table and shown in the in-app notification centre
• メール通知: user_notification_prefs の email_enabled フラグに従い Resend 経由で送信
• Email notifications: Sent via Resend according to the email_enabled flag in user_notification_prefs
• ユーザーが後から設定画面で通知を再有効化した場合、AppSettings.openAppSettings() で OS 設定画面へ誘導
• If the user later re-enables notifications from app settings, guide them to OS Settings via AppSettings.openAppSettings()

6.5 サーバー同期 API 6.5 Server sync APIs

モバイルからは POST /v1/mobile/actions/permissions/record 1 本 で送る。 BFF が user_device_permissions（OS 許可状態）と user_consents（同意の意思）を同時 upsert する。 web/portal が直接叩く下記 2 endpoint はモバイル経路では使用しない。

Mobile sends a single POST /v1/mobile/actions/permissions/record. The BFF upserts both user_device_permissions (OS state) and user_consents (intent) atomically. The two web/portal endpoints below are not used by the mobile path.

POST /v1/mobile/actions/permissions/record （モバイル正規ルート）(mobile canonical route)

Idempotency-Key 必須。Body: { code, granted, recorded_at? }。レスポンスは更新後 PermissionsData を含む ActionEnvelope（NAVIGATION_REFRESH_CURRENT）。

Idempotency-Key required. Body: { code, granted, recorded_at? }. Response is an ActionEnvelope (NAVIGATION_REFRESH_CURRENT) wrapping the refreshed PermissionsData.

PUT /v1/me/device-permissions （web/portal 用、モバイル不使用）(web/portal only — not for mobile)

OS ネイティブ許可状態を user_device_permissions テーブルに UPSERT します。

UPSERTs the OS native permission state into the user_device_permissions table.

POST /v1/me/consents （web/portal 用、モバイル不使用）(web/portal only — not for mobile)

ユーザーの同意の意思を user_consents テーブルに INSERT します。

INSERTs the user's expressed consent into the user_consents table.

6.6 パーミッション要求フロー 6.6 Permission request flow

sequenceDiagram
  participant U as ユーザー
  participant App as モバイルアプリ
  participant OS as OS
  participant BFF as Workers BFF (mobile permissions actions)

  Note over App: オンボーディング第 2 段階
  App->>U: 位置情報の利用目的を説明するモーダル
  U->>App: 「許可する」ボタンをタップ
  App->>OS: Permission.locationWhenInUse.request()
  OS-->>U: OS ネイティブダイアログ
  U->>OS: 「Appの使用中は許可」を選択
  OS-->>App: PermissionStatus.granted
  App->>BFF: POST /record { code: "location", granted: true }
Idempotency-Key: 
  BFF-->>App: ActionEnvelope { data: PermissionsData, navigation: refresh_current }

  App->>U: プッシュ通知の利用目的を説明するモーダル
  U->>App: 「許可する」ボタンをタップ
  App->>OS: Permission.notification.request()
  OS-->>U: OS ネイティブダイアログ
  U->>OS: 「許可」を選択
  OS-->>App: PermissionStatus.granted
  App->>BFF: POST /record { code: "notification", granted: true }
Idempotency-Key: 
  BFF-->>App: ActionEnvelope { data: PermissionsData, navigation: refresh_current }

  App->>U: メイン画面 (/main) へ遷移

6.7 位置情報昇格要求フロー（駐車開始時） 6.7 Location elevation flow (at parking start)

sequenceDiagram
  participant U as ユーザー
  participant App as モバイルアプリ
  participant OS as OS
  participant BFF as Workers BFF

  U->>App: 「駐車開始」ボタンをタップ
  App->>App: locationAlways の現在状態を確認
  alt 未許可
    App->>U: バックグラウンド位置情報の利用目的を説明するモーダル
    U->>App: 「許可する」をタップ
    App->>OS: Permission.locationAlways.request()
    OS-->>U: OS ネイティブダイアログ
    U->>OS: 「常に許可」を選択
    OS-->>App: PermissionStatus.granted
    App->>BFF: POST /v1/mobile/actions/permissions/record
{ code: "location", granted: true }
    BFF-->>App: ActionEnvelope (PermissionsData)
  else 拒否済み
    App->>U: degraded mode の説明 + 設定アプリへのリンク
    App->>App: whenInUse のみで続行
  end
  App->>BFF: POST /v1/mobile/actions/sessions/start
{ parking_lot_id, start_lat, start_lng }
  BFF-->>App: ActionEnvelope (session, navigation: parking_session/{id})

6.8 iOS Info.plist / Android AndroidManifest.xml 宣言一覧 6.8 iOS Info.plist / Android AndroidManifest.xml declarations

iOS — Info.plist

Android — AndroidManifest.xml

6.9 拒否後の再要求ロジック 6.9 Re-request logic after denial

OS は 2 度目の要求ダイアログを表示しません（iOS: permanentlyDenied、Android: shouldShowRequestPermissionRationale == false）。 再許可には OS 設定アプリへの誘導が必要です。

The OS will not show a second-time dialog (iOS: permanentlyDenied; Android: shouldShowRequestPermissionRationale == false). Re-granting requires directing the user to OS Settings.

• 検出: permission_handler の PermissionStatus.permanentlyDenied を確認
• Detection: check for PermissionStatus.permanentlyDenied from permission_handler
• 誘導: AppSettings.openAppSettings() で OS 設定画面を開くボタンをアプリ内に表示
• Direction: show an in-app button that calls AppSettings.openAppSettings() to open OS Settings
• 戻り時の再チェック: WidgetsBindingObserver.didChangeAppLifecycleState で AppLifecycleState.resumed を検知し、許可状態を再確認して POST /v1/mobile/actions/permissions/record を再送（Idempotency-Key で重複排除）
• Re-check on return: detect AppLifecycleState.resumed via WidgetsBindingObserver.didChangeAppLifecycleState, re-check permission state, and re-post POST /v1/mobile/actions/permissions/record (deduped by Idempotency-Key)