Cet article est destiné à l'intégration des développeurs.
Sur cette page, vous apprendrez à :
- Activer le mode authentifié
- Configurer l'authentification
- Se connecter
- Se déconnecter
- Gérer le succès ou l'échec de l'activation
- Gérer l'expiration de l'identité du visiteur
1. Aperçu de la messagerie authentifiée
Voici un aperçu du fonctionnement de notre messagerie authentifiée. Chaque étape sera détaillée ci-dessous.
Il est important de garder à l'esprit qu'ici, anonyme signifie que le visiteur n'a pas accédé à un espace authentifié, mais qu'il est toujours identifié par le système iAdvize.
2. Comment activer le mode authentifié dans le portail d'administration ?
Le mode authentifié existe en accès anticipé: contactez votre contact principal iAdvize pour le mettre en place. Lorsque ce mode est activé, le code iAdvize attendra une identité avant de démarrer.
3. Comment mettre en place le backend d'authentification du client (token provider) ?
Pour mettre en place l'authentification, voir cet article : Messagerie authentifiée iAdvize - implémentation du backend web
4. Comment s'authentifier avec iAdvize sur le site web du client ?
Pour mettre en place une authentification sécurisée des visiteurs, un mode d'authentification doit être activé.
Par conséquent, la balise iAdvize attendra une instruction d' "authentification" avant de charger et d'engager le visiteur dans une conversation. Ce mode diffère du mode standard non authentifié.
Cependant, il est également possible de laisser le visiteur chatter de manière anonyme avec le mode authentifié activé. Les détails sont fournis ci-dessous.
4.1. Inclure le code iAdvize
Vous pouvez envoyer l'instruction d'authentification avant ou après l'inclusion de la balise. Dans tous les cas, vous devrez inclure la balise principale d'iAdvize de cette façon :
<script>
window.iAdvizeInterface = window.iAdvizeInterface || [];
iAdvizeInterface.config = {
sid: '<YOUR-SITE-ID>'
}
</script>
<script async src="//<YOUR-PLATFORM>.iadvize.com/iadvize.js"></script>
Vous devrez remplacer `<YOUR-SITE-ID>` par l'identifiant réel de votre site, qui se trouve dans l'administration : https://ha.iadvize.com/admin/site/current/code.
4.2. Activer le code iAdvize avec une identité
Lorsque le mode authentifié est activé, le tag ne sera pas activé tant qu'une instruction d'authentification n'aura pas été envoyée.
-
cas A
- si le visiteur a besoin d'une identité réelle signée par le client serveur, le système attend un "token" (ou jeton).
-
cas B
- si le visiteur peut chatter sans identité réelle, utiliser une authentification anonyme.
Si le visiteur se connecte ultérieurement (voir la section suivante), la conversation se poursuivra, - soit avec le contenu de la conversation précédente (si elle existe), soit avec le contenu de la conversation anonyme précédente.
- si le visiteur peut chatter sans identité réelle, utiliser une authentification anonyme.
// Secured authentication - case A
iAdvizeInterface.push((iAdvize) => {
iAdvize.activate(async () => {
const visitor_token = await ... // your backend logic to generate a JWE
return {
authenticationOption : { type: 'SECURED_AUTHENTICATION', token: visitor_token }
};
});
});
// OR Anonymous authentication - case B
iAdvizeInterface.push((iAdvize) => {
iAdvize.activate(() => ({
authenticationOption: { type: 'ANONYMOUS' }
}));
});
4.3. Fournir une identité après une activation anonyme
Un scénario courant serait celui d'un visiteur qui arrive anonymement sur votre site web, puis se connecte à son espace authentifié.
Dans ce scénario, le cas B mentionné ci-dessus pour l'activation a été choisi. Cela signifie que le tag a été activé anonymement, en utilisant cette ligne :
iAdvizeInterface.push((iAdvize) => {
iAdvize.activate(() => ({ authenticationOption: { type: 'ANONYMOUS' } }));
});
Maintenant, après une connexion réussie, le client doit alimenter le tag iAdvize avec le jeton authentifiant le visiteur.
Cela peut être fait en déclenchant la même méthode "activate" :
const afterLoginIadvizeIdentityCallback = () => {
iAdvizeInterface.push((iAdvize) => {
iAdvize.activate(async () => {
const visitor_token = await ... // your backend logic to generate a JWE
return {
authenticationOption : { type: 'SECURED_AUTHENTICATION', token: visitor_token };
};
});
});
}; // it is the client responsibility to trigger such callback after sign-in
4.4. Qu'advient-il d'une conversation anonyme en cours lorsque le visiteur se connecte ?
Si le visiteur discutait anonymement puis s'est connecté :
- il conservera sa conversation en cours s'il n'a pas de conversation en cours dans son espace authentifié,
- il récupérera sa conversation précédente s'il a déjà discuté en étant authentifié.
4.5. Scénarios de conversation
| Scénario de conversation | Scénario | |
| 1 | Sur plusieurs ordinateurs / navigateurs 
|
|
| 2 |
Sur le site mobile et l'application mobile de la marque en utilisant un seul appareil.
|
|
| 3 | Disponible uniquement au troisième trimestre 2022 |
|
| 4 | Conversations multiples en cours |
|
| 5 | Session expirée |
|
5. Comment gérer le succès ou l'échec de l'activation ?
Les échecs surviennent pour diverses raisons, c'est pourquoi, lors de la création d'un système robuste et sécurisé, la mise en œuvre doit faire face à de tels cas. Les échecs d'authentification peuvent se produire à deux endroits :
5.1. L'inscription dans l'espace authentifié du visiteur échoue.
Dans ce cas, la logique du backend est incapable de générer un token : c'est alors au client d'activer le tag iAdvize. En d'autres termes, c'est à l'implémentation client de décider si :
- De ne pas activer le tag (c'est-à-dire de ne pas appeler les méthodes "iAdvize.activate"
- ou de se rabattre sur une activation anonyme à la place.
Si vous souhaitez garantir une expérience conversationnelle entièrement authentifiée, nous recommandons la première implémentation défensive.
5.2. La méthode "activate" d'iAdvize peut également échouer
Si le jeton est mal formaté ou si la signature est incorrecte, la méthode "iAdvize.activate" peut également échouer.
Pour faire face à cela, la méthode "iAdvize.activate" prend un argument facultatif : une fonction qui sera appelée avec un objet contenant le résultat de l'authentification ("authentication-success" ou "authentication-failure"). Cet objet comprend la raison pour laquelle l'authentification a échoué : un jeton malformé, une clé invalide, une double tentative de connexion, ...
const iAdvizeActivationCallback = (activation) => {
console.log(activation) ;
}
/* In case of success, we get : */
{
authentification : {
option : { type : 'SECURED_AUTHENTICATION', token : '<YOUR-TOKEN>' },
status : "authentication-success
}
}
/* In case of failure, we get :*/
{
authentification : {
option : { type : 'SECURED_AUTHENTICATION', token : '<YOUR-TOKEN>' },
status : 'authentication-failure',
reason : 'A login is already ongoing' // Or another relevant error
}
}
iAdvizeInterface.push(async (iAdvize) => {
const activation = await iAdvize.activate(async () => {
const token = await ... // your backend logic to generate a JWE - note that this can be called at anytime for refresh
return {
authenticationOption : { type : 'SECURED_AUTHENTICATION', token }
} ;
}) ;
iAdvizeActivationCallback(activation) ;
}) ;
En cas d'échec, nous vous recommandons de ne pas revenir à l'activation anonyme.
À noter : La logique javascript d'iAdvize a déjà implémenté des politiques de réessai.
Elle va automatiquement réessayer 3 fois en cas d'erreur. En cas d'échec, le système iAdvize renvoie une erreur.
Nous ne recommandons pas que l'implémentation du client ajoute des tentatives supplémentaires.
6. Comment se déconnecter ?
Lorsque le visiteur se déconnecte activement de votre site web ou que sa session web expire, vous devez également le déconnecter d'iAdvize.
Pour ce faire, vous pouvez simplement utiliser "logout" comme suit :
iAdvizeInterface.push(async (iAdvize) => {
await iAdvize.logout() ;
}) ;
Le visiteur ne pourra pas commencer une nouvelle conversation tant qu'une nouvelle activation ne sera pas effectuée.
C'est ainsi que l'on se déconnecte puis que l'on démarre le moteur de ciblage, ce qui peut conduire à une nouvelle conversation :
iAdvizeInterface.push(async (iAdvize) => {
await iAdvize.logout();
await iAdvize.activate(() => ({authentificationOption : {type : 'ANONYMOUS' }}));
});
7. FAQ
7.1 Où puis-je trouver la clé publique d'iAdvize ?
7.2 Mon visiteur est authentifié (un JWT est dans le stockage local) mais je n'ai pas de cadenas 🔒 sur le bureau de l'agent.
- Veillez, lorsque vous êtes dans un espace authentifié de votre site web où l'authentification des visiteurs est activée, à supprimer l'utilisation du système "extId" : A propos de l'utilisation de l'identifiant externe (extId)
7.3 JWT non valide
- Assurez-vous d'avoir défini toutes les claims requises avec les bons préfixes
{
"https://iadvize.com/userId" : "myuserid",
"iss" : "https://livechat.iadvize.com",
"exp":1602060589
}
- S'assurer que le JWT est signé avec le bon algorithme
{
"alg" : "RS256"
}
- S'assurer que le JWE est crypté avec le bon algorithme
{
"enc" : "A256GCM",
"alg" : "RSA-OAEP-256"
}
- Assurez-vous que vous utilisez la bonne clé privée et la bonne clé publique d'iAdvize. Assurez-vous qu'iAdvize a configuré votre clé publique dans vos paramètres.
