Ideal House
Aller au contenu principal

Intégration React / Next.js#

Utilisez le SDK navigateur ideal.house directement dans React ou Next.js. Il n'y a pas de package npm séparé ideal.house React dans ce guide.

Statut de vérification : le balisage du SDK a été vérifié par rapport au modèle actuel du tableau de bord ; la documentation officielle du cycle de vie/script de React et Next.js a été consultée le 7 septembre 2026. Aucune application client ni identifiants de production n'étaient disponibles, donc validez l'application compilée de bout en bout.

Avant de charger le SDK : ouvrez Tableau de bord → Paramètres, ajoutez l'origine de votre boutique en ligne à Allowed Origins (CORS), puis cliquez sur Enregistrer. Incluez le nom d'hôte publié et toutes les origines d'aperçu ou de préproduction que vous utilisez ; séparez plusieurs origines par des virgules. Voir les étapes de configuration.

Prérequis et limites#

Préparez un Shop ID, une Publishable Key, un SKU de catalogue importé, et une valeur de produit/variante rendue côté client. La Publishable Key peut être présente dans le balisage du navigateur. Conservez les secrets clients, les clés AI API et tout identifiant privé d'importation de produits sur le serveur.

Le SDK détecte les conteneurs DOM. React gère le moment où ces nœuds sont montés ; votre intégration gère la résolution de la variante actuelle et le remplacement du conteneur lorsque son SKU change.

Contrat minimal du SDK#

html
<script
  src="https://sdk.ideal.house/sdk.js"
  data-shop-id="<SHOP_ID>"
  data-publishable-key="<PUBLISHABLE_KEY>"
  async
></script>

<div data-idealhouse-button-container data-product-code="CHAIR-OAK-01"></div>

data-product-code doit être exactement égal au sku du catalogue ideal.house.

Composant React#

Montez un conteneur neuf chaque fois que le code produit change. Une clé key force React à remplacer le nœud DOM au lieu de réutiliser un conteneur que le SDK a peut-être déjà rempli :

tsx
type RoomVisualizerButtonProps = {
  productCode?: string | null;
};

export function RoomVisualizerButton({ productCode }: RoomVisualizerButtonProps) {
  const code = productCode?.trim();
  if (!code) return null;

  return (
    <div
      key={code}
      data-idealhouse-button-container
      data-product-code={code}
    />
  );
}

Transmettez le SKU de la variante sélectionnée, pas un titre de produit, un slug de route, un ID de base de données ou un libellé d'option. Si la sélection est incomplète, rendez null.

Chargeur App Router Next.js#

Placez le SDK une seule fois dans la mise en page partagée la plus étroite qui couvre les pages de produits. Next.js documente afterInteractive pour les scripts qui se chargent après une certaine hydratation :

tsx
import Script from 'next/script';

export function IdealhouseSdk() {
  return (
    <Script
      id="idealhouse-room-visualizer-sdk"
      src="https://sdk.ideal.house/sdk.js"
      strategy="afterInteractive"
      data-shop-id={process.env.NEXT_PUBLIC_IDEALHOUSE_SHOP_ID}
      data-publishable-key={process.env.NEXT_PUBLIC_IDEALHOUSE_PUBLISHABLE_KEY}
    />
  );
}

Rendez IdealhouseSdk une seule fois depuis une mise en page, puis rendez RoomVisualizerButton à l'intérieur d'un composant client qui gère la sélection de variante. Les valeurs préfixées par NEXT_PUBLIC_ sont expédiées au navigateur ; utilisez-les uniquement pour le Shop ID et la Publishable Key.

Pour le Pages Router ou le React pur, créez le script une seule fois dans le shell HTML, ou utilisez un effet de niveau supérieur unique :

tsx
useEffect(() => {
  if (document.querySelector('script[src="https://sdk.ideal.house/sdk.js"]')) return;
  const script = document.createElement('script');
  script.src = 'https://sdk.ideal.house/sdk.js';
  script.async = true;
  script.dataset.shopId = '<SHOP_ID>';
  script.dataset.publishableKey = '<PUBLISHABLE_KEY>';
  document.head.append(script);
}, []);

Le Strict Mode de React effectue intentionnellement un cycle de configuration de développement supplémentaire, donc la vérification de doublon est requise. Ne supprimez pas la balise partagée du SDK lorsqu'un composant de produit individuel est démonté.

Les changements de route côté client ne rechargent pas le script de la mise en page. Attribuez à chaque contrôle produit une clé combinant une identité de route stable et le SKU si le même SKU peut apparaître dans plusieurs vues montées simultanément. Pour les grilles, chaque carte a besoin de son propre SKU. Lorsque le défilement infini ajoute des cartes, React monte naturellement de nouveaux conteneurs propres.

Pour la sélection de variante, dérivez selectedVariant.sku de votre état de commerce et transmettez-le en tant que productCode. N'appelez pas une méthode de rafraîchissement non documentée du SDK. Les tiroirs d'aperçu rapide et les transitions de route doivent démonter leur composant précédent afin que le DOM traité ne fuit pas vers le produit suivant.

Si l'hydratation de React signale une incohérence, assurez-vous que le rendu serveur et le premier rendu client sont en accord. Il est valide de ne rendre aucun conteneur jusqu'à ce que l'état de commerce client ait résolu le SKU.

Importer les données produit#

Mappez le SKU canonique de variante du backend de commerce vers le sku de ideal.house. Utilisez Téléversement de produits, puis consultez importer des produits, état de la tâche, liste des produits, mettre à jour les produits, supprimer un produit, et erreurs et nouvelles tentatives.

Toute requête de catalogue backend, webhook, synchronisation planifiée ou service de jeton de lancement reste du code d'application ; le SDK côté navigateur ne le fournit pas.

Vérifier et supprimer#

Testez le rendu/hydratation serveur, un chargement forcé, la navigation client, les boutons Retour/Avance du navigateur, les changements de variante, les SKU nuls/inconnus, les cartes répétées, l'aperçu rapide, les états Suspense/chargement, le mobile, les contrôles de consentement et une compilation de production. Confirmez une requête SDK et l'égalité exacte du code produit DOM/SKU. Inspectez les paquets client compilés pour les secrets accidentels.

Pour supprimer l'intégration, supprimez le composant ou la balise SDK partagés ainsi que toutes les utilisations de RoomVisualizerButton, retirez les deux variables d'environnement publiques, recompilez, puis vérifiez que l'URL du SDK et le balisage data-idealhouse-* ont disparu.

Références officielles du framework#