Un lien collé dans l’éditeur Gutenberg qui se transforme automatiquement en aperçu enrichi, avec titre, image et description — ce comportement, familier pour un lien YouTube ou X, repose sur le protocole oEmbed, que WordPress intègre nativement depuis la version 2.9. Pour un front headless qui souhaite offrir la même expérience avec une source de contenu maison, plutôt qu’un service tiers déjà reconnu, il faut déclarer son propre fournisseur oEmbed.
Rappel : ce que fait oEmbed nativement
Lorsqu’un rédacteur colle une URL reconnue dans l’éditeur, WordPress interroge le point de terminaison oEmbed du service concerné, récupère une réponse structurée (titre, type de contenu, HTML d’intégration ou métadonnées), puis stocke cette réponse en cache pour éviter de la redemander à chaque affichage. Cette mécanique fonctionne aussi bien pour un site classique que pour un projet headless, à la différence près qu’un front découplé doit recevoir cette donnée via l’API REST plutôt que directement rendue en HTML par le thème.
Étape 1 : déclarer le fournisseur oEmbed personnalisé
add_action( 'init', function() {
wp_oembed_add_provider(
'#https://catalogue-partenaire\.example\.com/fiche/.*#i',
'https://catalogue-partenaire.example.com/api/oembed',
true
);
} );Le premier argument accepte une expression régulière (grâce au dernier paramètre à true), ce qui permet de reconnaître toute URL correspondant au motif du site partenaire, sans devoir lister chaque URL individuellement.
Étape 2 : fournir un point de terminaison oEmbed conforme
Le service distant interrogé doit répondre au format attendu par la spécification oEmbed, un simple objet JSON avec des champs standardisés :
{
"version": "1.0",
"type": "rich",
"title": "Fiche produit partenaire",
"author_name": "Catalogue Partenaire",
"html": "<div>Aperçu enrichi…</div>",
"width": 600,
"height": 200
}Si le service distant est lui-même une autre installation WordPress, le plugin natif de gestion des oEmbed peut suffire à générer cette réponse sans développement supplémentaire côté fournisseur.
Étape 3 : exposer la donnée oEmbed via l’API REST pour le front
Le contenu enrichi généré par oEmbed est normalement inséré directement dans le HTML du contenu, sous la forme d’un bloc wp:embed. Pour un front découplé qui ne rend jamais ce HTML tel quel, il est souvent préférable d’extraire la donnée structurée plutôt que le rendu HTML final :
add_filter( 'rest_prepare_post', function( $response, $post ) {
$donnees_embed = get_post_meta( $post->ID, '_oembed_donnees_structurees', true );
if ( $donnees_embed ) {
$response->data['aperçu_partenaire'] = json_decode( $donnees_embed, true );
}
return $response;
}, 10, 2 );Le front reçoit alors un objet structuré (titre, image, description) qu’il peut mettre en forme selon son propre système de composants, plutôt qu’un fragment HTML figé pensé pour un thème PHP classique.
Étape 4 : gérer le cache oEmbed avec attention
WordPress met en cache chaque réponse oEmbed dans une métadonnée du contenu qui contient le lien, afin d’éviter d’interroger le service distant à chaque affichage. Si le contenu distant change (une fiche produit partenaire mise à jour, par exemple), ce cache doit être invalidé explicitement, sinon l’aperçu affiché restera périmé. La fonction wp_oembed_reset_cache(), appliquée à l’article qui contient le lien, force un nouveau rafraîchissement au prochain affichage.
Ce qui reste hors du protocole oEmbed
Le protocole oEmbed reste pensé pour un aperçu d’intégration, pas pour une synchronisation complète de contenu entre deux systèmes. Pour un besoin de synchronisation plus profonde (mise à jour automatique du prix affiché, disponibilité en temps réel), un webhook dédié entre les deux systèmes reste plus adapté qu’un rafraîchissement du cache oEmbed, qui ne se déclenche que sur intervention explicite ou expiration du cache existant.
En résumé
Ajouter un fournisseur oEmbed personnalisé permet à un rédacteur de coller simplement un lien externe et d’obtenir un aperçu enrichi, sans devoir manuellement copier-coller titre et image. Pour un front headless, l’enjeu principal consiste à extraire la donnée structurée sous-jacente plutôt que le rendu HTML généré par défaut, afin de laisser le front décider librement de la mise en forme visuelle de cet aperçu.
