Engagement Messenger (EM) allows customers to extend CSM capabilities to any non-ServiceNow portal/website.
Language is a critical aspect of the experience when users interact with EM. The language for authenticated users is determined by the preferences set by the user in Service Portal and for guest users is determined by the default instance language. There can be scenarios where more granular control over the language of EM is required. For example, when EM is embedded on an English, French & German website, you would want to control the language based on the website's language
This blog details out the steps involved in configuring the language in which Engagement Messenger loads for guest users and/or authenticated users. The language can either be set dynamically from a script or be set to a static value.
Step 1:
Ensure that the version of EM embedded on the 3rd party website is V3.1.1 or higher. This version introduces the ability for EM to accept additional parameters (Documentation Link) which will be leveraged to pass the language details
Note: It is important to ensure that the code snippet embedded on the 3rd party website is referring to the latest version. One quick way to verify this is to check whether “sn_csm_ec.js?v=3.1” is present in embedded code (image below for reference). Refer to this documentation for more details
Step 2:
Import the UI Macro attached to the blog. This will create a new UI Macro with the name “sp_css_includes”. Alternatively, you can create a new UI Macro with the same name and copy the code from the attached file. This macro has additional code that parses the language details being passed to EM
Note: The macro ensures that the language preference is set only for guest users. If you wish to set the language preference for authenticated users as well remove the “$[AND] !gs.isLoggedIn()” code on line 37 in the macro (highlighted in the screenshot below)
Step 3:
While embedding Engagement Messenger on the 3rd party website the following additional points need to be taken care of:
- A new “feature context” for language needs to be defined
- Engagement Messenger needs to be triggered with the new feature context
- Additional code/logic needs to be added to set the value of the language in which EM should be loaded
Below is a sample code snippet that you can use directly while embedding EM (Note: Replace the module ID with your module details). The code snippet takes care of points 1 & 2 mentioned above. For point 3, the value of the variable “language” (on line 3) needs to be set.
<script>
var language; /*language = Uncomment and write your code to get website selected language*/
function langaugeFeatureContext() {
return {
feature: "LANGUAGE",
openOnLoad: true,
params: {
"lang": language
}
}
}
var langFeature = {
"feature": "LANGUAGE",
"static": {},
"params": {
"lang": "lang"
}
};
SN_CSM_EC.addNewFeatureContext(langFeature);
SN_CSM_EC.init({
moduleID: "https://instancename.service-now.com/#d27c94d6db403810a2a6a0ced39619da",
loadFeature: langaugeFeatureContext()
});
</script>Anatomy of the above code snippet:
- Lines 13-20 defines the new feature context to accept language parameters
- Line 21 adds the new feature context to Engagement Messenger
- Line 24 ensures that EM is triggered with the new feature context defined
Let’s take a couple of scenarios to illustrate point 3:
Scenario 1: You need to load Engagement Messenger in a fixed language on a website i.e. load in French on the website. Simply set the value of the variable language e.g. to “fr” for French. Below would be the code snippet you would embed on the website
<script>
var language = “fr”; /*language is set to french*/
function langaugeFeatureContext() {
return {
feature: "LANGUAGE",
openOnLoad: true,
params: {
"lang": language
}
}
}
var langFeature = {
"feature": "LANGUAGE",
"static": {},
"params": {
"lang": "lang"
}
};
SN_CSM_EC.addNewFeatureContext(langFeature);
SN_CSM_EC.init({
moduleID: "https://instancename.service-now.com/#d27c94d6db403810a2a6a0ced39619da",
loadFeature: langaugeFeatureContext()
});
</script>Scenario 2: You want to control the EM language based on the website language which can be identified from the URL. Let’s say the URL is of the format https://www.companyname.com/fr/ or https://www.companuname.com?lang=fr. Then additional logic needs to be added to parse the website URL, get the language details & set the language variable
Scenario 3: Let’s say the website has a selector that allows users to select the language of their choice. Then based on the selection, the variable language needs to be set & EM needs to be reloaded
Step 4:
The final step is to make a minor modification to the EM Header Widget so that the “Greetings Message” will be displayed. If this is not important, you can skip this step.
1. Go to Service Portal -> Widgets -> "CWF EC Header”
2. Make the highlighted change in the “client script” (on line 356)
You are all set. Once your finish the above steps, you can control the language in which EM loads for guests as well as authenticated users.
1 Comment
