Beginners Guide to MS Teams Development #1: Tabs

I hope you are all doing well while the pandemic is still at large. Well, since we all stay indoors most of the time, we can leverage the time to learn something new rather than hibernate 🐻💤

So this tutorial is my first of the beginner series for Microsoft Teams development. This is good for developers, who are using Microsoft Teams at your work and thinking about building some apps (can be internal tools, or publish for everybody) that run inside of Teams, and/or who have published some app on other platforms like Slack and want to gain more users on Teams. Also, you don't need to have prior experience with any Microsoft cloud technology to try this tutorial!

There are many different paths to learn how to build Teams apps, and this tutorial uses a bare-minimum code and minimal toolsets with some visual approach. Alternatively, try the tutorial on the Microsoft docs, if you want to jump ahead with the full-scale approach.

---

Okay, as the very first of this beginner series, let me quickly explain what tabs feature is.

Teams features: Tabs

There are a variety of features you can use to build Teams app, like Messaging extensions, conversational bots, etc. and Tabs are where you can display any information in any visual interface.

Technically, tabs are just iframes, where you can display any webpages. You just have to configure to display it correctly on Teams!

Here, I am going to show you how to create two types of Tabs - a personal tab (only viewable by the person who installed it) and a team tab (a team-level tab).

What you are going to do in this tutorial

1. Configure your app with App Studio
2. Build a personal tab on an online IDE and serve from there
3. Re-configure to modify it to a channel/group tab
4. Add more functions for the team tab
5. Add the dark mode support

The end result would look like this:

📓 Prerequisites

To be able to install apps to Teams, your organization's admin needs to grant permission.

Otherwise, you can sign up for Microsoft 365 developer program, a free, renewable subscription that comes with a developer tenant sandbox and sample data pack, like mock user data!

• Permission to develop on Teams or developer tenant (Sign up for M365 developer program!)
• App Studio - look for the app from the Apps menu in Teams client and install to your workspace
• Basic knowledge of JavaScript

1. Building a Personal Tab

🎏 Grabbing the code sample

In this tutorial, I am using the 3rd party tool, Glitch to host and run this project and the rest of the tutorial series. Glitch is a web-based IDE that you can write and run your node.js code, so at least for now, you can focus on learning the concepts and basics of Teams app development without worrying about running and tunneling localhost, or deploying. (I will cover them in the future!)

Go to the sample code page and remix the project. Remixing is like the forking a repo on GitHub, so it generates a copy of the project for you, so you can modify the code in the way you want without messing with the original 🙌

Once you get your own project repo, it serves up the app automatically and you get your own web server URL. For example, if your generated project name, usually it consists of a few random words, is achieved-diligent-bell, your webserver URL would be https://achieved-diligent-bell.glitch.me. You can customize the name too if you want, too.

⚙️ App Configuration: Creating App Manifest with App Studio

When you are building apps for Teams, you must create an app package to be installed to Teams client. The package includes:

📁 your-app-package
    └── 📄 manifest.json
    └── 🖼 color.png (192x192)
    └── 🖼 outline.png (32x32)

and the rest of the app code and assets must be hosted on your webserver. (In this tutorial, we are using Glitch to automatically serve your app).

We are not creating the manifest file manually today, but instead, we are going to create the app package using a visual tool called App Studio so you can create the package directly to Teams client.

🎛 Using App Studio

Once you have installed App Studio app in Teams client, open the app. You can launch it by clicking the . . . from the left menu bar.

Then, click the Manifest Editor tab from the top, then select Create a new app.

You are going to need to fill out all the required fields including the app names, descriptions, etc.

At the App URLs section, fill out your privacy and TOU webpages. In this example, I am just using the placeholder URL, https://example.com, but when you're developing apps to publish, you must have the web pages with the statements.

🔖 Configuring a personal tab

From the left menu, select Capabilities > Tabs.

