Intégration personnalisée pour recevoir des données depuis des systèmes externes

Dans Connectif, il est possible de recevoir des données depuis des systèmes externes afin d'utiliser des informations qui ne sont pas enregistrées par défaut sur la plateforme. Grâce à une intégration personnalisée, vous pourrez synchroniser les données de vos contacts en fonction des événements générés sur d'autres plateformes.

Cet article explique quels sont les types d'intégration personnalisée pour recevoir des données et comment créer un événement de ce type, avec un exemple d'intégration avec un ERP.

1. Propriétés

Événements de réception de données

• Les événements de réception de données sont un outil puissant pour étendre et personnaliser Connectif selon vos propres cas d'utilisation.

• Lors de la création d'un nouvel événement de réception, vous devez indiquer le contexte : 

  • API publique.

  • Webhook.

  • Web ou application mobile.
     

Événement de réception via API publique

Les événements de réception via API publique sont le mécanisme le plus sûr, car ils nécessitent une clé API. Ils sont conçus pour que les événements soient envoyés depuis votre serveur vers Connectif.

Caractéristiques et limites :

• La taille maximale d'un événement est de 512 Ko.

• Il est obligatoire de définir un champ email requis et clé primaire pour identifier le contact.

• Il est possible d'indiquer via la chaîne de requête createContact s'il faut créer ou générer une erreur lorsque le contact auquel l'événement appartient n'existe pas.

• Le nœud déclencheur du workflow généré par un événement de réception via API publique n'aura pas de contexte web.

• Ils nécessitent une validation stricte et ne permettent pas d'envoyer des champs qui ne sont pas définis dans l'événement.

Événement de réception via Webhooks

Les événements de réception via Webhook sont un mécanisme plus flexible, idéal lorsque l'émetteur des données n'est pas contrôlé, par exemple en utilisant un webhook d'un outil externe où il n'est pas possible de changer le format des données émises ou d'établir un en-tête de sécurité avec une clé API.

Caractéristiques et limites :

• La taille maximale d'un événement est de 512 Ko.

• Il est obligatoire de définir un champ email requis et clé primaire pour identifier le contact.

• Ils créent toujours le contact dans Connectif s'il n'existe pas.
• Ils permettent de définir un JSON Pointer pour mapper les champs vers des structures complexes. Idéal lorsque l'information de l'événement se trouve dans des objets complexes et imbriqués.
• Ils ne génèrent pas d'erreur de validation en cas de champs inconnus. Cela permet de ne mapper que les champs qui nous intéressent en ignorant simplement les autres.

• Le nœud déclencheur du workflow généré par un événement de réception via Webhook n'aura pas de contexte web.

Événement de réception via Web ou application mobile

Les événements de réception via Web ou application mobile permettent d'envoyer des événements directement depuis le côté client de votre site web ou de votre application mobile. Pour cela, il est nécessaire d'utiliser respectivement le SDK Web ou SDK Mobile.

Caractéristiques et limites :

• Les événements via Web ou application ne nécessitent pas un champ email obligatoire ni une clé primaire. Ils peuvent donc être envoyés pour des contacts anonymes ou connus lors du tracking web ou de votre application mobile.

• Le nœud déclencheur du workflow généré par un événement de réception via Web ou application mobile aura un contexte web. Après ce nœud, il est possible d'utiliser le nœud Afficher contenu web.
   

2. Comment fonctionne la création d'un événement de réception de données dans Connectif

Le processus de création d'un événement de réception de données comporte plusieurs étapes à suivre, quel que soit le mécanisme choisi. 

À titre d'exemple, voici comment créer un événement de réception de données pour connecter un ERP avec Connectif :

2.1. Création de l'intégration personnalisée

1. Accédez à "Intégrations > Personnalisées" et cliquez sur  Créer une nouvelle intégration.

2. Définissez le champ "Nom" pour identifier l'intégration.

3. (Optionnel) Personnalisez la couleur, ajoutez une description ou catégorisez l'intégration.

4. Cliquez sur  Mettre à jour.

2.2 Création et configuration de l'événement "Recevoir des données"

