deeplink-conventions

Deep link configuration conventions and security rules

항목	내용
적용 경로	`*/.well-known/` , `*/well_known_route` , `/AndroidManifest.xml` , `/.entitlements` , `/deep_link` , `*/deeplink` , `*/env_config` , `*/invite_link` , `*/coupon_link`

AASA (iOS Universal Links)#

Required Rules#

AASA must be served at /.well-known/apple-app-site-association
Content-Type: application/json required
Direct HTTPS serving (no redirects)
Server-only paths must be excluded with NOT prefix

Excluded Paths#

"paths": [
  "NOT /auth/*",
  "NOT /internal/*",
  "NOT /api/*",
  "*"
]

Path	Reason
`/auth/*`	OAuth callbacks (server token exchange required)
`/internal/*`	Internal server-to-server communication
`/api/*`	REST API endpoints

When Adding New Server Paths#

When adding new paths that should be handled by the server instead of the app:

Add NOT rule to dynamic AASA (well_known_route.dart)
Add the same rule to static AASA fallback file
The paths in both files must always be synchronized

assetlinks.json (Android App Links)#

Required Rules#

Served at /.well-known/assetlinks.json
Include both release + debug SHA-256 fingerprints
Path control is in AndroidManifest.xml (not assetlinks.json)

Path Exclusion Not Needed#

Android specifies only paths to include in intent-filter, so server callback paths are automatically excluded.

Dynamic + Static Synchronization#

File	Purpose	Serving Location	On Modification
`well_known_route.dart`	Dynamic AASA (per-environment Bundle ID)	Backend direct access domain	Modify server code
`web/.well-known/apple-app-site-association`	Static AASA	Firebase Hosting domain	Modify file + web deploy

The paths settings in both files must be identical.

Firebase Hosting Environment Rules#

When using Firebase Hosting as CDN/reverse proxy:

AASA Serving Priority#

1st: public directory static files (custom AASA)
2nd: Firebase auto-generated AASA (no custom NOT rules!)
3rd: rewrites → backend server (not reached)

Required Configuration#

Remove "**/.*" from firebase.json ignore — .well-known directory must be included in deployment
Specify Content-Type header — application/json for /.well-known/apple-app-site-association
Add .well-known copy to build script — flutter build web does not include web/.well-known

NOT Rules Included in Firebase Auto AASA#

Firebase auto AASA only includes the following (no custom rules):

"NOT /__/auth/action/"
"NOT /__/auth/handler/"
"NOT /_/*"

Custom static AASA must include both the above rules + project NOT rules.

URL Generation Rules#

Use Central Configuration (Required)#

When generating deep link URLs, always use the central configuration (EnvConfig.deeplinkBaseUrl).

// ✅ CORRECT: Use central configuration
final url = '${EnvConfig.deeplinkBaseUrl}/store/book/$bookId';

// ❌ WRONG: Direct domain composition
final url = 'https://$scheme.$domain/store/book/$bookId';

// ❌ WRONG: Hard-coded domain
final url = 'https://unibook.laputa.im/store/book/$bookId';

Domain Extraction#

// ✅ CORRECT: Extract domain via URI parsing
final domain = Uri.parse(EnvConfig.deeplinkBaseUrl).host;

// ❌ WRONG: String concatenation (risk of missing separator)
final domain = '${EnvConfig.deepLinkScheme}${EnvConfig.domain}';

Domain Migration Rules#

Backward Compatibility Required#

When changing domains, do not immediately remove the old domain.

Setting	New Domain	Old Domain
iOS entitlements	Add	Keep
Android intent-filter	Add	Keep
URL generation code	Use new domain	-

Full Scan Targets#

When changing domains, search all of the following areas:

Share link generation (chat invites, book sharing)
Coupon/promotion deep links
Admin console URL generation
Push notification payloads
Test code assertions
Example URLs in comments/documentation

Security Rules#

Do not expose internal-only paths in AASA/assetlinks.json
Include only release key SHA-256 fingerprints (debug keys for development only)
Do not include development Bundle IDs in production AASA