Support for the unified user experience

Note:

“StoreFront” continues to be the name used to refer to the enterprise app store that aggregates applications and desktops from Citrix Virtual Apps and Desktops sites into a single easy to use store for users. Citrix Receiver technology is now included in Citrix Workspace app. Implementing this transition in our products and documentation is an ongoing process. In-product content might still contain former names—for example, the unified experience refers to “Citrix Receiver”. Your patience during this transition is appreciated. For more detail about our new names, see https://www.citrix.com/about/citrix-product-guide/.

StoreFront supports the unified user experience. The unified experience delivers a centrally managed HTML5 user experience to all web and native Citrix Workspace apps. This supports customization and featured app groups management.

Stores created using this version of StoreFront use the unified experience.

Use the StoreFront management console to do the following Citrix Receiver for Web related tasks:

  • Create a Citrix Receiver for Web site.
  • Change the Citrix Receiver for Web site experience.
  • Select a unified Citrix Receiver for Web site to associate with the store.
  • Customize the Receiver appearance.

Use Javascript and CSS to customize Citrix Receiver for Web pages.

In multiple server deployments, use only one server at a time to make changes to the configuration of the server group. Ensure that the Citrix StoreFront management console is not running on any of the other servers in the deployment. Once complete, propagate your configuration changes to the server group so that the other servers in the deployment are updated.

Note:

If using XenApp 6.x, applications set to Stream to client or Streamed if possible, otherwise accessed from a server are not supported with the unified experience enabled.

Create a Citrix Receiver for Web website

A Citrix Receiver for Web site is created automatically, whenever you create a store. You can also create additional Receiver for Web sites using this procedure.

  1. On the Windows Start screen or Apps screen, locate and click the Citrix StoreFront tile.
  2. Select the Stores node in the left pane of the Citrix StoreFront management console and, in the Actions pane, click Manage Receiver for Web Sites > Add and follow the wizard.

Select a unified Citrix Receiver for Web site to associate with the store

When a new store is created using StoreFront, a Citrix Receiver for Web site is automatically created and associated with the store. Citrix Receiver for Web sites use the unified experience. When a store has multiple Receiver for Web sites, you need to select which Receiver for Web site is displayed when users access the store using Citrix Workspace app.

  1. On the Windows Start screen or Apps screen, locate and click the Citrix StoreFront tile.
  2. Select the Stores node in the left pane of the Citrix StoreFront management console, select a store in the center pane, and click Configure Unified Experience in the Actions pane. If you do not have a Citrix Receiver for Web website created, a message displays including a link to the Add Receiver for Web site wizard.
  3. Select the default Receiver for Web site which Citrix Workspace app clients display when users access this store.
  4. Click OK.

Customize the Citrix Receiver appearance

  1. On the Windows Start screen or Apps screen, locate and click the Citrix StoreFront tile.
  2. Select the Stores node in the left pane of the Citrix StoreFront management console and in the Actions pane, click Manage Receiver for Web Sites and click Configure.
  3. Select Customize Appearance and make selections to customize how the website displays after logging on.

localized image

Further customization using Javascript and CSS

Note:

In the examples in this section, add Javascript to the script.js file (for example in C:\inetpub\wwwroot\Citrix\StoreWeb\custom), and add CSS to the style.css file in the same directory.

Add a static header to the login page in Receiver for Web

Here ‘static’ here means fixed text like a welcome message, or a company name. For something that changes, such as a news message or server status, see Add a dynamic header to the login page in Receiver for Web.

You can add static text in four positions using the following lines of javascript:

$('.customAuthHeader').html("Example one - top of login screen");
$('.customAuthTop').html("Example two - above login box");
$('.customAuthBottom').html("Example three - below login box");
$('.customAuthFooter').html("Example four - bottom of login screen");

To make the text more obvious, add the following styling to custom.css:

.customAuthHeader,
.customAuthFooter,
.customAuthTop,
.customAuthBottom
{
 font-size:16px;
 color:yellow;
 text-align: center;
}

