Rank Math schema ACF: corrigir custom fields no JSON-LD

Tipo SEO Tecnico

Nome do erro Schema do Rank Math nao le custom fields do ACF EN: Rank Math schema not reading ACF custom fields

Severidade Atenção

Descrição O Rank Math schema ACF falha quando a variavel %customfield(field-name)% aponta para um nome que não casa com a meta key do ACF, ou quando o campo guarda um array ou objeto, fazendo a propriedade do JSON-LD sair vazia ou com dado errado.

O que é schema do Rank Math sem custom fields do ACF?

O Rank Math schema ACF e a integração entre o Schema Generator do Rank Math e os campos personalizados do Advanced Custom Fields PRO. Em vez de digitar um valor fixo numa propriedade do schema (como preco, autor ou data de evento), você insere a variavel %customfield(nome-do-campo)% e o Rank Math busca esse valor no banco a cada carregamento da página, deixando o JSON-LD dinâmico e sempre atualizado por post.

O ponto que quase todo mundo erra e técnico: o ACF grava o valor de cada campo como um postmeta comum, onde a meta key e exatamente o nome do campo (field name), não o rotulo (label) que aparece no editor. A variavel %customfield(field-name)% do Rank Math le esse postmeta direto pela meta key. Quando o nome dentro da variavel não bate com a meta key real, ou quando o campo guarda um valor serializado (array, objeto, repeater), o Rank Math não consegue extrair um texto valido e a propriedade do schema sai vazia, derrubando a validação do Google.

Como identificar

No Schema Markup Validator ou no teste de Resultados Aprimorados do Google a propriedade preenchida com %customfield(…)% aparece vazia ou com o valor literal da variavel, em vez do dado do campo.
O bloco de schema (Article, Product, Event) e gerado, mas o campo que deveria vir do ACF some do JSON-LD final visto no código-fonte da página.
Mensagem ‘Campo obrigatório ausente’ ou ‘Missing field’ no Search Console para a propriedade ligada ao ACF, mesmo com o campo preenchido no editor.
Em campos do tipo Repeater, Group ou Relationship a propriedade do schema sai com um valor quebrado como ‘Array’ ou um id numerico em vez do texto esperado.
Ao trocar o nome do grupo de campos ou do field no ACF, o schema que antes funcionava passa a sair vazio sem nenhum aviso no editor.

Antes de começar: Antes de adicionar snippets ao functions.php ou de mexer no template de schema em producao, faça backup do site (arquivos e banco) ou teste em um ambiente de staging, para reverter caso o JSON-LD da página quebre.

Como prevenir

Padronize os field names do ACF em minusculas com underscore e documente cada um, para sempre usar o nome certo dentro de %customfield(field-name)% sem depender do rotulo.
Antes de ligar um campo ao schema, confirme que ele guarda texto simples; para Repeater, Group, Relationship e Object, planeje um meta espelho desde o inicio.
Evite renomear field names de campos já ligados ao schema; se precisar, atualize a variavel no Schema Generator no mesmo deploy para não deixar a propriedade vazia.
Valide o JSON-LD no Schema Markup Validator a cada mudanca de campos ou de template de schema, antes de publicar, para pegar propriedade vazia cedo.

Causa

A variavel usa o rotulo (label) do campo em vez do field name real do ACF: o Rank Math le a meta key, que corresponde ao field name, entao %customfield(Preco do Produto)% falha enquanto %customfield(preco_produto)% funciona.
O campo ACF guarda um valor serializado (Repeater, Group, Relationship, ou Select múltiplo): o %customfield% le o postmeta cru e devolve um array serializado, que não vira texto valido na propriedade do schema.
O field tem Return Format definido como Object ou Array (comum em Image, Post Object e Taxonomy): o postmeta guarda apenas o id, entao a variavel retorna um número em vez do valor legivel esperado pelo schema.
O grupo de campos do ACF não casa com o post sendo renderizado por regra de localizacao, ou o campo esta vazio naquele post específico, fazendo o postmeta não existir e a variavel retornar string vazia.
O campo pertence a uma options page do ACF (acf_add_options_page), cujos valores ficam em option e não em postmeta do post, fora do alcance da variavel %customfield% que so le meta keys do post atual.

Como resolver

