With the sheer pace at which web technologies are evolving, frontend design & development have imploded over the past few years. The increased demand for website accessibility (a11y) is quite frankly unmatched and has left many businesses unprepared for the next billion users. With hot new tools, frameworks, concepts, and design principles being introduced every month. Features promoting accessibility often don’t find the right priority in a frontend team’s kanban boards of things to work on in a sprint.

While the developers building modern websites continue to remain burdened with features & bugs to fix on countless dependencies, platforms, and browsers. I was among them looking for effective tools that can boost accessibility using machine learning on the cloud when implemented. That’s how I came across Azure’s Immersive Reader. Read on to see what you can do with it and how exactly it integrates with your pre-built stack. In order to provide real-world accessibility features with something as simple as a few API calls (and tons of fun).

Unlocking Web Accessibility for all abilities 🌎

We rely on apps, websites, and services to go on about our daily lives. Some of these apps, websites, and services are the ones we build. Yeah, you (the reader) might be working in a startup, an organization, or an MNC. The choice between features potentially boosting accessibility or a deadline of tasks that need to be completed is always there. Some countries even ensure that Web Accessibility is legally enforceable. One can file class-action lawsuits against companies for not following the law. While building features & design elements geared towards accessibility might be hard, increasingly time-consuming, or tough to master. At least, in the short term, it doesn’t have to be. Here’s how the Immersive Reader can help

Recent case in late 2019, where the argument was termed on the basis of businesses not being liable to maintain accessible websites results in disabled people being effectively locked out of substantial portions of the economy.
On web accessibility becoming a legal requirement in India over the course of time.

Turn the slider right to left to see different features available.

With years of research and tens of products by Microsoft on how to better assist folks with the use of technology. Azure’s Immersive Reader features will truly sound like an end-to-end solution covering every basic accessibility feature that makes up any modern website’s “must-have” list.

A Fully Featured embedded web based Screen Reader
- Realistic male/female voices with fine tuned control over speech, tone and speed.
Translation support for over 60 languages (If words are written down, it can read it)
High contrasts color backgrounds for easy reading
Text scaling, spacing, focus, grammar and font support for all kinds of readers.
(Bonus) Visual cues for tougher words, and concepts
And so. Much. More.

The Immersive Reader is so good that only someone trying it can actually feel its true potential. Hence, I spun up this demo of my Immersive Reader instance hosted on Azure App Service. It’s an Immersive Reader application being used to read aloud articles on a blog that I have written in the past.

Take me to the Demo!

Take me to the Code

Bridging the gap with Immersive Reader

While the immersive reader gets high points on accessibility, it packs a punch with features through the Microsoft team’s research and years of work in the field of accessibility. This helps ensure that the experience is both frictionless and joyful as ever. I was actually looking for tools that folks can use to read and learn better on the web before coming across Immersive Reader from Azure. A useful application is a PWA app that folks can use to easily read aloud files and web pages and from anywhere without compromise.

Here’s some snapshots of the features that could be used to bridge the gap effectively between your product goals towards accessibility and your target audience. While the application could support even more things like keyboard shortcuts and more languages, that will surely come as the team expands and improves the product.

Seamless accurate translations built-in with math support

Get your entire content online automatically supported and available in 60+ languages. One step closer to bringing Internationalization on the platform.

Focus reading for folks struggling with attention disorders

Another application idea that is already out there. Students using Immersive Reader in already integrated into popular tools like Microsoft office and other platforms. I personally remember using this to listen and memorise notes faster with the little illustrations you get while reading.

Tons of options for users to choose from and customize their experience!

These screenshots barely scratch the surface of the level of ease and readability the immersive reader can provide to all its users! Key features and capabilities include focus mode, immersive reading, reading aloud, font spacing and short lines, parts of speech support, syllabification, a picture dictionary, etc.

Okay I am sold, how do I …. 🤔

.. build, integrate and run Immersive Reader on your website, application or platform. Sounds complex? Well, we are here to help. Azure and I have you covered from every major platform to every major application with all the tools and guides you will ever need. Here’s a step by step version of creating the demo for your eyes only.

Get the Access
- Did I tell you about pricing?
Get the resources setup and ready to go
- Create a resource group (will explain what that is)
- Create a AAD app registration (will explain what that is)
Integrating Immersive Reader in your app, website, platform, or service
- Bonus: Understanding the architecture
- Tweaking some code of your application to get Immersive ready
- Integrating using the Javascript SDK
- Adding more features to the Immersive Reader
- Finishing touches

