This article is intended to developer integration.
On this page, you will learn how to :
- Enable authenticated mode
- Setup authentication
- Sign-in
- Logout
- Deal with activation success or failure
- Deal with visitor identity expiration.
1. Authenticated Messaging overview
Here is an overview of how our authenticated messaging works. Every step will be detailed below.
It is important to keep in mind that here, anonymous means the visitor has not signed in their authenticated space, but is still identified by the iAdvize system.
2. How to enable authenticated mode in the administration portal ?
Authenticated mode is still in early access : get in touch with your iAdvize main contact to set it up.
When this mode is activated, the iAdvize tag will wait for an identity before starting. See the section below : 3. How to implement the customer authentication backend (token provider) ?
3. How to implement the customer authentication backend (token provider)?
To set up authentication, see this article: iAdvize Authenticated Messaging - web backend implementation
4. How to authenticate with iAdvize in client’s website?
To enforce a proper secured visitor authentication, the authentication mode needs to be activated. Therefore, the iAdvize tag will wait for an “authentication” instruction before loading and engaging the visitor in a conversation. It differs from the standard non-authenticated mode.
However, it is also possible to let the visitor chat in an anonymous way with authenticated mode on. Details are provided below.
4.1. Include the tag
You can dispatch the authentication instruction before the tag is included, or after. Either way, you will need to include the main iAdvize tag this way :
<script>
window.iAdvizeInterface = window.iAdvizeInterface || [];
iAdvizeInterface.config = {
sid: '<YOUR-SITE-ID>'
}
</script>
<script async src="//<YOUR-PLATFORM>.iadvize.com/iadvize.js"></script>
You will need to replace `<YOUR-SITE-ID>` with your actual site ID, which can be found on the admin : https://ha.iadvize.com/admin/site/current/code
4.2. Activate the tag with an identity
When the authenticated mode is on, the tag won’t activate until an authentication instruction is dispatched.
- Case A - if the visitor needs a real signed in identity from the client server needs, the system waits for a token,
- Case B - if the visitor can chat without a real identity, use an anonymous authentication.
If the visitor later signs in (see next section), the conversation will continue - either with the content of the previous signed in conversation (if it exists), or with the content of the previously anonymous conversation.
// 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. Provide an identity after an anonymous activation
A common scenario would be a visitor that arrives anonymously on your website, then signs in their authenticated space.
In this scenario, the Case B mentioned above for the activation has been chosen. Which means the tag has been activated anonymously, using this line:
iAdvizeInterface.push((iAdvize) => {
iAdvize.activate(() => ({ authenticationOption: { type: 'ANONYMOUS' } }));
});
Now, after a successful sign-in, the client needs to feed the iAdvize tag with the token authenticating the visitor. This can be done by triggering the same "activate" method:
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. What happens to an ongoing anonymous conversation when the visitor signs in ?
If the visitor was chatting anonymously, then signed in:
- they will keep their ongoing conversation if they do not have an ongoing conversation in their authenticated space
- they will get their previous conversation back if they chatted while authenticated before.
4.5. Conversation Scenarios
| 1. |
|
|
| 2. |
 |
|
| 3. | Multiple on-going conversation |
|
| 4. | Expired Session |
|
| 5. |
|
5. How to deal with activation success or failure ?
Failures happen for various reasons, therefore while creating robust and secure system the implementation needs to cope with such cases. Authentication failures can happen in two places:
5.1. The sign-in in the visitor’s authenticated space fails
In this case, the backend logic is unable to generate a token : it is then the client’s responsibility to activate the iAdvize tag. In other words, it is the client implementation responsibility to decide whether:
- Not to activate the tag (i.e. not calling "iAdvize.activate" methods)
- Or to fall back to an anonymous activation instead.
If you want to ensure a fully authenticated conversational experience, we recommend the first defensive implementation.
5.2. The iAdvize "activate" method can also fail
If the token is ill-formatted or if signature is incorrect, the "iAdvize.activate" can also fail.
To cope with this, the "iAdvize.activate" method takes an optional argument : a function that will be called with an object containing the result of the authentication ("authentication-success" or "authentication-failure"). This object includes the reason the authentication failed: a malformed token, an invalid key, a double login attempt, ...
const iAdvizeActivationCallback = (activation) => {
console.log(activation);
}
/* In case of success, logs :
{
authentication: {
option: { type: 'SECURED_AUTHENTICATION', token: '<YOUR-TOKEN>' },
status: 'authentication-success'
}
}
/* In case of failure, logs :
{
authentication: {
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);
});
In case of failure, we recommend that you do not fallback to the anonymous activation.
6. How to logout ?
When the visitor actively logouts from your website or their website session expires, you must also log them out of iAdvize. To do so, you can simply use `logout` like so:
iAdvizeInterface.push(async (iAdvize) => {
await iAdvize.logout();
}) ;
The visitor won’t be able to start a new conversation until a new activation is performed.
This is how you would log out then start the targeting engine, that could lead to a new conversation:
iAdvizeInterface.push(async (iAdvize) => {
await iAdvize.logout();
await iAdvize.activate(() => ({ authenticationOption: { type: 'ANONYMOUS' }}));
});
7. FAQ
7.1. Where could I find the iAdvize public key?
- Please see 2.4 iAdvize Public key (use for Production)
7.2. My visitor is authenticated (a JWT is in the local storage) but I don’t have a padlock 🔒 on the desk of the agent
- Be sure, when you are in an authenticated space of your website where the visitor authentication is enabled, to remove the usage of the `extId` system: About the External ID usage (extId)
7.3. JWT not valid
- Ensure you set all the required claims with the right prefixes
{
"https://iadvize.com/userId":"myuserid",
"iss":"https://livechat.iadvize.com",
"exp":1602060589
}
- Ensure the JWT is signed with the right algorithm
{
"alg": "RS256"
}
- Ensure the JWE is encrypted with the right algorithm
{
"enc": "A256GCM",
"alg": "RSA-OAEP-256"
}
- Ensure you use the right private key and the right iAdvize public key. Ensure iAdvize setup your public key in your settings