Intégration Ionic / Capacitor

Utilisez le custom element <ekoo-widget> dans vos applications Ionic (React, Vue, Angular)

Le widget charge automatiquement sa configuration depuis le backoffice. Les attributs d'apparence sont des surcharges optionnelles — inutile de les définir si le backoffice est configuré.

Attributs principaux

data-ekooReq

string

UUID du site Ekoo. Visible dans le backoffice → Paramètres du site.

data-ekoo-product-idReq

string

Référence produit (doit correspondre exactement au catalogue Ekoo).

data-ekoo-locale

string·default: auto

Code langue : fr, en, es, it, de, ar, cn, tw, hk, jp, kr, nl, tr, pl, pt, lu, be, ru. "auto" = détection navigator.language.

data-ekoo-variant

string

Référence stable d’une configuration widget. Le produit, ses audios et ses reviewers restent pilotés par data-ekoo-product-id ; seul l’habillage change.

data-ekoo-review-id

string

ID d'un avis audio spécifique. Si omis, le premier avis publié est utilisé.

data-ekoo-on-event

string (fn name)

Nom d'une fonction globale window appelée à chaque événement widget (printed, played-0, played-25…).

Apparence — surcharges backoffice

data-ekoo-direction

normal | reverse·default: normal

Sens d'expansion. normal = gauche→droite, reverse = droite→gauche.

data-ekoo-scale

number·default: 1

Facteur de zoom (ex: "1.2" pour 20% plus grand).

data-ekoo-animation

string·default: pulse

Type d'animation de l'icône au repos.

data-ekoo-animation-duration

string·default: continuous

Durée de l'animation.

data-ekoo-always-open

boolean·default: false

Si "true", le widget reste toujours déplié.

data-ekoo-show-image

boolean·default: true

Afficher ou masquer l'image produit dans le widget.

data-ekoo-not-fully-clickable

boolean·default: false

Si "true", seul le bouton lecture est cliquable.

data-ekoo-autoplay

boolean·default: false

Lecture audio automatique au chargement.

data-ekoo-show-transcript

boolean·default: false

Afficher un bouton pour lire la transcription.

data-ekoo-show-speed-button

boolean·default: false

Afficher un contrôle de vitesse de lecture.

data-ekoo-closed-state-main-text

string

Texte CTA principal affiché quand le widget est replié.

data-ekoo-closed-state-secondary-text

string

Texte secondaire sous le CTA quand le widget est replié.

SPA & Shadow DOM

data-ekoo-mode

spa | static·default: auto

Force le mode rendu. Auto-détecté (Next.js, Nuxt, React, Vue, Angular, Sapper). À utiliser seulement si la détection auto échoue.

data-shadow-mode

open | closed·default: open

"open" (par défaut) permet l'inspection, l'accès CSS externe et le tracking analytics. Définir à "closed" pour isoler complètement le widget.

Config JS globale

window.EKOO_FORCE_SPA = true

Force le mode SPA globalement (alternative à data-ekoo-mode="spa" sur chaque widget).

window.ekooShadowMode = "open"

Shadow DOM mode global (alternative à data-shadow-mode sur chaque widget).

Principe

Dans un contexte Ionic / Capacitor, le widget Ekoo s'utilise via le custom element <ekoo-widget>. Le script est chargé une seule fois dans index.html et le cycle de vie est géré via les hooks Ionic de chaque framework.

ekooLoad() — à appeler quand la vue contenant le widget apparaît.
ekooUnload() — à appeler quand la vue disparaît.
ekooReload() — pour forcer un rafraîchissement complet du widget.

1. Charger le script dans index.html

Ajoutez le script Ekoo dans le <head> de votre index.html. Il sera chargé une seule fois au démarrage de l'application.

index.html

html

1<head>
2  <meta charset="UTF-8" />
3  <title>My App</title>
4  <script src="https://app.ekoo.co/widgets/widget-4.0.0-standalone.js"</script>
5</head>

2. Utiliser le custom element

Placez le custom element <ekoo-widget> dans votre template avec les attributs suivants :

Custom element

html

1<ekoo-widget
2  data-ekoo="YOUR_WEBSITE_ID"
3  data-ekoo-product-id="MY_PRODUCT_ID"
4  data-ekoo-locale="fr"
5  data-shadow-mode="open"
6></ekoo-widget>

ℹ️

Note

Depuis le widget 4.0.0, le mode Shadow DOM "open" est la valeur par défaut, ce qui assure le bon fonctionnement du widget en tant que Web Component dans le contexte Ionic. L'attribut data-shadow-mode peut donc être omis.

Attributs clés