First, you’ll need to get yourself the access 🔐

If you haven’t signed up for a free Azure Account, I am not completely sure on what were you waiting for. Well, the wait has finished. New signups get 14,500 rupees worth of free credit, 12 month of free services which also contain 25+ always free services. Additionally. if you are a student then you are bound to get free credits under Azure for Students program without using a credit card.

Head on to the next step when you are in the system.

You ask, but Vipul what about the pricing? 💵 💵 💵

A standard tech blog has about a 1000 words. On average that comes around to 6500 characters. That’s means the Immersive Reader service can recite, parse and help folks understand your content about 460 times in 60+ languages before asking for a single dollar. Check for updated pricing.

That’s some value right here.

Then, create your own Immersive Reader resource 👩‍💻

After signing into Azure, you will land on the Azure dashboard. From there, head to the guide for creating your own Immersive Reader resource and configuring the Azure Active Directory (AAD or Azure AD) authentication. Most things in Azure are part of your subscription, where resources need to be created to access them. These help keep all resources used for an application or instance together, well organized, and easier to find. To get started on Immersive Reader hassle-free, one can use the Cloud shell script available for the user.

Each time an Immersive Reader resource is created, whether with this script or in the portal, it must also be configured with AAD permissions. The guide will help you with that. The steps are straightforward until the function call to be made in step number 3, which requires a lot of information upfront. I have tried condensing the function call into a nifty code snippet that can be reused when needed. It contains helpful context and information which would be needed to run the script. Let me know in the comments if you need help.

	Create-ImmersiveReaderResource
	-SubscriptionName 'MyOrganizationSubscriptionName' [1]
	-ResourceName 'MyOrganizationImmersiveReader' [0]
	-ResourceSubdomain 'MyOrganizationImmersiveReader' [0]
	-ResourceSKU 'S0' [0]
	-ResourceLocation 'westus2' [0]
	-ResourceGroupName 'MyResourceGroupName' [2]
	-ResourceGroupLocation 'westus2' [2]
	-AADAppDisplayName 'MyOrganizationImmersiveReaderAADApp' [3]
	-AADAppIdentifierUri 'https://MyOrganizationImmersiveReaderAADApp' [3]
	-AADAppClientSecret 'SomeStrongPassword' [3]
	-AADAppClientSecretExpiration '2021-12-31' [3]

	[0] – Your choice
	[1] – https://portal.azure.com/#blade/Microsoft_Azure_Billing/SubscriptionsBlade
	[2] – https://portal.azure.com/#blade/HubsExtension/BrowseResourceGroups
	[3] – Check Screenshot for Azure App Directory – App registration tab in the sidebar

view raw resource-gen-function guide hosted with ❤ by GitHub

When you finally end up running the function. As a result of the script, you will see an Immersive reader resource would have been created with the resource already configured with the right Azure AD. The JSON object, as shown below, should be the output that you should be getting after running the script. Use this object’s values, create your .env file as mentioned to store the secrets for the Immersive Reader application we will be building in the next steps. We are almost there!

Bonus: Understanding the architecture 🚀

Now that you have access to the service and configured your Azure Active Directory correctly. Let’s talk through the steps we are taking to build/tweak our application and subsequently integrate Immersive Reader. With the help of this architecture diagram, I hope it will be clear on how friction-less the entire progress is made to be from ideation to integration to customers actually using Immersive Reader.

In the initial steps on the left, we have used the cloud shell to create the 2 resources that were required. This was the resource group that holds our Immersive Reader resource(s). The other being the App Registration needed inside the Azure Active Directory. In the next steps, as we integrate the Immersive Reader into our app, the app will be requesting the AAD for an authentication token for the Immersive Reader. Using the SDK & the auth token, we will authenticate our requests to the immersive reader anytime the user clicks on the Immersive Reader button.

Tweaking some code on our way to improving accessibility

As we progress, there are some optimizations and features one could implement in their Immersive Reader to fit better with the UI/UX. We have already seen the Azure’s service can easily understand and read text off the screen. This is due to some tweaks that need to be made to the HTML code on the client side. Check out what you can do to improve the experience of your users.

Preparing your HTML content for Immersive Reader