This gives the following result:

static-text-example

To use HTML formatting, replace the 4 lines of javascript with the following:

$('.customAuthHeader').html("<b>Example one</b> – top of login screen");
$('.customAuthTop').html("<div style='background:black'>Example two – above login box</div>");
$('.customAuthBottom').html("<i>Example three – below login box</i>");
$('.customAuthFooter').html("<img src='logo.png'>Example four – bottom of login screen");

Note:

The fourth example line expects an image named logo.png in the custom directory.

Add a dynamic header to the login page in Receiver for Web

Here ‘dynamic’ means that some content is loaded and displayed every time, rather than being cached. Web browsers often cache things when they can, but Citrix Workspace app always caches the UI, and always loads the previously cached UI. That means if you use the previous example for something like service status, you do not get what you intended.

Instead, you need to make an Ajax call to dynamically load the content and insert it into the page. To do this:

  1. Define a useful utility function which fetches the content from a page in the \customweb directory on the server, and adds it to the page. This does the equivalent of the .html examples above, and the custom page can contain text, or an HTML snippet. Use the \customweb directory because it gets copied to all servers in a StoreFront server group (just like the \custom directory) but it does not get downloaded and cached.

  2. Arrange for this function to be called at a suitable point. Calling the function too early causes problems in Citrix Workspace app, because the script runs before the configuration has been fully loaded. A good time for this sort of action is beforeDisplayHomeScreen (but if you want to display content on the login page, then use beforeLogin instead). The following code handles both cases, and is suitable for web and native clients.

The full script is as follows:

function setDynamicContent(txtFile, element) {
   CTXS.ExtensionAPI.proxyRequest({
      url: "customweb/"+txtFile,
      success: function(txt) {$(element).html(txt);}});
}

var fetchedContent=false;
function doFetchContent(callback)
{
  if(!fetchedContent) {
    fetchedContent = true;
    setDynamicContent("ReadMe.txt", "#customScrollTop");
  }
  callback();
}

CTXS.Extensions.beforeDisplayHomeScreen = doFetchContent;
CTXS.Extensions.beforeLogon = doFetchContent;

This loads content from \customweb\readme.txt which, by default, contains some uninteresting information. Add your own file (status.txt) and adjust the script to call it for more useful results.

Show a click-through disclaimer before or after login

The following example is already provided in the script.js file as an example, but needs uncommenting. There are two versions of this code: the first is done pre-login for web browsers, and the second is done pre-main UI for native clients. If you only want a post-login message, delete the first function. However, using a pre-login message on its own is not a good option, as the login flow is only seen on web browsers (and not on native clients). Even then, the login flow is hidden when users are accessing from Citrix Gateway.

var doneClickThrough = false;

// Before web login
CTXS.Extensions.beforeLogon = function (callback) {
  doneClickThrough = true;
  CTXS.ExtensionAPI.showMessage({
    messageTitle: "Welcome!",
    messageText: "Only for WWCo Employees",
    okButtonText: "Accept",
    okAction: callback
  });
};

// Before main screen (both web and native)
CTXS.Extensions.beforeDisplayHomeScreen = function (callback) {
  if (!doneClickThrough) {
    CTXS.ExtensionAPI.showMessage({
      messageTitle: "Welcome!",
      messageText: "Only for WWCo Employees",
      okButtonText: "Accept",
      okAction: callback
    });
  } else {
    callback();
  }
};

Make the click-through disclaimer box wider

The message box used for CTXS.ExtensionAPI.showMessage() is pre-styled. You can adjust this style to make it larger, so that it looks OK for other messages. Add the following example function to script.js to shrink the style again afterwards. Call showLargeMessage() instead of CTXS.ExtensionAPI.showMessage() when you want a larger box.

function mkLargeMessageExitFn(origfn)
{
  if(origfn) {
    return function() {
      origfn();
      window.setTimeout(function() {$('body').removeClass('largeMessage');},500);
    };
  }
}

