Firebase Dynamic Links 종료 대응과 자체 링크 라우팅 서버 구축 방법

Firebase Dynamic Links가 종료되면 예전에 만든 page.link 주소가 더 이상 앱 실행 경로를 보장하지 않습니다. QR 코드, 문자, 카카오톡 공유 링크를 오래 뿌려 둔 서비스라면 미리 자체 링크 서버로 바꿔야 합니다.

실제 문제 상황

앱 딥링크는 단순히 앱을 여는 주소가 아닙니다. iOS는 유니버설 링크용 apple-app-site-association 파일을 확인하고, Android는 앱 링크 검증 정보를 봅니다. 앱이 없으면 웹 fallback이나 스토어로 보내는 규칙도 같이 필요합니다.

기존 공유 링크가 이미 배포됐다면 종료일 전에 대체 주소를 먼저 준비해야 합니다.

이전에 아이폰 탈옥 없이 듀얼 카카오톡 설치하기에서 iOS 앱 설치 경로를 다뤘다면, 이번에는 이미 배포된 공유 링크를 앱 진입 경로와 다시 연결하는 작업입니다.

적용 대상

• 예전 Firebase Dynamic Links 주소를 QR, 문자, 카카오톡 공유에 사용한 경우.
• iOS 유니버설 링크와 Android 앱 링크를 직접 운영해야 하는 경우.
• 앱 미설치 사용자를 스토어나 웹 랜딩으로 보내야 하는 경우.
• 내부 테스트용 링크만 쓰는 작은 프로젝트는 우선순위가 낮습니다.

사전 준비 사항

• 링크용 도메인: 예시는 link.example.com으로 둡니다.
• iOS Team ID와 Bundle ID.
• Android package name과 SHA-256 certificate fingerprint.
• Nginx나 Caddy 같은 정적 파일 제공 서버.

설치 절차

먼저 /.well-known/apple-app-site-association 파일을 준비합니다. iOS는 확장자 없는 JSON 파일을 기대하므로 Content-Type: application/json으로 내려주시면 됩니다.

{
  "applinks": {
    "apps": [],
    "details": [
      {
        "appIDs": ["<TEAM_ID>.com.example.app"],
        "components": [
          { "/": "/p/*", "comment": "product deep link" },
          { "/": "/share/*", "comment": "share deep link" }
        ]
      }
    ]
  }
}

Android는 /.well-known/assetlinks.json에 앱 서명 정보를 넣습니다.

[
  {
    "relation": ["delegate_permission/common.handle_all_urls"],
    "target": {
      "namespace": "android_app",
      "package_name": "com.example.app",
      "sha256_cert_fingerprints": ["<SHA256_FINGERPRINT>"]
    }
  }
]

1. 자체 링크 라우팅

link.example.com/p/123처럼 짧은 주소를 받으면 서버에서 앱 진입 정보와 fallback 주소를 함께 결정합니다. 앱이 열리지 않는 브라우저에서는 웹 랜딩을 보여주고, 설치가 필요한 경우에는 스토어 버튼을 표시합니다.

카카오톡 공유는 executionParams 값을 같이 넣어야 앱에서 어느 화면을 열지 알 수 있습니다. 공유 메시지에는 긴 원본 URL 대신 자체 링크 주소만 넣어주시면 됩니다.

1.1. Nginx 설정 예시

아래처럼 .well-known 파일은 리다이렉트 없이 바로 내려야 합니다.

server {
    server_name link.example.com;

    location /.well-known/apple-app-site-association {
        default_type application/json;
        root /var/www/link.example.com;
    }

    location /.well-known/assetlinks.json {
        default_type application/json;
        root /var/www/link.example.com;
    }

    location / {
        proxy_pass http://127.0.0.1:8080;
    }
}

주요 오류 및 해결 방안

제 경우 원인은 대부분 AASA 파일을 리다이렉트 뒤에 둔 점이었습니다. iOS는 /.well-known/apple-app-site-association 요청에서 301이나 HTML 응답을 만나면 링크 검증이 깨질 가능성이 높습니다. 해당 경로만큼은 인증, 리다이렉트, HTML 템플릿을 빼고 바로 JSON을 내려주는 편이 안전합니다.

확인

curl -I https://link.example.com/.well-known/apple-app-site-association
curl https://link.example.com/.well-known/assetlinks.json

첫 명령에서 200과 application/json이 보이고, 두 번째 명령에서 package name과 fingerprint가 출력되면 기본 검증 파일 제공은 정상입니다.