구조·마크업 · 공식 문서
자바스크립트 구조화 데이터, 구글이 읽는지 확인 순서
구글은 페이지를 렌더링한 뒤 DOM 에 있는 구조화 데이터를 읽습니다. 읽혔는지는 리치 결과 테스트에 URL 을 넣어 확인하고, 값의 출처부터 배포 뒤 감시까지 7단계로 점검합니다.
제작 도구가 소스 수정을 제한하면 구조화 데이터는 태그 관리자나 스크립트로 넣게 됩니다. 이때 처음 받은 HTML 에는 마크업이 없습니다.
구글 문서는 이 방식을 허용하고, 확인하는 도구와 주의할 자리를 따로 적었습니다. 그 순서를 따라가면 넣은 마크업이 읽히는지 직접 확인할 수 있습니다.
발견 01
구글은 자바스크립트로 넣은 구조화 데이터도 렌더링한 뒤 DOM 에서 읽습니다
Either way, Google Search can understand and process structured data that's available in the DOM when it renders the page.
어느 방식이든 구글 검색은 페이지를 렌더링할 때 DOM 에 있는 구조화 데이터를 이해하고 처리할 수 있다.
| 넣는 방법 | 마크업이 생기는 때 | 맞는 경우 | 공식 문서 원문 |
|---|---|---|---|
| Google 태그 관리자 | 브라우저에서 컨테이너가 실행될 때 | 개발 배포 없이 마케팅 담당이 넣을 때 | Google Tag Manager is a platform that lets you manage tags on your website without editing the code.Google 태그 관리자는 코드를 고치지 않고 웹사이트의 태그를 관리하는 플랫폼이다. |
| 맞춤 자바스크립트 | 스크립트가 DOM 에 script 태그를 붙일 때 | API 값으로 마크업을 채울 때 | Either way, Google Search can understand and process structured data that's available in the DOM when it renders the page.어느 방식이든 구글 검색은 페이지를 렌더링할 때 DOM 에 있는 구조화 데이터를 이해하고 처리할 수 있다. |
| 서버 측 렌더링 | 서버가 HTML 을 보낼 때(첫 HTML) | 가격·재고처럼 자주 바뀌는 값을 넣을 때 | If you are using server-side rendering, you can also include the structured data in the rendered output.서버 측 렌더링을 쓴다면 렌더링된 출력에 구조화 데이터를 함께 넣을 수도 있다. |
구글 소개 문서도 같은 내용을 적었습니다. 원문은 "Also, Google can read JSON-LD data when it is dynamically injected into the page's contents, such as by JavaScript code or embedded widgets in your content management system."입니다.
태그 관리자로 넣을 때는 컨테이너에 맞춤 HTML 태그를 추가하고, 그 안에 JSON-LD 블록을 붙인 뒤 컨테이너를 게시합니다. 컨테이너를 게시해야 사이트에 마크업이 나갑니다.
발견 02
읽혔는지는 값의 출처부터 배포 뒤 감시까지 7단계로 확인합니다
| 순서 | 단계 | 볼 것 | 공식 문서 원문 |
|---|---|---|---|
| 1 | 값의 출처 | 태그 관리자 변수가 페이지에 보이는 값을 읽어 오는가 | Use variables to extract the structured data from the page instead of duplicating the information in GTM. Duplicating the information in GTM increases the risk of having a mismatch between page content and the structured data inserted using GTM.GTM 에 정보를 복제하지 말고 변수로 페이지에서 구조화 데이터를 뽑아 온다. 복제하면 페이지 콘텐츠와 GTM 으로 넣은 구조화 데이터가 어긋날 위험이 커진다. |
| 2 | 보이는 내용 | 마크업한 내용이 화면에도 그대로 보이는가 | Don't mark up content that is not visible to readers of the page.페이지를 읽는 사람에게 보이지 않는 콘텐츠는 마크업하지 않는다. |
| 3 | URL 로 테스트 | 리치 결과 테스트에 코드 대신 URL 을 넣었는가 | We recommend that you use the URL input instead of the code input because there are JavaScript limitations when using the code input (for example, CORS restrictions).코드 입력은 자바스크립트 제약(예: CORS)이 있으므로 코드 입력보다 URL 입력을 권한다. |
| 4 | 결과 메시지 | 「페이지가 리치 결과 기능에 적합함」이라고 나오는가 | Success: If you did everything correctly and your structured data type is supported in the tool, you will see the message "Page is eligible for rich results".제대로 했고 도구가 지원하는 유형이면 「페이지가 리치 결과 기능에 적합함」이라는 메시지가 나온다. |
| 5 | 렌더링된 HTML | 도구가 지원하지 않는 유형이면 렌더링된 HTML 에 마크업이 있는가 | If you are testing a structured data type that is not supported by the Rich Results test, check the rendered HTML. If the rendered HTML contains the structured data, Google Search will be able to process it.리치 결과 테스트가 지원하지 않는 유형이면 렌더링된 HTML 을 확인한다. 렌더링된 HTML 에 구조화 데이터가 있으면 구글 검색이 처리할 수 있다. |
| 6 | URL 검사 | 서치 콘솔 URL 검사 도구로 구글이 렌더링한 페이지를 봤는가 | To test how Google crawls and renders a URL, use the Rich Results Test or the URL Inspection Tool in Search Console.구글이 URL 을 크롤링하고 렌더링하는 모습은 리치 결과 테스트나 서치 콘솔 URL 검사 도구로 확인한다. |
| 7 | 배포 뒤 감시 | 리치 결과 상태 보고서에서 템플릿 변경으로 깨진 페이지가 없는가 | Be sure to check your structured data using the Rich Results Test during development, and the Rich result status reports after deployment, to monitor the validity of your pages, which might break after deployment due to templating or serving issues.개발 중에는 리치 결과 테스트로, 배포 뒤에는 리치 결과 상태 보고서로 구조화 데이터를 확인한다. 템플릿이나 서버 문제로 배포 뒤에 깨질 수 있기 때문이다. |
코드 입력으로 테스트하면 스크립트가 다른 서버에서 값을 받아 오는 부분이 차단될 수 있습니다. 그래서 공개된 URL 을 넣어 구글이 실제로 렌더링한 결과를 봅니다.
태그 관리자에 상품명이나 제목을 직접 적어 두면 페이지가 바뀌어도 마크업은 그대로 남습니다. 변수로 화면 값을 읽어 오면 둘이 어긋날 일이 줄어듭니다. 생성기로 만든 코드를 고치는 법은 「JSON-LD 생성기」 편에 자세히 적었습니다.
발견 03
가격·재고처럼 자주 바뀌는 값과 네이버까지 생각하면 마크업은 첫 HTML 에 두는 편이 안전합니다
Be aware that dynamically-generated markup can make Shopping crawls less frequent and less reliable, which can be an issue for fast-changing content like product availability and price.
동적으로 만든 마크업은 쇼핑 크롤링을 드물고 덜 안정적으로 만들 수 있다. 재고·가격처럼 빨리 바뀌는 콘텐츠에서 문제가 될 수 있다.
| 경우 | 공식 문서가 적은 것 | 할 일 |
|---|---|---|
| Product 마크업 | Be aware that dynamically-generated markup can make Shopping crawls less frequent and less reliable, which can be an issue for fast-changing content like product availability and price.동적으로 만든 마크업은 쇼핑 크롤링을 드물고 덜 안정적으로 만들 수 있다. 재고·가격처럼 빨리 바뀌는 콘텐츠에서 문제가 될 수 있다. | 가격·재고는 서버 측 렌더링으로 첫 HTML 에 넣습니다 |
| 네이버 검색로봇 | 자바스크립트가 수집되어 있지 않으면 정적인 HTML의 내용을 먼저 수집/분석하여 색인 처리합니다. | 네이버 유입이 중요한 페이지는 마크업을 첫 HTML 에 둡니다 |
| 크롤링 차단 | Don't block your structured data pages to Googlebot using robots.txt, noindex, or any other access control methods.robots.txt·noindex 나 다른 접근 제어 방법으로 구조화 데이터가 있는 페이지를 Googlebot 에 차단하지 않는다. | 마크업이 든 페이지와 스크립트 파일을 robots.txt 에서 허용합니다 |
구글과 네이버가 자바스크립트를 처리하는 단계 전체는 「자바스크립트 SEO」 편에 자세히 적었습니다.
발견 04
B2B·B2C·B2G 는 자바스크립트로 넣게 되는 이유와 먼저 볼 단계가 다릅니다
예시 ① 문의형 기업 사이트의 칼럼 페이지(B2B)
마케팅 담당이 개발 일정 없이 칼럼에 Article 마크업을 넣으려고 태그 관리자를 씁니다. 제목과 날짜를 태그에 직접 적으면 글마다 같은 값이 들어갑니다.
그래서 1단계인 값의 출처가 핵심입니다. 제목은 페이지 제목에서, 날짜는 화면의 게시일 칸에서 변수로 읽어 옵니다.
예시 ② 상품 수천 개를 파는 자사 쇼핑몰(B2C)
프런트엔드가 가격과 재고를 API 로 받아 그리면서 Product 마크업도 같은 스크립트로 붙이는 구조입니다. 구글 문서는 이 경우 쇼핑 크롤링이 드물어질 수 있다고 적었습니다.
가격과 재고만큼은 서버에서 첫 HTML 에 넣고, 테스트는 URL 입력으로 상품 몇 개를 골라 합니다.
예시 ③ 공공기관 누리집 유지보수 사업(B2G)
유지보수 범위에 소스 수정이 없어 BreadcrumbList 를 스크립트로 넣자는 제안이 나옵니다. 공공기관 누리집은 네이버 유입 비중도 함께 봐야 합니다.
과업지시서에 마크업을 첫 HTML 에 넣는 일을 넣거나, 스크립트로 넣었다면 7단계인 배포 뒤 감시를 정기 점검 항목에 둡니다.
그럼 지금 넣어 둔 마크업은 어떻게 확인하나요?
- 마크업을 넣은 페이지 종류를 하나씩 골라 대표 URL 을 적어 둡니다.
- 태그 관리자 태그를 열어 값이 직접 적혀 있는지, 변수로 화면에서 읽어 오는지 봅니다.
- 대표 URL 을 리치 결과 테스트에 URL 로 넣고 결과 메시지를 확인합니다.
- 도구가 지원하지 않는 유형이면 렌더링된 HTML 에서 script 태그를 찾습니다.
- 서치 콘솔 URL 검사 도구로 구글이 렌더링한 페이지를 봅니다.
- 가격·재고처럼 자주 바뀌는 값과 네이버 유입이 큰 페이지는 서버에서 넣도록 개발 일정에 올립니다.
조사 방법
- Google Search Central 「Generate structured data with JavaScript」 (문서 수정일 2025-12-10) · 최종 확인일 2026-10-25 · https://developers.google.com/search/docs/appearance/structured-data/generate-structured-data-with-javascript
- Google Search Central 「Introduction to structured data markup in Google Search」 (문서 수정일 2025-12-10) · 최종 확인일 2026-10-18 · https://developers.google.com/search/docs/appearance/structured-data/intro-structured-data
- Google Search Central 「General structured data guidelines」 (문서 수정일 2026-07-10) · 최종 확인일 2026-10-18 · https://developers.google.com/search/docs/appearance/structured-data/sd-policies
- Google Search Central 「Fix Search-related JavaScript problems」 (문서 수정일 2025-12-18) · 최종 확인일 2026-10-25 · https://developers.google.com/search/docs/crawling-indexing/javascript/fix-search-javascript
- 네이버 서치어드바이저 「자바스크립트 검색 최적화」 · 최종 확인일 2026-10-25 · https://searchadvisor.naver.com/guide/seo-advanced-javascript
- 확인 순서 7단계는 위 문서들이 테스트와 가이드라인으로 적은 일을 넣기 전, 테스트, 배포 뒤 차례로 묶은 것입니다. 묶는 방식은 편집 판단입니다.
- 예시 ①②③은 이해를 돕기 위해 만든 가상 상황이며, 실제 기업·기관 사례가 아닙니다.
- 구글 원문은 영어판(hl=en)이고, 도구·보고서 이름은 같은 문서 한국어판(hl=ko) 표기를 따랐습니다. 네이버 서치어드바이저 가이드 화면에는 수정일이 보이지 않습니다.