SDK du Widget

Le SDK du Widget Chatim vous permet d'integrer et de controler programmatiquement le widget de chat Chatim sur votre site web.

Installation

Ajoutez le code suivant a votre site web, juste avant la balise fermante </body> :

<script>
  window.chatim = window.chatim || {};
  window.chatim.cmd = window.chatim.cmd || [];
  window.chatim.settings = { projectId: "YOUR_PROJECT_ID" };
</script>
<script src="https://widget.chatim.app/widget.js" async></script>

Remplacez YOUR_PROJECT_ID par l'identifiant reel de votre projet depuis le tableau de bord Chatim.

Options de configuration

Configurez le widget en definissant les proprietes sur window.chatim.settings :

window.chatim.settings = {
  projectId: "YOUR_PROJECT_ID",  // Required
  params: {                       // Optional: Custom parameters
    userId: "user-123",
    utm_source: "google",
    utm_campaign: "summer_sale"
  }
};

API JavaScript

Ouvrir le Widget

window.chatim.widget.open();

Fermer le Widget

window.chatim.widget.close();

Definir la configuration du Widget

window.chatim.widget.setConfig(config);

Met a jour la configuration du widget dynamiquement au moment de l'execution.

Obtenir la configuration du Widget

const config = window.chatim.widget.getConfig();

Renvoie l'objet de configuration actuel, ou null si le widget n'est pas encore initialise.

Definir les parametres personnalises

window.chatim.widget.setParams({
  lastPage: "/checkout",
  cartValue: 99.99,
  isPremium: true
});

Met a jour les parametres personnalises apres l'initialisation du widget. Les parametres sont fusionnes avec les valeurs existantes (non remplaces).

Redemarrer le Chat

window.chatim.widget.restartChat();

Efface toutes les donnees et l'historique de chat stockes, ferme le widget et reinitialise avec une nouvelle session. Utile lorsqu'un utilisateur se deconnecte ou que vous souhaitez reinitialiser la conversation.

Reference API

window.chatim.settings

window.chatim.widget

Parametres personnalises

Les parametres personnalises vous permettent d'envoyer des donnees supplementaires sur vos visiteurs a Chatim. Ces donnees sont stockees avec les sessions de chat et affichees dans le panneau Visiteur du tableau de bord d'administration.

Cas d'utilisation

• Identification utilisateur - Transmettre les IDs utilisateur, email ou identifiants de compte
• Attribution marketing - Suivre les parametres UTM et les sources de campagnes
• Donnees e-commerce - Envoyer la valeur du panier, les categories de produits ou l'historique d'achats
• Segmentation utilisateur - Inclure le type de plan, le statut d'abonnement ou le niveau utilisateur

Definir les parametres a l'initialisation

window.chatim.settings = {
  projectId: "YOUR_PROJECT_ID",
  params: {
    userId: "user-123",
    email: "[email protected]",
    utm_source: "google",
    planType: "premium",
    isPremium: true
  }
};

Mettre a jour les parametres au moment de l'execution

// Update params when user logs in
window.chatim.widget.setParams({
  userId: user.id,
  email: user.email,
  planType: user.subscription
});

// Track page-specific data
window.chatim.widget.setParams({
  lastPage: window.location.pathname,
  productViewed: "SKU-12345"
});

Types de donnees pris en charge

Non pris en charge : Objets, tableaux, fonctions, undefined

Regles de nommage des parametres

• Commencer par une lettre ou un tiret bas
• Alphanumerique + tiret bas uniquement
• Maximum 50 caracteres
• Noms reserves : projectId, demo, __proto__, constructor, prototype

Limites

Visualiser les parametres

Les parametres personnalises apparaissent dans le tableau de bord Chatim sous Visiteurs - cliquez sur un visiteur pour voir sa section Parametres personnalises.

Parametres URL automatiques

Le widget peut capturer automatiquement les parametres URL des pages visiteurs sans aucune modification de code. Configurez cela dans Parametres du Widget > Parametres URL.

• Capturer tous - Capture tous les parametres URL valides
• Liste blanche uniquement - Capture uniquement les parametres specifies (par defaut : utm_source, utm_medium, utm_campaign, utm_term, utm_content, ref)

Priorite de fusion

1. Parametres URL (priorite la plus basse)
2. window.chatim.settings.params (remplace les parametres URL)
3. window.chatim.widget.setParams() (priorite la plus haute)

File de commandes

Le SDK inclut une file de commandes qui vous permet d'appeler les methodes du widget avant que le widget ne soit completement charge. Les commandes sont automatiquement executees une fois le widget pret.

Format fonction (Recommande)

window.chatim.cmd.push(function() {
  window.chatim.widget.close();
});

