dev.to

Integrating SEO Components into Discord

Discord 링크 미리보기에 컴포넌트 임베드 적용하기

Discord가 Open Graph 미리보기를 대체하는 컴포넌트 임베드를 지원합니다. 글쓴이는 서버에서 생성한 JSON으로 제목, 이미지 갤러리, 버튼을 구성하고 Astro 블로그에 적용하는 절차와 크롤링 조건, 제한 사항을 정리합니다.

에디터 노트

이 방식의 장점은 풍부한 미리보기를 추가하면서 기존 OG 미리보기를 그대로 남긴다는 데 있습니다. 글쓴이가 제시한 흐름에서는 컴포넌트 JSON이 없거나 유효하지 않을 때 OG 카드로 돌아가므로, 기본 메타데이터가 여전히 표시 품질을 좌우합니다. 댓글에서도 초기 HTML의 OG 태그와 컴포넌트 페이로드를 각각 CI에서 검사하자는 제안이 나왔습니다. 이는 글에 나온 서버 렌더링 조건과 페이로드 전체 무효화 규칙에 직접 대응합니다. 반면 Discord 캐시가 Cache-Control을 따르는지는 글쓴이도 확인하지 못했고, 댓글에서도 답이 나오지 않았습니다. 테스트에서는 쿼리 문자열을 바꾸는 방법이 제시됐지만 캐시 제어 전반의 기준까지 제공되지는 않습니다.

AI 요약

Discord에 웹사이트 링크를 올리면 기본적으로 Open Graph(OG) 태그를 읽어 제목, 설명, 이미지를 미리보기 카드로 표시합니다. 글쓴이는 이 카드 대신 텍스트와 이미지 갤러리, 버튼을 조합한 컴포넌트 임베드를 표시하는 방법을 자신의 Astro 블로그에 적용해 설명합니다.

크롤러가 읽는 정보

사이트는 HTTPS를 사용해야 하고, OG 태그는 JavaScript 실행 뒤가 아니라 서버가 반환하는 HTML의 <head>에 있어야 합니다. Discord 크롤러는 user-agent에 Discordbot을 표시하므로, 앞단에 WAF나 CDN, 요청 제한 장치가 있다면 크롤러 접근을 허용해야 합니다. 기본 미리보기에는 og:title, og:description, og:image, og:url 같은 OG 태그가 쓰입니다. 크롤러는 페이지를 가져와 이 태그를 읽고, 컴포넌트 임베드 정보가 있으면 JSON도 확인합니다. JSON이 없거나 유효하지 않으면 기본 OG 카드로 돌아갑니다.

JSON 구성과 제한

임베드 JSON은 <head> 안에 application/json 스크립트로 넣거나, 같은 도메인 또는 하위 도메인에 둔 JSON 파일을 link 태그로 지정할 수 있습니다. 외부 JSON 파일은 원시 데이터 기준 3,000바이트까지 허용됩니다. 글쓴이는 이미지 갤러리와 버튼을 넣을 때 더 큰 내용을 담을 수 있도록 인라인 방식을 선택했습니다.

최상위 컴포넌트는 type 17인 Container여야 하며, 전체 컴포넌트는 최대 40개입니다. 사용할 수 있는 유형은 Action Row(type 1), 링크 버튼(type 2, style 5), Section(type 9), Text Display(type 10), Thumbnail(type 11), Media Gallery(type 12), Separator(type 14), Container(type 17)입니다. 목록에 없는 유형이나 버튼에 허용되지 않은 키가 들어가면 일부만 제외되는 것이 아니라 전체 페이로드가 무효가 됩니다. 이미지에는 URL을 지정하면 Discord가 크기와 파일 형식을 가져옵니다. PNG, GIF, JPEG, WebP, AVIF를 지원하며, Media Gallery는 MP4, MOV, WebM도 지원합니다.

블로그 적용과 점검

