텔레그램 미니앱 딥링크가 홈으로만 열렸다

버튼을 누르면 홈 메뉴가 떴다. 오류는 없었다. 앱은 정상적으로 열렸고 화면 지정만 무시됐다.

커뮤니티용 텔레그램 봇에는 채팅 버튼으로 여는 미니앱(Web App)이 붙어 있다. 봇의 한 명령은 답변에 미니앱 버튼을 붙여 주는데, 이 버튼은 미니앱의 홈 말고 그 명령에 해당하는 화면을 바로 열어야 한다. 2026년 7월 말에 그게 안 됐다. 원인을 찾아 고쳐서 배포했는데 사용자 쪽에서는 그대로였다. 원인이 두 개였고 서로 관계가 없었다.

해시에 텔레그램 파라미터가 같이 붙어 왔다

화면 지정은 URL 프래그먼트로 넘기고 있었다. 버튼 URL 뒤에 #화면키를 붙이고, 미니앱은 시작할 때 location.hash를 읽어 그 화면을 연다. 단일 페이지 앱에서 흔한 방식이고 브라우저에서 URL을 직접 열면 잘 동작한다.

텔레그램 안에서는 다르다. 텔레그램 클라이언트는 미니앱을 열 때 tgWebAppData, tgWebAppVersion 같은 자기 launch 파라미터를 URL 해시로 전달한다. 내가 붙인 조각은 그 파라미터와 한데 붙어서 도착했다.

#화면키&tgWebAppData=query_id%3D...&tgWebAppVersion=7.0&tgWebAppPlatform=ios

앱은 #만 떼어 낸 문자열 전체를 화면 키와 비교했다. 일치하는 키가 없으니 아무 화면도 열지 않았고, 밑에 깔려 있던 홈이 그대로 보였다. 일치하지 않으면 조용히 홈에 머무는 구조라 오류로 드러나지도 않았다.

쿼리로 옮기고, 옛 버튼도 계속 읽는다

화면 지정을 프래그먼트에서 쿼리 파라미터로 옮겼다. 내 환경에서는 버튼 URL의 쿼리 문자열이 그대로 전달됐다.

# before
url = f"{PUBLIC_URL}#{screen}" if screen else PUBLIC_URL
# after
url = f"{PUBLIC_URL}?d={screen}" if screen else PUBLIC_URL

앱 쪽은 쿼리를 먼저 읽는다. 그걸로 끝낼 수는 없었다. 채팅방에는 이전에 봇이 보낸 메시지가 남아 있고, 거기 달린 버튼은 여전히 옛 #화면키 형태의 URL을 갖고 있다. 이미 뿌려진 버튼을 봇이 일괄로 바꿀 수는 없어서, 앱이 옛 형태도 계속 읽게 했다.

function wantedScreen() {
  // 쿼리가 우선: 텔레그램은 쿼리를 건드리지 않는다.
  const q = new URLSearchParams(location.search).get("d");
  if (q) return q.trim();
  // 채팅에 남은 옛 버튼은 해시 형태다. 첫 조각만 읽고,
  // "=" 를 품은 조각은 텔레그램 파라미터이므로 지정 없음으로 본다.
  const first = (location.hash || "").replace(/^#/, "").split(/[&?]/)[0].trim();
  return first.includes("=") ? "" : first;
}

해시는 구분자로 잘라 첫 조각만 취한다. 뒤에 텔레그램 파라미터가 붙어 있어도 내 조각만 남는다. 그리고 첫 조각에 =가 들어 있으면 버린다. 화면 지정 없이 연 경우에는 해시의 첫 조각이 tgWebAppData=...인데, 화면 키에는 =가 들어갈 일이 없으니 이걸 화면 키로 오해하지 않는다.

이 함수에는 Node로 돌리는 테스트를 붙였다. app.js는 브라우저용 단일 스크립트라 통째로 불러올 수 없어서, 소스에서 이 함수만 정규식으로 떼어 내 가짜 location 객체를 넣고 실행한다. 쿼리 형태, 텔레그램 해시가 같이 붙은 쿼리 형태, 옛 해시 형태, 텔레그램 파라미터만 있는 해시를 각각 확인한다.

배포했는데 그대로였다

딥링크 처리를 고쳐서 재배포했다. 사용자에게는 고치기 전의 동작이 계속 나왔다.

미니앱은 aiohttp 서버가 서비스하고 그 앞에 Cloudflare가 있다. 정적 파일의 응답 헤더를 보니 엣지 캐시에서 나온 것으로 표시되고 있었다.

cf-cache-status: HIT

Cloudflare는 .js, .css 같은 정적 파일 확장자를 기본으로 캐시한다. 내 환경에서는 /static/ 아래 파일이 4시간 동안 캐시됐다. 재배포로 원본 서버의 app.js가 바뀌어도 URL이 같으니 엣지는 가지고 있던 옛 파일을 계속 내줬다. 셸인 index.html은 DYNAMIC으로 표시됐다. 캐시되지 않고 매번 원본에서 온다는 뜻이다.

딥링크만의 문제도 아니었다. 앱의 JS와 그것이 호출하는 API가 한 번의 배포로 같이 바뀌는데, 사용자에게는 몇 시간 동안 옛 JS와 새 API의 조합이 나갈 수 있다.

캐시는 그대로 두고 에셋 URL을 바꿨다

셸 HTML을 내보낼 때 에셋 경로에 파일 내용의 해시를 쿼리로 붙인다.

def _asset_version() -> str:
    h = hashlib.sha256()
    for name in ("app.js", "styles.css"):
        path = STATIC_DIR / name
        if path.exists():
            h.update(path.read_bytes())
    return h.hexdigest()[:10]

async def _index(request):
    html = (STATIC_DIR / "index.html").read_text(encoding="utf-8")
    v = request.app.get("asset_version", "")
    for name in ("app.js", "styles.css"):
        html = html.replace(f"/static/{name}", f"/static/{name}?v={v}")
    return web.Response(text=html, content_type="text/html",
                        headers={"Cache-Control": "no-store"})

버전은 서버가 뜰 때 한 번 계산해서 앱 상태에 넣어 둔다. 파일 내용이 바뀌면 해시가 바뀌고 셸이 가리키는 에셋 URL이 바뀐다. 엣지 입장에서는 본 적 없는 URL이라 원본에서 새로 가져간다. 내용이 그대로면 해시도 그대로라서 에셋을 건드리지 않은 배포에서는 캐시가 유지된다. 배포 시각이나 빌드 번호 대신 내용 해시를 쓴 이유다.

셸이 캐시되면 전부 의미가 없어진다. 옛 버전 번호를 계속 가리키기 때문이다. 그때 index.html은 캐시되지 않고 있었지만, 그 동작에 기대지 않고 응답에 Cache-Control: no-store를 명시했다.

테스트로 고정한 성질은 셋이다. 같은 내용이면 같은 버전이 나오고 내용이 바뀌면 버전이 바뀐다. 셸에 버전 없는 에셋 참조가 남지 않는다. 셸 응답이 no-store다. 내용을 바꿔 보는 검사는 실제 소스를 건드리지 않고 임시 디렉터리에 복사한 파일로 한다.

다음에 배포가 반영되지 않으면 코드를 다시 열기 전에 cf-cache-status부터 본다.