클라우드 Mac에서 Universal Links 연결 파일 점검하기

출시 브랜치의 상품 링크는 브라우저에서 정상적으로 열리는데, 테스트 기기에 App을 설치하고 나면 계속 웹페이지로만 열릴 때가 있습니다. 이때 곧바로 App의 링크 처리 코드를 수정하면 실제 문제 지점을 놓치기 쉽습니다. 기기는 먼저 도메인이 제공하는 연결 파일을 가져와 해당 도메인이 지정된 App에 관련 경로의 처리를 허용하는지 확인해야 합니다. 클라우드 Mac에서 파일 전달 경로를 먼저 점검한 뒤 기기에서 다시 테스트하세요. 서버와 기기에서 확인한 증거를 따로 기록하는 편이 링크를 반복해서 누르는 것보다 효과적입니다.

실패 사례 하나를 먼저 확정하기

전체 링크, 열려야 하는 App, 실제로 열린 방식, 기기의 OS 버전, App 빌드 버전을 기록합니다. 링크는 최소 두 개 준비하세요. 하나는 App에서 열려야 하고, 다른 하나는 웹페이지에 남아 있어야 합니다. “모든 링크가 안 된다”라고만 적지 마세요. 도메인, 경로, 쿼리 매개변수에 따라 전혀 다른 규칙이 적용될 수 있습니다.

테스트 방법도 확인해야 합니다. 클릭 가능한 링크를 눌러 들어가는 것과 브라우저 주소창에 URL을 직접 입력하는 것은 같은 검증 방법이 아닙니다. 팀에서 재현 테스트를 할 때는 동일한 진입 방식을 사용하세요. 프로덕션과 사전 출시 환경의 도메인이 다르다면 기록도 각각 작성해야 합니다. 한 도메인의 파일로 다른 도메인에서 나타난 현상을 설명할 수는 없습니다.

“서버가 지금 무엇을 반환하는가”와 “이 기기가 지금 링크를 어떻게 여는가”를 별도 열에 기록하세요. 전자는 바로 다시 확인할 수 있지만, 후자는 설치 상태와 캐시의 영향을 받을 수 있습니다.

파일이 리디렉션 없이 제공되는지 확인하기

클라우드 Mac의 터미널에서 팀이 실제로 관리하는 도메인을 설정하세요. App 번들 식별자를 도메인으로 입력하면 안 됩니다. 연결 파일은 /.well-known/apple-app-site-association에서 직접 가져올 수 있어야 합니다. 확인 명령이 리디렉션을 자동으로 따라가게 하지 마세요. 리디렉션 이후의 성공 응답을 파일이 직접 제공된 것으로 오인하기 쉽습니다.

export APP_DOMAIN='填入团队实际控制的域名'
test "$APP_DOMAIN" != '填入团队实际控制的域名' || exit 1
curl -sS -D aasa-headers.txt \
  -o aasa-body.json \
  "https://${APP_DOMAIN}/.well-known/apple-app-site-association"
cat aasa-headers.txt
wc -c aasa-body.json
plutil -lint -- aasa-body.json

HTTP 상태가 200인지, 로그인 페이지나 다른 경로를 가리키는 Location이 없는지, 본문이 HTML 오류 페이지가 아닌지, Content-Type이 application/json인지 확인합니다. plutil 검사를 통과해도 구문을 파싱할 수 있다는 뜻일 뿐, 규칙이 올바르다는 뜻은 아닙니다. 네트워크 오류로 명령이 종료됐다면 먼저 도메인 이름 확인과 TLS 연결을 점검하세요. 디스크에 남아 있는 예전 aasa-body.json을 이번 요청의 결과로 사용해서는 안 됩니다. 점검 중에는 기존 파일을 삭제한 뒤 다시 실행하고, 응답 헤더와 본문을 함께 보관하면 됩니다.

네트워크 경로 하나만 테스트하지 않기

파일이 캐시나 리버스 프록시를 거친다면 팀에서 평소 사용하는 네트워크와 클라우드 Mac에서 같은 주소를 각각 요청하고, 본문과 응답 헤더의 캐시 정보를 비교하세요. 두 경로의 결과가 다르면 먼저 배포 경로, 캐시 키, 갱신 절차를 확인합니다. 문제를 감추기 위해 캐시 규칙을 전부 완화하지 마세요. 목표는 같은 도메인의 연결 파일이 기대한 내용을 안정적으로 반환하게 하는 것입니다.