For Immersive Reader to read your data correctly, make sure to assign a div with the right ID and then use the same to fetch the content from the HTML while sending the data using the SDK method, launchAsync()

	<body>
	<div class="container"><button class="immersive-reader-button" data-button-style="iconAndText data-locale="en"></button>
	<h1 id="ir-title">Vipul Gupta's Immersive Reader Demo</h1>
	<div id="ir-content" lang="en-us">
	<h2>What is Serverless?</h2>
	<p>
	Serverless computing is a cloud computing execution model in which the cloud provider runs the server, and
	dynamically manages the allocation of machine resources. Pricing is based on the actual amount of resources
	consumed by an application, rather than on pre-purchased units of capacity or bandwidth.
	</p>
	</div>
	</div>
	</body>

view raw index.html hosted with ❤ by GitHub

Customising the Immersive Reader button

Well, everyone loves a little customising. It’s all CSS after all. Read more here.

	<style type="text/css">
	.immersive-reader-button {
	background-color: white;
	margin-top: 5px;
	border: 1px solid black;
	float: right;
	}
	</style>

view raw immersive-button.css hosted with ❤ by GitHub

Checkout the sample HTML snippet I have created using all these best practises to work well with the immersive reader application.

Azure documentation contains quick start guides for C#, Node.js, Java (Android), Kotlin (Android) and Swift (iOS). The method I show here are geared towards accessiblity however can be used in any tech stack you would like to follow for your build.
Check the quickstart guides on Azure Docs for Immersive Reader

Edit: My original plan was to build some really easy-to-use templates for even no-code users when I discovered the Immersive Reader. But, I was able to find some truly great templates/applications/websites for major Javascript web frameworks already implementing this service. Hence, for my sole dislike of reinventing the wheel without adding value to the readers. I instead thought it is more beneficial to curate them for you all. One can use these examples to take references and get started more easily. To remove all your doubts about platforms, Immersive Reader also has a Javascript SDK. Well, as I said, we got you covered.

Immersive reader for Express from Azure team!
Immersive Reader on Express + HTML from @canaxess
On React from @sinyaa
Even by using Azure Functions + Immersive Reader. I love Azure functions.
(Lastly) Why not test your own site using Edge with Immersive Reader available or web extension to use Immersive Reader on Chrome over any website.

If you are looking for any more templates or help on working with Immersive Reader, feel free to comment below and I would love to help you out regarding the same.

Integrating Immersive Reader in your apps or website 😍⌨️

With resources, base website and the framework ready to go

Step 1: Using the API to fetch the authentication token

First, we would be needing to fetch the AD Authentication token. Without the AD token, the requests to the Immersive Reader resource can’t be authenticated. I am using Node’s request module to pass the required headers and data that are needed. We are listening for a response with callbacks in place to handle both the response and the error. You can find the code implemented for reference in all the templates above in some shape or form.

	// Making a request to get the token with access to the .env file we created back in step 2

	// One can wrap this into a route/endpoint for the frontend to query before starting the Immersive Reader resource
	// router.get('/GetTokenAndSubdomain', function(req, res) {
	request.post({
	headers: { 'content-type': 'application/x-www-form-urlencoded' },
	url: `https://login.windows.net/${process.env.TENANT_ID}/oauth2/token`,
	form: {
	grant_type: 'client_credentials',
	client_id: process.env.CLIENT_ID,
	client_secret: process.env.CLIENT_SECRET,
	resource: 'https://cognitiveservices.azure.com/'
	}
	},
	function (err, res, tokenResult) {
	if (err) {
	console.log(err);
	return res.status(500).send('Cognitive Services token error, did not receive the token');
	}

	var tokenResultParsed = JSON.parse(tokenResult);

	if (tokenResultParsed.error) {
	console.log(tokenResult);
	return res.send({ error: "Unable to acquire Azure AD token. Please check if your .env values are correct." })
	}

	var token = tokenResultParsed.access_token;
	var subdomain = process.env.SUBDOMAIN;
	return res.send({ token, subdomain });
	});
	// })

view raw getTheToken.js hosted with ❤ by GitHub

To prevent unauthorized use against your Immersive Reader resource make sure to put your GetTokenAndSubdomain API endpoint secured behind some form of authentication.
Read more about Oauth2

Step 2: Authenticating & using the Immersive Reader Javascript SDK

To get started on the Javascript SDK for the Immersive Reader, first install the SDK using npm inside your application’s root directory. This will install the NPM package inside your node_modules folder and would be ready to be imported as and when you wish.

$ npm install --save @microsoft/immersive-reader-sdk

The full Immersive Reader SDK reference can be found here. If you are not comfortable with NPM packages, one can still get access to the SDK methods by using <script> to get access to the SDK resource. Later, this can be used to

