Widgets

Une intégration peut fournir des widgets : des blocs réutilisables que les utilisateurs insèrent dans leurs emails, popups ou « smart content ».

Rien à héberger de votre côté

Un widget est une déclaration (JSON) stockée dans votre intégration. ShopiMind le rend lui-même, côté serveur, par destinataire. Vous n'exposez aucune route de rendu ni iframe, et aucun code partenaire n'est jamais exécuté.

Les widgets se déclarent dans le champ widgets de votre intégration (un tableau de déclarations). Chaque déclaration a une key, un name/description localisés, des targets (email_template | popup | smart_content), un render_type, et un config_schema.

Les trois types de rendu

Forme	Champs	Rendu
render_type: "image"	image_url_template	ShopiMind construit la balise <img> à partir de votre URL.
render_type: "html" + render_mode: "static"	html_template (+ css_template)	Votre HTML/CSS, validé et sanitisé (aucun JS), résolu par destinataire. Compatible email.
render_type: "html" + render_mode: "dynamic"	renderer_key	Réutilise un renderer ShopiMind existant (ex. spm_countdown). Email → GIF, web → JS live.

Widget image

{
  "key": "promo_banner",
  "name": { "fr": "Bannière promo", "en": "Promo banner" },
  "targets": ["email_template", "popup"],
  "render_type": "image",
  "image_url_template": "https://votre-service/img?promo={widget.code}&u={var=contact.email}"
}

Widget HTML statique (render_mode: "static")

Votre html_template + css_template sont stockés, puis sanitisés et résolus par destinataire (aucun <script>, compatible email).

{
  "key": "info_card",
  "name": { "fr": "Carte info", "en": "Info card" },
  "targets": ["email_template", "popup", "smart_content"],
  "render_type": "html",
  "render_mode": "static",
  "html_template": "<table ...><td>{widget.title}<a href=\"{widget.cta_url}\">{widget.cta_label}</a></td></table>",
  "css_template": ".spm-card{background:{widget.bg};color:{widget.fg}}",
  "config_schema": {
    "fields": [
      { "key": "title",   "type": "text",  "default": "Bonjour {var=contact.first_name}", "supports_variables": true },
      { "key": "cta_url", "type": "text",  "default": "{var=shop.url}", "supports_variables": true },
      { "key": "bg",      "type": "color", "default": "#3CB4A4" },
      { "key": "fg",      "type": "color", "default": "#FFFFFF" }
    ]
  }
}

Widget HTML dynamique (render_mode: "dynamic")

Vous réutilisez un renderer ShopiMind existant via renderer_key. Le code du renderer vit chez ShopiMind (co-conçu avec vous) — vous n'envoyez aucun script.

{
  "key": "deadline_countdown",
  "name": { "fr": "Compte à rebours", "en": "Countdown" },
  "targets": ["email_template", "popup", "smart_content"],
  "render_type": "html",
  "render_mode": "dynamic",
  "renderer_key": "spm_countdown",
  "config_schema": {
    "fields": [
      { "key": "endDate",  "type": "datetime" },
      { "key": "timezone", "type": "text", "default": "Europe/Paris" },
      { "key": "digitBgColor", "type": "color", "default": "#1a1a1a", "strip_hash": true }
    ]
  }
}

Placeholders dans le rendu

Trois familles, toutes résolues côté serveur :

Placeholder	Source	Résolu
{var=…}	Données ShopiMind par destinataire — ex. {var=contact.first_name}, {var=shop.url}, {var=custom_data.<schema>.<champ>}	Au moment de l'envoi, par destinataire
{widget.<champ>}	La config du widget choisie par l'utilisateur (son config_schema)	Au rendu
{integration.<champ>}	Les valeurs non sensibles de la config de l'intégration	Au rendu

Un secret ne transite jamais dans une URL d'image / un HTML rendu (seules les valeurs non sensibles alimentent {integration.*}).

Config posée par l'intégrateur

Un champ de config_schema déclaré owner: "integrator" est invisible côté marchand : c'est l'intégrateur qui pose sa valeur par boutique (via l'API, voir Config intégrateur). Elle est résolue ici en {integration.<key>}, avec le default déclaré comme repli. Pratique pour une URL de tracking, un identifiant de compte, etc.

config_schema d'un widget

Un widget déclare un config_schema (mêmes types que la config d'intégration) — les valeurs choisies par l'utilisateur sont résolues via {widget.<champ>} :

• Types de champ : text · number · color · select · checkbox · datetime.
• Disposition : fields (à plat) ou groups (chaque groupe = un onglet).
• Flags utiles : default, options (pour select), label, supports_variables (autorise un {var=…} dans le champ), strip_hash (couleur sans le #, pour certaines URLs d'image).