function showLargeMessage(details)
{
  $('body').addClass('largeMessage');
  details.cancelAction = mkLargeMessageExitFn(details.cancelAction);
  details.okAction = mkLargeMessageExitFn(details.okAction);
  CTXS.ExtensionAPI.showMessage(details);
};

This adds a marker class when the large message is being shown. When the box is closed, it removes this marker class after a small delay (needed to avoid a nasty ‘jump’).

Add some CSS to adjust the size of this box based on the presence of this marker class. For example, try the following in custom\style.css:

.largeTiles .largeMessage .messageBoxPopup
{
  width:800px;
}

Then, when a messageBoxPopup is shown on a large UI and the largeMessage flag is set, it is 800 pixels wide. Existing code ensures that it is centered. (On a small UI such as a mobile phone, the default message box is already full width).

wide-disclaimer-box

To squeeze in even more text, you can reduce font size by adding the following to custom\style.css, or alternatively consider adding scrollable content.

.largeTiles .largeMessage .messageBoxText
{
  font-size:10px;
}

Make the click-through disclaimer box have scrollable content

When you call showMessage you can pass some HTML rather than just a string, to add style. To do this, replace messageText, in any of the previous example calls to showMessage, with the following:

    CTXS.ExtensionAPI.showMessage({
          messageTitle: "Welcome!",
          messageText: "&lt;div class='disclaimer'&gt;rhubarb rhubarb  rhubarb ... rhubarb rhubarb&lt;/div&gt;",
          okButtonText: "Accept",
          okAction: callback });

Then add the following to style.css:

.disclaimer {
    height: 200px;
    overflow-y: auto;
}

This gives the following result:

scrolling-text-example

There is another custom area specifically for this. You can add the following line of Javascript to set its content:

$('#customBottom').html("For ACME Employees Only");

Define the style in style.css. Set position:static to ensure that the scrolling area works as expected.

#customBottom
{
 text-align:center;
 font-size:30px;
 position:static;
}

Note:

If you dynamically resize this area using a script, you must call the CTXS.ExtensionAPI.resize() command to let Citrix Workspace app know that something has changed.

Make the folder view the default, when users go to the Apps tab

To do this, monitor for the ‘view change’ event. If the view to the ‘store’ (the internal name for the apps view) changes, navigate to the root folder. Watch out for:

  • When the onViewChange event fires, to say the store view is changing, the view has not finished drawing. Therefore, if you navigate to the folder immediately, the initialization code for the store view simply undoes your work, because it runs after your code. To avoid this, add a 1 ms delay to ensure that your code executes after the current stack unwinds.

  • The three lines containing the word ‘whitespace’ ensure that the initial All Apps UI is drawn off screen by putting a large custom area above it. This stops the All Apps view flickering before the folders appear.

Add the following code to script.js as usual:

$('#customScrollTop').append('&lt;div class="whitespace"&gt;&lt;/div&gt;');

CTXS.Extensions.onViewChange = function(view) {
  if (view == "store") {
    $('.whitespace').height(5000);
    window.setTimeout(function() {
      CTXS.ExtensionAPI.navigateToFolder("/");
      $('.whitespace').height(0);
    }, 1);
  }
};

You can use the following code to achieve this. Start by remembering every app in a bundle, and then remove them from the ‘All Apps display’ list.

var bundleApps = [];

CTXS.Extensions.sortBundleAppList = function(apps,bundle, defaultfn) {
  for (var i = 0; i &lt; apps.length; i++) {
    bundleApps.push(apps[i]);
  }
  defaultfn();
};

CTXS.Extensions.filterAllAppsDisplay = function(allapps) {
  for (var i = 0; i &lt; allapps.length; i++) {
    if ($.inArray(allapps[i], bundleApps) != -1) {
       allapps.splice(i, 1);
       i--;
    }
  }
};

