# Como corrigir o Vídeo Schema no Rank Math PRO

O erro do Vídeo Schema no Rank Math PRO ocorre quando o Vídeo Rich Snippet e gerado sem os campos obrigatorios pelo Google, como thumbnailUrl, contentUrl ou embedUrl e uploadDate, fazendo o Teste de Resultados Aprimorados reprovar a marcacao do vídeo.

## O que é Vídeo Schema no Rank Math PRO?

O Vídeo Schema no Rank Math PRO e a marcacao estruturada do tipo VideoObject que descreve um vídeo da página para o Google, permitindo o Vídeo Rich Snippet com thumbnail, título, data de envio e momentos-chave nos resultados de busca. No Rank Math, esse schema chega ao post de duas formas: pela detecção automática de vídeos do conteúdo no recurso PRO de Vídeo Sitemap, e pela adicao manual do schema Vídeo no Schema Generator, dentro da aba Schema do editor.

O erro aparece quando essa marcacao e emitida incompleta ou com dados que não casam com o vídeo real. Segundo a documentação do Rank Math, a detecção automática preenche os campos obrigatorios como thumbnail, embed URL e duracao, mas isso depende dos módulos Schema e Sitemap ativos e, no caso de vídeos do YouTube, de uma chave de API valida para buscar os detalhes. Quando algo nessa cadeia falha, o Google reporta campos ausentes ou invalidos no Teste de Resultados Aprimorados e o Vídeo Rich Snippet não e exibido.

## Como identificar

- O Teste de Resultados Aprimorados do Google acusa 'Campo ausente "thumbnailUrl"' ou 'Campo ausente "contentUrl" ou "embedUrl"' no item Vídeo da página.
- No Search Console, o relatório de Vídeos mostra 'Itens invalidos' com o aviso 'Campo obrigatório ausente: uploadDate' ou aviso equivalente para duration.
- A página tem vídeo embutido, mas nenhum Vídeo Rich Snippet (thumbnail e duracao) aparece na busca, mesmo após a reindexacao.
- Na aba Schema do Rank Math o tipo Vídeo aparece com campos em branco, como Content URL ou Thumbnail URL, ou apontando para um arquivo que não existe.
- O Vídeo Sitemap em /vídeo-sitemap.xml fica vazio ou não lista a URL do post que contem o vídeo.

**Antes de começar:** Antes de alterar módulos do Rank Math, editar schema em lote ou trocar a chave de API em producao, faça um backup do site (arquivos e banco de dados) ou teste primeiro em um ambiente de staging, para reverter caso a marcacao quebre em outras páginas.

## Como prevenir

- Mantenha os módulos Schema e Sitemap do Rank Math sempre ativos e use uma chave de API do YouTube com cota própria do projeto para a detecção automática não falhar.
- Ao publicar posts com vídeo, valide a URL no Teste de Resultados Aprimorados antes de divulgar, garantindo thumbnailUrl, contentUrl ou embedUrl e uploadDate presentes.
- Padronize a forma de embutir vídeos (bloco nativo ou oEmbed) para que o Rank Math varra o conteúdo, e mapeie em Sitemap -> Vídeos os custom fields usados por outros plugins.
- Monitore o relatório Vídeos no Search Console periodicamente para pegar itens invalidos antes que o Vídeo Rich Snippet caia da busca.

Erros relacionados

