# OG 이미지 개요

카카오톡, Slack, X, Facebook에 내 페이지 링크를 공유하면, 앱은 페이지의 `og:image` 태그에 있는 이미지를 보여 줍니다. Mocco가 이 이미지를 대신 그립니다. 템플릿을 고르고 문구를 넣은 다음, 이미지 URL을 태그에 넣으면 됩니다. Mocco는 크롤러가 처음 요청할 때 카드를 그리고, 그 뒤로는 저장해 둔 이미지를 제공합니다.

카드는 모두 1200×630픽셀이고, 글은 가운데 영역에 배치되어 카카오톡이 2:1로 잘라도 잘리지 않습니다. 한국어는 단어 중간이 아니라 단어 사이에서 줄을 바꾸고, 한자, 일본어, 이모지도 그려집니다.

## 템플릿

| 템플릿 | 항목 | 용도 |
| --- | --- | --- |
| `simple` | `brand`(1–60자), `accent`(선택, `#2563eb` 같은 색상), `title`(1–120자), `subtitle`(선택, 160자까지) | 랜딩·제품 페이지 |
| `article` | `brand`(1–60자), `accent`(선택), `eyebrow`(선택, 60자까지: 섹션이나 분류), `title`(1–120자), `description`(선택, 200자까지) | 글·게시물·문서 |

`brand`는 카드 맨 위의 이름이고, `accent`는 그 위 선의 색입니다. 같은 목록을 Mocco API의 `GET /v1/og/templates`에서 키 없이 읽을 수 있습니다.

## 서명 시크릿

이미지 URL에는 프로젝트의 **OG 서명 시크릿**으로 만든 서명이 들어갑니다. 그래서 내 프로젝트의 이미지는 나만 발급할 수 있고, 다른 사람이 내 카드에 자기 문구를 넣을 수 없습니다. 서명이 맞지 않는 URL은 거부됩니다.

1. 프로젝트를 열고 **API 키**로 갑니다. **OG 이미지 서명** 카드에 프로젝트에 시크릿이 있는지 표시됩니다.
2. 소유자나 관리자가 **시크릿 생성**을 누릅니다. Mocco는 시크릿과 예시 URL을 **한 번만** 보여 줍니다. 시크릿을 서버에 복사해 두세요(예: `MOCCO_OG_SECRET`). 브라우저나 앱에는 절대 넣지 마세요. 시크릿이 있으면 누구나 이 프로젝트의 이미지 URL에 서명할 수 있습니다.
3. **시크릿 교체**는 시크릿을 바로 바꿉니다. 이전 시크릿으로 서명한 URL은 그 즉시 모두 동작하지 않으므로, 새 시크릿으로 URL에 다시 서명하세요.

소유자나 관리자가 아닌 멤버는 시크릿이 있는지와 마지막으로 교체한 때만 볼 수 있습니다.

## 이미지 URL 얻기

- **콘솔에서:** **OG 이미지** 페이지(**API 키** 탭의 **템플릿 갤러리 열기**)에서 내용을 채우는 대로 템플릿을 미리 보고 서명된 URL을 복사합니다. [이미지 URL에 서명하기](https://www.mocco.club/docs/ko/articles/v7iw2i-sign-urls#콘솔에서)를 참고하세요.
- **서버에서:** 빌드하거나 동적으로 제공하는 페이지라면 `@mocco/node`나 서명 방법대로 URL에 서명합니다. [이미지 URL에 서명하기](https://www.mocco.club/docs/ko/articles/v7iw2i-sign-urls)를 참고하세요.
- **CI에서:** API 키로 이미지를 미리 그려 두면 첫 크롤러가 기다리지 않습니다. [CI에서 이미지 미리 그리기](https://www.mocco.club/docs/ko/articles/irw7vm-pre-render)를 참고하세요.
- **에이전트에서:** MCP 도구 `mocco_og_url`은 서명된 URL을 돌려주고, `mocco_og_templates`는 템플릿과 항목을 알려 줍니다.

그다음 [OG 미리보기](https://www.mocco.club/docs/ko/articles/w9vc8r-check-a-page)로 페이지가 어떻게 펼쳐지는지 확인하세요.