If you use this customization, it is a good idea to change the text string “All Apps” to say “Other Apps”, to avoid users getting confused. To do this edit the strings.en.js file in the custom directory, then add a tag for the AllAppsTitle. For example, with changes in yellow:

(function ($) {
  $.localization.customStringBundle("en", {
   <span style="background-color: yellow;">AllAppsTitle: "Other Apps",</span>
   Example1: "This is an example",
   Example2: "This is another example"
});
})(jQuery);

Change the default UI text

You can change any of the text used in the UI if you know what its label is called. For example, to change the ‘Install’ screen used in Receiver for Web on Google Chrome to ‘Get Started’, add a custom string as follows:

(function ($) {
  $.localization.customStringBundle("en", {
   <span style="background-color: yellow;">Install: "Get Started",</span>
   Example1: "This is an example",
   Example2: "This is another example"
});
})(jQuery);

get-started

To discover the name of the label to change:

  1. On the StoreFront server look in the directory C:\inetpub\wwwroot\citrix\StoreWeb\receiver\js\localization\en (assuming your store is called ‘Store’).
  2. Open the file ctxs.strings_something.js in notepad.
  3. Look for the string you want to change. Note: instead of editing this file directly, create override values in the custom directory as for the ‘install’ example.

Important:

Do not try to overwrite the images on the server. This confuses any clients that have already downloaded the images, because they do not know they have changed. It also makes upgrade hard, or impossible.

You can add your own images to the \custom directory, and add CSS to reference them. Each featured category (called ‘bundles’ internally) uses two images:

  • The first image is used as a tile in the carousel.
  • The second image is used as a background image behind the header on the detail page. This image is stretched to fill the width of the screen, and a blur is added to its bottom edge.

You can use different images for each screen. Consider using the same image but double its background height in the detail page, so that only the top half of the image is displayed. Because the image is stretched on the detail page, use an image which looks good if deformed.

The first bundle has class ‘appBundle1’, the second ‘appBundle2’ and so on up to ‘appBundle8’. The following example uses image ‘clouds.png’, which you can download by right-clicking on the following image:

clouds

  1. Save the image in the \custom directory. The image needs to be about 520 × 256 pixels to be consistent with the others (but it is scaled as needed).
  2. Add the following to style.css:
.appBundle1 {
  background-image: url('clouds.png');
}

.bundleDetail.appBundle1 {
  background-image: url('clouds.png');
  background-size: 100% 200%;
}

This gives the following result:

featured image carousel

featured image detail

Prevent a company logo looking blurry

Receiver for Web needs to handle both regular (‘low DPI’) screens, and newer hi-res (‘high DPI’) screens that have a higher number of pixels per square inch, correctly. For example, Apple Retina screens are twice the resolution of non-retina screens. On laptops, screens are typically x1.5, x2 or even x3 the “normal” number of pixels for their size. As x2 is by far the most common, and makes the most difference, Citrix Workspace app has most of its image assets at two resolutions. An image that is 100 × 100 pixels on a normal screen, also has a x2 version at 200 × 200 pixels.

When you upload logo images from the StoreFront management console, make sure they are x2 images. In other words, they are approximately double the width and height of the ‘space’ on a regular screen. (Images uploaded at x1 are not enlarged to x2.) The ‘space’ on a regular screen is 170 × 40 pixels, so the logo image you upload should be around 340 × 80 pixels.

StoreFront creates a copy of the logo and scales it to half the size. This image is used on low DPI displays.

Occasionally, this results in a blurred image because half the image detail has been discarded. This is rare as logos tend to be bold and simple. If your logo suffers from this problem, use the following workaround:

  1. Create two versions of your logo, one at the x1 size and one at the x2 size, and save them in the \custom directory.
  2. Edit the custom\style.css so that it references the two different images. This give something like:
<span style="color: green;">/* The following section of the file is reserved for use by StoreFront. */</span>
<span style="color: green;">/* CITRIX DISCLAIMER: START OF MANAGED SECTION. PLEASE DO NOT EDIT ANY STYLE IN THIS SECTION */</span>
<span style="color: green;">/* CITRIX DISCLAIMER: END OF MANAGED SECTION. */</span>
<span style="color: green;">/* You may add custom styles below this line. */</span>