- [Como corrigir marcação inválida no Schema Generator do Rank Math](https://full.services/wp-fixer/corrigir-schema-generator-rank-math/)
- [Como corrigir schema markup quebrado no WordPress](https://full.services/wp-fixer/corrigir-schema-markup-quebrado-wordpress/)
- [Como corrigir Breadcrumbs duplicados entre Astra Pro e Rank Math](https://full.services/wp-fixer/corrigir-breadcrumbs-duplicados-astra-pro-rank-math/)

## Causa

- O módulo Schema ou o módulo Sitemap do Rank Math esta desativado em Rank Math -> Painel -> Módulos, entao a detecção automática de vídeo e o Vídeo Sitemap PRO não rodam e o VideoObject sai sem os campos preenchidos.
- O vídeo e do YouTube e a chave de API do YouTube em Rank Math -> Sitemap -> Vídeos esta ausente, invalida ou com cota esgotada, impedindo o Rank Math de buscar thumbnail, duracao e data de envio para preencher o schema.
- O schema Vídeo foi adicionado manualmente pelo Schema Generator com os campos Thumbnail URL e Content URL ou Embed URL vazios ou usando variaveis que não resolvem, deixando thumbnailUrl e contentUrl fora da marcacao final.
- O campo Upload Date do schema Vídeo esta em branco ou em formato fora do ISO 8601, fazendo o Google rejeitar uploadDate como obrigatório ausente ou invalido.
- O vídeo esta embutido por um método que o Rank Math não varre, como um shortcode de outro plugin ou um custom field não mapeado em Rank Math -> Sitemap -> Vídeos, de modo que o post nem entra no Vídeo Sitemap nem recebe o VideoObject automático.

## Como resolver

1. Ative os módulos Schema e Sitemap do Rank Math: A detecção automática de vídeo e o Vídeo Sitemap PRO so funcionam com esses dois módulos ligados. Ative ambos antes de qualquer ajuste de campo, conforme a documentação do Rank Math.

```
Painel WP -> Rank Math SEO -> Painel -> aba Módulos
Ative o módulo Schema (Structured Data)
Ative o módulo Sitemap
```

2. Configure a chave de API do YouTube para vídeos externos: Se o vídeo vem do YouTube, o Rank Math precisa de uma chave de API valida para buscar thumbnail, duracao e data de envio automaticamente. Sem ela, o schema sai com campos ausentes.

```
Painel WP -> Rank Math SEO -> Sitemap Settings -> Vídeos
Cole a chave em 'YouTube API Key' (gerada no Google Cloud Console)
Salve as alterações e atualize o post que contem o vídeo
```

3. Preencha os campos obrigatorios no Schema Generator: Abra o post no editor, va na aba Schema e edite o tipo Vídeo. Garanta os campos exigidos pelo Google: nome, descrição, thumbnail e a URL do vídeo ou do embed, além da data de envio em formato de data.

```
Editor do post -> aba Rank Math -> Schema -> Edit no item Vídeo
Preencha Thumbnail URL (thumbnailUrl) com uma imagem acessivel publicamente
Preencha Content URL (contentUrl) ou Embed URL (embedUrl) do vídeo
Preencha Upload Date no formato AAAA-MM-DD
```

4. Valide a marcacao no Teste de Resultados Aprimorados: Depois de salvar, rode a URL do post no Teste de Resultados Aprimorados do Google. Ele aponta exatamente qual campo do Vídeo ainda esta ausente ou invalido para você corrigir.

```
Abra https://search.google.com/test/rich-results
Cole a URL pública do post e clique em Testar URL
Confira o item Vídeo e corrija os campos sinalizados como ausentes
```

5. Reenvie a página ao Google pelo Search Console: Com o schema valido, peca a reindexacao para o Google reprocessar a marcacao. O Vídeo Rich Snippet so reaparece após esse novo rastreamento.

```
Google Search Console -> Inspecao de URL -> cole a URL do post
Clique em 'Solicitar indexação'
Acompanhe o relatório Vídeos em Search Console -> Aprimoramentos
```


## Código

```php
<?php
/**
 * Completa campos obrigatorios do Video Schema do Rank Math
 * quando a deteccao automatica deixa thumbnailUrl ou uploadDate vazios.
 */
add_filter( 'rank_math/snippet/rich_snippet_video_entity', 'full_fix_video_schema' );
function full_fix_video_schema( $entity ) {
    if ( empty( $entity['thumbnailUrl'] ) ) {
        $thumb = get_the_post_thumbnail_url( get_the_ID(), 'full' );
        if ( $thumb ) {
            $entity['thumbnailUrl'] = esc_url_raw( $thumb );
        }
    }
    if ( empty( $entity['uploadDate'] ) ) {
        // Google exige ISO 8601; usa a data de publicacao do post.
        $entity['uploadDate'] = get_the_date( 'c', get_the_ID() );
    }
    return $entity;
}
```

## Perguntas frequentes

### Por que o Vídeo Schema do Rank Math acusa campo ausente no teste do Google

O Google exige nome, descrição, thumbnailUrl, uploadDate e a URL do vídeo em contentUrl ou embedUrl. Quando o Rank Math gera o VideoObject sem um desses campos, o Teste de Resultados Aprimorados aponta o item Vídeo como invalido por campo obrigatório ausente.

### O Rank Math gera o Vídeo Schema automaticamente

Sim. Segundo a documentação do Rank Math, ele detecta vídeos no conteúdo e adiciona o post ao Vídeo Sitemap com os campos exigidos, como thumbnail, embed URL e duracao. Isso depende dos módulos Schema e Sitemap ativos e, para vídeos do YouTube, de uma chave de API valida.

### Preciso de uma chave de API do YouTube para o Vídeo Schema funcionar

Para vídeos do YouTube, sim. A chave permite ao Rank Math buscar thumbnail, duracao e data de envio e preencher o schema. Sem chave valida ou com a cota esgotada, esses campos saem em branco e o Vídeo Rich Snippet não aparece.

### Qual a diferenca entre contentUrl e embedUrl no Vídeo Schema

O contentUrl aponta para o arquivo de vídeo direto, enquanto o embedUrl aponta para o player incorporavel, como a URL de embed do YouTube. O Google exige pelo menos um dos dois, e o Rank Math oferece ambos os campos no Schema Generator.

### Por que o Vídeo Rich Snippet não aparece mesmo com o schema valido

A marcacao valida e condicao, mas não garantia. Após corrigir os campos, peca a reindexacao pelo Search Console e aguarde o Google reprocessar a página. O snippet so reaparece em um novo rastreamento e a criterio do Google.

### Como saber qual campo do Vídeo esta faltando

Rode a URL do post no Teste de Resultados Aprimorados do Google. Ele lista o item Vídeo e marca cada campo ausente ou invalido, como thumbnailUrl ou uploadDate, indicando exatamente o que corrigir no Schema Generator do Rank Math.

### O Vídeo Sitemap vazio impede o Vídeo Schema

São recursos ligados. Se o post não entra no Vídeo Sitemap, em geral o Rank Math não detectou o vídeo, e o VideoObject automático também não e emitido. Confira se o módulo Sitemap esta ativo e se o método de embed do vídeo e varrido pelo plugin.

**Fonte:** [Rank Math — Video Sitemap (Knowledge Base)](https://rankmath.com/kb/video-sitemap/)