<script src="https://contentstorage.onenote.office.net/onenoteltir/immersivereadersdk/immersive-reader-sdk.1.0.0.js"></script>

Next, with this token that we have received. We can send the HTML data through to the Immersive Reader resource on another request. This request is triggered whenever someone would click on our Immersive Reader button. Please make sure to not add this token visibly to your client-side code as it would result in misuse and folks using your auth token to incur heavy charges on your Azure instance.

ImmersiveReader.launchAsync(token, subdomain, data, options)
    .catch(function (error) {
        alert("Error in launching the Immersive Reader. Check the console.");
        console.log(error);
});

In a real-world application, a backend service would be responsible for getting the authentication token while the SDK call can be done from the frontend using the Immersive Reader SDK. I wrote a neat little function to handle both the fetching of the token from the backend route where hopefully our authentication token is there and passing the data to the launchAsync method of the Immersive Reader SDK method with some options.

	tokenGetOverHereandLaunch() {
	fetch(tokenURL, { credentials: `include`, cache: "no-store" })
	.then(response => response.json())
	.then(body => {
	// https://docs.microsoft.com/en-us/azure/cognitive-services/immersive-reader/reference#chunk
	const data = {
	chunks: [{
	content: htmlContent,
	lang: "en-us",
	mimeType: "text/html"
	}]
	};
	// https://docs.microsoft.com/en-us/azure/cognitive-services/immersive-reader/reference#options
	const options = {
	uiLang: "en-us",
	timeout: 90,
	uiZIndex: 5,
	useWebview: true,
	onExit: () => console.log("Closing Immersive Reader"),
	allowFullscreen: false,
	hideExitButton: false,
	cookiePolicy: CookiePolicy,
	disableFirstRun: false,
	readAloudOptions: ReadAloudOptions,
	translationOptions: TranslationOptions,
	displayOptions: DisplayOptions,
	}
	// The backend service needs to be configured to fetch the token from the authentication directory
	launchAsync(body.token, body.subdomain, data, options)
	.catch(function (error) {
	console.log(`Error in launching the Immersive Reader: ${error}`);
	});
	})
	.catch((error) => {
	console.error(`Error: ${error}`);
	});
	}

view raw launch-the-immersive.js hosted with ❤ by GitHub

Following these steps will be enough to add the power of Immersive Reader to your application. As you learn more by doing and reading tutorials, I look forward to your fine-tuned applications of this resource to help folks while browsing the web.

Going even beyond: More ideas to Improve Accessibility

Using lighthouse to improve your site on browsers
Tons of resources on fonts, animations, books & websites on accessibility in one place. More. Even more.
HTML Validation checks that an HTML page follows the HTML specification. To test a page, use the W3C Markup Validation Service. It is required to fix any errors and recommended to fix any warnings.
With upwards trend of flashing lights. Use Azure video insights to mask, flag or block seizure inducing segments from video on your platform or at least provide warning to folks.
Run the WAVE accessibility checker, to identify accessibility errors and warnings.
Check that the site can be fully controlled using just the keyboard (no mouse).
Using Azure Cognitive Text Analytics API’s to translate, parse, and abstract text from online sources, presentations, PDF’s, notes to make sure everyone has equal access to knowledge.
Developer Stream from Azure about Accessibility
Read more about new developments on Seeing AI to get inspiration & even more use-cases.

… and several more are available online as you go out and start exploring. This is the just the beginning.

Food for thought: Accessibility as a process, not just a check

In the end, the Immersive Reader can’t be thought of as a complete end-to-end solution for improving the accessibility of your product. When it is, in fact, a step in the right direction. With more browsers like Edge supporting accessibility features like Immersive Reader by default. Things are looking quite positive in bringing accessibility to the everyone.

Having a screen reader does help. But, we as developers, designers, educators, managers need to take ownership. Making sure the products we build, no matter how complex or use case they serve, always default to being accessible for all in the wider public. This way, we ensure that the web works for us rather than the other way around. Keeping the ability to access the web, its content, and services without barriers allows all people to participate in our society and prevent further marginalization.

Oh here’s a inital screencast I made on the demo I did while playing around the features.

That’s it, folks. Thanks for reading. Hopefully, from this article, you found new ways to boost the accessibility in your stack. This idea can be further built on to create new, more feature-rich applications. Looking forward to seeing what you build with this newfound knowledge. Till then, live in the mix!

Discover more from Mixster

Subscribe to get the latest posts to your email.

Mixster

Life is Vanilla | vipulgupta2048

Boosting Web Accessibility to the next level with Azure Immersive Reader