| name | kakao-share-optimization |
| description | 카카오톡 링크 공유 시 OG 미리보기를 최적화하는 방법. 카카오 캐시 초기화, 이미지 사양, JavaScript SDK 공유 구현, SPA 환경 대응을 다룬다. <example>사용자: "카카오톡 공유했는데 미리보기 이미지가 옛날 거 나와요"</example> <example>사용자: "Next.js에서 카카오톡 공유 미리보기 구현하려면?"</example> <example>사용자: "Kakao.Share.sendDefault 사용법 알려줘"</example>
|
카카오톡 공유 최적화 (Kakao Share Optimization)
소스:
검증일: 2026-08-26 (최초 2026-06-04 · 08-26 freshness 재검증: 이미지 규격·Kakao.Share API VERIFIED. SDK 2.8.1→2.8.2 갱신, CSR 대응책에서 Rendertron 제외·Edge og 주입 대안 추가)
SDK 기준 버전: 2.8.2 (2026-08-06 출시, 내부 개선 — 2.8.1과 API 동일. integrity 해시는 공식 다운로드 페이지에서 해당 버전 값으로 교체)
1. 카카오톡 OG 미리보기 기본 구조
카카오톡은 링크 공유 시 서버 사이드에서 대상 URL을 크롤링해 OG 메타태그를 읽는다. 카카오 크롤러는 JavaScript를 실행하지 않으므로, SSR/SSG로 OG 태그를 응답 HTML에 직접 포함해야 한다.
필수 OG 태그
<meta property="og:title" content="페이지 제목" />
<meta property="og:description" content="페이지 설명" />
<meta property="og:image" content="https://example.com/og.jpg" />
<meta property="og:url" content="https://example.com/post/123" />
<meta property="og:type" content="website" />
og:url이 실제 공유 URL과 불일치하면 공유 동작이 혼란스러워진다 (canonical 일치 권장)og:image는 반드시 절대 URL + HTTPS
2. 이미지 요구사항
| 항목 | 값 | 근거 |
|---|
| 권장 크기 | 800 × 400 px (가로:세로 2:1) | 카카오 데브톡 공식 답변 — 스크랩 시 800×400으로 자동 스마트 크롭 |
| 최소 크기 | 200 × 200 px | 메시지 템플릿 공식 사양 |
| 최대 파일 크기 | 5 MB | 메시지 템플릿 공식 사양 |
| 프로토콜 | HTTPS 절대 URL 필수 | HTTP 이미지는 무시될 수 있음 |
| 권장 형식 | JPEG / PNG | 카카오 메시지 API는 JPG/JPEG/PNG/PDF 업로드 허용 |
주의: 카카오 공식 문서에는 SVG/WebP 지원 여부가 명문화돼 있지 않다. 실무 보고와 메시지 템플릿 업로드 허용 형식을 종합하면 SVG는 미리보기가 안 뜨는 사례가 다수다. 안전하게 JPEG 또는 PNG를 쓴다.
주의: OG 이미지 크기 가이드는 페이스북·카카오를 모두 만족시키려고 1200 × 630 (1.91:1) 을 쓰는 경우도 많다. 카카오 단독 최적화는 800 × 400 (2:1), 멀티플랫폼 호환은 1200 × 630.
카카오 스마트 크롭
카카오는 스크랩 시 내부 스마트 크롭 API로 이미지를 800×400으로 자동 변환한다. 인물 포함 이미지의 크롭 위치가 자동 조정될 수 있고, 이 동작은 옵션으로 제어할 수 없다. 텍스트·로고는 이미지 중앙 80% 안전 영역에 배치한다.
3. 카카오 캐시 문제와 초기화
카카오 서버는 한 번 크롤링한 OG를 캐싱한다. OG를 수정해도 공유 미리보기에 반영되지 않는다면 수동 캐시 초기화가 필요하다.
초기화 방법 (공식 도구)
- https://developers.kakao.com/tool/clear/og 접속 (카카오 계정 로그인 필요)
- 입력 칸에 대상 URL 입력 —
http/https 정확히 구분, SSL 사이트는 반드시 https
- 현재 캐시된 OG 정보 확인 후 캐시 초기화 버튼 클릭
주의: 초기화 후에도 반영까지 수 분~수십 분 지연이 발생할 수 있다. 급한 경우 og:image URL에 쿼리스트링(?v=2)을 추가해 우회한다. 다만 CDN 캐시도 함께 갱신해야 의미가 있다.
페이스북 디버거 병행
페이스북 OG 디버거(https://developers.facebook.com/tools/debug/)도 함께 돌려 메타태그 자체의 정합성을 점검한다.
4. Kakao JavaScript SDK 공유 구현
SDK 로드 (2.8.2 기준)
<script
src="https://t1.kakaocdn.net/kakao_js_sdk/2.8.2/kakao.min.js"
integrity="${INTEGRITY_VALUE}"
crossorigin="anonymous"
></script>
<script>
Kakao.init('YOUR_JAVASCRIPT_APP_KEY');
console.log(Kakao.isInitialized());
</script>
주의: ${INTEGRITY_VALUE}(SHA-384 해시)는 카카오 공식 다운로드 페이지에서 버전별로 갱신된다. 공식 페이지에서 그 시점의 값을 복사해 넣는다. SDK 버전을 올릴 때 integrity도 함께 갱신해야 한다.
주의: Kakao.init()에는 카카오 개발자 콘솔의 JavaScript 키를 넣는다. REST API 키·Admin 키와 혼동하지 않는다.
피드(feed) 공유
Kakao.Share.sendDefault({
objectType: 'feed',
content: {
title: '제목',
description: '설명',
imageUrl: 'https://example.com/og.jpg',
imageWidth: 800,
imageHeight: 400,
link: {
mobileWebUrl: 'https://example.com/post/123',
webUrl: 'https://example.com/post/123',
},
},
buttons: [
{
title: '자세히 보기',
link: {
mobileWebUrl: 'https://example.com/post/123',
webUrl: 'https://example.com/post/123',
},
},
],
serverCallbackArgs: {
postId: '123',
},
});
sendDefault vs sendCustom vs sendScrap
| 메서드 | 용도 | 핵심 파라미터 |
|---|
Kakao.Share.sendDefault | 코드에서 직접 템플릿 정의 | objectType (feed/list/location/commerce/text) |
Kakao.Share.sendCustom | 카카오 콘솔에서 만든 커스텀 템플릿 사용 | templateId, templateArgs |
Kakao.Share.sendScrap | 대상 URL의 OG를 카카오가 스크랩해서 전송 | requestUrl (필수), templateId(선택) |
주의: SDK v1.43.0부터 모듈명이 Kakao.Link에서 Kakao.Share로 변경됐다. 옛 문서나 블로그의 Kakao.Link.sendDefault는 현행 SDK에서 deprecated 또는 동작 안 함. Kakao.Share.*만 사용한다.
sendScrap — OG 기반 공유
Kakao.Share.sendScrap은 별도 콘텐츠 구성 없이 URL만 넘기면 카카오가 해당 페이지의 OG 태그를 읽어 미리보기를 만든다. OG 캐시 동작에 100% 의존하므로 캐시 초기화 + SSR 정합성이 필수다.
Kakao.Share.sendScrap({
requestUrl: 'https://example.com/post/123',
});
5. SPA (Next.js / React) 환경에서 OG 처리
카카오 크롤러는 JavaScript를 실행하지 않는다. CSR로 document.querySelector('meta[property="og:title"]').setAttribute(...)를 해도 카카오는 변경된 값을 읽지 못한다. 반드시 서버에서 렌더링된 HTML에 OG 태그가 포함돼 있어야 한다.
Next.js (App Router) — generateMetadata
import type { Metadata } from 'next';
export async function generateMetadata({ params }: { params: { id: string } }): Promise<Metadata> {
const post = await fetchPost(params.id);
return {
title: post.title,
description: post.description,
openGraph: {
title: post.title,
description: post.description,
url: `https://example.com/post/${params.id}`,
images: [{ url: post.ogImageUrl, width: 800, height: 400 }],
type: 'article',
},
};
}
Next.js (Pages Router) — next/head
import Head from 'next/head';
export default function Post({ post }) {
return (
<>
<Head>
<meta property="og:title" content={post.title} />
<meta property="og:description" content={post.description} />
<meta property="og:image" content={post.ogImageUrl} />
<meta property="og:url" content={`https://example.com/post/${post.id}`} />
</Head>
{/* ... */}
</>
);
}
export async function getServerSideProps(ctx) {
const post = await fetchPost(ctx.params.id);
return { props: { post } };
}
순수 CSR React SPA
- 빌드 타임 프리렌더(Vike·vite-prerender-plugin) 또는 SSR 도입 — 정공법 (
frontend/seo-vite-spa 단계 4·5)
- CDN/Edge(Cloudflare Worker·Vercel Edge)에서 카카오 스크래퍼 UA(
kakaotalk-scrap)·페이스북·네이버 봇에만 og:* 메타를 주입한 HTML 셸을 응답 — 가장 가볍고 빠른 대안
prerender.io / rendertron / react-snap — Rendertron은 2022년 Google이 archive 처리(유지보수 없음), 동적 렌더링 자체가 Google 기준 "권장 아님·임시 우회책". 이미 운영 중이 아니면 도입하지 않는다 (2026-08-26 정정)- Cloudflare Workers / Vercel Edge Function으로 크롤러 User-Agent 분기 응답
- 가능하면 Next.js 같은 SSR/SSG 프레임워크로 마이그레이션
6. 카카오 메시지 vs 공유 vs 채널
| 기능 | API | 로그인 필요 | 대상 |
|---|
| 카카오톡 공유 | Kakao.Share.sendDefault / sendScrap | ❌ | 친구·채팅방 |
| 나에게 메시지 | Kakao.API.request({ url: '/v2/api/talk/memo/default/send' }) | ✅ | 본인 |
| 친구에게 메시지 | Kakao.API.request({ url: '/v1/api/talk/friends/message/default/send' }) | ✅ + 친구 동의 | 친구 |
| 채널 추가/메시지 | Kakao.Channel.* | 비즈 채널 필요 | 채널 구독자 |
대부분의 공개 페이지 공유에는 Kakao.Share.sendDefault (비로그인 가능)를 쓴다.
7. 디버깅 체크리스트
링크 공유 미리보기가 안 뜨거나 이상하면 순서대로 점검한다.
- HTTPS 절대 URL인가 —
og:image와 og:url이 HTTP거나 상대경로면 무시될 수 있다
- SSR/SSG로 OG가 응답 HTML에 포함되는가 —
curl https://example.com/post/123 | grep og: 결과 확인
- 이미지 사양 — 5MB 이하, 200×200 이상, JPEG/PNG인가
- 카카오 OG 캐시가 옛날 값을 들고 있는가 —
developers.kakao.com/tool/clear/og로 초기화
og:url이 실제 공유 URL과 일치하는가 — 불일치 시 클릭 시 다른 페이지로 갈 수 있음- 리다이렉트 체인이 과한가 — 카카오 크롤러는 리다이렉트 다수에서 실패할 수 있음
- SDK 호출 시 콘솔 에러 —
Kakao.isInitialized() 결과, Kakao.init 키 종류 확인
8. 흔한 실수 패턴 (Anti-patterns)
| 실수 | 결과 | 해결 |
|---|
| HTTP 이미지 URL | 미리보기 이미지 누락 | HTTPS 절대 URL 사용 |
| SVG 이미지 사용 | 미리보기 없음 | JPEG/PNG 변환 |
| 5MB 초과 이미지 | 미리보기 없음 | 압축·리사이징 |
| CSR로 OG meta 동적 변경 | 카카오 미인식 | SSR/SSG로 응답 HTML에 포함 |
| 캐시 초기화 없이 OG 수정 후 공유 | 옛 미리보기 노출 | OG 초기화 도구 사용 |
og:url 미설정·불일치 | 공유 URL 혼란 | 실제 공유 URL과 정확히 일치시킴 |
Kakao.Link.sendDefault 사용 | 동작 안 함 (v1.43.0+ 변경) | Kakao.Share.sendDefault로 변경 |
REST API 키로 Kakao.init | 동작 안 함 | JavaScript 키 사용 |
SDK 로드 안 하고 Kakao 호출 | Kakao is not defined | SDK <script> 로드 + Kakao.init 선행 |
imageWidth/imageHeight 누락 | 이미지 일부 잘림·왜곡 | 권장 800×400으로 명시 |
9. 권장 워크플로우
- OG 메타태그 작성 (SSR/SSG로 응답 HTML에 포함)
- 이미지 준비 — 800×400 JPEG/PNG, 5MB 이하, HTTPS URL
- 로컬에서 페이스북 디버거로 OG 정합성 확인
- 배포 후 카카오 공유 디버거로 미리보기 확인
- 수정 시 카카오 OG 초기화 도구로 캐시 초기화
- SDK 공유 버튼 —
Kakao.Share.sendDefault 또는 sendScrap
- 버전 업그레이드 시 CDN URL과 integrity 동시 갱신