Descubra o field name real do campo no ACF: Abra o grupo de campos no ACF e copie o valor do campo Nome (Field Name), não o Rotulo (Label). E esse nome, em minusculas com underscore, que vira a meta key no banco e que o Rank Math precisa receber dentro da variavel.
```
Painel WP -> ACF -> Grupos de Campos -> abra o grupo
Clique no campo e anote o valor do campo 'Nome do Campo' (Field Name)
```
Use a variavel customfield com o field name correto no Schema Generator: No editor do post, abra a aba Schema do Rank Math, edite o template e na propriedade desejada insira a variavel com o field name exato. Conforme a documentação do Rank Math, a sintaxe e %customfield(field-name)%, trocando field-name pelo nome real do campo.
```
Editor do post -> Rank Math -> Schema -> Editar o schema
Na propriedade (ex.: author, price), insira: %customfield(field_name)%
Substitua field_name pelo nome anotado no passo 1
```
Confirme o valor cru gravado no postmeta: Para ter certeza de que a meta key existe e guarda texto simples, confira o valor cru do campo no post. Se o retorno for um array serializado (comeca com a:), o campo não serve direto para o schema e precisa ser exposto por um campo auxiliar.
```
Painel WP -> Ferramentas -> via plugin de inspecao de postmeta, busque a meta key do passo 1
Confirme que o valor e um texto simples, não algo iniciado por 'a:1:{' (array serializado)
```
Para campos serializados, exponha um meta espelho em texto: Repeater, Group, Relationship e campos com Return Format Object não saem como texto pela variavel. Crie um postmeta auxiliar simples com o valor já formatado via hook acf/save_post e aponte o %customfield% para essa meta key espelho.
```
Adicione o snippet PHP da seção de código ao functions.php do tema filho ou a um plugin próprio
Salve o post para gerar a meta key espelho
No Schema Generator, aponte a propriedade para %customfield(meta_espelho)%
```
Valide o JSON-LD no Schema Markup Validator: Depois do ajuste, rode a URL do post no validador para confirmar que a propriedade saiu preenchida com o dado do ACF. O próprio Rank Math recomenda validar o resultado antes de considerar o schema correto.
```
Abra o Schema Markup Validator (validator.schema.org) e cole a URL do post
Confirme que a propriedade ligada ao ACF mostra o valor do campo, não a variavel literal
```

PHP

<?php
// Espelha um campo ACF serializado (Repeater/Group/Object) em um postmeta de texto
// simples, para o Rank Math ler via %customfield(rm_autor_nome)% no Schema Generator.
add_action( 'acf/save_post', 'full_acf_espelho_schema', 20 );
function full_acf_espelho_schema( $post_id ) {
    if ( ! function_exists( 'get_field' ) ) {
        return;
    }
    // 'autor' = field name do ACF; ajuste para o seu campo.
    $valor = get_field( 'autor', $post_id );

    // Se for array/objeto (Post Object, Relationship), extrai um texto legivel.
    if ( is_array( $valor ) ) {
        $valor = isset( $valor['post_title'] ) ? $valor['post_title'] : reset( $valor );
    } elseif ( is_object( $valor ) && isset( $valor->post_title ) ) {
        $valor = $valor->post_title;
    }

    // Grava a meta key espelho que o Rank Math vai consumir.
    update_post_meta( $post_id, 'rm_autor_nome', sanitize_text_field( (string) $valor ) );
}

Perguntas frequentes

Qual a sintaxe da variavel para puxar um campo ACF no schema do Rank Math

Conforme a documentação do Rank Math, a sintaxe e %customfield(field-name)%, trocando field-name pelo nome real do campo. Como o ACF grava o valor como postmeta usando o field name como meta key, a variavel le esse valor direto quando os nomes batem.

Por que a propriedade do schema sai vazia mesmo com o campo ACF preenchido

Quase sempre porque a variavel aponta para o rotulo do campo em vez do field name real, ou porque o campo guarda um array serializado. O Rank Math le a meta key exata, entao confira o Field Name no ACF e use exatamente esse valor na variavel.

O Rank Math le campos Repeater ou Group do ACF no schema

Não de forma direta. Esses campos gravam um valor serializado no postmeta e a variavel %customfield% devolve esse array cru, que não vira texto valido. A saida e criar um postmeta espelho em texto via hook acf/save_post e apontar a variavel para ele.

