자동화

ujinify.com 업로드 스크립트가 REST API(Application Programming Interface, 외부에서 워드프레스 데이터를 주고받는 통로)로 랭크매스 포커스 키워드를 보내고 있었다. 응답도 200이 왔다. 에러도 없었다. 그런데 글을 열어보면 포커스 키워드 칸이 비어 있다.

조용히 무시당한 거다. 한동안 이걸 몰랐고, 그동안은 글마다 에디터를 열어서 손으로 키워드를 입력했다. 글이 늘수록 이게 제일 귀찮은 수작업이었다.

이 글은 그 문제를 해결한 방법을 정리한다. wp.data라는 워드프레스 내부 저장소(앱 안에서 데이터를 관리하는 공간)를 직접 건드리는 방식이다.

REST API가 랭크매스 포커스 키워드를 무시하는 이유

REST API로 글을 저장할 때 meta 필드에 rank_math_focus_keyword를 넣으면 된다고 생각했다. 실제로 그렇게 했다. 그리고 저장은 됐다. 응답 코드도 200이었다.

랭크매스가 이 값을 받아도 포커스 키워드로 반영하지 않는다. 에러를 주지도 않는다. 그냥 없는 것처럼 동작한다.

정확한 내부 원인까지는 확인하지 못했다. 확인한 건 하나다. 랭크매스의 점수 계산 엔진(SEO 점수를 계산하는 프로그램)이 브라우저 자바스크립트(JavaScript, 웹 브라우저에서 실행되는 프로그래밍 언어)로 돌아가서, 에디터 화면을 열었을 때만 점수가 계산된다. 키워드도 그 화면 안에서 넣으면 들어갔다.

스크립트가 이걸 감지해서 경고는 띄워주게 됐지만, 근본 해결은 아니었다. 에디터를 열고 직접 넣는 수밖에 없었다. 그러다 자동화할 방법을 찾기 시작했다.

wp.data 저장소에서 랭크매스 액션 찾기

wp-admin(워드프레스 관리자 화면) 글 에디터를 열어둔 상태에서 시작했다.

이 글의 코드는 브라우저 개발자 도구 콘솔(Console, 코드를 직접 실행할 수 있는 창)에 그대로 붙여 넣어도 돌아가는 코드다. 나는 같은 코드를 Playwright(브라우저 자동 조종 도구)로 실행했다. 워드프레스 블록 에디터는 wp.data라는 내부 저장소 시스템을 쓴다. 워드프레스 공식 문서에도 나오는 방식이다. 플러그인도 여기에 자기 저장소를 등록할 수 있다. 랭크매스도 그렇게 했다.

콘솔에 이렇게 입력하면 랭크매스 저장소에 접근할 수 있다.

wp.data.select('rank-math')

그리고 액션(Action, 저장소에 변경을 가하는 명령)을 확인하려면 이렇게 입력한다.

wp.data.dispatch('rank-math')

여기서 액션이 87개나 나왔다. 이름을 하나씩 보다가 바로 눈에 띄는 게 있었다. updateKeywords, updateDescription, updateSerpDescription, updateTitle. 이름만 봐도 뭘 하는지 명확했다.

아래 스크린샷은 이 방식으로 값을 넣은 글의 에디터 화면이다. 오른쪽 랭크매스 패널에 포커스 키워드와 점수(78/100)가 들어가 있다.

액션 이름은 랭크매스 버전에 따라 바뀔 수 있다. 지금 여기서 나열하는 이름들은 현재 ujinify.com에 설치된 랭크매스에서 직접 확인한 것들이다. 버전이 다르면 이름이 달라질 수 있으니 반드시 직접 확인해야 한다.

updateKeywords로 포커스 키워드 직접 입력하기

확인했으니 바로 써봤다. 콘솔에서 이렇게 입력했다.

wp.data.dispatch('rank-math').updateKeywords('세션 ID')

포커스 키워드 칸에 바로 들어갔다. 4초쯤 기다렸더니 랭크매스 점수가 22점에서 71점으로 뛰었다.

이게 맞는 방법이었다. REST API를 우회해서 에디터가 직접 받아서 처리하는 경로로 넣는 거다.

저장까지 마치려면 core/editor(워드프레스 에디터의 핵심 저장소)의 savePost()를 써야 한다. 비동기 함수라서 await를 붙여서 호출했다.

await wp.data.dispatch('core/editor').savePost()

내가 쓴 순서는 이렇다. updateKeywords를 먼저 호출하고, 점수 갱신을 잠깐 기다린 뒤, savePost()로 저장했다.

updateDescription, updateTitle로 다른 메타데이터 채우기

포커스 키워드만 넣었는데 점수가 71점이었다. 메타 설명(검색 결과에 표시되는 글 요약문)이 비어 있었다.

