InputDev SDK Documentation �

Le backend de formulaires le plus simple et professionnel pour les développeurs modernes.

📖 Table des matières

• Introduction
• Quick Start
• Comment ça fonctionne
• Installation
• Utilisation JavaScript
• SDK JavaScript Avancé
• Validation Email
• Événements
• Codes d'erreur
• Sécurité
• Mode Silence
• Limites
• Bonnes pratiques
• Exemple complet

🚀 Introduction

InputDev permet de transformer un simple formulaire en système de collecte de données sécurisé et professionnel.

✨ Avantages principaux

• Aucune configuration serveur nécessaire - Déployez en minutes
• Aucune dépendance externe - SDK ultra-léger et autonome
• Installation en moins de 1 minute - Intégration instantanée
• Validation automatique - Emails et champs intégrés
• Sécurité de niveau entreprise - HTTPS, CORS, anti-spam
• Filtrage intelligent des champs - Ignore automatiquement les éléments non-pertinents
• Retour visuel immédiat - Boutons verts/rouges selon succès/erreur
• Deux versions disponibles - Minifiée (8.3KB) et complète (10.3KB)

⚡ Quick Start (Démarrage rapide)

Étape 1 — Ajouter le script

Via CDN (recommandé)

<script src="https://unpkg.com/@inputdev/sdk@latest/inputdev-sdk.prod.js"></script>

⚡ Note importante : Utilisez la version .prod.js qui est la seule version fonctionnelle actuellement

Via NPM

npm install @inputdev/sdk
import InputDev from "@inputdev/sdk";

Étape 2 — Ajouter votre clé API

<form data-inputdev="grts_VotreCleApiDeCeSite">
  <input type="text" name="name" required />
  <input type="email" name="email" required />
  <button type="submit">Envoyer</button>
</form>

🎉 C'est terminé ! Le formulaire est maintenant connecté à InputDev.

🔧 Comment ça fonctionne

1. Navigateur - L'utilisateur soumet le formulaire
2. InputDev API - Les données sont validées et envoyées en HTTPS
3. Stockage sécurisé - Elles sont enregistrées dans votre tableau de bord

📦 Installation

Via CDN (recommandé pour production)

Deux versions disponibles :

• Version minifiée (8.3KB) : Pour production - chargement ultra-rapide
• Version complète (10.3KB) : Pour développement - avec commentaires

Version Minifiée (Production)

<script src="https://unpkg.com/@inputdev/sdk@latest/inputdev-sdk.min.js"></script>

Version Complète (Développement)

<script src="https://unpkg.com/@inputdev/sdk@latest/inputdev-sdk.prod.js"></script>

CDN Alternative (JSDelivr)

<script src="https://cdn.jsdelivr.net/npm/@inputdev/sdk@latest/inputdev-sdk.min.js"></script>

Via NPM

npm install @inputdev/sdk
import InputDev from "@inputdev/sdk";

💻 Utilisation JavaScript (Pour Frameworks)

Idéal pour les frameworks JavaScript (React, Vue, Angular, etc.) où vous contrôlez déjà les données du formulaire :

const sdk = new InputDev();

await sdk.submit("grts_VotreCleApiDeCeSite", {
  name: "John",
  email: "[email protected]", 
  plan: "premium"
});

Paramètres

| Paramètre | Type | Obligatoire | Description | |-----------|------|-------------|-------------| | apiKey | string | Oui | Clé publique fournie par InputDev | | data | object | Oui | Données à envoyer |

🚀 SDK JavaScript Avancé

Pour le HTML classique avec un contrôle total des champs et une gestion personnalisée :

<form id="contact-form">
  <!-- ... vos champs ici ... -->
  <button type="button" onclick="submitFormulaire()">Envoyer</button>
</form>

<script src="https://unpkg.com/@inputdev/sdk@latest/inputdev-sdk.prod.js"></script>
<script>
  // Fonction réutilisable, contrôle total des champs
  function submitFormulaire() {
    const dev = new InputDevSDK();
    const data = {
      email: "[email protected]",
      message: "Message par défaut",
      telephone: "+22990000000",
      plan: "free"
    };
    dev.submit("grts_VotreCleApiDeCeSite", data); // SDK gère erreurs et succès automatiquement
  }
</script>

Avantages du SDK avancé

• Contrôle total des données - Gérez chaque champ manuellement
• Validation personnalisée - Appliquez vos règles métier
• Gestion d'erreurs avancée - Messages d'erreur sur mesure
• Performance optimisée - Envoi asynchrone et optimisé