Attribut	Statut	Description
`data-ekoo`	Obligatoire	Votre identifiant unique de site web Ekoo.
`data-product-id`	Obligatoire	L'ID du produit correspondant à votre catalogue Ekoo.
`data-ekoo-variant`	Optionnel	Référence d'une configuration widget enregistrée dans le backoffice (ex : "homepage"). Sélectionne l'habillage appliqué ; le produit, ses audios et ses reviewers proviennent toujours de data-ekoo-product-id.
`data-shadow-mode`	Optionnel	"open" est désormais la valeur par défaut (widget 4.0.0). À définir à "closed" uniquement si vous avez besoin d'une isolation complète des styles.

4. Product ID dynamique

Le custom element <ekoo-widget> observe les changements d'attributs. Pour mettre à jour le product ID dynamiquement, utilisez setAttribute:

Mise à jour dynamique du product ID

javascript

1const widget = document.querySelector('ekoo-widget')
2if (widget) {
3  widget.setAttribute('data-ekoo-product-id', newProductId)
4}

💡

ekooReload() après changements multiples

Si vous constatez des incohérences visuelles après plusieurs changements de produit, appelez window.ekooReload() pour forcer une réinitialisation complète du widget.

5. Ionic React

pages/ProductPage.tsx — Ionic React

tsx

1import React from 'react'
2import {
3  IonContent,
4  IonPage,
5  useIonViewDidEnter,
6  useIonViewWillLeave,
7} from '@ionic/react'
8
9interface ProductPageProps {
10  productId: string
11}
12
13const ProductPage: React.FC<ProductPageProps> = ({ productId }) => {
14  useIonViewDidEnter(() => {
15    window.ekooLoad?.()
16  })
17
18  useIonViewWillLeave(() => {
19    window.ekooUnload?.()
20  })
21
22  return (
23    <IonPage>
24      <IonContent>
25        <h1>My product</h1>
26        {/* @ts-expect-error — custom element not typed by default */}
27        <ekoo-widget
28          data-ekoo="YOUR_WEBSITE_ID"
29          data-ekoo-product-id={productId}
30          data-ekoo-locale="fr"
31          data-shadow-mode="open"
32        />
33      </IonContent>
34    </IonPage>
35  )
36}
37
38export default ProductPage

6. Ionic Vue

views/ProductPage.vue — Ionic Vue

vue

1<template>
2  <ion-page>
3    <ion-content>
4      <h1>My product</h1>
5      <ekoo-widget
6        data-ekoo="YOUR_WEBSITE_ID"
7        :data-ekoo-product-id="productId"
8        data-ekoo-locale="fr"
9        data-shadow-mode="open"
10      />
11    </ion-content>
12  </ion-page>
13</template>
14
15<script setup lang="ts">
16import { IonPage, IonContent, onIonViewDidEnter, onIonViewWillLeave } from '@ionic/vue'
17
18defineProps<{
19  productId: string
20}>()
21
22onIonViewDidEnter(() => {
23  window.ekooLoad?.()
24})
25
26onIonViewWillLeave(() => {
27  window.ekooUnload?.()
28})
29</script>

💡

Vue : déclarer le custom element

Pour éviter les warnings Vue concernant le custom element, ajoutez ekoo-widget dans la configuration compilerOptions.isCustomElement de votre vite.config.ts.

7. Ionic Angular

Pour Angular, vous devez ajouter CUSTOM_ELEMENTS_SCHEMA au module ou composant qui utilise le custom element :

product.page.ts — Ionic Angular

typescript

1import { Component } from '@angular/core'
2import { CUSTOM_ELEMENTS_SCHEMA } from '@angular/core'
3import { ViewDidEnter, ViewWillLeave } from '@ionic/angular'
4
5@Component({
6  selector: 'app-product',
7  schemas: [CUSTOM_ELEMENTS_SCHEMA],
8  template: `
9    <ion-content>
10      <h1>My product</h1>
11      <ekoo-widget
12        data-ekoo="YOUR_WEBSITE_ID"
13        [attr.data-ekoo-product-id]="productId"
14        data-ekoo-locale="fr"
15        data-shadow-mode="open"
16      ></ekoo-widget>
17    </ion-content>
18  `,
19})
20export class ProductPage implements ViewDidEnter, ViewWillLeave {
21  productId = 'my-product-123'
22
23  ionViewDidEnter() {
24    (window as any).ekooLoad?.()
25  }
26
27  ionViewWillLeave() {
28    (window as any).ekooUnload?.()
29  }
30}

ℹ️

CUSTOM_ELEMENTS_SCHEMA

Sans CUSTOM_ELEMENTS_SCHEMA, Angular affichera une erreur car il ne reconnaît pas <ekoo-widget> comme un composant Angular natif.

Résumé du cycle de vie

Vue entre (visible) → ekooLoad()
Vue quitte (masquée) → ekooUnload()
Product ID change → mettre à jour l'attribut avec setAttribute
Incohérence visuelle → ekooReload()

Intégration Ionic / Capacitor

Principe

1. Charger le script dans index.html

2. Utiliser le custom element

Attributs clés

4. Product ID dynamique

5. Ionic React

6. Ionic Vue

7. Ionic Angular

Résumé du cycle de vie

Aller plus loin