글쓴이는 OG 태그와 같은 제목, 설명, 대표 이미지를 재사용해 임베드를 만듭니다. 본문에는 Discord Markdown 형식의 제목과 설명을 넣고, Media Gallery에 대표 이미지를 표시하며, 글과 블로그로 연결되는 버튼 두 개를 추가합니다. Section에 붙이는 Thumbnail은 이미지가 작게 보여 Media Gallery로 바꿨고, 글과 이미지 사이의 Separator는 불필요하다고 판단해 넣지 않았습니다. 글마다 관리하던 배경색은 16진수에서 10진수로 변환해 accent_color에 사용합니다.

사이트는 정적 생성 방식이라 임베드 JSON도 빌드 단계에서 HTML에 포함합니다. Discord 미리보기는 약 30분 캐시되며 테스트 때 URL에 ?v=2처럼 쿼리 값을 추가하면 새 주소로 확인할 수 있습니다. 페이지와 이미지 전체를 가져오는 데 주어진 시간은 10초라 이미지가 많은 갤러리에서는 제한에 더 빨리 도달할 수 있습니다. 글쓴이는 크롤러가 어떤 태그를 찾고 어떤 형식을 선택했는지 확인할 때 Discord Embed Debugger를 먼저 사용하라고 안내합니다.

dev.to 반응

  • @alexshev — 서버 렌더링 HTML에 OG 태그가 있어야 한다는 조건은 놓치기 쉽습니다. Discord 컴포넌트를 테스트하기 전에 CI에서 초기 HTML을 가져와 제목, 설명, 이미지 태그를 확인하면 클라이언트 전용 메타데이터로 바뀌는 회귀를 막을 수 있습니다.
    • @thomasbnt — 네, CI에 넣기 좋은 아이디어입니다.
  • @dharu_89ac9b8f48aa5d359f6 — 기본 OG 카드에서 버튼과 Media Gallery가 있는 type 17 Container 임베드로 옮기면 미리보기가 Discord에 더 자연스럽게 어울립니다. 테스트 중 ?v=2로 캐시를 피하는 방법이 유용하네요. Discord가 Cache-Control: no-cache 같은 일반 HTTP 캐시 헤더도 따르는지, 아니면 ?v=N이 믿을 만한 방법인지 궁금합니다. 블로그 글에는 작은 Thumbnail보다 넓은 Media Gallery가 낫다는 점에도 동의합니다. 페이로드 구조와 10초 제한, 흔한 실수를 공유해줘서 고맙습니다.
    • @thomasbnt — 읽어주셔서 감사합니다. 의견도 반갑습니다. Discord 캐시는 Cloudflare 뒤에 있어서 Cache-Control이 우회하는지는 모르겠습니다. 테스트가 필요합니다.
  • @glenallen — 대체 미리보기도 단순한 안전망이 아니라 완성도 있게 다뤄야 합니다. 페이로드가 유효해도 클라이언트 차이나 렌더링 실패 때문에 사용자가 OG 카드만 볼 수 있습니다. CI에서 서버 렌더링 메타데이터가 완전한지 확인하고, 컴포넌트 페이로드가 Discord 스키마와 크기 제한을 지키는지도 검사하면 좋겠습니다. 기본 링크 미리보기는 안정적으로 유지하면서 사용자 경험을 더하는 점진적 개선이 적절합니다.
  • @jabinpou — 외부 JSON의 3,000바이트 제한은 유용한 정보입니다. 번역 제목이나 이모지를 포함할 때 빌드 과정에서 인코딩된 바이트 길이를 측정하나요? 짧아 보여도 UTF-8 바이트 수는 다를 수 있습니다.
    • @thomasbnt — 그렇게 할 수 있습니다.
  • @botsailorofficial — 웹의 SEO 관점을 Discord에 적용하는 아이디어가 좋습니다. Discord 콘텐츠는 이미 서버 안에 있는 사람들만을 위한 것이 아니며, 링크 미리보기와 제목, 메타데이터를 조금 개선해도 콘텐츠를 발견하고 공유하기 쉬워질 수 있습니다. Discord를 전통적인 웹사이트처럼 만들려는 대신 기존 콘텐츠를 사람과 검색 엔진이 더 잘 이해하도록 돕는 접근이 마음에 듭니다.
    • @thomasbnt — 맞습니다. 글을 읽어주셔서 감사합니다.

원문: dev.to / 번역·요약: Trawling

원문 보기 ↗토론 보기 ↗