updateDescription으로 메타 설명을 넣었더니 73점이 됐다.

wp.data.dispatch('rank-math').updateDescription('여기에 메타 설명 텍스트를 넣는다')

같은 방식으로 SEO 제목도 바꿀 수 있다.

wp.data.dispatch('rank-math').updateTitle('여기에 SEO 제목을 넣는다')

updateSerpDescription도 있었는데, SERP에 표시되는 설명을 따로 관리하는 액션이다. 저장소에 이름이 있으니 확인해두면 된다.

이후 본문 첫 10% 안에 키워드가 없다는 항목이 걸려 있어서 첫 문단에 문장을 하나 추가했다. 긴 문단을 쪼개고, 제목이 키워드로 시작하게 순서를 바꿨다. 첫 번째 글은 최종 76점까지 올라갔다. 두 번째 글은 70점에서 시작해서 본문에 실제 캡처 이미지 2장을 추가했더니 78점이 됐다.

아래 스크린샷은 랭크매스 패널의 항목 목록이다. 통과 항목은 초록, 감점 항목은 빨강이다. URL 항목이 빨간색으로 남아 있다.

점수 갱신이 늦거나 예전 값이 나올 때 확인법

헷갈리는 지점이 있었다. window.rankMathEditor.resultManager.getResults()로 테스트 통과 여부를 읽었는데, 키워드가 제목에도 본문에도 분명히 있는데 전부 false로 나왔다.

화면 항목 목록에는 ‘제목에 포커스 키워드를 사용하고 있습니다’가 통과로 표시돼 있었다. 이 값은 갱신이 늦거나 예전 스냅샷(특정 시점의 데이터 복사본)을 돌려주는 거였다. 그래서 getResults() 반환값은 신뢰하지 않기로 했다. 화면에 보이는 항목 목록을 기준으로 삼는다.

또 하나. 통과(has: true)로 표시돼도 점수가 다 들어오지 않는 항목이 있다. 이미지 항목은 1/6점, 본문 길이는 2/8점처럼 부분 점수로 처리되는 경우가 있었다. 점수가 기대보다 낮게 나오면 이걸 먼저 확인해야 한다. 통과 여부만 보고 끝내면 안 된다.

화면에 뜬 점수와 데이터베이스에 저장된 점수가 다를 수도 있다. 저장 후에는 REST API로 get-post-seo-meta를 조회해서 DB에 실제로 반영된 점수를 따로 확인해야 한다. 이 단계를 빼면 안 된다. 화면 숫자만 믿다가 나중에 데이터가 다른 걸 발견하면 그때는 더 번거롭다.

이 방법의 한계와 실제 적용 시 주의점

이 방법에는 명확한 한계가 있다. 숨기지 않겠다.

• 브라우저 에디터를 열어야 한다. REST API나 MCP(Model Context Protocol, AI 도구가 외부 서비스에 명령을 보내는 통신 방식)만으로는 동작하지 않는다. 점수 계산 엔진이 브라우저 자바스크립트라서, 에디터 화면이 열려 있어야 실행된다.
• 액션 이름이 버전마다 다를 수 있다. updateKeywords, updateDescription 같은 이름은 현재 내 사이트 랭크매스에서 직접 확인한 것들이다. 업데이트 후에 이름이 바뀌면 동작하지 않는다. 사용 전에 반드시 wp.data.dispatch('rank-math')를 콘솔에서 직접 실행해서 목록을 확인해라.
• 저장 후 DB 값을 반드시 확인해야 한다. 화면 점수와 실제 DB에 저장된 점수가 다를 수 있다. REST API로 get-post-seo-meta를 조회하는 단계를 절대 생략하지 마라.
• 올릴 수 없는 점수가 존재한다. URL에 한국어 키워드가 없는 항목(5점), 유료 Content AI 항목(5점)은 구조적으로 올리기 어렵거나 올리지 않을 항목이다. 이 점수를 제외하면 실제 달성 가능한 최대치는 처음부터 그만큼 낮다.

수작업으로 키워드를 하나씩 입력하는 것보다는 낫다. 하지만 완전 자동화는 아니다. 에디터 화면을 열고 콘솔에서 코드를 실행하는 단계는 여전히 남는다.

지금은 이 정도로 쓰고 있다.

랭크매스 점수가 왜 에디터를 열어야 계산되는지는 랭크매스 SEO 16점→76점 글에, 같은 결의 버그 다섯 개는 워드프레스 SEO 버그 5개 총정리에 정리해뒀다.

같은 랭크매스 주제로 이어서 읽으면 좋은 글: 랭크매스 무료 기능으로 고아 포스트 2개 찾아낸 이야기, 메타 설명 오류 — 색인됐는데 검색 안 되던 이유.