wp_oembed_add_provider : reconnaître un service vidéo maison

Un client du secteur de la formation professionnelle héberge ses vidéos sur sa propre plateforme, développée en interne, plutôt que sur YouTube ou Vimeo. Ses rédacteurs, habitués au confort d’oEmbed pour les vidéos YouTube, ont naturellement essayé de coller un lien de leur plateforme maison directement dans l’éditeur, en espérant voir apparaître un lecteur intégré. Rien ne s’est passé, évidemment : WordPress ne connaît que les fournisseurs déclarés dans sa liste blanche.

La bonne nouvelle, c’est que cette liste n’est pas figée. La fonction wp_oembed_add_provider() permet d’y ajouter n’importe quel service tiers, à condition que celui-ci expose un point de terminaison conforme aux spécifications oEmbed.

Comment fonctionne la reconnaissance oEmbed

Quand un lien est collé seul sur sa propre ligne dans l’éditeur, WordPress compare son domaine à la liste des fournisseurs enregistrés. En cas de correspondance, il interroge le point de terminaison oEmbed du service pour récupérer un objet JSON contenant, entre autres, le code d’intégration HTML du lecteur. Ce mécanisme est entièrement découplé du service : YouTube, Vimeo ou une plateforme interne sont traités de façon identique dès lors que le format de réponse respecte la norme.

Déclarer le fournisseur personnalisé

Supposons que la plateforme du client s’appelle « FormaTube », accessible sur videos.formatube-client.fr, avec un point de terminaison oEmbed disponible sur /oembed :

function ft_ajouter_fournisseur_oembed() {
    wp_oembed_add_provider(
        '#https?://videos\.formatube-client\.fr/v/.*#i',
        'https://videos.formatube-client.fr/oembed',
        true // le deuxième paramètre indique une regex plutôt qu'un simple domaine
    );
}
add_action( 'init', 'ft_ajouter_fournisseur_oembed' );

Le troisième paramètre à true indique que le premier argument est une expression régulière plutôt qu’une simple URL avec un caractère générique. C’est utile pour ne reconnaître qu’un format d’URL précis, par exemple uniquement les liens de visionnage individuel et non les pages de catégorie de la plateforme.

Ce que doit renvoyer le point de terminaison côté plateforme vidéo

Côté serveur vidéo, la réponse JSON attendue par WordPress ressemble à ceci pour un type video :

{
  "version": "1.0",
  "type": "video",
  "provider_name": "FormaTube",
  "title": "Introduction à la gestion de projet",
  "html": "<iframe src=\"https://videos.formatube-client.fr/embed/42\" width=\"640\" height=\"360\" frameborder=\"0\" allowfullscreen></iframe>",
  "width": 640,
  "height": 360
}

Sans ce format exact, WordPress affichera simplement le lien brut ou une carte de type lien riche générique, sans jamais déclencher d’erreur visible côté rédacteur, ce qui rend le diagnostic parfois délicat.

Diagnostiquer une intégration qui ne s’affiche pas

• Vérifier que le lien est bien seul sur sa ligne, sans texte ni autre élément autour dans le même paragraphe.
• Tester le point de terminaison oEmbed directement dans un navigateur avec les paramètres ?url=...&format=json.
• Vider le cache d’oEmbed de WordPress si un test précédent a échoué : les résultats, y compris les échecs, sont mis en cache dans la table wp_postmeta sous forme de transients liés à l’article.
• Confirmer que le domaine du point de terminaison n’est pas bloqué par une règle de pare-feu applicatif entre le serveur WordPress et la plateforme vidéo.

Étendre le principe à Gutenberg

Le bloc natif « Intégration » (embed) de l’éditeur de blocs s’appuie sur exactement ce même mécanisme côté serveur. Une fois le fournisseur déclaré via wp_oembed_add_provider(), il fonctionne aussi bien dans l’éditeur classique que dans un bloc Gutenberg dédié, sans configuration supplémentaire côté JavaScript. Ce point ne concerne toutefois pas la récupération de ce contenu en contexte headless, qui suit une autre logique déjà traitée séparément.

En résumé

wp_oembed_add_provider() transforme n’importe quelle plateforme vidéo interne en fournisseur de premier ordre pour les rédacteurs, à condition qu’elle expose une réponse oEmbed conforme. Le confort gagné pour l’équipe éditoriale justifie largement les quelques lignes de configuration nécessaires côté WordPress.