Preciso editar código para usar custom fields do ACF no schema

Para campos de texto simples não: basta inserir %customfield(field-name)% no Schema Generator. So precisa de código quando o campo e serializado ou tem Return Format Object, situacao em que você cria um meta espelho em PHP com o valor já formatado.

Por que um campo de imagem ou Post Object do ACF retorna um número no schema

Porque o postmeta desses campos guarda apenas o id do anexo ou do post, não a URL ou o título. A variavel le esse id cru. Para o schema, exponha a URL ou o texto final num meta auxiliar e aponte a variavel para essa meta key.

A variavel customfield le campos de uma options page do ACF

Não. Campos de options page são salvos na tabela de options, não no postmeta do post atual, e a variavel %customfield% so enxerga meta keys do post sendo renderizado. Para valores globais, use outra variavel ou um hook que escreva no postmeta do post.

Devo validar o schema depois de ligar um campo ACF

Sim. O Rank Math recomenda validar o resultado no Schema Markup Validator. Cole a URL do post e confirme que a propriedade mostra o valor do campo, e não a variavel literal, antes de considerar o schema correto.

Informativo

Como corrigir o erro de llms.txt no SEOPress

O erro de llms.txt no SEOPress acontece quando o recurso esta desligado no painel ou quando as regras de reescrita do WordPress não foram atualizadas, fazendo o endereco /llms.txt retornar 404 ou vir em branco.

Grave

Como corrigir o schema de produto do Rank Math no WooCommerce

O schema de produto do Rank Math no WooCommerce fica invalido quando o markup sai sem offers, review ou aggregateRating, quando aparece em páginas de arquivo, ou quando o WooCommerce duplica a marcacao Product.

Atenção

Como corrigir canibalizacao de keyword no WordPress com Rank Math

A canibalizacao de keyword no WordPress ocorre quando duas ou mais páginas do mesmo site disputam o mesmo termo de busca, dividindo cliques, autoridade e sinais de relevancia. O Rank Math ajuda a detectar a focus keyword repetida e a corrigir com consolidacao, canonical ou redirecionamento 301.

Crítico

Como corrigir páginas com noindex acidental no WordPress

O noindex acidental no WordPress acontece quando uma página recebe a diretiva robots noindex sem intencao, instruindo o Google a remove-la do indice. A causa mais comum e a opção 'Desencorajar mecanismos de busca' nas Configurações de Leitura, ou um noindex herdado do plugin de SEO.

Grave

Como corrigir robots.txt bloqueando páginas importantes no WordPress

Um robots txt no WordPress bloqueando páginas importantes acontece quando uma regra Disallow ampla impede o Google de rastrear seções do site, derrubando o tráfego orgânico. A causa mais comum é a opção 'Desencorajar mecanismos de busca' nas Configurações de Leitura ou uma regra herdada de plugin que barra pastas indevidas.

Atenção

Como corrigir a integração com o Google Search Console no SEOPress

O erro de integração do SEOPress com o GSC (Google Search Console) ocorre quando a meta tag de verificação não é impressa no head do site ou quando a autorização da API do Google Search Console (recurso do SEOPress PRO) expira ou é concedida para a conta ou propriedade errada.

Setores

Extensões

Integrações

Como corrigir o schema do Rank Math que não le custom fields do ACF PRO no WordPress

O que é schema do Rank Math sem custom fields do ACF?

Como identificar

Como prevenir

Causa

Como resolver

Perguntas frequentes

Itens relacionados

Como corrigir o erro de llms.txt no SEOPress

Como corrigir o schema de produto do Rank Math no WooCommerce

Como corrigir canibalizacao de keyword no WordPress com Rank Math

Como corrigir páginas com noindex acidental no WordPress

Como corrigir robots.txt bloqueando páginas importantes no WordPress

Como corrigir a integração com o Google Search Console no SEOPress

Setores

Extensões

Integrações

Extensões

Hero Sections

Seções de CTA

Login

Blog

Cabeçalhos

Seções de FAQ

Cadastro

Blog individual

Rodapés

Seções de contato

Seções de preços

Faixas

Portfólio

Seções de equipe

Números

Logotipos