(Dans cette section, nous allons créer l'événement de réception et configurer les champs où les données reçues seront stockées).

5. Dans l'onglet Recevoir des données, cliquez sur Créer un nouvel événement de réception.

6. Dans la fenêtre pop-up, choisissez le type de connexion pour l'événement et cliquez sur Aller à l'éditeur. Dans notre exemple, via API publique.

7. Attribuez un Nom et un Alias à l'événement.

8. Cliquez sur   Ajouter un nouveau champ pour créer un champ de type Email, afin de collecter l'adresse e-mail du contact. 

9. Répétez l'action indiquée au point précédent autant de fois que vous souhaitez recevoir de données. 

10. Cliquez sur  Enregistrer et, dans l'écran de confirmation, cliquez sur  Retour à la liste des événements.

2.3. Création de la clé API pour activer la réception de données

(Dans cette section, il est expliqué comment générer l'adresse pour notifier le type d'événement créé, le endpoint).

10. Rendez-vous dans "Paramètres de la boutique > API et accès IP" et, dans Clés API, cliquez sur   Créer une nouvelle clé API.

11. Dans la section Événements personnalisés, activez la permission pour Écrire.

12. Enregistrez la clé API et, dans le menu des clés API, localisez celle que vous venez de créer et cliquez sur le bouton pour la copier (indiqué sur l'image).

13. Utilisez la clé API pour effectuer la requête d'envoi de l'événement depuis votre système. 

2.4. Obtention du endpoint de notification

(Dans cette section, il est expliqué comment générer l'adresse pour notifier le type d'événement créé, le endpoint).

14. Dans l'onglet Recevoir des données, cliquez sur  Modifier.

15. Cliquez sur  Copier l'URL pour copier dans le presse-papiers l'adresse du endpoint.

2.5. Envoi des données à Connectif

(Dans cette section, il est expliqué comment établir la communication avec le endpoint et envoyer des données).

16. Dans votre code, collez cette URL avec la clé API et le corps de la requête pour générer l'événement de réception. En cas d'événements via Webhook ou Web/App, vous n'aurez pas besoin d'utiliser la clé API.

17. Effectuez l'appel au endpoint pour lui notifier les données de l'événement.

2.5.1 Exemple d'envoi de données via Postman (Webhook)

Une fois l'événement de réception configuré dans Connectif, il est possible de réaliser des tests d'envoi de données en utilisant Postman pour vérifier que l'information est bien reçue.

Configurer la requête

1. Ouvrez Postman et créez une nouvelle requête.
2. Sélectionnez la méthode POST.
3. Saisissez en URL le endpoint généré pour l'événement de réception.

Exemple :

https://webhook-api.connectif.cloud/{store-id}/custom-events/alias/webhook-event-example

Configurer les en-têtes (Headers)

Ajoutez les en-têtes nécessaires pour l'envoi des données :

Configurer le corps de la requête (Body)

Sélectionnez Body > raw > JSON et saisissez une charge utile conforme aux champs définis dans l'événement.

Exemple :

{
    "email": "john.doe@example.org",
    "phone": "+34666777888",
    "name": "Hi there!"
}

Envoyer la requête

Cliquez sur Send pour effectuer la requête.

Si la requête est traitée correctement, l'événement sera reçu par Connectif et pourra être utilisé dans des workflows, segmentations ou processus d'automatisation.

Il est recommandé de vérifier la réception de l'événement via un workflow de test ou en consultant l'activité du contact associé aux données envoyées.

Résultat :

L'image suivante montre un exemple d'une requête effectuée correctement depuis Postman et la réponse renvoyée par Connectif.

2.5.2 Exemple d'envoi de données via Postman (API)

Une fois l'événement de réception configuré et la clé API créée, il est possible d'utiliser Postman pour vérifier que Connectif reçoit correctement les données envoyées.

Configurer la requête

1. Ouvrez Postman et créez une nouvelle requête.
2. Sélectionnez la méthode HTTP indiquée dans la documentation du endpoint que vous allez utiliser.
3. Saisissez l'URL correspondant au endpoint de l'API.

Exemple :

https://api.connectif.cloud/custom-events/alias/api-event-example?createContact=true

Configurer les en-têtes (Headers)

Ajoutez les identifiants requis par le endpoint via les en-têtes correspondants.

Remplacez {api_key} par la clé secrète correspondante.

 Configurer le corps de la requête (Body)

Sélectionnez Body > raw > JSON et saisissez une charge utile conforme aux champs définis dans l'événement.

Exemple :

{ 
    "email": "john.doe@example.org", 
    "name": "Hi there!", 
    "phone": "+34666777888" 
}

Envoyer la requête

Cliquez sur Send pour effectuer la requête.

Si la requête est traitée correctement, l'API renverra une réponse satisfaisante et les données seront enregistrées dans Connectif selon la fonctionnalité utilisée.

Résultat :

L'image suivante montre un exemple d'une requête effectuée correctement via API publique en utilisant une clé API avec des permissions d'écriture pour les événements personnalisés.

2.6. Synchronisation des données avec les informations du contact

(Dans cette section, il est expliqué comment synchroniser les données dans Connectif via un workflow).

18. Accédez à “Workflows”, cliquez sur  Créer un nouveau workflow et sélectionnez Créer un workflow vierge.

19. Créez la structure de votre workflow avec le nœud de type déclencheur “Déclencheur [nom de votre intégration]” et le nœud de type action “Définir un champ”.

20. Dans le nœud “Déclencheur Recevoir des données de…”, cliquez sur  (Modifier la configuration du nœud).

21. Vérifiez que les données collectées par le nœud "Déclencheur Recevoir des données de...", provenant de l'événement dans le système externe, sont correctes.

22. Cliquez sur  Enregistrer.

23. Dans le nœud “Définir un champ”, cliquez sur  (Modifier la configuration du nœud).

24. Reliez les variables pour assigner l'information collectée par l'intégration personnalisée aux champs de contact correspondants.

25. Cliquez sur  Mettre à jour.

26. Dans le workflow, cliquez sur  Enregistrer pour sauvegarder les modifications et sur  Démarrer pour l'activer.

2.7. Création d'un segment dynamique Plus de l'intégration

Avec Connectif, vous pourrez créer un segment dynamique Plus pour filtrer selon les activités et champs liés à l'intégration personnalisée.

Une fois que vous créez un segment de contacts de l'intégration personnalisée, celle-ci ne pourra pas être supprimée. De plus, si l'un de ses champs est utilisé comme condition de segmentation, il ne pourra pas être supprimé ni modifié. 

Continuez à apprendre !

Pour exploiter tout le potentiel de votre compte Connectif, nous vous recommandons de poursuivre avec les articles suivants :

• Intégration personnalisée pour envoyer des données, pour envoyer des données depuis Connectif vers des systèmes ou applications externes.

• Détecter et réagir aux liens web créés en dehors de Connectif, pour identifier et répondre aux clics sur n'importe quel lien de votre site web.

• Intégration avec Facebook et Instagram, pour gérer les audiences de votre compte Facebook Ads avec Connectif.

• Formulaires intégrés, pour détecter et collecter dans Connectif les formulaires déjà existants sur votre site web.