Desktop and Application Streaming

Web application redirection options for the AppStream 2.0 Client

The Amazon AppStream 2.0 client is powerful tool for extending the capabilities of AppStream 2.0 beyond what an HTML5 web browser can provide. Many features, such as local printer redirection, USB redirection and file system redirection are only available via the AppStream 2.0 client. Customers using the AppStream 2.0 streaming URL connection method often ask how a streaming URL generated via a web application can be redirected to the AppStream 2.0 client. In this blog, I will walk you through options on how to redirect AppStream 2.0 streaming URLs to the AppStream 2.0 client and things to consider when doing so.

Basic URL redirection

The AppStream 2.0 technical documentation provides the basics on how to redirect a streaming session URL to the AppStream 2.0 client. The URL must be base64 encoded in order for the client to consume the URL and must be prefixed by the client’s protocol amazonappstream:. Using that information, we can construct a basic AJAX call that, on success, will redirect the streaming session to the AppStream 2.0 client.

In the following example, we are using the POST response method to send an email address, previously inputted by the user, to an Amazon API Gateway invoke URL. If a successful response is returned, the streaming URL is encoded by the btoa() method and redirected to the client. If the AppStream 2.0 client is installed on the local system, it will open and launch the redirected URL.

$.ajax({
    method: 'POST',
    url: 'API-GW-INVOKE-URL',
    data: JSON.stringify({
        'email': email
    }),
    contentType: 'application/json',
    success: function (response, status) {
        console.log('Status: ' + status + '. ');
        window.location.href = 'amazonappstream:' + btoa(response.as2url);
    },
    error: function (response, status) {
        console.log('Status: ' + status + '.');
        window.location.reload;
    }
});

When the URL is redirected to the AppStream 2.0 client, your users may be presented with a prompt informing them that the website is trying to open AppStream 2.0 client.

Image showing a browser prompt when a website is opening an external application.

NOTE: If using custom domains for your AppStream 2.0 streaming endpoints, you may need to allow those domains in the client’s configuration. For more information please see, Set the TrustedDomains Registry Value to Enable Other Domains for the AppStream 2.0 Client.

Managing your user’s experience

If your users are using managed Windows systems to connect to their AppStream 2.0 streaming sessions, you can use the following ADMX templates to configure either the default application handler for AppStream 2.0 client links or configure which websites are allowed to open the client without user intervention. This will allow your users to avoid being prompted by the browser when opening a streaming URL in the AppStream 2.0 client.

NOTE: Please make sure your allow list for the websites/domains that are allowed to automatically open the AppStream 2.0 client are trusted.

If using GPOs is not an option, some of these configuration can also be set via registry entries, please see the policy documentation links above for more details.

Dealing with a mixed user base

If some of your user base is unable to use the AppStream 2.0 client, the preceding AJAX call will not work for them. They will either get a message saying that there is no application to handle that type of link, or with some browsers, no message or notification will displayed to the users at all.  Obviously that would be a frustrating experience for those users and so it’s important to design your web application to handle users that may not be using the AppStream 2.0 client.

One option is to use a JavaScript library like Custom Protocol Check. This JavaScript library will detect if a custom protocol is available to the browser and take an action if it’s detected, if the protocol is not detected, then another defined action will be taken. In following example, we modify the previous AJAX call code with the Custom Protocol Check function. If the AppStream 2.0 client protocol is detected, the AppStream 2.0 streaming URL will be opened in the client, however if the protocol is not detected, the URL will be opened in the web browser.

$.ajax({
    method: 'POST',
    url: 'API-GW-INVOKE-URL',
    data: JSON.stringify({
        'email': email
    }),
    contentType: 'application/json',
    success: function (response, status) {
        console.log('Status: ' + status + '. ');
        customProtocolCheck('amazonappstream:' + btoa(response.as2url),
            () => { 
                console.log("AS2 client was not found, launching AS2 session in browser.")
                window.location.replace(response.as2url);
            },
            () => {
                console.log("AS2 client was found and opened the streaming URL successfully.");
                window.location.reload;
            }, 3000
    ); 
    },
    error: function (response, status) {
        console.log('Status: ' + status + '.');
        window.location.reload;
    }
});

This will allow you to maintain one function that can serve both your web client and desktop client user base, without requiring any action by the user.

Another option would be requiring your users to input what client platform they would like to use before generating the AppStream 2.0 streaming URL. The following AJAX call example, again modifying the first example AJAX call code, will either launch the streaming session in the web browser or launch the session in the AppStream 2.0 desktop client depending on what the user chose. The method of that input could be a radio button, a checkbox, a text button etc.

$.ajax({
    method: 'POST',
    url: 'API-GW-INVOKE-URL',
    data: JSON.stringify({
        'email': email
    }),
    contentType: 'application/json',
    success: function (response, status) {
        console.log('Status: ' + status + '. ')
        if (platform == 'web') {
            console.log('API call was successful, launching AS2 session in browser.');
            window.location.replace(response.as2url);
        }
        else if (platform == 'as2client') {
            console.log('API call was successful, redirecting AS2 session to AS2 client.');
            window.location.href = 'amazonappstream:' + btoa(response.as2url);
            window.location.reload;
        }
    },
    error: function (response, status) {
        console.log('Status: ' + status + '.');
        window.location.reload;
    }
});

Conclusion

And that’s it! You should now know the options for redirecting streaming URLs generated in web applications to the AppStream 2.0 client and what should be considered when doing so. For more information on how to get started building an AppStream 2.0 web application, please see our ISV Workshop series.