window.chatim.cmd.push(() => {
  window.chatim.widget.open();
  console.log('Widget opened!');
});

Mettre en file d'attente les commandes avant le chargement du Widget

<script>
  window.chatim = window.chatim || {};
  window.chatim.cmd = window.chatim.cmd || [];
  window.chatim.settings = { projectId: "YOUR_PROJECT_ID" };

  // Queue a function to run when widget is ready
  window.chatim.cmd.push(() => {
    console.log('Widget is ready!');
    window.chatim.widget.close();
  });
</script>
<script src="https://widget.chatim.app/widget.js" async></script>

Cas d'utilisation courants

Ouvrir le Widget au clic sur un bouton

<button onclick="window.chatim.widget.open()">
  Chat with us
</button>

Ouvrir le Widget au defilement vers le bas

window.addEventListener('scroll', function() {
  if ((window.innerHeight + window.scrollY) >= document.body.offsetHeight) {
    window.chatim.widget.open();
  }
});

Redemarrer le Chat a la deconnexion

function onUserLogout() {
  window.chatim.widget.restartChat();
}

Ouvrir le Widget apres un delai

setTimeout(function() {
  window.chatim.widget.open();
}, 5000);

Exemples d'integration SPA

React

import { useEffect } from 'react';

function App() {
  useEffect(() => {
    window.chatim = window.chatim || {};
    window.chatim.cmd = window.chatim.cmd || [];
    window.chatim.settings = {
      projectId: 'YOUR_PROJECT_ID',
      params: { userId: getCurrentUserId() }
    };

    const script = document.createElement('script');
    script.src = 'https://widget.chatim.app/widget.js';
    script.async = true;
    document.body.appendChild(script);

    return () => document.body.removeChild(script);
  }, []);

  return <button onClick={() => window.chatim.widget.open()}>Open Chat</button>;
}

Next.js

'use client';

import { useEffect } from 'react';
import Script from 'next/script';

export default function ChatWidget() {
  useEffect(() => {
    window.chatim = window.chatim || {};
    window.chatim.cmd = window.chatim.cmd || [];
    window.chatim.settings = { projectId: 'YOUR_PROJECT_ID' };
  }, []);

  return (
    <Script
      src="https://widget.chatim.app/widget.js"
      strategy="lazyOnload"
    />
  );
}

Vue.js

export default {
  mounted() {
    window.chatim = window.chatim || {};
    window.chatim.cmd = window.chatim.cmd || [];
    window.chatim.settings = { projectId: 'YOUR_PROJECT_ID' };

    const script = document.createElement('script');
    script.src = 'https://widget.chatim.app/widget.js';
    script.async = true;
    document.body.appendChild(script);
  },
  methods: {
    openChat() {
      window.chatim.widget.open();
    }
  }
}

Exemple d'integration e-commerce

// On page load
window.chatim.settings = {
  projectId: "YOUR_PROJECT_ID",
  params: {
    userId: getUserId(),
    userType: isLoggedIn() ? "registered" : "guest",
    utm_source: getUrlParam("utm_source")
  }
};

// On product view
function trackProductView(product) {
  window.chatim.widget.setParams({
    lastProductViewed: product.name,
    lastProductPrice: product.price
  });
}

// On add to cart
function trackAddToCart(cart) {
  window.chatim.widget.setParams({
    cartValue: cart.total,
    cartItems: cart.items.length
  });
}

Support herite

Pour la retrocompatibilite, ces APIs heritees sont toujours prises en charge :

// Legacy settings (still works)
window.chatimSettings = { projectId: "YOUR_PROJECT_ID" };

// Legacy widget methods (still works)
window.chatimWidget.open();
window.chatimWidget.close();

Nous recommandons d'utiliser le nouveau namespace window.chatim pour toutes les nouvelles implementations.

Depannage

Le Widget n'apparait pas

1. Verifiez que votre projectId est correct
2. Verifiez la console du navigateur pour les erreurs
3. Assurez-vous que le script se charge (verifiez l'onglet Reseau)
4. Verifiez qu'aucun bloqueur de publicites n'interfere

Les commandes ne s'executent pas

1. Assurez-vous que window.chatim et window.chatim.cmd sont initialises avant d'appeler les methodes
2. Verifiez que l'URL du script du widget est correcte
3. Verifiez que le script s'est charge avec succes

getConfig renvoie Null

getConfig() renvoie null avant que le widget ne soit completement initialise. Utilisez une approche de sondage :

const checkWidget = setInterval(() => {
  const config = window.chatim.widget.getConfig();
  if (config) {
    clearInterval(checkWidget);
    console.log('Widget config:', config);
  }
}, 100);

Besoin d'aide ?

Si vous avez besoin d'aide pour l'integration du SDK, contactez [email protected].