식별자와 경로 규칙 대조하기

JSON의 applinks.details에서 해당 항목을 찾아 팀 식별자와 App 번들 식별자로 구성된 appID를 문자 단위로 대조합니다. 그런 다음 실패한 링크의 URL 경로를 규칙에 하나씩 적용해 보세요. 경로의 대소문자 구분, 끝의 슬래시 유무, 제외 규칙이 포괄적인 규칙보다 먼저 영향을 미치는지 여부는 파일에서 실제로 사용하는 규칙 형식에 따라 각각 검증해야 합니다. 웹 라우트에 접속할 수 있다는 이유만으로 App이 링크를 처리할 수 있다고 추정하지 마세요.

쿼리 매개변수는 App이 열린 뒤 콘텐츠를 찾는 데 도움이 될 수 있지만, URL 경로의 규칙 일치 여부를 확인하는 작업을 대신할 수는 없습니다. 팀이 기존 paths에서 components로 이전 중이라면 먼저 대상 기기의 OS가 사용하는 형식을 지원하는지 확인하고, 실제 테스트 링크로 검증하세요. 비교할 테스트 사례 없이 식별자, 규칙, App 코드를 한꺼번에 바꾸지 마세요.

빌드 산출물과 기기 확인하기

서버 파일이 올바르다면 App 빌드에 설정된 연결 도메인을 확인합니다. 도메인 항목은 실제로 파일을 제공하는 호스트 이름을 가리켜야 합니다. 서로 다른 하위 도메인을 기본적으로 동일하게 취급해서는 안 됩니다. 기기에 설치된 App이 방금 확인한 빌드 버전인지, 다른 출시 브랜치의 패키지는 아닌지 확인하세요. 설정을 수정했다면 반드시 다시 빌드해 설치해야 합니다. 서버 파일만 갱신해서는 이미 설치된 App의 설정이 바뀌지 않습니다.

테스트 기기에 “수정 전” 결과를 남긴 다음 새 빌드를 설치하고, 이전과 같은 출처에서 같은 링크를 클릭하세요. 서버는 새 규칙을 반환하는데 기기에서는 여전히 이전과 같이 동작한다면 App을 재설치한 뒤 다시 테스트하고 두 결과를 모두 기록할 수 있습니다. 연결 파일을 가져오고 검증하는 과정이 즉시 완료된다고 가정하지 마세요. 한 번 클릭한 결과만으로 서버 수정이 효과 없었다고 단정해서는 안 됩니다.

한꺼번에 재시도하지 말고 경계별로 원인 찾기

파일을 가져올 수 없거나 리디렉션이 반환되면 파일 전달 경로를 처리합니다. 파일은 가져오지만 식별자나 경로가 맞지 않으면 규칙 또는 빌드 설정을 처리합니다. 둘 다 맞는데 특정 기기 한 대에서만 실패한다면 설치 이력, 기기 버전, 링크를 클릭한 위치를 비교하세요. 한 번에 한 계층만 수정하고, 수정 전후의 응답 헤더, 파일 본문, 빌드 식별자, 기기에서 관찰한 결과를 보관해야 어떤 변경이 효과를 냈는지 확인할 수 있습니다.

출시 절차에 점검 포함하기

출시 작업에 간단한 점검을 추가할 수 있습니다. 프로덕션 도메인의 연결 파일을 요청해 리디렉션이 없는지, 상태가 올바른지, JSON을 파싱할 수 있는지 확인하고, App에서 열려야 하는 경로 하나와 열리지 않아야 하는 경로 하나로 규칙을 검증합니다. 자동 점검으로 확인할 수 있는 것은 서버와 정적 설정까지입니다. 기기에서 “클릭한 뒤 어디에서 열리는가”는 빌드를 설치한 뒤 별도로 검증해야 합니다.

마지막으로 실패 사례, 실제 응답, 일치하는 규칙, 기기 재테스트 결과를 한 기록에 모아 두세요. 다음에 “웹페이지는 열리는데 App은 열리지 않는다”는 문제가 생기면 담당자가 링크 코드와 캐시 중 무엇이 원인인지 추측하기보다, 가장 최근에 검증을 통과한 지점부터 점검을 이어갈 수 있습니다.

자주 묻는 질문