Click the Add button under Add a personal tab and enter the info.
Under Content URL, enter your webpage URL (should be https://[your-project-name].glitch.me/index.html).

Currently, the index.html file has nothing more than a few lines of static HTML code (and some CSS):

<h1>Hello world! </h1>
<p>This is the bare-minimum setting for MS Teams Tabs. </p>

Feel free to tweak the content in the index.html as you want. This is the content to be displayed in your Teams client.

🎉 Finish creating the app manifest package

Go to Finish > Test and distribute.

If you get any errors, go fix it, otherwise, click Install your client.

Ta-da, now you have the personal tab at the left menu 🎉

If something is wrong after installing it properly, check if the Content URL is set correctly. Make sure that you're using your own web server URL, like https://[your-project-name].glitch.me/index.html.

You can stop here, or proceed to make it into a team tab at the next step.

2. Building a Channel/Group Tab

Now, let's transform this into a channel/group tab. It requires a few extra steps.

🎏 Grabbing the code sample on Glitch

You can directly remix the code sample by clicking the remix link here this time. Or feel free to continue with the previous code sample and modify the code.

Notice that this code sample has the additional config.html, also some JavaScript code added.

⚙️ Tweaking App Configuration

Go back to App Studio, open the app you just create, and let's modify the tabs settings. (Or create a new app if you want a fresh one! In this case, you will need to fill out the app details for the new app.)

🔖 Configuring a team tab

Go to Capabilities > Tabs. You can either leave or delete the personal tab you have created previously.

Click the "Add" button under Team tab, and enter the info.
Under Configuration URL, enter your web URL (should be https://[your-project-name].glitch.me/config.html). Even if you don't have any configurable content, this field is required.

Using JavaScript SDK for Tabs to load the content

Unlike the personal tab, which can be just a plain static HTML, for the team tab, let's use the SDK to load the main content.

Notice that these lines of code are included in the config.html:

<script src="https://statics.teams.cdn.office.net/sdk/v1.6.0/js/MicrosoftTeams.min.js"></script>

Note: As you may notice, this example uses SDK version 1.6.0. If your code doesn't work as expected, check the version you are using!

microsoftTeams.initialize();

microsoftTeams.settings.setSettings({
  contentUrl: 'https://msteams-teamtab-minimum.glitch.me/index.html',
  });
microsoftTeams.settings.setValidityState(true); 

You can add some dynamic values like some user locale info by using the getContext() method. To learn more about the Teams SDK, read the SDK documentation.

Then, try the app by going to Finish > Test and distribute and install the app.

If everything goes well, your app appears at the top of the client 🎉

🔦 Theming (Supporting Dark Mode & High-Contrast Mode)

But wait, what if you and your potential app users are in the dark mode? Does it automatically handle the color change in the iframe?

No. So let's fix that.

Take a look at one of the view HTML files. Notice it has JavaScript to handle the theme detection (and theme change event handling).

In this example, on the default (light) theme, the default text color (typically black) is used, otherwise, white.

microsoftTeams.getContext((context) => {
  if(context.theme !== 'default') {
    document.body.style.color = '#fff';
  }
});

microsoftTeams.registerOnThemeChangeHandler((theme)=> { 
  if(theme !== 'default') {
    document.body.style.color = '#fff';
    document.body.style.color = 'inherit';
  }
});

Now, let's toggle the theme and see how the change is reflected.

You can change the client theme color by going to the settings menu from your avatar at the top-right.

The font color should be white in the dark or high-contrast mode like this:

🙌

I hope you have better ideas on how you can get started with Microsoft Teams app development.

---

In the tutorial, to make as simple as possible, I did not tell you how to use the recommended toolsets, however, in the reality, you probably create a full-fledged app with more tools with VS Code and probably some front-end framework like React with a build manager, etc, and deploy to Azure! Stay tuned for these tutorials too.

To learn more, please go check the links below.

In the next tutorials, I will show you how to create interactive message extensions. So, see you next time 👋

Learn more

• MS Teams Documentation - Overview
• Build a Hello World App - this instruction uses VSCode, ngrok, and React.js
• Microsoft Azure tutorials & articles on Dev.to

Comments

[Sunil Kumar]

I have specially created dev.to account to like your post and comment that - Thank you for the article.
I was struggling from past 3-4 days to create a teams tab app. There are lot of tutorials about Visual Studio Code and many many articles about it, which makes everything so confusing for a beginner like me.

Your article helped me to understand the things what I exactly wanted.
Thank You
Sunil

[Tomomi Imura 🐱]

I am so glad it helped! (and oops sorry for my super late reply 🥺)

[Warrior]

Nice write up.

We also had some experience with Microsoft Teams Tab development recently and made a short blog post as well - moveworkforward.com/blog/microsoft... (feel free to link to it).

[Tomomi Imura 🐱]

This is great! Thanks for sharing with me. I will share with my teammates too 🙌

[Sudipta K Paik]

Drung the configuration of tabs app, I want to sign in (Social), for this I need to open the app in new tab.

How Can I do that?

[Ojasava Paras]

How do I solve the permission Issue?

[Tomomi Imura 🐱]

Aw, so sorry for not noticing your message for such a long time... I think you are talking about the permission to be able to sideload your app to the Teams client? This is something you need to ask your admin, or create your own tenant.

The doc for admins to set up is at: docs.microsoft.com/en-us/microsoft...