Skip to content

Latest commit

 

History

History
 
 

ts

README.md

page_type description products languages extensions urlFragment
sample
Microsoft Teams sample which displays deeplinks based on the values passed dynamically to the context.
office-teams
office
office-365
ts
contentType createdDate
samples
02-21-2024 13:38:27
officedev-microsoft-teams-samples-tab-deeplink-pass-values-ts

Passing Values with Deep Links for Tab Apps and Standalone Web Apps

Deep links load applications with additional information that can be used to carry out app logic (e.g., querying a DB, displaying certain data, navigating the user to deeper pages, etc.). This Microsoft Teams tab app sample shows how you can create and use deep links to pass values to tab apps, and how the link's formatting and consumption methods may vary based on the user's access environment (i.e., if they are using Microsoft Teams vs. the app's public URL).

Included Features

  • Tabs
  • Deep Links

Interaction with app

Initial state of tab app

State of tab app before use

Generating a deep link with tab app

Tab app displaying generated deep link

Initial state of tab app accessed through deep link

Tab app displaying value passed from deep link

Generating deep link with standalone web app

Standalone web app displaying generated deep link

Prerequisites

  • Microsoft Teams is installed and you have an account (not a guest account)
  • To test locally, NodeJS must be installed on your development machine (version 16.14.2 or higher)
  • dev tunnel or ngrok latest version or equivalent tunneling solution

Setup

Note: This app was created using Yo Teams, the Microsoft Teams app generator: YoTeams Documentation

All required source code are located in the ./src folder:

  • client client side code
  • server server side code
  • public static files for the web site
  • manifest for the Microsoft Teams app manifest

  1. Setup NGROK

    • Run ngrok - point to port 3007

      ngrok http 3007 --host-header="localhost:3007"

      Alternatively, you can also use the dev tunnels. Please follow Create and host a dev tunnel and host the tunnel with anonymous user access command as shown below:

      devtunnel host -p 3007 --allow-anonymous

  2. Setup code

    • Clone the repository

      git clone https://github.com/OfficeDev/Microsoft-Teams-Samples.git

    • Create a .env file under samples/tab-deeplink-pass-values/ts, and copy/paste the contents of .env_sample into it. Then, update the below configurations:

      • PUBLIC_HOSTNAME should point to your tunnel url (e.g., 124.ngrok-free.app)
      • APPLICATION_ID should be the ID of your Microsoft Teams application

    • In a terminal, navigate to samples/tab-deeplink-pass-values/ts

      cd samples/tab-deeplink-pass-values/ts

    • Install npm modules

      npm install

    • Start the app

      gulp serve

  3. Upload tab app to Teams

    • Go to Teams and select Apps
    • Select Manage your apps > Upload an app > Upload a custom app
    • Go to your project directory, browse to the ./package folder, select the app package zip folder, and choose Open.
    • Select Add in the pop-up dialog box. Your app is uploaded to Teams.

To access the app, you can either open the tab in Microsoft Teams, or you can access it directly in the browser through your tunnel's public URL.

Interacting with the app

Note: When you first load the app (without using a deep link), it says "This app was NOT accessed using a deep link" under the "Current Access Information" section. This section tells you the state of the app and how it was accessed.

Generate a deep link

  1. Enter a value in the text box and click the "Create Deep Link" button to generate a deep link for this app.
    • The generated deep link will contain the information required to not only open the app, but also to pass on the entered value. In a real scenario, the app can then use that text value to perform operations like DB searches, navigation, etc.
    • If you are currently accessing the app through Teams (as a "tab app"), then the generated deep link will be configured to open in Teams. If you are accessing the app directly through its public URL (as a "standalone app"), then the deep link will be configured to open the standalone version.
  2. Click the deep link to open the app in a new window.
    • When the app loads using the deep link, you can see that the text you entered in the textbox was successfully passed on to the app by checking the status under "Current Access Information".

View the standalone web app

  1. To switch to the standalone app from the tab app, right-click the tab and select "Open in browser" or "Open in new window". Or, you can also enter your tunnel's public URL directly in the browser.

Deep Link Generation Demo

Gif demonstrating how to generate a deep link

Further Reading

Useful Guidance from Yo Teams

Building the app

The application is built using the build Gulp task.

npm i -g gulp-cli
gulp build

Building the manifest

To create the Microsoft Teams Apps manifest, run the manifest Gulp task. This will generate and validate the package and finally create the package (a zip file) in the package folder. The manifest will be validated against the schema and dynamically populated with values from the .env file.

gulp manifest

Deploying the manifest

Using the yoteams-deploy plugin, automatically added to the project, deployment of the manifest to the Teams App store can be done manually using gulp tenant:deploy or by passing the --publish flag to any of the serve tasks.

Configuration

Configuration will be stored in the .env file. Please create one based on the .env_sample file included in the samples/tab-deeplink-pass-values/ts folder.

Debug and test locally

To debug and test the solution locally you use the serve Gulp task. This will first build the app and then start a local web server on port 3007, where you can test your Tabs, Bots or other extensions. Also this command will rebuild the App if you change any file in the /src directory.

gulp serve

To debug the code you can append the argument debug to the serve command as follows. This allows you to step through your code using your preferred code editor.

gulp serve --debug

Useful links

Additional build options

You can use the following flags for the serve, ngrok-serve and build commands:

  • --no-linting or -l - skips the linting of Typescript during build to improve build times
  • --debug - builds in debug mode and significantly improves build time with support for hot reloading of client side components
  • --env <filename>.env - use an alternate set of environment files
  • --publish - automatically publish the application to the Teams App store

Deployment

The solution can be deployed to Azure using any deployment method.

Logging

To enable logging for the solution you need to add msteams to the DEBUG environment variable. See the debug package for more information. By default this setting is turned on in the .env file.

Example for Windows command line:

SET DEBUG=msteams

If you are using Microsoft Azure to host your Microsoft Teams app, then you can add DEBUG as an Application Setting with the value of msteams.

Further reading