.logo-container {
    background-image: url('mylogo_x1.png');
    background-size: 169px 21px;
}

.highdpi .logo-container {
    background-image: url('mylogo_x2.png');
    background-size: 169px 21px;
}

Note:

  • Ensure that these custom styles are not inside the ‘managed section’. Otherwise they are overwritten, or they confuse the StoreFront management console.
  • Both styles specify the same background size. This is because the size is specified in ‘logical’ units, and for the x2 image, the background size is half the width and height of the actual logo.

Set a background image

Note:

The unified experience is designed for a simple white background. Background images tend to be distracting. If you add a background image, try to use an image that is light and simple. If necessary, adjust any fonts so that they continue to work against this image.

Example 1: CSS reference to uploaded image

Change the custom.css as follows:

.storeViewSection {
   background: url('images/background.jpg') no-repeat center center fixed;
   background-size: cover;
}

Note:

The background-size:cover; statement does not work in some older browsers.

Example 2: CSS reference to existing image with tweaks

Change the custom.css as follows:

.storeViewSection {
   background: url('../media/bg_bubbles.jpg') no-repeat center center fixed;
    background-size: cover;
    color: white;
}

// Tweak fonts
.smallTiles .storeapp .storeapp-name,
.largeTiles .storeapp .storeapp-name {
    color: white;
}

// Tweak bundle area so it doesn't clash as badly
.largeTiles .applicationBundleContainer {
    background-color: rgba(255, 255, 255, 0.4);
    margin-top: 0;
    padding-top: 25px;
}

.smallTiles .applicationBundleContainer {
    background-color: rgba(255, 255, 255, 0.4);
    margin-top: 0;
    padding-top: 14px;
}

This gives the following result:

background image

Find errors in your code

There are several ways to debug. Always try a browser first. This is far easier than debugging customizations in Citrix Workspace app. You can add the following arguments after the ? or # in the page URL, and you can string several together. For example:

http://storefront.wwco.net/Citrix/StoreWeb/#-tr-nocustom

-errors — Normally, we try to suppress any errors that might occur in the code, but you can highlight them instead. This argument displays an alert box when an error occurs.

-debug — This argument disables any exception handling for customization code. This is useful with the development tools built into modern browsers (like F12 in Google Chrome or Internet Explorer), and you are debugging exceptions yourself.

-nocustom — This argument disables your script and CSS customizations. This is useful if Citrix Workspace app is not working, and you want to find out if it is due to an error you have introduced.

-tr — This argument provides tracing of the Citrix Workspace app UI code in a separate browser tab, including any tracing you add with calls to CTXS.ExtensionAPI.trace().

Unified user experience

This section describes the features and appearance of the unified experience.

Card layout

Apps in the store are represented in a “card” layout. You can expand a panel below each card to show more details and actions.

Home

Home displays the favorites.

unified UI home

Favorites

Click or tap the star to make an item a favorite:

star icon

Search across all apps, desktops, and categories:

star icon

Settings

Access settings from the drop-down menu:

settings icon

The menu shows the user name, taken from the Active Directory display name. If the display name is left blank (we do not recommend this), the domain and account name display. Use the menu to open the Settings page, check Citrix Workspace app version, or log off.

unified UI settings

Settings allow you to resume any disconnected sessions, and disconnect all of your current sessions and log you out respectively. Display the settings page in card or list layout:

card-list icon

Connect. Resumes any disconnected sessions.

Disconnect. Disconnects all of your current sessions and logs you off.

Activate Citrix Receiver. Downloads a file that adds this store to the local Citrix Workspace app.

Change Citrix Receiver. Opens a page that checks for a local Citrix Workspace app. This also allows users to switch between launching resources using the locally installed Citrix Workspace app, and launching them in an HTML5 browser.