Bundle ID 불일치로 인해 iOS 유니버설 링크가 작동하지 않는 이유는 무엇인가요? Bundle ID 불일치는 애플리케이션의 서명된 애플리케이션 식별자(Application Identifier)가 연결된 도메인의 해당 AASA appID/appIDs 항목과 일치하지 않을 때 발생하며, 이로 인해 연결된 도메인(associated-domain) 검증이 실패하게 됩니다.
Bundle ID(CFBundleIdentifier)는 Apple 생태계 내에서 개별 iOS 애플리케이션을 식별하는 고유 문자열입니다. 유니버설 링크 아키텍처에서 Bundle ID는 애플리케이션 식별자 접두사(Application Identifier Prefix)와 결합하여 애플리케이션 식별자를 형성하며, 운영체제는 이를 호스팅된 apple-app-site-association 파일과 대조하여 네이티브 URL 처리를 승인합니다.
| 용어 | 정의 |
|---|---|
| Bundle ID | Xcode에서 iOS 앱 타겟에 할당된 고유한 역방향 DNS 식별자(CFBundleIdentifier). |
| 애플리케이션 식별자 접두사 (Application Identifier Prefix) | Apple 개발자 계정 설정에서 할당된 앱 ID 접두사(대개 팀 ID와 동일하지만 항상 그렇지는 않음). |
| 유니버설 링크 (Universal Links) | 웹 HTTPS URL을 네이티브 앱 뷰로 직접 라우팅하기 위한 Apple의 표준 메커니즘. |
| 연결된 도메인 (Associated Domains) | 앱이 처리할 수 있는 웹 도메인을 선언하는 Xcode 자격(Entitlement) (applinks:). |
| AASA 파일 | 앱 URL 처리를 승인하기 위해 도메인에 호스팅되는 JSON 파일(apple-app-site-association). |
표준 진단 체인
아래 다이어그램은 앱 설치 및 도메인 검증 과정에서 실행되는 다중 계층 검증 시퀀스를 보여줍니다:
Layer 1: Signed App Binary
│
├── application-identifier (<Prefix>.<BundleID>)
├── com.apple.developer.team-identifier
└── com.apple.developer.associated-domains (applinks:example.com)
│
▼
Layer 2: AASA Delivery & CDN Ingestion
│ (Apple-managed infrastructure retrieves origin AASA)
▼
Layer 3: AASA Schema & Pattern Matching
│ (Validates appIDs array and components/paths routing rules)
▼
Layer 4: Device Association State
│ (Operating system registers verified domains in local database)
▼
Layer 5: Application Routing Execution
│ (System routes matching URLs to application lifecycle handlers)

