Configuring User Names Displayed

 

1. Purpose

This document describes the way of displaying user names as of unblu release 3.2.6. User names in this context are the names displayed for authenticated users.

Display names here can be:

  • The name displayed for a mouse cursor in a running co-browsing session
  • The name displayed in the chat
  • The name displayed in agent workspace

2. User display names as of unblu version 3.2.6

For unblu version 3.2.6 and newer, the way user names are displayed and how the correct name to display is selected has changed slightly. It is mainly simplified in the code and receives a better separation of concerns.

The improved solution is oriented at the MVC (model view controller) pattern and separates:

  • the user model (the data representing a user)
  • the evaluation of the display name depending on the purpose (controller providing the view)
  • the localization of the display name (if a configured name should be taken, e.g. "agent" for a support agent in english or "Berater" in german)

2.1.1. The user model

The user model is created by a number of different product parts:

  • In the cloud, user informations include username, firstname, lastname and roles.
  • In on premise setups with unblu single sign on (SSO) distribution, these sources are currently supported:
    • trusted headers: HTTP request headers received with each request (provided e.g. by a proxy in front of the unblu server) are taken as authentication information (username, displayname, roles can be provided)
    • JEE: The servlet container running unblu inside can provide Authentication information to unblu per request (provides username). Additional informations can be provided again using HTTP request headers (displayname)
    • edbs (finnova interface): proprietary interface essentially providing similar informations as the cloud version

2.1.2. Display name evaluation

Since not all sources can provide the same model informations, it is important to define a consistent way of selecting model parts for the display name - depending on the display name purpose.

Example requirements:

  • The cloud can provide first and last name. Co-browsing users should be displayed with the last name of the agent as mouse cursor label.
  • The mouse cursor label should always be displaying a localized text "Agent" (en), "Berater" (de) etc. but the name displayed in the agent workspace should be the real name of the authenticated support agent.
  • The mouse label of the co-browsing visitor should be the technical id submitted to the unblu server, but the agent mouse label should represent the real name of the support agent.

2.1.2.1. Display name usages

Display names are used for these purposes:

  • As a mouse label of a co-browsing visitor or co-visitor / agent
  • As a chat label of a co-browsing visitor or co-visitor / agent
  • As real name of an authenticated user (e.g. on top of agent workspace)

2.1.2.2. Evaluation order configuration

The following configuration settings exist (as of unblu version 3.2.6). They specify the selection order of data to use for particular purposes. Evaluation is done in such a way, that if data is available for a key listed further in front, it overrides data available further back in the configuration.

The first configuration example is configuring, how personal or privatename display should happen. That's the case, where the user wants to see his own name as a confirmation he's logged in correctly.

privatenamedefault.displayNameEvaluationOrder=displayname,firstlast,username,identifier # available are: 'firstlast', 'displayname', 'username', 'identifier'

This configuration would take a displayname if available (only available with unblu SSO when using JEE and trusted header sources and not always provided), as fallback it would use firstname and lastname if available, then the username and last the identifier.


The order of evaluation can be changed by changing the order of the keys in the configuration list. Also, it is possible to only provide a subset:

privatenamedefault.displayNameEvaluationOrder=firstlast,username

Note, that certain configurations are useless and misleading:

privatenamedefault.displayNameEvaluationOrder=identifier,firstlast,username # will always pick identifier since this is mandatory in the model. The other options listed are never taken and thus are misleading in this list

Also note, that providing an empty display name evaluation order is an error:

privatenamedefault.displayNameEvaluationOrder= # this is logged as an error, the server starts but will always return 'empty' display names

 

Display name evaluation exists for privatename as well as participantname usage. The latter has two flavors: visitor (old name recorder) as well as co-visitor (old name player).

2.1.3. List of display name configuration properties

The following list represents all configuration options available regarding display name evaluation as of unblu version 3.2.6. The list always shows the default configuration for each property and as a comment in the back the list of available options

# settings affecting the private display name
privatenamedefault.displayNameEvaluationOrder=displayname,firstlast,username,identifier # available are: 'firstlast', 'displayname', 'username', 'identifier'

# settings affecting the co-visitor display name
participantnamedefault.player.displayNameEvaluationOrder=firstlast,displayname,nickname,staticname # available are: 'firstlast', 'displayname', 'nickname', 'username', 'staticname', 'identifier'
participantnamedefault.player.showFirstnameEnabled=true # whether or not display name should include firstname if evaluation order picked 'firstlast'
participantnamedefault.player.showLastnameEnabled=true # whether or not display name should include lastname if evaluation order picked 'firstlast'
participantnamedefault.player.participantNameDefaultPlayerKey=participantnamedefault.player # the name of the text property to use when 'staticname' is chosen

# settings affecting the visitor display name
participantnamedefault.recorder.displayNameEvaluationOrder=firstlast,displayname,nickname,staticname # available are: 'firstlast', 'displayname', 'nickname', 'username', 'staticname', 'identifier'
participantnamedefault.recorder.showFirstnameEnabled=true # whether or not display name should include firstname if evaluation order picked 'firstlast'
participantnamedefault.recorder.showLastnameEnabled=true # whether or not display name should include lastname if evaluation order picked 'firstlast'
participantnamedefault.recorder.participantNameDefaultPlayerKey=participantnamedefault.recorder # the name of the text property to use when 'staticname' is chosen

Additional informations:

  • If firstname or lastname is available but excluded with showXXnameEnabled=false, it will be ignored in the evaluation order and the next evaluation order element is used

2.1.4. List of display name localized text properties

The following list represents the localized text properties typically taken into account, if staticname has been chosen in the evaluation order (only available for participantnameor no option was left, but a participant name has to be evaluated (final fallback).

participantnamedefault.player.<lang>=
participantnamedefault.recorder.<lang>=

3. Examples

3.1.1. In a cloud setup

Co-browsing users must see the last name of the agent as mouse cursor label.

participantnamedefault.player.displayNameEvaluationOrder=firstlast
participantnamedefault.player.showFirstnameEnabled=false

3.1.2. In an on premise setup using JEE

The mouse cursor label must always be displaying a localized text "Agent" (en), "Berater" (de) etc. but the name displayed in the agent workspace must be the real name of the authenticated support agent (falling back to the user id if no real name should be available for some reason).

# JEE providing username as additional header
com.unblu.authentication.idpropagation.jee.enabled=true
com.unblu.authentication.idpropagation.jee.headerDisplayNameTrusted=x-unblu-user-displayname

participantnamedefault.player.displayNameEvaluationOrder=nickname,staticname
privatenamedefault.displayNameEvaluationOrder=displayname,identifier
# localized text properties
participantnamedefault.player.de=Berater
participantnamedefault.player.en=Agent

3.1.3. In an on premise setup using Trusted Headers

The mouse label of the co-browsing visitor to be the technical id submitted to the unblu server in the REMOTE-USER HTTP header (falling back to a static default configuration, in case the id is missing).

com.unblu.authentication.idpropagation.trustedheader.enabled=true
com.unblu.authentication.idpropagation.trustedheader.headerUserId=REMOTE-USER
participantnamedefault.recorder.displayNameEvaluationOrder=identifier,staticname

How can we help?

Chat with us and we will take you through our site!

Read about how we use cookies and how you can control them by clicking "Cookie Settings." If you continue to use this site, you consent to our use of cookies.