📧 Validation Email

InputDev valide automatiquement les adresses email pour garantir la qualité des données collectées. La validation fonctionne en deux temps : affichage des messages et blocage de la soumission si nécessaire.

Comment ça fonctionne ?

Le SDK détecte automatiquement les champs email de deux manières :

1. Type d'input : Tous les <input type="email"> sont validés
2. Nom du champ : Tous les champs dont le nom contient "email" (insensible à la casse)

⚠️ Important : Les names sont très importants ! Ils déterminent quels champs seront validés et comment les données seront stockées.

Messages dans la console (pour le débogage)

📧 VALIDATION EMAIL
⚠️ Erreurs trouvées:
• L'email "email" est invalide: test@invalid
💡 Corrigez les emails avant de soumettre à nouveau

Messages sous le formulaire (pour l'expérience utilisateur)

<div class="inputdev-email-error-message" data-inputdev-error-for="email">
  <span style="text-decoration: underline; font-weight: bold;">InputDev SDK</span> : 
  <span style="font-weight: bold;">Veuillez entrer une adresse email valide</span>
</div>

Processus de validation

1. Détection : Le SDK identifie les champs avec "email" dans le nom (insensible à la casse)
2. Validation en temps réel : Vérification lors de la perte de focus (blur event)
3. Feedback visuel : Bordure rouge et message d'erreur sous le champ
4. Blocage de soumission : Empêche l'envoi si un email est invalide
5. Nettoyage automatique : Supprime l'erreur quand l'utilisateur corrige

Exemple de validation

<form data-inputdev="grts_VotreCleApiDeCeSite">
  <input type="text" name="name" placeholder="Nom" required>
  
  <!-- ✅ Sera validé (type="email") -->
  <input type="email" name="contact" placeholder="Contact" required>
  
  <!-- ✅ Aussi validé (type="email" + name contient "email") -->
  <input type="email" name="email" placeholder="Email" required>
  
  <!-- ✅ Validé (name contient "email") -->
  <input type="text" name="user_email" placeholder="Email utilisateur">
  
  <!-- ❌ Non validé (ni type="email", ni name avec "email") -->
  <input type="text" name="phone" placeholder="Téléphone">
  
  <button type="submit">Envoyer</button>
</form>

Types de validation

✅ Champs qui seront validés

• <input type="email" name="quelconque"> (peu importe le name)
• <input type="text" name="email"> (name contient "email")
• <input type="text" name="user_email"> (name contient "email")
• <input type="email" name="EMAIL_ADDRESS"> (les deux conditions)

❌ Champs qui ne seront PAS validés

• <input type="text" name="contact"> (ni type email, ni name avec "email")
• <input type="tel" name="phone"> (ni type email, ni name avec "email")
• <input type="text" name="message"> (ni type email, ni name avec "email")

Types de validation

✅ Emails valides

• [email protected]
• [email protected]
• [email protected]

❌ Emails invalides

• email@
• user.domain.com
• user@domain

Importance des names (noms de champs)

Les names sont cruciaux pour le fonctionnement d'InputDev :

1. Validation : Les names déterminent quels champs sont validés automatiquement
2. Stockage : Les names deviennent les clés dans votre base de données
3. Identification : Les names permettent d'identifier chaque champ de manière unique

Bonnes pratiques pour les names

• ✅ Utilisez des names descriptifs : name="email_utilisateur"
• ✅ Utilisez des names simples : name="telephone"
• ✅ Soyez cohérent : name="email" et name="confirmation_email"
• ❌ Évitez les names vides ou manquants
• ❌ Évitez les caractères spéciaux : name="email-utilisateur" (préférer _)

Styles appliqués automatiquement

.inputdev-email-error {
    border: 2px solid #ef4444 !important;
    box-shadow: 0 0 0 3px rgba(239, 68, 68, 0.1) !important;
    outline: none !important;
}

.inputdev-email-error-message {
    color: #ef4444;
    font-size: 12px;
    margin-top: 4px;
    display: block;
}

⚠️ Important : Si un email est invalide, la soumission du formulaire est complètement bloquée. L'utilisateur doit corriger l'email avant de pouvoir envoyer le formulaire.

💡 Astuce : La validation fonctionne en mode normal et en mode silence. En mode silence, seul le message sous le formulaire s'affiche (pas de logs console).

📡 Événements

Vous pouvez écouter les événements globaux pour personnaliser l'expérience utilisateur :

document.addEventListener("inputdev:success", (event) => {
  console.log("Succès :", event.detail);
  // Rediriger, afficher un message, etc.
});

document.addEventListener("inputdev:error", (event) => {
  console.error("Erreur :", event.detail);
  // Afficher une notification, logger l'erreur, etc.
});

🔄 Comportement de Soumission (Important)

⚠️ Le SDK bloque temporairement le rechargement de la page

Le SDK InputDev utilise un comportement moderne de type SPA (Single Page Application) pour garantir une meilleure expérience utilisateur :

📋 Ce qui se passe lors de la soumission

1. e.preventDefault() : Le rechargement automatique de la page est bloqué
2. Bouton désactivé : Le bouton submit est désactivé pendant 3 secondes pour éviter les double-soumissions
3. Texte changé : Le bouton affiche "Envoi en cours..." pendant le traitement
4. Requête asynchrone : L'envoi se fait en AJAX sans rechargement
5. Gestion des résultats : Succès ou erreur sont gérés via les événements

✅ Avantages de ce comportement

• 🔄 Évite les soumissions multiples - Protection contre les doubles clics
• 📱 Meilleure UX - Pas de rechargement brutal de la page
• 🔧 Gestion d'erreur améliorée - Messages d'erreur sans perdre le formulaire
• 📊 Feedback visuel - Indicateur de chargement clair
• 🎯 Compatible SPA - Fonctionne parfaitement avec React, Vue, Angular

💡 Note : Ce comportement est intentionnel et professionnel. Il garantit que vos utilisateurs ne perdent jamais leurs données et offre une expérience moderne et fluide.

� Codes d'erreur

| Code | Signification | Solution | |------|---------------|----------| | API_001 | Clé API invalide | Vérifiez votre clé | | DOM_001 | Domaine non autorisé | Ajoutez le domaine autorisé | | QUO_001 | Quota dépassé | Passez à un plan supérieur | | NET_001 | Erreur réseau | Vérifiez la connexion | | VAL_001 | Validation échouée | Vérifiez les champs |

🔐 Sécurité

• Requêtes envoyées en HTTPS - Chiffrement de bout en bout
• Validation côté client et serveur - Double couche de sécurité
• Domaine autorisé configurable - Protection contre l'usage non autorisé
• Anti-spam intégré - Protection automatique

ℹ️ Sécurité : La clé API est publique et conçue pour rester dans le frontend. Elle est sécurisée par validation de domaine et quotas automatiques.

� Mode Silence

Pour désactiver les logs en production :

<form data-inputdev-silence="grts_VotreCleApiDeCeSite">

📊 Limites

• Nombre de soumissions par mois - Dépend du plan choisi
• Nombre maximum de formulaires - Variable selon le plan
• Nombre de sites/clés actives - Une clé, un site
• SSL obligatoire - HTTPS requis pour la sécurité
• Domaines autorisés - Configurable par clé

⭐ Bonnes pratiques

• ✅ Toujours utiliser HTTPS
• ✅ Toujours définir des champs name
• ✅ Toujours gérer les événements erreur
• ✅ Surveiller votre quota
• ✅ Tester en environnement de développement

📋 Exemple complet réel

<!DOCTYPE html>
<html>
<head>
  <script src="https://unpkg.com/@inputdev/sdk@latest/inputdev-sdk.prod.js"></script>
</head>
<body>

<form data-inputdev="grts_VotreCleApiDeCeSite">
  <div class="form-group">
    <label for="name">Nom complet</label>
    <input type="text" id="name" name="name" required>
  </div>
  
  <div class="form-group">
    <label for="email">Email</label>
    <input type="email" id="email" name="email" required>
  </div>
  
  <div class="form-group">
    <label for="message">Message</label>
    <textarea id="message" name="message" required></textarea>
  </div>
  
  <button type="submit">Envoyer</button>
</form>

<script>
  // Écouter les événements pour une meilleure UX
  document.addEventListener('inputdev:success', (event) => {
    alert('Message envoyé avec succès !');
    // Réinitialiser le formulaire
    document.querySelector('form').reset();
  });
  
  document.addEventListener('inputdev:error', (event) => {
    console.error('Erreur lors de l\'envoi :', event.detail);
    alert('Une erreur est survenue. Veuillez réessayer.');
  });
</script>

</body>
</html>

� Support & Liens

• 📖 Documentation Complète : docs.inputdev.dev
• 💬 Discord : [Rejoindre la communauté]
• 🐛 Issues : [Signaler un bug]

📄 Licence

MIT License - voir le fichier LICENSE pour plus de détails.