빠른 수정 체크리스트: 30초 진단 루틴
유니버설 링크가 예기치 않게 웹 처리 방식으로 폴백되는 경우 다음 항목을 순서대로 확인하세요:
- 서명된 식별자 추출: 컴파일된 바이너리의 임베디드 자격을 검사하여 정확한
application-identifier(<Prefix>.<BundleID>)를 확인합니다. - 자격 형식 확인:
com.apple.developer.associated-domains에 불필요한 경로, 쿼리 문자열 또는 후행 슬래시 없이 정확한 호스트 이름(예:applinks:subdomain.domain.com)이 포함되어 있는지 확인합니다. - 원본 AASA 감사:
https://subdomain.domain.com/.well-known/apple-app-site-association을 가져와서 서명된 애플리케이션 식별자가appIDs에 정확히 나열되어 있는지 확인합니다. - 경로 일치 유효성 검사: 대상 URL이 AASA 설정에 정의된
components또는paths패턴과 일치하는지 확인합니다. - 도메인 범위 확인: 연결된 도메인 자격이 대상 호스트 이름을 포함하고 있으며 해당 호스트 이름에 대한 AASA 설정을 사용할 수 있는지 확인합니다. 서브도메인의 경우, 필요에 따라 명시적인 호스트 이름이나 지원되는
*.와일드카드 형식을 사용하세요. - 개발 모드 격리: 반복 작업 중 Apple CDN 캐싱을 우회하려면 개발 서명 빌드에
?mode=developer를 사용하세요.
Bundle ID 및 애플리케이션 식별자 정확도가 중요한 이유
애플리케이션 식별자의 구조
유니버설 링크 검증은 애플리케이션의 표시 이름, 내부 URL 체계 또는 번들 이름을 평가하지 않습니다. applinks.Details에 관한 Apple 문서에 따르면, 보안 모델은 엄격하게 다음과 같이 구조화된 완전한 자격을 갖춘 애플리케이션 식별자에 의존합니다:
항목 설명:
ApplicationIdentifierPrefix: Apple 개발자 계정 설정에 할당된 앱 ID 접두사(예:9JA723G82S). 많은 최신 개발자 계정에서 이 값은 10자리의 팀 ID와 일치하지만, 엔지니어는 두 값이 상호 교환 가능하다고 가정하지 말고 Apple 개발자 포털에서 실제 접두사를 확인해야 합니다.CFBundleIdentifier(Bundle ID): 타겟의 빌드 설정에 정의된 대소문자를 구분하는 역방향 DNS 문자열(예:com.example.mobileapp).
호스팅된 apple-app-site-association (AASA) JSON 파일에서 이 복합 문자열은 appIDs 배열 또는 appID 딕셔너리 항목 내에 나타납니다(예: 9JA723G82S.com.example.mobileapp). 컴파일된 바이너리의 임베디드 자격과 호스팅된 AASA 항목 간에 문자 불일치, 대소문자 차이 또는 후행 공백이 있는 경우 도메인 검증이 실패합니다.
Bundle ID 불일치는 통합 트리아주 과정에서 가장 우선순위가 높은 원인 중 하나이지만, 유니버설 링크가 웹으로 폴백될 수 있는 유일한 이유는 아닙니다.
연결된 도메인과 AASA가 양방향 연동을 구축하는 방식
설치된 애플리케이션이 도메인 검증 없이 선언할 수 있는 커스텀 URL 체계와 달리, 유니버설 링크는 안전한 양방향 연동을 구축합니다:
- 앱에서 도메인으로의 선언: 컴파일된 iOS 애플리케이션은 코드 서명에
com.apple.developer.associated-domains자격을 포함하여 특정 웹 도메인에 대한 소유권을 주장함을 선언합니다. - 도메인에서 앱으로의 승인: 웹 도메인은
https://<domain>/.well-known/apple-app-site-association또는https://<domain>/apple-app-site-association에 AASA JSON 파일을 호스팅하여 특정 애플리케이션에 라우팅 권한을 부여함을 확인합니다.
설치 또는 앱 업데이트 중에 운영체제는 도메인에 대해 검색된 AASA 설정과 앱의 서명된 연결된 도메인 자격을 비교하여 검증합니다. 앱 연동에 사용된 애플리케이션 식별자는 AASA 설정에 선언된 해당 식별자와 일치해야 합니다. 식별자가 일치한 후, 요청된 URL은 구성된 components 또는 paths 규칙도 충족해야 합니다.
실패 증상: 식별자 불일치로 인해 웹 폴백이 발생하는 이유
애플리케이션 식별자 불일치가 발생하면 iOS는 일반적으로 애플리케이션 식별자 불일치를 치명적인 런타임 예외로 표시하지 않습니다. 대신 이 실패는 연결된 도메인 검증 상태, 기기 진단 또는 결과적인 웹 폴백 동작에 반영됩니다:
- 시스템 처리: 도메인 연동이 실패하면 시스템은 검증된 유니버설 링크 경로를 통해 앱을 호출하지 않습니다. URL이 열린 방식과 주변 브라우저 컨텍스트에 따라, URL은 네이티브 애플리케이션으로 전달되는 대신 웹 처리 상태로 유지되거나 웹으로 폴백됩니다.
- 사용자 경험 영향: 사용자가 메시지, 메일 또는 Safari에서 일치하는 웹 링크를 탭할 때 시스템이 승인된 네이티브 앱 매핑을 인식하지 못하고 브라우저에서 웹 URL을 엽니다.
참조: Bundle ID ──> 유니버설 링크 아키텍처
Apple의 CDN이 AASA 파일을 가져오고 캐시하는 방식
설치 핸드셰이크 및 Apple CDN 메커니즘
com.apple.developer.associated-domains 자격을 포함하는 애플리케이션이 설치되거나 업데이트될 때, 시스템은 연결된 도메인 관계를 설정하거나 새로 고칩니다:
- CDN 중개 스크레이퍼: 시스템이 연결된 도메인 관계를 설정하거나 새로 고칠 때, Apple의 연결된 도메인 인프라를 통해 도메인의 AASA 데이터를 가져오고 해당 데이터를 사용하여 연동을 검증합니다.
- 독립적인 캐싱 수명 주기: Apple이 관리하는 CDN은 자체 새로 고침 및 캐싱 수명 주기를 제어하므로 원본 업데이트가 CDN을 통해 즉시 표시된다고 가정해서는 안 됩니다. 변경 사항을 테스트할 때는 적절한 경우 문서화된 개발 대체 모드를 사용하고 기기 연동 상태를 검사하세요.
- 원본 서버 요구 사항: 원본 웹 서버는
application/jsonMIME 형식을 사용하여 유효하고 신뢰할 수 있는 TLS 인증서(자체 서명된 인증서는 거부됨)와 함께 HTTPS를 통해 AASA 파일을 제공해야 합니다. AASA 호스팅은 HTTP 리디렉션에 의존해서는 안 되며, AASA 엔드포인트는 HTTP 200 OK와 함께 파일을 직접 반환해야 합니다.
AASA JSON 형식 일관성
최신 iOS 버전은 레거시 paths 배열과의 하위 호환성을 유지하면서 세분화된 components 딕셔너리 구문을 지원합니다.
유니버설 링크 디버깅에 관한 Apple 개발자 기술 노트 TN3155에 따르면, 특정 details 항목 내에서 개발자는 최신 appIDs + components 구조 또는 레거시 appID + paths 구조를 사용해야 하며, 혼합된 구성은 예상치 못한 검증 동작을 유발할 수 있으므로 동일한 항목에서 두 구조를 혼용해서는 안 됩니다.
이전 AASA 예제에는 일반적으로 "apps": []가 포함되어 있었습니다. 최신 Apple OS 릴리스를 타겟팅하는 배포의 경우 이 키는 필수가 아니며, 이를 특별히 요구하는 레거시 OS 버전을 지원하는 경우에만 유지하세요.
진단 프로토콜: 단계별 해결 워크플로
1단계: codesign을 사용하여 서명된 앱 자격 검사
내보낸 IPA 또는 디버그 빌드에 정확히 예상되는 애플리케이션 식별자와 연결된 도메인이 포함되어 있는지 확인하려면 macOS codesign 명령줄 유틸리티를 사용하여 바이너리의 코드 서명을 직접 검사합니다. application-identifier, com.apple.developer.team-identifier, com.apple.developer.associated-domains를 함께 확인하세요.
프로비저닝 프로필은 프로필이 허용하는 기능과 도메인을 보여주며, 서명된 실행 파일(codesign)은 배포된 바이너리에 실제로 포함된 내용을 보여줍니다.
2단계: 호스팅된 AASA JSON 스키마 감사
원본 서버가 인증이나 리디렉션 없이 공개적으로 액세스할 수 있는 유효한 AASA 파일을 호스팅하고 있는지 확인합니다. 이전 AASA 예제에는 일반적으로 "apps": []가 포함된 반면, 현대의 최신 iOS릴리스를 타겟팅하는 구성은 이 키를 생략한다는 점에 유의하세요.
아래 표준 AASA JSON 스키마는 최신 appIDs 및 components 구조를 사용한 올바른 경로 라우팅을 보여줍니다:
```json
{
"applinks": {
"details": [
{
"appIDs": [
"9JA723G82S.com.example.mobileapp",
"9JA723G82S.com.example.mobileapp.staging"
],
"components": [
{
"/": "/product/*",
"comment": "Matches product detail routes"
},
{
"/": "/invite/*",
"?": { "ref": "?*" },
"comment": "Matches referral links with custom query parameters"
},
{
"/": "/help/*",
"exclude": true,
"comment": "Excludes customer support URLs from native routing"
}
]
}
]
}
}
3단계: 진단 CLI 도구 실행 (codesign, swcutil, curl)
swcutil 진단을 제공하는 macOS 버전에서는 해당 도구를 사용하여 연결된 도메인 데이터를 검사하거나 유효성을 검사합니다. 명령 옵션은 OS 및 도구 체인 릴리스에 따라 다를 수 있으므로, 아래 진단 워크플로를 실행하기 전에 swcutil --help를 통해 사용 가능한 옵션을 확인하세요:
# 0. Confirm available options (syntax may vary by OS and toolchain release)
swcutil --help
# 1. Unpack the exported IPA archive
unzip -q YourApp.ipa -d UnpackedApp
# 2. Extract and inspect signed entitlements directly from the executable binary
codesign -d --entitlements :- "UnpackedApp/Payload/YourApp.app" > signed-entitlements.plist 2>/dev/null
/usr/libexec/PlistBuddy -c "Print" signed-entitlements.plist
# 3. Check whether the AASA data can be downloaded for the domain using swcutil (macOS diagnostic tool)
sudo swcutil dl -d custom.opwakeup.com
# 4. Validate AASA pattern matching against a specific URL using swcutil
sudo swcutil verify -d custom.opwakeup.com -j ./apple-app-site-association -u https://custom.opwakeup.com/product/123
# 5. Query the Apple-managed Associated Domains CDN diagnostic endpoint directly
curl -i https://app-site-association.cdn-apple.com/a/v1/custom.opwakeup.com
에지(Edge)에서 전달되는 AASA 데이터를 트러블슈팅할 때는 Apple이 관리하는 연결된 도메인 CDN 엔드포인트를 검사하세요. 이 엔드포인트는 공개 API 계약이라기보다는 진단 인프라로 취급해야 합니다.
4단계: AASA 테스트를 위해 연결된 도메인 개발 모드 사용
연결된 도메인 구성에 관한 Apple 문서에 따르면, Apple은 개발을 위한 대체 모드를 제공합니다. developer 모드(?mode=developer)를 사용하면 적격한 개발 기기가 Apple이 관리하는 CDN을 우회하고 HTTPS를 통해 연결된 도메인에서 직접 AASA 파일을 가져올 수 있습니다.
아래 구성은 별도의 Xcode 자격 구성에서 개발 모드를 선언하는 방법을 보여줍니다:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>com.apple.developer.associated-domains</key>
<array>
<string>applinks:custom.opwakeup.com</string>
</array>
</dict>
</plist>
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>com.apple.developer.associated-domains</key>
<array>
<string>applinks:custom.opwakeup.com?mode=developer</string>
</array>
</dict>
</plist>
운영체제가 도메인 연동을 설정하면 애플리케이션 수준 라우팅은 표준 UIKit 또는 SwiftUI 수명 주기 대리자를 사용하여 들어오는 URL 페이로드를 처리합니다:
import UIKit
// ----------------------------------------------------------------------------
// 1. UIKit AppDelegate Implementation
// ----------------------------------------------------------------------------
@main
class AppDelegate: UIResponder, UIApplicationDelegate {
var window: UIWindow?
func application(
_ application: UIApplication,
didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
) -> Bool {
return true
}
// Standard Apple Universal Link Continuation Callback
func application(
_ application: UIApplication,
continue userActivity: NSUserActivity,
restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void
) -> Bool {
guard userActivity.activityType == NSUserActivityTypeBrowsingWeb,
let incomingURL = userActivity.webpageURL else {
return false
}
print("Handling verified Universal Link: \(incomingURL.absoluteString)")
// Dispatch incomingURL to internal router or SDK layer for parameter extraction
return handleIncomingRoute(incomingURL)
}
private func handleIncomingRoute(_ url: URL) -> Bool {
// Application-level destination routing logic
// Note: Returning true indicates the app handled the activity, not that URL parsing succeeded.
return true
}
}
// ----------------------------------------------------------------------------
// 2. SceneDelegate Lifecycle Implementation (iOS 13+)
// ----------------------------------------------------------------------------
class SceneDelegate: UIResponder, UIWindowSceneDelegate {
var window: UIWindow?
func scene(_ scene: UIScene, willConnectTo session: UISceneSession, options connectionOptions: UIScene.ConnectionOptions) {
if let userActivity = connectionOptions.userActivities.first(where: { $0.activityType == NSUserActivityTypeBrowsingWeb }),
let incomingURL = userActivity.webpageURL {
print("Cold-launch Universal Link: \(incomingURL.absoluteString)")
}
}
func scene(_ scene: UIScene, continue userActivity: NSUserActivity) {
if userActivity.activityType == NSUserActivityTypeBrowsingWeb,
let incomingURL = userActivity.webpageURL {
print("Foreground Universal Link: \(incomingURL.absoluteString)")
}
}
}
실물 하드웨어에서 클라이언트 측 개발 모드를 활성화하려면:
- iOS 16 이상에서 설정 > 개인정보 보호 및 보안 > 개발자 모드(Developer Mode)로 이동하여 켜기로 전환합니다(기기 재부팅 필요).
- 설정 > 개발자(Developer) > 연결된 도메인 개발(Associated Domains Development)으로 이동하여 스위치를 켭니다.
?mode=developer자격이 포함된 개발 프로비저닝 프로필로 서명된 개발 빌드를 설치합니다.- 배포 참고 사항:
?mode=developer는 개발 및 내부 테스트 구성으로만 제한하고, 배포 시 해당 구성을 명시적으로 요구하고 지원하는 경우가 아니라면 프로덕션 연결된 도메인 자격에 포함하지 마세요.
근본 원인 결정 트리
Universal Link falls back to web handling
│
├── Does signed application-identifier match AASA appIDs?
│ ├── NO ──> Correct App ID Prefix or Bundle ID in AASA
│ └── YES
│
├── Does associated-domains entitlement list the exact domain?
│ ├── NO ──> Add applinks:<domain> to target entitlements
│ └── YES
│
├── Does sudo swcutil dl -d <domain> succeed?
│ ├── NO ──> Fix origin HTTPS, TLS certificates, or 301/302 redirects
│ └── YES
│
├── Does sudo swcutil verify match the target URL path?
│ ├── NO ──> Correct components or paths syntax in AASA
│ └── YES
│
└── Check device association state and internal application routing handlers

진단 매트릭스: 유니버설 링크 실패의 근본 원인
| 실패 모드 | 기저의 근본 원인 | 관찰된 시스템 동작 | 권장 조치 |
|---|---|---|---|
| Bundle ID 오타 | AASA appIDs의 대소문자 구분 또는 문자 불일치 |
링크가 네이티브 앱 대신 브라우저를 엽니다. | AASA JSON의 문자열을 수정하고 원본에 다시 배포합니다. |
| App ID 접두사 불일치 | 실제 개발자 앱 ID 접두사 대신 잘못된 접두사 사용 | 설치 중 도메인 연동이 실패합니다. | Apple 회원 센터에서 애플리케이션 식별자 접두사를 확인합니다. |
| 서브도메인 불일치 | 자격은 www.example.com을 가리키는데 AASA는 example.com에 있음 |
앱이 서브도메인의 링크를 클레임하지 못합니다. | 클레임된 각 서브도메인에 전용 AASA 파일을 호스팅하거나 와일드카드를 구성합니다. |
| 엔드포인트의 HTTP 리디렉션 | 원본 서버가 AASA URL에 대해 301 또는 302 리디렉션을 반환함 | Apple CDN 스크레이퍼가 AASA 파일을 거부합니다. | 웹 서버가 200 OK를 직접 반환하도록 구성합니다. |
| AASA 형식 불일치 | 레거시 appID/paths와 현대의 appIDs/components 혼용 |
일관성 없거나 부분적인 경로 일치 발생 | 최신 appIDs + components 구문으로 표준화합니다. |
| URL 패턴 불일치 | AASA는 성공적으로 다운로드되지만 요청된 URL이 패턴과 일치하지 않음 | 링크가 웹 브라우저에서 열립니다. | swcutil verify를 사용하여 경로 구문과 구성 요소를 확인합니다. |
| 릴리스에 남아 있는 개발 모드 | 배포 빌드가 개발 대체 모드를 유지함 | 배포 빌드의 비표준 자격 | 릴리스 빌드 구성에서 ?mode=developer를 제거합니다. |

Xcode에서 이중 환경 구성 구현하기
다중 빌드 구성 관리 (Debug, Staging, Production)
엔터프라이즈 개발 파이프라인은 빌드 환경(예: com.example.app.debug, com.example.app.staging, com.example.app)에 따라 서로 다른 Bundle ID를 관리하는 경우가 많습니다.
모든 빌드 구성에서 유니버설 링크가 정상적으로 작동하도록 유지하려면:
-
명시적 AASA 선언: 호스팅된 AASA 파일은
appIDs배열에 각 환경의 완전한 자격을 갖춘 애플리케이션 식별자를 명시적으로 나열해야 합니다:"appIDs": [ "9JA723G82S.com.example.app", "9JA723G82S.com.example.app.staging", "9JA723G82S.com.example.app.debug" ] -
타겟별 자격: Xcode 빌드 구성Settings를 사용하여 빌드 구성당 개별
.entitlements파일을 연결하고, 내부 디버그 빌드가 프로덕션 도메인을 쿼리하지 않도록 합니다.
타겟 식별자 관리
유니버설 링크 트러블슈팅을 위해서는 와일드카드 식별자에 의존하는 대신 서명된 빌드의 정확한 Bundle ID와 애플리케이션 식별자 접두사를 사용하세요. 각 호스트 이름을 명시적으로 처리합니다. 앱이 example.com 및 www.example.com을 클레임하는 경우 해당되는 연결된 도메인 항목을 구성하고 각 호스트 이름이 적절한 AASA 데이터를 제공하는지 확인하세요. 유니버설 링크를 실제로 처리하는 타겟에 자격이 구성되어 있는지 확인하고, 해당하는 경우 앱 확장(App Extension) 또는 watchOS 타겟을 별도로 확인하세요.
CI/CD에서 임베디드 프로비저닝 프로필 및 서명된 바이너리 유효성 검사
TestFlight에 바이너리를 업로드하기 전에 지속적 통합(CI) 빌드 스크립트 내에서 자격 및 애플리케이션 식별자 검증을 자동화합니다:
# Automated CI validation script
security cms -D -i /path/to/embedded.mobileprovision > provision.plist
# 1. Inspect profile entitlements for allowed Associated Domains
/usr/libexec/PlistBuddy -c "Print :Entitlements:com.apple.developer.associated-domains" provision.plist
# 2. Extract actual signed entitlements from the compiled executable binary
codesign -d --entitlements :- "UnpackedApp/Payload/YourApp.app" > signed-entitlements.plist 2>/dev/null
SIGNED_APP_ID=$(/usr/libexec/PlistBuddy -c "Print :application-identifier" signed-entitlements.plist)
echo "Extracted Signed Application Identifier: $SIGNED_APP_ID"
# 3. Validate that signed Associated Domains match the target domain
/usr/libexec/PlistBuddy -c "Print :com.apple.developer.associated-domains" signed-entitlements.plist
# 4. Verify that the signed App ID exists in the hosted AASA file via Python
python3 -c "
import json, sys
signed_id = sys.argv[1]
data = json.load(open('apple-app-site-association'))
app_ids = [app for detail in data.get('applinks', {}).get('details', []) for app in detail.get('appIDs', [])]
if signed_id not in app_ids:
print(f'AASA mismatch: {signed_id} not found in AASA appIDs: {app_ids}')
sys.exit(1)
print(f'AASA consistency check passed: {signed_id} registered')
" "$SIGNED_APP_ID"
검증 스크립트가 오류 코드로 종료되면 빌드 파이프라인을 중단하여 프로덕션에 작동하지 않는 딥 링크 바이너리가 배포되는 것을 방지합니다.

유니버설 링크 일치 기준
안정적인 라우팅을 보장하려면 다음 조건을 동시에 충족해야 합니다:
Signed App Configuration:
application-identifier = <ApplicationIdentifierPrefix>.<CFBundleIdentifier>
com.apple.developer.associated-domains = applinks:<hostname>
AASA Configuration:
appIDs = [..., "<ApplicationIdentifierPrefix>.<CFBundleIdentifier>", ...]
components / paths = Matching target URL paths and query parameters
System Eligibility:
1. Associated Domains entitlement explicitly contains the target hostname.
2. The signed Application Identifier matches an authorized entry in the domain's AASA appIDs.
3. The incoming URL satisfies the AASA routing patterns.
4. Device association state and user/browser context permit native application delegation.
자격, AASA 연동 및 URL 패턴이 모두 일치하더라도 관찰된 라우팅은 여전히 기기 상태와 사용자 또는 브라우저 컨텍스트에 따라 다를 수 있습니다. 예를 들어 사용자가 Safari에서 동일한 도를 이미 브라우징하는 동안 유니버설 링크를 탭하면 운영체제는 Safari에 머무르려는 사용자의 의도를 존중할 수 있습니다.
자주 묻는 질문 (FAQ)
AASA 파일에서 애플리케이션 식별자의 정확한 형식은 무엇인가요?
유니버설 링크가 개발 모드에서는 작동하지만 프로덕션에서는 실패하는 이유는 무엇인가요?
AASA appIDs 배열에 와일드카드 별표를 사용할 수 있나요?
요약 및 결정 프레임워크
유니버설 링크 라우팅 안정성은 Apple 개발자 포털 앱 ID 구성, Xcode com.apple.developer.associated-domains 자격, 그리고 호스팅된 apple-app-site-association JSON 파일 등 세 가지 노드 전반의 정확하고 문자 단위의 일치 여부에 따라 달라집니다. 타사 SDK나 라우팅 프레임워크는 실패한 운영체제 도메인 연동을 복구할 수 없으며, iOS가 유니버설 링크를 애플리케이션에 성공적으로 전달한 후에만 URL을 처리할 수 있습니다. 운영체제 수준에서 유니버설 링크가 올바르게 연동되었음에도 매개변수 추출이 실패하는 경우, 도메인 연동 레이어와는 별개로 애플리케이션 수준 라우팅 레이어를 검사하세요.
유니버설 링크 연동 성공 후 애플리케이션에 동적 링크 매개변수 복원 및 온보딩 라우팅도 필요한 경우, OpoInstall은 해당 애플리케이션 수준 워크플로를 위한 선택적 SDK 레이어를 제공합니다.
도메인 구성 패턴 및 딥 링크 통합에 대해 자세히 알아보려면 OpoInstall 딥 링크 문서를 검토하세요.
관련 자료
-
개념: 애플리케이션 식별자 검증, AASA 스키마 유효성 검사, Apple CDN 캐싱, 자격 추출
-
기술: iOS 유니버설 링크, Xcode 자격, Apple 개발자 포털, 공유 웹 자격 증명(Shared Web Credentials)
-
표준: IETF RFC 8259 (JSON 데이터 교환), TLS 1.3 사양
-
진단 도구: Apple
codesignCLI 도구, macOSswcutil도구, Apple 관리 CDN 캐시 쿼리
공식 문서
Share this article



