I built a link preview API — here's what I learned about Open Graph

Context

URL을 붙여넣으면 플랫폼이 og:image, og:title, og:description, og:url 등의 메타데이터를 수집해 카드 형태로 표시하는 링크 프리뷰 시스템은 누락된 이미지, 잘못된 폴백, 캐시된 오래된 데이터 등으로 인해 자주 깨진다. 대부분의 개발자들은 공식 문서에 명시되지 않은 숨겨진 요구사항을 모르고 구현하기 때문에 프리뷰가 정상 작동하지 않는 상황이 반복된다.

Technical Solution

• og:image 태그의 픽셀 크기를 1200x630 픽셀로 설정: 이 크기 미만(200x200 이하)이면 플랫폼이 이미지를 무시함
• og:image URL을 절대 경로 형식으로 지정: 상대 경로(/images/preview.png) 대신 전체 도메인 포함(https://yourdomain.com/images/preview.png)
• og:image 파일 형식을 PNG 또는 JPEG로 제한: SVG는 거의 모든 플랫폼에서 프리뷰 이미지로 렌더링되지 않음
• og:image 파일 크기를 1MB 이하로 유지: 더 큰 이미지는 크롤 윈도우 내에서 타임아웃될 수 있음
• Twitter Cards의 twitter:card 타입을 summary 또는 summary_large_image로 명시: 같은 OG 태그를 사용해도 twitter:card 타입에 따라 렌더링 방식이 달라짐
• og:url을 페이지의 캐노니컬 URL과 일치하도록 설정: 불일치하면 플랫폼이 잘못된 URL에 대해 프리뷰를 캐시함
• og:description이 없을 때의 폴백 체인 이해: og:description → meta name="description" → 본문 첫 단락 순서로 폴백됨

Impact

아티클에서 정량적 수치가 제시되지 않음

Key Takeaway

Open Graph 프리뷰 시스템은 공식 문서의 기본 태그 4개(og:title, og:description, og:image, og:url) 외에 이미지 크기, 절대 URL 경로, 파일 형식, 각 플랫폼별 고유 태그(Twitter Cards) 등 다층의 암묵적 요구사항이 존재하며, 이를 플랫폼별·HTML 포맷별로 안정적으로 파싱하는 것이 단순해 보이는 작업을 몇 주의 엣지 케이스 처리로 변환한다.